# `Chronicle.Captures`
[🔗](https://github.com/Cratis/Chronicle.Elixir/blob/main/lib/chronicle/captures.ex#L4)

Idiomatic API for working with Chronicle captures.

Captures turn data that arrives from outside the event log into events appended to this
event store. Declare one with `use Chronicle.Captures.Capture` (see its moduledoc for the
DSL) and either register it with `Chronicle.Client`'s `captures:` option (or `otp_app:`
auto-discovery), or call the functions here directly.

## Usage

    {:ok, _} = Chronicle.Captures.register(MyApp.Captures.InvoiceCapture)
    {:ok, _} = Chronicle.Captures.start(MyApp.Captures.InvoiceCapture)
    {:ok, captures} = Chronicle.Captures.list()

## Options

Every function accepts:

  * `:client` — the client name (default: `Chronicle.Client`)

# `captured_events`

```elixir
@spec captured_events(String.t(), keyword()) :: {:ok, [map()]} | {:error, term()}
```

Reads the private events a capture has appended, most recent first.

# `delete`

```elixir
@spec delete(module() | String.t(), keyword()) :: :ok | {:error, term()}
```

Deletes a capture, identified by its module or its capture id.

# `list`

```elixir
@spec list(keyword()) ::
  {:ok, [Chronicle.Captures.CaptureDetails.t()]} | {:error, term()}
```

Lists every capture registered for the current event store.

# `register`

```elixir
@spec register(module(), keyword()) ::
  {:ok, Chronicle.Captures.CaptureDetails.t()} | {:error, term()}
```

Registers (saves) a capture.

`capture` is a module using `Chronicle.Captures.Capture`. Saving an already-started capture
fails on the kernel; stop it first.

# `register_discovered`

```elixir
@spec register_discovered(keyword()) :: :ok | {:error, term()}
```

Registers every discoverable capture.

Idempotent: skips a capture whose declaration already matches the kernel's. Warns (rather
than failing) before saving over a started capture whose declaration changed — saving a
started capture stops it, so it comes back stopped. Starts a capture only when it declares
`start: true`.

# `start`

```elixir
@spec start(module() | String.t(), keyword()) :: :ok | {:error, term()}
```

Starts a capture, identified by its module or its capture id.

# `stop`

```elixir
@spec stop(module() | String.t(), keyword()) :: :ok | {:error, term()}
```

Stops a capture, identified by its module or its capture id.

# `validate`

```elixir
@spec validate(module() | String.t(), keyword()) ::
  {:ok, [String.t()]} | {:error, term()}
```

Validates a capture declaration against the kernel's CDL compiler, without saving it.

`capture` is either a module using `Chronicle.Captures.Capture` or raw CDL text.

---

*Consult [api-reference.md](api-reference.md) for complete listing*