@spec add(t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Adds one raw text document. Takes :docid and :metadata.

@spec add_many(t(), list()) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Adds several documents in one request.

The response reports per-document results, so a {:ok, _} can still carry individual failures under "documents".

@spec add_vector(t(), [number()], keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Adds one precomputed embedding. Takes :docid and :metadata.

@spec cancel_reindex(t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Cancels a reindex job.

@spec delete(t(), String.t()) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Deletes one document by id, along with its chunks.

@spec detail(t()) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Fetches the collection's settings plus document and chunk counts.

@spec export_archive(t()) :: {:ok, binary()} | {:error, PaveDBClient.Error.t()}

Downloads this collection as a binary zip archive.

@spec get(t(), String.t()) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Fetches one document by id, with its metadata and chunk ids.

@spec get_chunk(t(), String.t()) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Fetches one chunk's record by its rid.

@spec get_chunk_content(t(), String.t()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Fetches one chunk's raw text as %{"content" => text, "content_type" => type}.

@spec get_query(t(), String.t()) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Fetches one logged search, including the result ids it returned.

@spec get_reindex(t(), String.t()) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Fetches a reindex job's status.

@spec ingest(t(), Path.t(), keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Uploads a local file. Takes :docid, :metadata, :content_type, and :csv_options.

@spec list_chunks(t(), String.t()) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Lists the chunks a document was split into. Listings carry no chunk text.

@spec list_documents(t()) :: {:ok, [map()]} | {:error, PaveDBClient.Error.t()}

Lists the collection's documents.

@spec list_queries(
  t(),
  keyword()
) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Lists logged searches, newest first. Takes :limit and :offset.

@spec matches(t(), String.t(), keyword()) ::
  {:ok, [map()]} | {:error, PaveDBClient.Error.t()}

Searches and returns just the matches, skipping the response envelope.

@spec rename(t(), String.t()) :: {:ok, t()} | {:error, PaveDBClient.Error.t()}

Renames the collection and returns a handle pointing at the new slug.

The original handle still carries the old name, so keep the returned one.

@spec replay_query(t(), String.t()) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Replays one logged search against the collection's current data.

Compare the replayed ids with the stored ones to detect drift.

@spec restore_archive(t(), binary(), keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Restores a binary zip archive into this collection's name.

Creates a new collection by default; pass replace: true to replace one.

@spec search(t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Searches by text and returns the full response envelope.

Takes :k, :filters, :content_filter, :mode, and :include_common. Use matches/3 for the hits alone.

@spec search_vector(t(), [number()], keyword()) ::
  {:ok, map()} | {:error, PaveDBClient.Error.t()}

Searches with a precomputed query vector. Takes the same options as search/3.

@spec start_reindex(
  t(),
  keyword()
) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Starts a resumable reindex. Takes :embedder_type, :embed_model, and :embedder_config.

@spec update(
  t(),
  keyword()
) :: {:ok, map()} | {:error, PaveDBClient.Error.t()}

Updates editable metadata. Takes :display_name.