X402.AuthCapture.Resource (X402 v0.9.0)

Copy Markdown View Source

Durable hold-before-handler orchestration for auth-capture escrow resources.

run/4 accepts only an initial escrow authorization. It retains PaymentInfo, saltNonce, a pre-signed void, and durable execution phases. A confirmed hold precedes the handler. The handler returns {:ok, json_value, actual_amount} or {:error, reason}. Results must be plain JSON values without custom encoders, at most 64 levels deep and one MiB of encoded JSON. Invalid results and exceptions retain uncertain execution; they never authorize running the handler again.

Synchronous resources capture actual usage and confirm voiding the remainder before returning content. Deferred resources may return content after durable metering; the application must subsequently call resume/2 to capture and void. A valid pre-signed void is retained before funding, including for zero-charge or explicitly failed handlers.

resume/3 is application-only recovery. It may continue funding or settlement, and can run a supplied handler only if the durable executing phase has never been entered. It cannot recover the value or metering of a crashed handler. Never expose this API as an unauthenticated client endpoint.

Production requires the executor's shared durable store. There are no leases, TTL eviction, or automatic retries of uncertain handler execution. Applications must schedule recovery and monitor unresolved payment records. Authorization flow (terminal charge) and standalone refunds use X402.AuthCapture.Engine directly; this resource orchestrates escrow flow only.

Summary

Functions

Builds an escrow resource with an explicit receiver-consent signer.

Resumes safe financial work, never uncertain handler execution.

Confirms a hold, executes once, and durably meters before returning content.

Read-only verification of an initial authorization under this resource's flow and mode.

Types

handler()

@type handler() :: (-> {:ok, term(), non_neg_integer()} | {:error, term()})

result()

@type result() :: {:ok, term(), map()} | {:pending, String.t()} | {:error, term()}

t()

@type t() :: %X402.AuthCapture.Resource{
  authorizer: X402.Signer.t(),
  engine: X402.AuthCapture.Engine.t(),
  max_records: pos_integer(),
  mode: :sync | :deferred
}

Functions

new(opts)

(since 0.9.0)
@spec new(keyword()) :: {:ok, t()} | {:error, term()}

Builds an escrow resource with an explicit receiver-consent signer.

resume(resource, payment_info_hash, handler \\ nil)

(since 0.9.0)
@spec resume(t(), String.t(), handler() | nil) :: result()

Resumes safe financial work, never uncertain handler execution.

Supply a handler only when recovering funding that has not reached execution. Deferred, already-metered work needs no handler.

run(resource, envelope, requirements, handler)

(since 0.9.0)
@spec run(t(), map(), map(), handler()) :: result()

Confirms a hold, executes once, and durably meters before returning content.

verify(resource, envelope, requirements)

(since 0.9.0)
@spec verify(t(), map(), map()) :: {:ok, map()} | {:error, term()}

Read-only verification of an initial authorization under this resource's flow and mode.