Coffrify (Coffrify v0.9.0)

View Source

Official Elixir client for the Coffrify API.

Coffrify is encrypted file-transfer infrastructure. This SDK is the canonical Elixir client and mirrors the JavaScript SDK (@coffrify/sdk v0.9.0) feature-for-feature.

Quickstart

client = Coffrify.new(api_key: System.fetch_env!("COFFRIFY_API_KEY"))

{:ok, page} = Coffrify.Resources.Transfers.list(client, limit: 20)
{:ok, %{webhook: wh, secret: secret}} =
  Coffrify.Resources.Webhooks.create(client,
    name: "My CI",
    url: "https://ci.example.com/hooks/coffrify",
    events: ["transfer.created", "transfer.downloaded"]
  )

IO.puts("Store this secret in your secret manager: " <> secret)

Configuration

Pass options to new/1:

  • :api_key (required) — API key starting with cof_ (or legacy cfy_ / fxa_).
  • :api_url (default "https://api.coffrify.com") — override for staging or private deployments.
  • :workspace_id — pin requests to a specific workspace. Defaults to the key's workspace.
  • :timeout_ms (default 30_000) — per-request timeout.
  • :user_agent — custom User-Agent (defaults to coffrify-elixir/0.9.0).
  • :max_retries (default 3) — number of retries when retry_policy is not set.
  • :retry_base_delay_ms (default 500) — initial backoff delay.
  • :retry_policy — custom Coffrify.Runtime.Retry.Policy; overrides the legacy options above.
  • :auto_idempotency (default true) — auto-generate Idempotency-Key on POST/PUT/PATCH/DELETE.
  • :idempotency_store — a Coffrify.Runtime.Idempotency adapter for crash-safe replay.
  • :idempotency_ttl_ms (default 24h) — how long cached idempotent responses are kept.
  • :circuit_breaker — a Coffrify.Runtime.CircuitBreaker PID.
  • :rate_limiter — a Coffrify.Runtime.RateLimit adapter (TokenBucket or LeakyBucket).
  • :telemetry_metadata (default %{}) — static metadata merged into every :telemetry.execute/3 payload.
  • :finch_name — optional Finch pool name passed to Req.
  • :hooks — keyword list of :before_request, :after_response, :on_retry, :on_error callbacks.

Summary

Types

request_method()
request_opts()
t()

Functions

new(opts)

Build a new Coffrify client.

request(client, method, path, body \\ nil, opts \\ [])

Issue an HTTP request against the Coffrify API.

request!(client, method, path, body \\ nil, opts \\ [])

Same as request/5 but raises on error.

version()

Return the static SDK version as a string.

Types

request_method()

@type request_method() :: :get | :post | :put | :patch | :delete

request_opts()

@type request_opts() :: [
  idempotency_key: String.t() | nil,
  skip_retry: boolean(),
  headers: [{String.t(), String.t()}],
  timeout_ms: pos_integer() | nil,
  query: keyword() | map()
]

t()

@type t() :: %Coffrify{
  api_key: String.t(),
  api_url: String.t(),
  auto_idempotency: boolean(),
  circuit_breaker: pid() | atom() | nil,
  finch_name: atom() | nil,
  hooks: keyword(),
  idempotency_store: term() | nil,
  idempotency_ttl_ms: pos_integer(),
  rate_limiter: term() | nil,
  retry_policy: Coffrify.Runtime.Retry.Policy.t(),
  telemetry_metadata: map(),
  timeout_ms: pos_integer(),
  user_agent: String.t(),
  workspace_id: String.t() | nil
}

Functions

new(opts)

@spec new(keyword()) :: t()

Build a new Coffrify client.

Raises Coffrify.Error.InvalidApiKey when the provided API key does not start with a known prefix (cof_, cfy_, fxa_).

request(client, method, path, body \\ nil, opts \\ [])

@spec request(t(), request_method(), String.t(), term(), request_opts()) ::
  {:ok, term()} | {:error, Exception.t()}

Issue an HTTP request against the Coffrify API.

Returns {:ok, body} on a 2xx response, or {:error, %Coffrify.Error{}} for every other outcome (4xx, 5xx, transport errors, circuit-open).

Examples

Coffrify.request(client, :get, "/transfers", nil, query: [limit: 10])
Coffrify.request(client, :post, "/webhooks", %{name: "ci", url: "..."})

request!(client, method, path, body \\ nil, opts \\ [])

@spec request!(t(), request_method(), String.t(), term(), request_opts()) :: term()

Same as request/5 but raises on error.

version()

@spec version() :: String.t()

Return the static SDK version as a string.