@mercuryo-ai/magicpay-sdk 0.1.0-test.2

package/docs/examples.md

@@ -0,0 +1,432 @@
+# 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);
+```

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@mercuryo-ai/magicpay-sdk",
+  "version": "0.1.0-test.2",
+  "description": "Official MagicPay SDK for TypeScript and Node — session state and secret request flows",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js"
+    },
+    "./agentbrowse": {
+      "types": "./dist/agentbrowse.d.ts",
+      "import": "./dist/agentbrowse.js"
+    },
+    "./gateway": {
+      "types": "./dist/gateway.d.ts",
+      "import": "./dist/gateway.js"
+    },
+    "./request-flow": {
+      "types": "./dist/request-flow.d.ts",
+      "import": "./dist/request-flow.js"
+    },
+    "./secret-flow": {
+      "types": "./dist/secret-flow.d.ts",
+      "import": "./dist/secret-flow.js"
+    },
+    "./session-client": {
+      "types": "./dist/session-client.d.ts",
+      "import": "./dist/session-client.js"
+    },
+    "./session-flow": {
+      "types": "./dist/session-flow.d.ts",
+      "import": "./dist/session-flow.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nuanu-ai/mercuryo-agent-pay.git",
+    "directory": "packages/magicpay-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/nuanu-ai/mercuryo-agent-pay/issues"
+  },
+  "homepage": "https://github.com/nuanu-ai/mercuryo-agent-pay/tree/main/packages/magicpay-sdk",
+  "keywords": [
+    "magicpay",
+    "sdk",
+    "payments",
+    "sessions",
+    "agent-payments"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md",
+    "docs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@mercuryo-ai/agentbrowse": "^0.2.50"
+  },
+  "peerDependenciesMeta": {
+    "@mercuryo-ai/agentbrowse": {
+      "optional": true
+    }
+  },
+  "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",
+    "pack:verify": "node scripts/verify-pack-artifact.mjs",
+    "prepack": "npm run build",
+    "smoke:pack-install": "node scripts/verify-pack-install-smoke.mjs",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@mercuryo-ai/agentbrowse": "workspace:*",
+    "@types/node": "^22.0.0",
+    "typescript": "5.9.2",
+    "vitest": "^4.0.18"
+  }
+}