@spec create(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1Extractions.Input.t()
) ::
  {:ok, ArchAstro.Types.Extraction.t()} | {:error, ArchAstro.Error.reason()}

Start an extraction

Records a text-extraction job for a document (file) or a URL (url + mode). The job is owner-scoped and tagged with the caller-supplied destination namespace, without committing knowledge to an agent (no embeddings, no agent attach).

Exactly one of file or (url + mode) is required.

Document extraction (file) runs synchronously: the response already reflects the final state (done with its output, or an error if extraction couldn't complete), status 201. URL extraction (url + mode) submits an async crawl and returns immediately with state running, status 202 — poll GET /extractions/:extraction for its terminal state.

The extraction job. Document extraction returns 201 with state: "done"; link/site extraction returns 202 with state: "running".

@spec get(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.Extraction.t()} | {:error, ArchAstro.Error.reason()}

Retrieve an extraction

Returns a single extraction job and its current state. Poll this endpoint after starting an async (link/site) extraction until state is done or failed.

An extraction that exists but is not visible to the current viewer returns 404 rather than 403, so the resource's existence is not revealed.

The extraction job.