Ceramic

Elixir client for the Ceramic search API, built on Req.

Installation

def deps do
  [
    {:ceramic, "~> 0.1.2"}
  ]
end

Full documentation is on hexdocs.pm/ceramic.

Usage

client = Ceramic.new()  # reads CERAMIC_API_KEY (and CERAMIC_BASE_URL if set)

{:ok, response} = Ceramic.search(client, "California rental laws", max_results: 5)
response.request_id
response.result.results  # [%Ceramic.SearchResponse.Item{title: ..., url: ..., description: ...}]

Ceramic.search!/3 raises Ceramic.Error instead of returning an error tuple.

Per-request overrides apply to one call and leave the client unchanged:

Ceramic.search(client, query,
  timeout: 10_000,
  extra_headers: %{"x-request-source" => "cron"},
  extra_query: %{"debug" => 1},
  extra_body: %{"experimental" => true}
)

Errors

Every failure is a %Ceramic.Error{}. Match on kind and status:

case Ceramic.search(client, query) do
  {:ok, response} -> response
  {:error, %Ceramic.Error{kind: :validation}} -> # rejected before sending
  {:error, %Ceramic.Error{kind: :api_status, status: 401, body: body}} -> # body["code"]
  {:error, %Ceramic.Error{kind: :timeout}} -> # retries exhausted
end

Retries and timeouts

Requests retry twice on 408, 409, 429, 5xx, and connection errors, with backoff of 1s, 2s, 4s. A Retry-After header sets the delay and an x-should-retry header overrides the decision. The receive timeout is 60s and the connect timeout is 5s.

Override per client: Ceramic.new(max_retries: 0, timeout: 10_000). Any other option goes to Req.new/1.

License

Apache-2.0. See LICENSE.