Returns a specification to start this module under a supervisor.

See Supervisor.

@spec close(pid()) :: :ok

Gracefully shuts down the client.

@spec connect(pid()) :: :ok

Establishes the WebSocket connection and joins the Phoenix channel.

Blocks until the join is acknowledged. Returns :ok on success or raises on error.

@spec did(pid()) :: String.t()

Returns the agent's DID — either provided in config or assigned by the node on connect.

@spec get_credential(pid(), String.t()) :: {:ok, map()} | {:error, term()}

Retrieves a stored credential by ID.

@spec handle(pid(), String.t(), Layr8.Handler.handler_fn()) :: :ok

Registers a handler for a DIDComm message type.

Must be called before connect/1. Raises Layr8.AlreadyConnectedError if called after.

Handler Signature

fn msg -> {:reply, %Layr8.Message{...}} | :noreply | :pass | {:error, reason} end

@spec handle_all(pid(), Layr8.Handler.handler_fn()) :: :ok

Registers a catch-all handler invoked when no specific handler matches.

Must be called before connect/1. Raises Layr8.AlreadyConnectedError if called after.

Handler Signature

fn msg -> {:reply, %Layr8.Message{...}} | :noreply | :pass | {:error, reason} end

@spec list_credentials(
  pid(),
  keyword()
) :: {:ok, [map()]} | {:error, term()}

Lists stored credentials for a holder. Defaults: holder = did/1.

@spec mcp(pid(), String.t()) :: {:ok, Layr8.Mcp.Binding.t()} | {:error, term()}

Sets up MCP (Model Context Protocol) over DIDComm on a protocol base and returns a binding whose Layr8.Mcp.peer/2 yields a caller.

Must be called before connect/1 (like handle/3): it registers the protocol subscription the cloud-node needs in order to deliver #{base}/* replies. Idempotent per base — calling it twice returns a second binding over the same subscription rather than raising the way a duplicate handle/3 would. Compose freely with your own handle/3 registrations.

See Layr8.Mcp for the call surface.

@spec refresh_grants(pid(), String.t() | nil) :: :ok

Forgets the cached Verifiable Grants for did (default: this agent's), so the next message re-reads them.

The cache TTL is the whole freshness story: a grant minted seconds ago is invisible until it lapses. An agent that has just been TOLD it was granted something — by a request/approve flow, or by a person on the other end of a chat — should not have to wait out a timer it cannot see.

@spec request(pid(), Layr8.Message.t() | map(), keyword()) :: {:ok, Layr8.Message.t()}

Sends a DIDComm message and waits for a correlated response (matched by thread ID).

Returns {:ok, Layr8.Message.t()} or raises Layr8.ProblemReportError / Layr8.NotConnectedError.

Options

• :timeout — milliseconds to wait for a reply (default 30s)
• :parent_thread — set pthid for nested thread correlation

@spec request_result(pid(), Layr8.Message.t() | map(), keyword()) ::
  {:ok, Layr8.Message.t()} | {:error, term()}

request/3 without the raises: returns {:ok, Message.t()} or {:error, reason} — :timeout, :not_connected, or {:problem_report, code, comment}.

Same request path, same options. This exists because a remote call failing is an ordinary outcome for some callers (Layr8.Mcp routes on it rather than rescuing), while for others an unanswered request is exceptional — the SDK should not force either one to convert.

@spec send(pid(), Layr8.Message.t() | map(), keyword()) :: :ok

Sends a DIDComm message.

By default waits for server acknowledgment. Pass fire_and_forget: true to skip.

Returns :ok or raises Layr8.NotConnectedError.

@spec sign_credential(pid(), map(), keyword()) :: {:ok, String.t()} | {:error, term()}

Signs a W3C Verifiable Credential. Defaults: issuer = did/1, format = "compact_jwt".

@spec sign_presentation(pid(), [String.t()], keyword()) ::
  {:ok, String.t()} | {:error, term()}

Signs a W3C Verifiable Presentation. Defaults: holder = did/1, format = "compact_jwt".

@spec start_link(start_opts()) :: GenServer.on_start()

Starts the Layr8 Client GenServer.

Accepts the same keys as Layr8.Config.resolve!/1 plus:

• :on_disconnect — called with the disconnect reason
• :on_reconnect — called after successful reconnection
• :on_grant_miss — called when a message went out with NO covering Verifiable Grant and the node then denied it, when the covering set had to be capped, or when the grants could not be read at all. See Layr8.Wallet: the sender is the only party that knows nothing was attached, and the node's denial names the grant it could not find, which sends people to check a grant that is fine.

Raises Layr8.Error if required config fields are missing.

@spec store_credential(pid(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Stores a signed credential JWT for a holder. Defaults: holder = did/1.

@spec verify_credential(pid(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Verifies a signed credential. Defaults: verifier = did/1.

@spec verify_presentation(pid(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Verifies a signed presentation. Defaults: verifier = did/1.