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 join_did(pid(), String.t(), keyword()) ::
  {:ok, Layr8.DidHandle.t()} | {:error, term()}

Joins an additional DID on this client's existing WebSocket connection and returns a Layr8.DidHandle for it.

Must be called after connect/1 — it rides the connection that call established. The counterpart of the node-sdk's joinDid (src/client.ts), and the same shape mcp-pod uses to host one Instance DID per connected account on a single socket.

Options

• :protocols — this DID's payload_types subscription. Defaults to the protocols derived from :handlers. The problem-report protocol is appended unless already present (or a catch-all is registered), so the node can deliver denials addressed to this DID
• :handlers — %{msg_type => handler_fn} that fire for messages received on THIS DID; the client-global registry is the fallback
• :handle_all — catch-all handler for this DID
• :did_spec — merged over the SDK defaults, e.g. %{"storage" => "persistent", "controller" => owner_did}. controller matters: helix enforces issuer == resource_controller on grants, so a DID whose controller is the node makes every grant issued by its owner fail

Returns {:error, %Layr8.NotConnectedError{}} before connect/1, {:error, :already_joined} for a DID already hosted, and {:error, :primary_did} for the DID connect/1 joined — that one is reachable through send/3 and request/3 directly.

@spec joined_dids(pid()) :: [String.t()]

Lists the DIDs joined with join_did/3 (the connected DID is did/1).

@spec leave_did(pid(), String.t()) :: :ok

Leaves a DID joined with join_did/3 and forgets its handlers. The connection and every other DID stay up. No-op for a DID not joined.

@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_from(pid(), String.t(), Layr8.Message.t() | map(), keyword()) ::
  {:ok, Layr8.Message.t()}

request/3 from a DID joined with join_did/3. Prefer Layr8.DidHandle.request/3.

@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 request_result_from(pid(), String.t(), Layr8.Message.t() | map(), keyword()) ::
  {:ok, Layr8.Message.t()} | {:error, term()}

request_result/3 from a DID joined with join_did/3. Prefer Layr8.DidHandle.request_result/3.

@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 send_from(pid(), String.t(), Layr8.Message.t() | map(), keyword()) :: :ok

send/3 from a DID joined with join_did/3. Prefer Layr8.DidHandle.send/3.

@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.