@spec advance_replay_position(String.t()) :: :ok

Advances the replay position for a cassette. Creates the state if it doesn't exist.

@spec append_entry(String.t(), Reqord.CassetteEntry.t()) :: :ok

Appends a new entry to the cassette state. Creates the state if it doesn't exist.

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec clear_context(pid()) :: :ok

Clears cassette context for the current process.

@spec clear_entries(String.t()) :: :ok

Clears all entries for a cassette.

@spec get_context(pid()) :: map()

Retrieves cassette context for the current process.

Returns an empty map if no context has been set.

Examples

iex> Reqord.CassetteState.get_context(self())
%{}

iex> Reqord.CassetteState.put_context(self(), %{model: "gpt-4"})
iex> Reqord.CassetteState.get_context(self())
%{model: "gpt-4"}

@spec get_entries(String.t()) :: [Reqord.CassetteEntry.t()]

Gets the current accumulated entries for a cassette. Returns empty list if no state exists.

@spec get_replay_position(String.t()) :: non_neg_integer()

Gets the current replay position for a cassette. Returns 0 if no state exists.

@spec put_context(pid(), map()) :: :ok

Stores cassette context for the current process.

This allows macro-generated tests to provide additional metadata that will be merged with the test context when determining cassette names.

Examples

# In a macro-generated test setup
Reqord.CassetteState.put_context(self(), %{
  provider: "google",
  model: "gemini-2.0-flash"
})

@spec reset_replay_position(String.t()) :: :ok

Resets the replay position to 0 for a cassette.

@spec start_for_cassette(String.t()) :: {:ok, pid()} | {:error, term()}

Starts a named GenServer for a specific cassette.

@spec stop_for_cassette(String.t()) :: :ok

Stops the named GenServer for a cassette.