# `Threadline`
[🔗](https://github.com/szTheory/threadline/blob/v0.2.0/lib/threadline.ex#L1)

Audit platform for Elixir teams using Phoenix, Ecto, and PostgreSQL.

Threadline combines trigger-backed row-change capture, rich action semantics
(actor/intent/context), and operator-grade exploration.

# `actor_history`

Returns `AuditTransaction` records for a given actor, ordered by
`occurred_at` descending.

## Options

- `:repo` — required `Ecto.Repo` module

# `export_csv`

Exports matching audit changes as CSV (same `filters` / `opts` as `Threadline.Query.timeline/2`).

See `Threadline.Export` and `Threadline.Query.timeline/2`.

# `export_json`

Exports matching audit changes as JSON (same `filters` / `opts` as `Threadline.Query.timeline/2`).

Pass `json_format: :ndjson` in `opts` for newline-delimited objects. See `Threadline.Export`
and `Threadline.Query.timeline/2`.

# `history`

Returns `AuditChange` records for a given schema record, ordered by
`captured_at` descending.

Structs include `:changed_from` when present in the row (sparse prior values on
UPDATE under an opt-in per-table capture function; `nil` when disabled or on
INSERT/DELETE rows).

## Options

- `:repo` — required `Ecto.Repo` module

# `record_action`

Records a semantic audit action.

## Required options

- `:actor` or `:actor_ref` — `%ActorRef{}` identifying who performed the action
- `:repo` — the `Ecto.Repo` module to use for insertion

## Optional options

- `:status` — `:ok` or `:error` (default: `:ok`)
- `:verb` — string or atom (e.g., `"update"`)
- `:category` — string or atom (e.g., `"membership"`)
- `:reason` — atom (e.g., `:insufficient_permissions`)
- `:comment` — free-text string explanation
- `:correlation_id` — cross-boundary correlation ID string
- `:request_id` — request ID string (from `Plug.RequestId` / `x-request-id`)
- `:job_id` — Oban job ID string

## Returns

- `{:ok, %AuditAction{}}` on success
- `{:error, %Ecto.Changeset{}}` if changeset validation fails
- `{:error, :missing_actor}` if no actor was provided
- `{:error, :invalid_actor_ref}` if the actor fails ActorRef validation
- `{:error, :missing_repo}` if `:repo` is not provided

# `timeline`

Returns `AuditChange` records across tables, filtered by the given options,
ordered by `captured_at` descending.

## Options

- `:table` — string or atom; filters by `table_name`
- `:actor_ref` — `%ActorRef{}`; filters by actor via a JOIN to `audit_transactions`
- `:from` — `DateTime`; inclusive lower bound on `captured_at`
- `:to` — `DateTime`; inclusive upper bound on `captured_at`
- `:repo` — required `Ecto.Repo` module

---

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