@mercuryo-ai/magicpay-sdk 0.1.0-test.5 → 0.1.0-test.6

package/README.md

@@ -1,27 +1,46 @@
 # @mercuryo-ai/magicpay-sdk
 
-MagicPay SDK is the TypeScript and Node client for MagicPay workflow sessions and
-secret request flows. It gives a trusted runtime a consistent way to read
-session state, fetch a stored-secret catalog, create a secret request, poll for
-approval, and claim a one-time secret payload. The root package is the MagicPay
-domain surface. AgentBrowse-specific form matching and protected-fill helpers
-live in a separate `@mercuryo-ai/magicpay-sdk/agentbrowse` subpath.
+MagicPay SDK is the TypeScript and Node SDK for requesting, approving, and
+claiming stored-secret values for one protected step in a MagicPay workflow.
 
-## Install
+Use it when your application, worker, agent runtime, or MCP tool needs to:
 
-Install the MagicPay SDK:
+- load the stored-secret catalog for the current protected step;
+- create one approval request for one protected field group;
+- poll until the request is fulfilled or reaches a terminal state;
+- claim the single-use secret payload;
+- continue the surrounding session flow with typed SDK helpers.
 
-```bash
-npm i @mercuryo-ai/magicpay-sdk
-```
+MagicPay SDK focuses on the MagicPay domain flow itself. It is not a browser
+automation package. Your runtime still owns browser control, approval UX,
+orchestration, and the business action that happens after the claim succeeds.
+
+## When To Use It
+
+This package is the right entry point when:
+
+- you already know which protected step you are continuing;
+- you run trusted Node or TypeScript code;
+- you want a typed client instead of assembling raw HTTP requests yourself.
+
+Typical integrations:
 
-For AgentBrowse-based browser execution, install both packages:
+- backend services and workers;
+- MCP tools and agent backends;
+- browser automation runtimes that already know the protected target;
+- provider-specific API flows that consume a claimed payload outside the
+  browser.
+
+## Install
+
+Install the root SDK:
 
 ```bash
-npm i @mercuryo-ai/magicpay-sdk @mercuryo-ai/agentbrowse
+npm i @mercuryo-ai/magicpay-sdk
 ```
 
-## API Access
+Create your API key at
+[`agents.mercuryo.io/signup`](https://agents.mercuryo.io/signup).
 
 MagicPay API base URL:
 
@@ -29,106 +48,31 @@ MagicPay API base URL:
 https://agents-api.mercuryo.io/functions/v1/api
 ```
 
-Create an API key in your MagicPay control plane and pass both values into
-`createMagicPayClient(...)`.
+## Choose An Entrypoint
 
-## Entrypoints
+Most integrations use the root package only.
 
-| Entrypoint | Purpose |
+| Entrypoint | Use it when |
 | --- | --- |
-| `@mercuryo-ai/magicpay-sdk` | Networked MagicPay client and consumer-facing types. |
-| `@mercuryo-ai/magicpay-sdk/core` | Pure domain helpers for session state and secret request status interpretation. |
-| `@mercuryo-ai/magicpay-sdk/agentbrowse` | Bridge helpers for AgentBrowse observed forms and protected fill execution. |
-
-## Runtime Model
-
-MagicPay SDK is runtime-agnostic. The root package works with any trusted
-runtime that can create a MagicPay request input and consume a claimed secret
-payload. AgentBrowse is one browser runtime integration path. Claimed secret
-values can be consumed by browser automation, API clients, MCP tools, or custom
-agent runtimes.
-
-## Integration Modes
+| `@mercuryo-ai/magicpay-sdk` | You want the main networked client for catalog, request, poll, claim, and session helpers. |
+| `@mercuryo-ai/magicpay-sdk/core` | You want the pure domain helpers without the networked client wrapper. |
+| `@mercuryo-ai/magicpay-sdk/agentbrowse` | You already use `@mercuryo-ai/agentbrowse` and want the optional bridge from observed forms to MagicPay request and fill input. |
 
-MagicPay SDK supports two explicit integration modes.
+If your runtime already starts from observed protected forms and you want the
+optional browser bridge helpers, add AgentBrowse as well:
 
-### Mode A. Runtime-Agnostic Secret Flow
-
-Use only the root `@mercuryo-ai/magicpay-sdk` entrypoint when your runtime already
-knows how it wants to consume a claimed secret payload.
-
-In this mode you:
-
-- create or read sessions;
-- fetch catalogs;
-- create secret requests;
-- poll until approval or another terminal status;
-- claim the one-time payload;
-- hand the payload to your own browser automation, API client, MCP tool, or
-  other runtime.
-
-This mode does not require AgentBrowse imports.
-
-### Mode B. Explicit AgentBrowse Bridge
-
-Use `@mercuryo-ai/magicpay-sdk/agentbrowse` only when your runtime already uses
-`@mercuryo-ai/agentbrowse` and wants a typed bridge from observed forms to MagicPay
-request inputs and protected-fill execution.
-
-In this mode you:
-
-- observe protected forms with AgentBrowse;
-- build MagicPay request input from an observed form;
-- enrich observed forms with catalog candidates;
-- prepare protected-fill input from a fulfilled MagicPay claim.
-
-AgentBrowse stays an explicit optional dependency. The root SDK does not
-implicitly enable or require it.
-
-## Glossary
-
-| Term | Meaning |
-| --- | --- |
-| `session` | One MagicPay workflow session. |
-| `catalog` | Stored secrets available for a host inside a session. |
-| `storedSecretRef` | The saved secret you want MagicPay to provide for a request. |
-| `secret request` | A request for a one-time secret payload tied to a workflow step. |
-| `claim` | The one-time retrieval of approved secret values. |
-| `fillRef` | Stable identifier for the protected fill target tied to a request. |
-| `pageRef` | Stable identifier for the observed page that contains the fill target. |
-| `scopeRef` | Stable identifier for a protected surface inside the page. |
-
-## Main Flow
-
-```mermaid
-flowchart LR
-  A[sessionId] --> B[fetchCatalog]
-  B --> C[pick storedSecretRef]
-  C --> D{input source}
-  D -->|manual| E[build request input]
-  D -->|AgentBrowse| F[buildRequestInputForObservedForm]
-  E --> G[client.secrets.createRequest]
-  F --> G
-  G --> H[pollUntil]
-  H -->|fulfilled| I[claim]
-  H -->|denied / expired / failed / canceled| J[branch in your app]
-  I --> K{payload consumer}
-  K -->|custom runtime| L[consume secret values]
-  K -->|AgentBrowse| M[prepareProtectedFillFromClaim]
-  M --> N[fillProtectedForm]
+```bash
+npm i @mercuryo-ai/magicpay-sdk @mercuryo-ai/agentbrowse
 ```
 
 ## Quick Start
 
-### Root Client
-
-Use the root package when your runtime already knows the request context it
-wants to send to MagicPay. This is Mode A: runtime-agnostic secret flow.
+This example shows the primary root-SDK path. It assumes you already have a
+MagicPay workflow session and know which protected step you are continuing.
 
 ```ts
 import { createMagicPayClient } from '@mercuryo-ai/magicpay-sdk';
 
-// Create a networked MagicPay client for your runtime.
 const client = createMagicPayClient({
   gateway: {
     apiKey: process.env.MAGICPAY_API_KEY!,
@@ -139,10 +83,8 @@ const client = createMagicPayClient({
 const sessionId = 'sess_123';
 const pageUrl = 'https://checkout.airline.example/payment';
 
-// Load the stored-secret catalog for the current host.
 const catalog = await client.secrets.fetchCatalog(sessionId, pageUrl);
 
-// Create a request for one stored secret and the exact fields this step needs.
 const created = await client.secrets.createRequest({
   sessionId,
   clientRequestId: 'checkout-card-1',
@@ -157,104 +99,15 @@ const created = await client.secrets.createRequest({
     storedSecretRef: 'secret_card_primary',
     kind: 'payment_card',
     host: catalog.host,
-    scopeRef: 'payment_surface',
+    scopeRef: 'payment_form',
     fields: ['pan', 'exp_month', 'exp_year', 'cvv'],
   },
 });
 
-// Wait for approval or another terminal outcome.
-const ready = await client.secrets.pollUntil(sessionId, created.requestId);
-if (!ready.success) {
-  throw new Error(ready.reason);
-}
-if (ready.result.snapshot.status !== 'fulfilled') {
-  throw new Error(`Request ended as ${ready.result.snapshot.status}`);
-}
-
-// Claim the one-time secret payload after approval.
-const claim = await client.secrets.claim(sessionId, created.requestId);
-if (!claim.success) {
-  throw new Error(claim.reason);
-}
-
-// Use the claimed values in your runtime.
-console.log(claim.result.secret.values);
-```
-
-### AgentBrowse Bridge
-
-Use the AgentBrowse subpath when your runtime starts from `observe(...)` and
-then wants to request and fill a secret through MagicPay. This is Mode B:
-explicit AgentBrowse bridge.
-
-```ts
-import { act, observe } from '@mercuryo-ai/agentbrowse';
-import {
-  fillProtectedForm,
-  type ProtectedFillForm,
-} from '@mercuryo-ai/agentbrowse/protected-fill';
-import { createMagicPayClient } from '@mercuryo-ai/magicpay-sdk';
-import {
-  buildRequestInputForObservedForm,
-  enrichObservedFormsForUrl,
-  prepareProtectedFillFromClaim,
-} from '@mercuryo-ai/magicpay-sdk/agentbrowse';
-
-// Create the MagicPay client that will own the approval flow.
-const client = createMagicPayClient({
-  gateway: {
-    apiKey: process.env.MAGICPAY_API_KEY!,
-    apiUrl: 'https://agents-api.mercuryo.io/functions/v1/api',
-  },
+const ready = await client.secrets.pollUntil(sessionId, created.requestId, {
+  stopWhen: 'fulfilled',
 });
 
-const sessionId = 'sess_123';
-
-// Observe the current page and collect protected fill forms.
-const observation = await observe(browserSession, 'Find the login form');
-if (!observation.success || !observation.url || !Array.isArray(observation.fillableForms)) {
-  throw new Error('AgentBrowse did not return observed forms.');
-}
-
-const observedForms = observation.fillableForms as ProtectedFillForm[];
-
-// Load the stored-secret catalog for the observed host.
-const catalog = await client.secrets.fetchCatalog(sessionId, observation.url);
-
-// Attach catalog candidates to the observed forms.
-const enrichedForms = enrichObservedFormsForUrl(
-  observedForms,
-  { [catalog.host]: catalog },
-  observation.url
-);
-const loginForm =
-  enrichedForms.find((form) => form.purpose === 'login') ?? enrichedForms[0] ?? null;
-if (!loginForm) {
-  throw new Error('No protected fill form was observed.');
-}
-
-// Convert the observed form into a MagicPay secret request input.
-const requestInput = buildRequestInputForObservedForm({
-  sessionId,
-  merchantName: 'Airline Example',
-  storedSecretRef: 'secret_login_primary',
-  urlOrHost: observation.url,
-  catalog,
-  fillableForm: loginForm,
-  page: {
-    ref: loginForm.pageRef,
-    url: observation.url,
-    ...(observation.title ? { title: observation.title } : {}),
-  },
-});
-
-if (!requestInput.success) {
-  throw new Error(requestInput.reason);
-}
-
-// Create the approval request and wait until it is fulfilled.
-const created = await client.secrets.createRequest(requestInput.input);
-const ready = await client.secrets.pollUntil(sessionId, created.requestId);
 if (!ready.success) {
   throw new Error(ready.reason);
 }
@@ -262,165 +115,41 @@ if (ready.result.snapshot.status !== 'fulfilled') {
   throw new Error(`Request ended as ${ready.result.snapshot.status}`);
 }
 
-// Claim the one-time payload once the request is approved.
 const claim = await client.secrets.claim(sessionId, created.requestId);
 if (!claim.success) {
   throw new Error(claim.reason);
 }
 
-// Convert the claim into AgentBrowse protected-fill input.
-const prepared = prepareProtectedFillFromClaim({
-  fillableForm: loginForm,
-  catalog,
-  claim: claim.result,
-  request: created.snapshot,
-});
-
-// Fill the protected fields in the browser.
-const browserFill = await fillProtectedForm({
-  session: browserSession,
-  fillableForm: prepared.fillableForm,
-  protectedValues: prepared.protectedValues,
-  fieldPolicies: prepared.fieldPolicies,
-});
-
-if (!browserFill.success) {
-  throw new Error(browserFill.reason);
-}
-
-// Re-observe after the protected fill. The submit button is a fresh action target,
-// so reacquire it from the live page instead of guessing from older inventory.
-const submitObservation = await observe(
-  browserSession,
-  'Find the single actionable submit target that sends the filled login form.'
-);
-if (!submitObservation.success || submitObservation.targets.length === 0) {
-  throw new Error(submitObservation.reason ?? submitObservation.message);
-}
-
-// Goal-based observe narrows the inventory to the submit action we care about.
-const submitTarget = submitObservation.targets[0];
-if (!submitTarget?.ref || submitTarget.capability !== 'actionable') {
-  throw new Error('AgentBrowse did not return an actionable submit target.');
-}
-
-const submitAction = await act(browserSession, submitTarget.ref, 'click');
-if (!submitAction.success) {
-  throw new Error(submitAction.reason ?? submitAction.message);
-}
-```
-
-### Claim And Use Secrets Outside The Browser
-
-Use the claimed payload directly when your runtime wants to authenticate to an
-API, call a provider SDK, or pass a secret into an MCP tool flow.
-
-```ts
-import { createMagicPayClient } from '@mercuryo-ai/magicpay-sdk';
-
-// Create the MagicPay client for the claim step.
-const client = createMagicPayClient({
-  gateway: {
-    apiKey: process.env.MAGICPAY_API_KEY!,
-    apiUrl: 'https://agents-api.mercuryo.io/functions/v1/api',
-  },
-});
-
-// Claim the approved secret payload.
-const claim = await client.secrets.claim('sess_123', 'req_123');
-if (!claim.success) {
-  throw new Error(claim.reason);
-}
-
-// Forward the claimed values to the API you want to call.
-const response = await fetch('https://api.airline.example/login', {
-  method: 'POST',
-  headers: { 'content-type': 'application/json' },
-  body: JSON.stringify({
-    username: claim.result.secret.values.username,
-    password: claim.result.secret.values.password,
-  }),
-});
-
-if (!response.ok) {
-  throw new Error(`Provider login failed with ${response.status}`);
-}
+console.log(claim.result.secret.values);
 ```
 
-## Polling Defaults
-
-`client.secrets.pollUntil(...)` uses a conservative profile by default:
-
-- timeout: `180_000` ms
-- initial interval: `10_000` ms
-- max interval: `30_000` ms
-- backoff multiplier: `1.2`
-
-Override these values when your application needs a different approval window.
-
-## Error Reference
-
-### `buildRequestInputForObservedForm(...)`
-
-| Kind | When it happens | What to do |
-| --- | --- | --- |
-| `host_resolution_failed` | No usable host could be resolved from the page URL, host, or catalog. | Pass a valid page URL or a catalog with a host. |
-| `stored_secret_not_available` | The chosen `storedSecretRef` is not available for the observed form and host. | Fetch the catalog again or choose a different stored secret. |
-
-### `client.secrets.poll(...)` and `client.secrets.pollUntil(...)`
+The normal flow is:
 
-| Kind | When it happens | What to do |
-| --- | --- | --- |
-| `not_found` | The request ID does not exist in the session. | Recreate the request or refresh local state. |
-| `aborted` | The caller aborted the poll. | Decide whether to resume or stop. |
-| `other` | MagicPay returned another transport or backend failure. | Inspect `status`, `errorCode`, and logs. |
-| `timeout` | `pollUntil(...)` exceeded its timeout. | Continue polling later or surface a timeout to the user. |
+1. fetch the catalog for the current host
+2. create one approval request for the exact fields you need
+3. wait until the request is fulfilled
+4. claim the one-time payload
+5. hand the payload to your runtime
 
-### `client.secrets.claim(...)`
+## What Happens Next
 
-| Kind | When it happens | What to do |
-| --- | --- | --- |
-| `not_fulfilled` | The request is not approved yet. | Keep polling or ask the user to approve it. |
-| `already_claimed` | The one-time secret payload was already claimed. | Create a new secret request. |
-| `aborted` | The caller aborted the claim request. | Retry only if the application still needs the payload. |
-| `other` | MagicPay returned another transport or backend failure. | Inspect `status`, `errorCode`, and logs. |
+After the claim succeeds, your runtime decides what to do with the values:
 
-## `nextAction` Reference
+- fill a protected browser form;
+- authenticate to an external API;
+- hand the payload to another tool;
+- continue a larger workflow session.
 
-`describeSecretRequestStatus(...)` and `pollUntil(...)` return a status contract with
-`nextAction` values that are useful for orchestration:
-
-| `nextAction` | Meaning |
-| --- | --- |
-| `poll-secret` | Approval is still pending. |
-| `fill-secret` | The request is fulfilled and can be claimed. |
-| `ask-user` | A human decision or recovery step is needed. |
-| `request-secret` | Create a new request instead of continuing the current one. |
-
-## Testing
-
-Pass `fetchImpl` into `createMagicPayClient(...)` to fully control network
-responses in tests.
-
-```ts
-import { createMagicPayClient } from '@mercuryo-ai/magicpay-sdk';
-
-const client = createMagicPayClient({
-  gateway: {
-    apiKey: 'test_api_key',
-    apiUrl: 'https://agents-api.mercuryo.io/functions/v1/api',
-  },
-  fetchImpl: async (url, init = {}) => {
-    const method = (init.method ?? 'GET').toUpperCase();
-    if (method === 'GET' && String(url).includes('/secrets/catalog')) {
-      return new Response(JSON.stringify([]), {
-        status: 200,
-        headers: { 'content-type': 'application/json' },
-      });
-    }
-    throw new Error(`Unexpected ${method} ${url}`);
-  },
-});
-```
+## Continue Reading
 
-See [`docs/examples.md`](./docs/examples.md) for more complete recipes.
+- Start with [Getting Started](./docs/getting-started.md) for the first root
+  integration.
+- Read [Integration Modes](./docs/integration-modes.md) if you need help
+  choosing between the root SDK, pure helpers, and the optional AgentBrowse
+  bridge.
+- Use [API Reference](./docs/api-reference.md) and
+  [Error Reference](./docs/error-reference.md) as lookup documents while
+  integrating.
+- Use [Examples Index](./docs/examples.md) for runnable snippets.
+- Use [Glossary](./docs/glossary.md) when terms like `storedSecretRef`,
+  `fillRef`, or `scopeRef` are still new.

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "@mercuryo-ai/magicpay-sdk",
-  "version": "0.1.0-test.5",
-  "description": "Official MagicPay SDK for TypeScript and Node — session state and secret request flows",
+  "version": "0.1.0-test.6",
+  "description": "TypeScript and Node SDK for MagicPay stored-secret request, claim, and session flows",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MercuryoAI/magicpay-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MercuryoAI/magicpay-sdk/issues"
+  },
+  "homepage": "https://github.com/MercuryoAI/magicpay-sdk#readme",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -50,8 +58,7 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE.md",
-    "docs"
+    "LICENSE.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -71,14 +78,17 @@
     "@types/node": "^22.0.0",
     "typescript": "5.9.2",
     "vitest": "^4.0.18",
-    "@mercuryo-ai/agentbrowse": "0.2.52"
+    "@mercuryo-ai/agentbrowse": "0.2.53"
   },
   "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist',{ recursive: true, force: true })\" && tsc -p tsconfig.build.json",
-    "check-types": "tsc --noEmit",
-    "docs:verify": "node scripts/verify-public-docs.mjs",
+    "build:deps": "pnpm --dir ../.. --filter @mercuryo-ai/agentbrowse build",
+    "build": "npm run build:deps && node -e \"require('node:fs').rmSync('dist',{ recursive: true, force: true })\" && tsc -p tsconfig.build.json",
+    "check-types": "npm run build:deps && tsc --noEmit",
+    "docs:check-types": "npm run build && tsc -p tsconfig.examples.json --noEmit",
+    "docs:export": "node scripts/export-public-repo.mjs",
+    "docs:verify": "npm run docs:check-types && node scripts/verify-public-docs.mjs",
     "pack:verify": "node scripts/verify-pack-artifact.mjs",
     "smoke:pack-install": "node scripts/verify-pack-install-smoke.mjs",
-    "test": "vitest run"
+    "test": "npm run build:deps && vitest run"
   }
 }

package/docs/examples.md

@@ -1,432 +0,0 @@
-# Examples
-
-This document collects recipe-style examples for the current public MagicPay SDK
-surface.
-
-## Choose An Integration Mode
-
-The public SDK supports two explicit modes:
-
-- Mode A: use `@mercuryo-ai/magicpay-sdk` when your runtime can create request
-  input and consume claimed secrets on its own.
-- Mode B: use `@mercuryo-ai/magicpay-sdk/agentbrowse` only when your runtime
-  already depends on `@mercuryo-ai/agentbrowse` and needs the observed-form
-  bridge.
-
-The examples below stay grouped the same way: root-package recipes first, then
-the explicit AgentBrowse bridge.
-
-## Read Session State
-
-```ts
-import { createMagicPayClient } from '@mercuryo-ai/magicpay-sdk';
-
-// Create a networked MagicPay client.
-const client = createMagicPayClient({
-  gateway: {
-    apiKey: process.env.MAGICPAY_API_KEY!,
-    apiUrl: 'https://agents-api.mercuryo.io/functions/v1/api',
-  },
-});
-
-// Fetch the latest server-backed session envelope.
-const session = await client.sessions.get('sess_123');
-
-// Project the envelope into a simpler orchestration state.
-const state = client.sessions.describe(session);
-
-// Use the projected state for logs, UI, or control flow.
-console.log({
-  closed: state.closed,
-  approvalPending: state.approvalPending,
-  activeRequestDomain: state.activeRequest?.domain ?? null,
-});
-```
-
-## Request, Poll, And Claim
-
-```ts
-import { createMagicPayClient } from '@mercuryo-ai/magicpay-sdk';
-
-// Create a networked MagicPay client.
-const client = createMagicPayClient({
-  gateway: {
-    apiKey: process.env.MAGICPAY_API_KEY!,
-    apiUrl: 'https://agents-api.mercuryo.io/functions/v1/api',
-  },
-});
-
-const sessionId = 'sess_123';
-const pageUrl = 'https://checkout.airline.example/payment';
-
-// Load the stored-secret catalog for the current host.
-const catalog = await client.secrets.fetchCatalog(sessionId, pageUrl);
-
-// Create a request for one stored secret and the exact fields this step needs.
-const created = await client.secrets.createRequest({
-  sessionId,
-  clientRequestId: 'payment-card-1',
-  fillRef: 'checkout_card',
-  purpose: 'payment_card',
-  merchantName: 'Airline Example',
-  page: {
-    url: pageUrl,
-    title: 'Payment',
-  },
-  secretHint: {
-    storedSecretRef: 'secret_card_primary',
-    kind: 'payment_card',
-    host: catalog.host,
-    scopeRef: 'payment_surface',
-    fields: ['pan', 'exp_month', 'exp_year', 'cvv'],
-  },
-});
-
-// Wait until the request is fulfilled or another terminal status appears.
-const ready = await client.secrets.pollUntil(sessionId, created.requestId, {
-  stopWhen: 'fulfilled',
-});
-
-if (!ready.success) {
-  throw new Error(ready.reason);
-}
-if (ready.result.snapshot.status !== 'fulfilled') {
-  throw new Error(`Request ended as ${ready.result.snapshot.status}`);
-}
-
-// Claim the one-time payload after approval.
-const claim = await client.secrets.claim(sessionId, created.requestId);
-if (!claim.success) {
-  throw new Error(claim.reason);
-}
-
-// Use the claimed secret values in your runtime.
-console.log(claim.result.secret.values);
-```
-
-## Poll Until A Terminal Status
-
-```ts
-import { createMagicPayClient } from '@mercuryo-ai/magicpay-sdk';
-
-// Create a networked MagicPay client.
-const client = createMagicPayClient({
-  gateway: {
-    apiKey: process.env.MAGICPAY_API_KEY!,
-    apiUrl: 'https://agents-api.mercuryo.io/functions/v1/api',
-  },
-});
-
-// Poll until the request reaches any terminal status.
-const result = await client.secrets.pollUntil('sess_123', 'req_123', {
-  stopWhen: 'terminal',
-  timeoutMs: 180_000,
-  intervalMs: 10_000,
-  maxIntervalMs: 30_000,
-  backoffMultiplier: 1.2,
-});
-
-if (!result.success) {
-  // Transport failures and timeouts still need caller-level handling.
-  console.log(result.kind, result.reason);
-} else {
-  // Branch on the final request status.
-  switch (result.result.snapshot.status) {
-    case 'fulfilled':
-      console.log('Claim and consume the one-time secret payload.');
-      break;
-    case 'denied':
-      console.log('A user denied the request.');
-      break;
-    case 'expired':
-      console.log('Create a new request.');
-      break;
-    case 'failed':
-    case 'canceled':
-      console.log('Inspect logs or surface recovery to the caller.');
-      break;
-    default:
-      throw new Error(`Unexpected status ${result.result.snapshot.status}`);
-  }
-}
-```
-
-## AgentBrowse Observe -> Request -> Fill
-
-This example is Mode B: explicit AgentBrowse bridge.
-
-```ts
-import { act, observe } from '@mercuryo-ai/agentbrowse';
-import {
-  fillProtectedForm,
-  type ProtectedFillForm,
-} from '@mercuryo-ai/agentbrowse/protected-fill';
-import { createMagicPayClient } from '@mercuryo-ai/magicpay-sdk';
-import {
-  buildRequestInputForObservedForm,
-  enrichObservedFormsForUrl,
-  prepareProtectedFillFromClaim,
-} from '@mercuryo-ai/magicpay-sdk/agentbrowse';
-
-// Create the MagicPay client that owns the approval flow.
-const client = createMagicPayClient({
-  gateway: {
-    apiKey: process.env.MAGICPAY_API_KEY!,
-    apiUrl: 'https://agents-api.mercuryo.io/functions/v1/api',
-  },
-});
-
-const sessionId = 'sess_123';
-
-// Observe the page and collect protected fill forms.
-const observation = await observe(browserSession, 'Find the login form');
-if (!observation.success || !observation.url || !Array.isArray(observation.fillableForms)) {
-  throw new Error('AgentBrowse did not return observed forms.');
-}
-
-const forms = observation.fillableForms as ProtectedFillForm[];
-
-// Load the stored-secret catalog for the observed host.
-const catalog = await client.secrets.fetchCatalog(sessionId, observation.url);
-
-// Attach stored-secret candidates to the observed forms.
-const enrichedForms = enrichObservedFormsForUrl(forms, { [catalog.host]: catalog }, observation.url);
-const form = enrichedForms.find((candidate) => candidate.purpose === 'login') ?? enrichedForms[0] ?? null;
-if (!form) {
-  throw new Error('No observed form is available.');
-}
-
-// Build a MagicPay request input from the observed login form.
-const requestInput = buildRequestInputForObservedForm({
-  sessionId,
-  merchantName: 'Airline Example',
-  storedSecretRef: 'secret_login_primary',
-  urlOrHost: observation.url,
-  catalog,
-  fillableForm: form,
-  page: {
-    ref: form.pageRef,
-    url: observation.url,
-    ...(observation.title ? { title: observation.title } : {}),
-  },
-});
-
-if (!requestInput.success) {
-  throw new Error(requestInput.reason);
-}
-
-// Create the approval request and wait until it is fulfilled.
-const created = await client.secrets.createRequest(requestInput.input);
-const ready = await client.secrets.pollUntil(sessionId, created.requestId, {
-  stopWhen: 'fulfilled',
-});
-
-if (!ready.success) {
-  throw new Error(ready.reason);
-}
-if (ready.result.snapshot.status !== 'fulfilled') {
-  throw new Error(`Request ended as ${ready.result.snapshot.status}`);
-}
-
-// Claim the one-time payload after approval.
-const claim = await client.secrets.claim(sessionId, created.requestId);
-if (!claim.success) {
-  throw new Error(claim.reason);
-}
-
-// Convert the claim into AgentBrowse protected-fill input.
-const prepared = prepareProtectedFillFromClaim({
-  fillableForm: form,
-  catalog,
-  claim: claim.result,
-  request: created.snapshot,
-});
-
-// Fill the protected fields in the browser.
-const browserFill = await fillProtectedForm({
-  session: browserSession,
-  fillableForm: prepared.fillableForm,
-  protectedValues: prepared.protectedValues,
-  fieldPolicies: prepared.fieldPolicies,
-});
-
-if (!browserFill.success) {
-  throw new Error(browserFill.reason);
-}
-
-// Re-observe after the protected fill so the submit action comes from the live page.
-const submitObservation = await observe(
-  browserSession,
-  'Find the single actionable submit target that sends the filled login form.'
-);
-if (!submitObservation.success || submitObservation.targets.length === 0) {
-  throw new Error(submitObservation.reason ?? submitObservation.message);
-}
-
-// Goal-based observe already narrows the inventory to the submit step we need next.
-const submitTarget = submitObservation.targets[0];
-if (!submitTarget?.ref || submitTarget.capability !== 'actionable') {
-  throw new Error('AgentBrowse did not return an actionable submit target.');
-}
-
-const submitAction = await act(browserSession, submitTarget.ref, 'click');
-if (!submitAction.success) {
-  throw new Error(submitAction.reason ?? submitAction.message);
-}
-```
-
-## Claim And Call An External API
-
-```ts
-import { createMagicPayClient } from '@mercuryo-ai/magicpay-sdk';
-
-// Create the MagicPay client for the claim step.
-const client = createMagicPayClient({
-  gateway: {
-    apiKey: process.env.MAGICPAY_API_KEY!,
-    apiUrl: 'https://agents-api.mercuryo.io/functions/v1/api',
-  },
-});
-
-// Claim the approved secret payload.
-const claim = await client.secrets.claim('sess_123', 'req_123');
-if (!claim.success) {
-  throw new Error(claim.reason);
-}
-
-// Forward the claimed values to the external API call.
-const response = await fetch('https://api.airline.example/login', {
-  method: 'POST',
-  headers: { 'content-type': 'application/json' },
-  body: JSON.stringify({
-    username: claim.result.secret.values.username,
-    password: claim.result.secret.values.password,
-  }),
-});
-
-if (!response.ok) {
-  throw new Error(`Provider login failed with ${response.status}`);
-}
-```
-
-## Claim And Hand Off To An MCP Tool
-
-```ts
-import { createMagicPayClient } from '@mercuryo-ai/magicpay-sdk';
-
-// Create the MagicPay client for the claim step.
-const client = createMagicPayClient({
-  gateway: {
-    apiKey: process.env.MAGICPAY_API_KEY!,
-    apiUrl: 'https://agents-api.mercuryo.io/functions/v1/api',
-  },
-});
-
-// Claim the approved secret payload.
-const claim = await client.secrets.claim('sess_123', 'req_123');
-if (!claim.success) {
-  throw new Error(claim.reason);
-}
-
-// Repackage the claimed values for your MCP tool contract.
-const mcpInput = {
-  type: 'provider_login',
-  payload: {
-    username: claim.result.secret.values.username,
-    password: claim.result.secret.values.password,
-  },
-};
-
-console.log(mcpInput);
-```
-
-## Testing With `fetchImpl`
-
-```ts
-import { createMagicPayClient } from '@mercuryo-ai/magicpay-sdk';
-
-// Predefine the fake transport responses your test expects.
-const responses = new Map([
-  [
-    'GET https://agents-api.mercuryo.io/functions/v1/api/sessions/sess_123/secrets/catalog?host=checkout.airline.example',
-    new Response(JSON.stringify([]), {
-      status: 200,
-      headers: { 'content-type': 'application/json' },
-    }),
-  ],
-]);
-
-// Inject fetchImpl so tests never hit the real network.
-const client = createMagicPayClient({
-  gateway: {
-    apiKey: 'test_api_key',
-    apiUrl: 'https://agents-api.mercuryo.io/functions/v1/api',
-  },
-  fetchImpl: async (url, init = {}) => {
-    const method = (init.method ?? 'GET').toUpperCase();
-    const key = `${method} ${String(url)}`;
-    const response = responses.get(key);
-    if (!response) {
-      throw new Error(`Unexpected ${key}`);
-    }
-    return response;
-  },
-});
-
-// Run the SDK call against the mocked transport.
-await client.secrets.fetchCatalog('sess_123', 'https://checkout.airline.example/login');
-```
-
-## Pure Domain Helpers
-
-`@mercuryo-ai/magicpay-sdk/core` keeps the pure helpers that do not need network
-state from the client object.
-
-```ts
-import {
-  describeSecretRequestStatus,
-  evaluateSecretRequestForFill,
-  resolveSecretCatalogContext,
-} from '@mercuryo-ai/magicpay-sdk/core';
-
-// Interpret what the current request status means for orchestration.
-const status = describeSecretRequestStatus('pending', 'secret_read');
-console.log(status.nextAction);
-
-// Check whether the fulfilled request still matches the observed fill context.
-const readiness = evaluateSecretRequestForFill(
-  {
-    requestId: 'req_123',
-    fillRef: 'checkout_card',
-    requestType: 'secret_read',
-    status: 'fulfilled',
-    host: 'checkout.airline.example',
-    scopeRef: 'payment_surface',
-    createdAt: '2026-03-31T12:00:00.000Z',
-    updatedAt: '2026-03-31T12:01:00.000Z',
-  },
-  {
-    fillRef: 'checkout_card',
-    observedHost: 'checkout.airline.example',
-    observedScopeRef: 'payment_surface',
-  }
-);
-
-// Consume the readiness result inside your own orchestration layer.
-console.log(readiness.kind);
-
-// Resolve the host-specific catalog entry without creating a client.
-const context = resolveSecretCatalogContext(
-  {
-    'checkout.airline.example': {
-      host: 'checkout.airline.example',
-      syncedAt: '2026-03-31T12:00:00.000Z',
-      storedSecrets: [],
-    },
-  },
-  'https://checkout.airline.example/login'
-);
-
-// Use the resolved host and catalog in pure domain logic.
-console.log(context.host, context.catalog);
-```