@conto_finance/sdk 0.3.1 → 0.4.0

package/dist/index.mjs

@@ -1,39 +1,20 @@
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __commonJS = (cb, mod) => function __require() {
-  try {
-    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
-  } catch (e) {
-    throw mod = 0, e;
-  }
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
+import {
+  BrowserCheckoutTargetVerificationError,
+  canonicalizeBrowserCheckoutTarget,
+  createVerifiedBrowserCheckoutDriver,
+  fingerprintBrowserCheckoutTarget
+} from "./chunk-O5RAAB2U.mjs";
+import {
+  __commonJS,
+  __toESM
+} from "./chunk-B7F5QLE5.mjs";
 
 // package.json
 var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@conto_finance/sdk",
-      version: "0.3.1",
+      version: "0.4.0",
       description: "Conto SDK for AI agent payment authorization",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
@@ -43,6 +24,21 @@ var require_package = __commonJS({
           types: "./dist/index.d.ts",
           import: "./dist/index.mjs",
           require: "./dist/index.js"
+        },
+        "./playwright": {
+          types: "./dist/playwright.d.ts",
+          import: "./dist/playwright.mjs",
+          require: "./dist/playwright.js"
+        },
+        "./browserbase": {
+          types: "./dist/browserbase.d.ts",
+          import: "./dist/browserbase.mjs",
+          require: "./dist/browserbase.js"
+        },
+        "./checkout-verifier": {
+          types: "./dist/checkout-verifier.d.ts",
+          import: "./dist/checkout-verifier.mjs",
+          require: "./dist/checkout-verifier.js"
         }
       },
       publishConfig: {
@@ -55,10 +51,11 @@ var require_package = __commonJS({
         "dist"
       ],
       scripts: {
-        build: "tsup src/index.ts --format cjs,esm --dts",
-        dev: "tsup src/index.ts --format cjs,esm --dts --watch",
+        build: "tsup src/index.ts src/playwright.ts src/browserbase.ts src/checkout-verifier.ts --format cjs,esm --dts",
+        dev: "tsup src/index.ts src/playwright.ts src/browserbase.ts src/checkout-verifier.ts --format cjs,esm --dts --watch",
         lint: "tsc --noEmit",
-        "test:contract": "npm run build && node --test test/contract.test.mjs",
+        test: "npm run lint && npm run test:contract && npm run test:consumer",
+        "test:contract": "npm run build && node --test test/contract.test.mjs test/playwright.test.mjs test/browserbase.test.mjs test/checkout-verifier.test.mjs test/developer-experience.test.mjs",
         "test:consumer": "npm run build && node --test test/consumer.test.mjs",
         "verify:release": "node scripts/verify-release.mjs",
         prepublishOnly: "npm run verify:release && npm run lint && npm run test:contract && npm run test:consumer"
@@ -78,18 +75,27 @@ var require_package = __commonJS({
         url: "https://github.com/conto-finance/conto.git",
         directory: "packages/sdk"
       },
-      homepage: "https://conto.finance/docs/sdk",
+      homepage: "https://conto.finance/docs/sdk/installation",
       bugs: {
-        url: "https://github.com/conto-finance/conto/issues"
+        email: "support@conto.finance"
       },
       dependencies: {
         "@sentry/node": "^10.63.0"
       },
+      peerDependencies: {
+        "playwright-core": ">=1.50.0"
+      },
+      peerDependenciesMeta: {
+        "playwright-core": {
+          optional: true
+        }
+      },
       overrides: {
         esbuild: "0.28.1"
       },
       devDependencies: {
         "@types/node": "22.19.18",
+        "playwright-core": "1.61.0",
         tsup: "^8.5.1",
         typescript: "^5.9.3"
       }
@@ -115,7 +121,66 @@ import * as Sentry2 from "@sentry/node";
 import { randomUUID } from "crypto";
 
 // src/http.ts
+var PUBLIC_PAYMENT_REASONS = /* @__PURE__ */ new Set([
+  "The available balance is insufficient for this payment.",
+  "This payment exceeds a configured spending limit.",
+  "This recipient is not allowed by the current payment controls.",
+  "This payment is outside the permitted schedule.",
+  "The available payment budget is insufficient.",
+  "This payment does not meet the current payment controls.",
+  "This payment requires approval before it can proceed."
+]);
+function customerPaymentReasons(value) {
+  return Array.isArray(value) ? [
+    ...new Set(
+      value.filter(
+        (reason) => typeof reason === "string" && PUBLIC_PAYMENT_REASONS.has(reason)
+      )
+    )
+  ] : [];
+}
+var VALIDATION_FIELDS = /* @__PURE__ */ new Set([
+  "amount",
+  "recipientAddress",
+  "senderAddress",
+  "recipientName",
+  "purpose",
+  "category",
+  "chainId",
+  "walletId",
+  "idempotencyKey",
+  "txHash",
+  "approvalToken"
+]);
+function customerFieldErrors(body, status) {
+  if (![400, 422].includes(status) || !["VALIDATION_ERROR", "INVALID_REQUEST", "INVALID_INPUT"].includes(String(body.code)))
+    return void 0;
+  const fields = record(body.details).fields;
+  if (!Array.isArray(fields)) return void 0;
+  const names = [
+    ...new Set(
+      fields.map((item) => record(item).field).filter(
+        (field) => typeof field === "string" && VALIDATION_FIELDS.has(field)
+      )
+    )
+  ];
+  return names.length ? names.map((field) => ({
+    field,
+    message: "Check this field against the documented request schema."
+  })) : void 0;
+}
 var MAX_RETRY_DELAY_MS = 3e4;
+function assertSecureBaseUrl(baseUrl) {
+  let parsed;
+  try {
+    parsed = new URL(baseUrl);
+  } catch {
+    throw new Error(`Invalid base URL: ${baseUrl}`);
+  }
+  if (parsed.protocol !== "https:" && parsed.hostname !== "localhost" && parsed.hostname !== "127.0.0.1") {
+    throw new Error("baseUrl must use https (except for localhost)");
+  }
+}
 function abortError() {
   const error = new Error("Request aborted");
   error.name = "AbortError";
@@ -246,6 +311,7 @@ function responseErrorMetadata(response, data) {
   return {
     code,
     status: response.status,
+    fieldErrors: customerFieldErrors(body, response.status),
     requestId: safeRequestId(
       response.headers.get("x-request-id"),
       response.headers.get("x-correlation-id"),
@@ -288,12 +354,14 @@ var ContoAdmin = class {
     }
     this.orgApiKey = config.orgApiKey;
     this.baseUrl = (config.baseUrl || "https://conto.finance").replace(/\/$/, "");
+    assertSecureBaseUrl(this.baseUrl);
     this.timeout = config.timeout || 3e4;
     this.agents = new AgentsClient(this);
     this.wallets = new WalletsClient(this);
     this.cards = new AdminCardsClient(this);
     this.policies = new PoliciesClient(this);
     this.team = new TeamClient(this);
+    this.paymentRails = new PaymentRailsClient(this);
   }
   /** Make an authenticated request to the Conto API */
   async request(method, path, body) {
@@ -348,6 +416,22 @@ var ContoAdmin = class {
     }
   }
 };
+var PaymentRailsClient = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Read gate and configuration readiness without calling Stripe. */
+  async getStripeLinkCheckoutReadiness() {
+    return this.client.request("GET", "/api/stripe-link/checkout-readiness");
+  }
+  /**
+   * Ask Conto to verify that its configured Stripe credential resolves to its
+   * configured merchant account. This call never returns either identifier.
+   */
+  async verifyStripeLinkCheckoutAccount() {
+    return this.client.request("POST", "/api/stripe-link/checkout-readiness");
+  }
+};
 var AdminCardsClient = class {
   constructor(client) {
     this.client = client;
@@ -466,44 +550,55 @@ var AgentsClient = class {
   }
   /** Get a single agent by ID */
   async get(agentId) {
-    return this.client.request("GET", `/api/agents/${agentId}`);
+    return this.client.request("GET", `/api/agents/${encodeURIComponent(agentId)}`);
   }
   /** Update an agent */
   async update(agentId, input) {
     return this.client.request(
       "PATCH",
-      `/api/agents/${agentId}`,
+      `/api/agents/${encodeURIComponent(agentId)}`,
       input
     );
   }
   /** Delete an agent (soft delete) */
   async delete(agentId) {
-    return this.client.request("DELETE", `/api/agents/${agentId}`);
+    return this.client.request(
+      "DELETE",
+      `/api/agents/${encodeURIComponent(agentId)}`
+    );
   }
   /** Freeze an agent, blocking all transactions */
   async freeze(agentId, input) {
-    return this.client.request("POST", `/api/agents/${agentId}/freeze`, {
-      ...input.freezeWallets !== void 0 && { freezeWallets: input.freezeWallets }
-    });
+    return this.client.request(
+      "POST",
+      `/api/agents/${encodeURIComponent(agentId)}/freeze`,
+      {
+        ...input.freezeWallets !== void 0 && { freezeWallets: input.freezeWallets }
+      }
+    );
   }
   /** Unfreeze an agent, restoring transaction ability */
   async unfreeze(agentId, input) {
-    return this.client.request("POST", `/api/agents/${agentId}/unfreeze`, {
-      ...input.unfreezeWallets !== void 0 && { unfreezeWallets: input.unfreezeWallets }
-    });
+    return this.client.request(
+      "POST",
+      `/api/agents/${encodeURIComponent(agentId)}/unfreeze`,
+      {
+        ...input.unfreezeWallets !== void 0 && { unfreezeWallets: input.unfreezeWallets }
+      }
+    );
   }
   /** List wallets linked to an agent */
   async listWallets(agentId) {
     return this.client.request(
       "GET",
-      `/api/agents/${agentId}/wallets`
+      `/api/agents/${encodeURIComponent(agentId)}/wallets`
     );
   }
   /** Link a wallet to an agent with spending limits */
   async linkWallet(agentId, input) {
     return this.client.request(
       "POST",
-      `/api/agents/${agentId}/wallets`,
+      `/api/agents/${encodeURIComponent(agentId)}/wallets`,
       input
     );
   }
@@ -511,38 +606,45 @@ var AgentsClient = class {
   async unlinkWallet(agentId, walletId) {
     return this.client.request(
       "DELETE",
-      `/api/agents/${agentId}/wallets/${walletId}`
+      `/api/agents/${encodeURIComponent(agentId)}/wallets/${encodeURIComponent(walletId)}`
     );
   }
   /** List policies assigned to an agent */
   async listPolicies(agentId) {
     return this.client.request(
       "GET",
-      `/api/agents/${agentId}/policies`
+      `/api/agents/${encodeURIComponent(agentId)}/policies`
     );
   }
   /** Assign a policy to an agent */
   async assignPolicy(agentId, policyId) {
-    return this.client.request("POST", `/api/agents/${agentId}/policies`, {
-      policyId
-    });
+    return this.client.request(
+      "POST",
+      `/api/agents/${encodeURIComponent(agentId)}/policies`,
+      {
+        policyId
+      }
+    );
   }
   /** Unassign a policy from an agent */
   async unassignPolicy(agentId, policyId) {
     return this.client.request(
       "DELETE",
-      `/api/agents/${agentId}/policies?policyId=${policyId}`
+      `/api/agents/${encodeURIComponent(agentId)}/policies?policyId=${encodeURIComponent(policyId)}`
     );
   }
   /** List SDK keys for an agent */
   async listSdkKeys(agentId) {
-    return this.client.request("GET", `/api/agents/${agentId}/sdk-keys`);
+    return this.client.request(
+      "GET",
+      `/api/agents/${encodeURIComponent(agentId)}/sdk-keys`
+    );
   }
   /** Create an SDK key for an agent (key value is returned only once) */
   async createSdkKey(agentId, input) {
     return this.client.request(
       "POST",
-      `/api/agents/${agentId}/sdk-keys`,
+      `/api/agents/${encodeURIComponent(agentId)}/sdk-keys`,
       input
     );
   }
@@ -550,7 +652,7 @@ var AgentsClient = class {
   async revokeSdkKey(agentId, keyId) {
     return this.client.request(
       "DELETE",
-      `/api/agents/${agentId}/sdk-keys?keyId=${keyId}`
+      `/api/agents/${encodeURIComponent(agentId)}/sdk-keys?keyId=${encodeURIComponent(keyId)}`
     );
   }
 };
@@ -579,25 +681,28 @@ var WalletsClient = class {
   }
   /** Get a single wallet by ID */
   async get(walletId) {
-    return this.client.request("GET", `/api/wallets/${walletId}`);
+    return this.client.request("GET", `/api/wallets/${encodeURIComponent(walletId)}`);
   }
   /** Update a wallet */
   async update(walletId, input) {
     return this.client.request(
       "PATCH",
-      `/api/wallets/${walletId}`,
+      `/api/wallets/${encodeURIComponent(walletId)}`,
       input
     );
   }
   /** Delete a wallet (cannot delete if linked to agents) */
   async delete(walletId) {
-    return this.client.request("DELETE", `/api/wallets/${walletId}`);
+    return this.client.request(
+      "DELETE",
+      `/api/wallets/${encodeURIComponent(walletId)}`
+    );
   }
   /** Provision a wallet for onchain transactions */
   async provision(walletId) {
     return this.client.request(
       "POST",
-      `/api/wallets/${walletId}/provision`,
+      `/api/wallets/${encodeURIComponent(walletId)}/provision`,
       {}
     );
   }
@@ -605,7 +710,7 @@ var WalletsClient = class {
   async refreshBalance(walletId) {
     return this.client.request(
       "POST",
-      `/api/wallets/${walletId}/refresh-balance`,
+      `/api/wallets/${encodeURIComponent(walletId)}/refresh-balance`,
       {}
     );
   }
@@ -632,43 +737,53 @@ var PoliciesClient = class {
   }
   /** Get a single policy by ID */
   async get(policyId) {
-    return this.client.request("GET", `/api/policies/${policyId}`);
+    return this.client.request("GET", `/api/policies/${encodeURIComponent(policyId)}`);
   }
   /** Update a policy */
   async update(policyId, input) {
     return this.client.request(
       "PATCH",
-      `/api/policies/${policyId}`,
+      `/api/policies/${encodeURIComponent(policyId)}`,
       input
     );
   }
   /** Delete a policy */
   async delete(policyId) {
-    return this.client.request("DELETE", `/api/policies/${policyId}`);
+    return this.client.request(
+      "DELETE",
+      `/api/policies/${encodeURIComponent(policyId)}`
+    );
   }
   /** List rules for a policy */
   async listRules(policyId) {
-    return this.client.request("GET", `/api/policies/${policyId}/rules`);
+    return this.client.request(
+      "GET",
+      `/api/policies/${encodeURIComponent(policyId)}/rules`
+    );
   }
   /** Add a single rule to a policy */
   async addRule(policyId, rule) {
     return this.client.request(
       "POST",
-      `/api/policies/${policyId}/rules`,
+      `/api/policies/${encodeURIComponent(policyId)}/rules`,
       rule
     );
   }
   /** Add multiple rules to a policy */
   async addRules(policyId, rules) {
-    return this.client.request("POST", `/api/policies/${policyId}/rules`, {
-      rules
-    });
+    return this.client.request(
+      "POST",
+      `/api/policies/${encodeURIComponent(policyId)}/rules`,
+      {
+        rules
+      }
+    );
   }
   /** Update a single rule */
   async updateRule(policyId, ruleId, input) {
     return this.client.request(
       "PATCH",
-      `/api/policies/${policyId}/rules/${ruleId}`,
+      `/api/policies/${encodeURIComponent(policyId)}/rules/${encodeURIComponent(ruleId)}`,
       input
     );
   }
@@ -676,14 +791,51 @@ var PoliciesClient = class {
   async deleteRule(policyId, ruleId) {
     return this.client.request(
       "DELETE",
-      `/api/policies/${policyId}/rules/${ruleId}`
+      `/api/policies/${encodeURIComponent(policyId)}/rules/${encodeURIComponent(ruleId)}`
     );
   }
   /** Delete all rules for a policy */
   async deleteAllRules(policyId) {
     return this.client.request(
       "DELETE",
-      `/api/policies/${policyId}/rules`
+      `/api/policies/${encodeURIComponent(policyId)}/rules`
+    );
+  }
+  /** List the version history for a policy (newest first). */
+  async listVersions(policyId, params) {
+    const query = new URLSearchParams();
+    if (params?.limit) query.set("limit", String(params.limit));
+    if (params?.offset) query.set("offset", String(params.offset));
+    const qs = query.toString() ? `?${query.toString()}` : "";
+    return this.client.request(
+      "GET",
+      `/api/policies/${encodeURIComponent(policyId)}/versions${qs}`
+    );
+  }
+  /** Get a single version's snapshot. */
+  async getVersion(policyId, version) {
+    return this.client.request(
+      "GET",
+      `/api/policies/${encodeURIComponent(policyId)}/versions/${encodeURIComponent(version)}`
+    );
+  }
+  /** Diff two versions of a policy. */
+  async compareVersions(policyId, from, to) {
+    return this.client.request(
+      "GET",
+      `/api/policies/${encodeURIComponent(policyId)}/versions/compare?from=${encodeURIComponent(from)}&to=${encodeURIComponent(to)}`
+    );
+  }
+  /**
+   * Restore an earlier version. Appends a new ROLLED_BACK version. If the
+   * organization requires governance approval for policy changes, the API
+   * returns a pending-approval response instead of applying the rollback.
+   */
+  async rollbackVersion(policyId, version, options) {
+    return this.client.request(
+      "POST",
+      `/api/policies/${encodeURIComponent(policyId)}/versions/${encodeURIComponent(version)}/rollback`,
+      options ?? {}
     );
   }
 };
@@ -709,6 +861,19 @@ if (process.env.SENTRY_DSN) {
     enableLogs: true
   });
 }
+function isValidBrowserActionObservation(value) {
+  if (!value || typeof value !== "object") return false;
+  const observation = value;
+  if (typeof observation.reference !== "string" || !observation.reference.trim() || observation.reference.length > 255 || typeof observation.observedAt !== "string" || Number.isNaN(Date.parse(observation.observedAt)) || typeof observation.pageUrl !== "string" || observation.pageUrl.length > 2048) {
+    return false;
+  }
+  try {
+    const pageUrl = new URL(observation.pageUrl);
+    return pageUrl.protocol === "https:" && !pageUrl.username && !pageUrl.password;
+  } catch {
+    return false;
+  }
+}
 var ContoError = class extends Error {
   constructor(message, metadata) {
     super(message);
@@ -719,6 +884,8 @@ var ContoError = class extends Error {
     this.retryAfter = metadata.retryAfter;
     this.retryGuidance = metadata.retryGuidance;
     this.actionUrl = metadata.actionUrl;
+    this.fieldErrors = metadata.fieldErrors;
+    this.reasons = metadata.reasons;
   }
 };
 var ExternalCardConfirmationPendingError = class extends ContoError {
@@ -734,6 +901,20 @@ var ExternalCardConfirmationPendingError = class extends ContoError {
     this.receipt = receipt;
   }
 };
+var BrowserActionFinalizationPendingError = class extends ContoError {
+  constructor(input) {
+    super("Browser action completed but finalization is pending", {
+      code: "BROWSER_ACTION_FINALIZATION_PENDING",
+      status: 0,
+      retryGuidance: "Persist the result and observation, then retry finalizeBrowserAction with the same dispatch attempt. Do not execute the browser action again."
+    });
+    this.name = "BrowserActionFinalizationPendingError";
+    this.authorizationId = input.authorizationId;
+    this.dispatchAttemptId = input.dispatchAttemptId;
+    this.result = input.result;
+    this.observation = input.observation;
+  }
+};
 function generatedIdempotencyKey(prefix) {
   return `${prefix}_${randomUUID()}`;
 }
@@ -763,6 +944,24 @@ function withQuery(path, query) {
   const queryString = searchParams.toString();
   return queryString ? `${path}?${queryString}` : path;
 }
+function rethrowAmbiguousCommerceMutation(error, executionId, action) {
+  if (error instanceof ContoError && (error.status === 0 || error.status >= 500)) {
+    throw new ContoError(error.message, {
+      code: error.code,
+      status: error.status,
+      requestId: error.requestId,
+      retryAfter: error.retryAfter,
+      retryGuidance: action === "authorize" ? `Call getCommerceExecution(${JSON.stringify(
+        executionId
+      )}). If it is PROCESSING, treat the authorization as consumed and do not authorize or click again.` : `Call getCommerceExecution(${JSON.stringify(
+        executionId
+      )}), then refreshCommerceExecution(${JSON.stringify(
+        executionId
+      )}). Do not ${action} again until the existing execution is reconciled.`
+    });
+  }
+  throw error;
+}
 var Conto = class {
   constructor(config) {
     if (!config.apiKey) {
@@ -773,13 +972,290 @@ var Conto = class {
     }
     this.apiKey = config.apiKey;
     this.baseUrl = (config.baseUrl || "https://conto.finance").replace(/\/$/, "");
+    assertSecureBaseUrl(this.baseUrl);
     this.timeout = config.timeout || 3e4;
     this.payments = new PaymentsClient(this);
     this.cards = new CardsClient(this);
+    this.connectedCards = new ConnectedCardsClient(this);
     this.x402 = new X402Client(this);
     this.mpp = new MppClient(this);
   }
-  /** Make an authenticated request to the Giro API */
+  /**
+   * List masked Link payment methods for a session-created connection that is
+   * explicitly bound to this agent. No Link token or payment artifact is
+   * returned through the agent SDK.
+   */
+  async listStripeLinkPaymentMethods(connectionId) {
+    return this.request(
+      "GET",
+      withQuery("/api/sdk/stripe-link/payment-methods", { connectionId })
+    );
+  }
+  /**
+   * Normalize and durably revise a partial agent purchase proposal without
+   * creating a payment side effect. Missing facts return as NEEDS_CONTEXT
+   * requirements; changed writes require the exact prior revision.
+   */
+  async normalizeCommerceProposal(input) {
+    const proposalKey = input.proposalKey?.trim();
+    if (!proposalKey || proposalKey.length < 8 || proposalKey.length > 255) {
+      throw new ContoError("proposalKey must contain 8 to 255 characters", {
+        code: "INVALID_PROPOSAL_KEY",
+        status: 0
+      });
+    }
+    return this.request(
+      "POST",
+      "/api/sdk/commerce-proposals/normalize",
+      { ...input, proposalKey },
+      { idempotent: true }
+    );
+  }
+  /** Reload one durable proposal head in this agent and tenant scope. */
+  async getCommerceProposal(proposalId) {
+    return this.request(
+      "GET",
+      `/api/sdk/commerce-proposals/${encodeURIComponent(proposalId)}`
+    );
+  }
+  /**
+   * Evaluate policy and begin one exact Stripe Link commerce intent.
+   *
+   * The stable idempotency key makes transport retries safe. Reusing it with a
+   * different intent is rejected by the API.
+   */
+  async beginCommerceExecution(input) {
+    const idempotencyKey = input.idempotencyKey?.trim();
+    if (!idempotencyKey || idempotencyKey.length < 8 || idempotencyKey.length > 255) {
+      throw new ContoError("idempotencyKey must contain 8 to 255 characters", {
+        code: "INVALID_IDEMPOTENCY_KEY",
+        status: 0,
+        retryGuidance: "Generate one stable identifier per commerce intent and reuse it for retries."
+      });
+    }
+    return this.request(
+      "POST",
+      input.executionMethod === "AGENT_CHECKOUT" || input.executionMethod === "BROWSER_CHECKOUT" ? "/api/sdk/checkout-guard/executions" : "/api/sdk/commerce-executions",
+      {
+        ..."connectionId" in input ? {
+          connectionId: input.connectionId,
+          paymentMethodId: input.paymentMethodId
+        } : {},
+        ..."browserSessionId" in input ? {
+          browserSessionId: input.browserSessionId,
+          action: input.action
+        } : {},
+        executionMethod: input.executionMethod ?? "MPP",
+        idempotencyKey,
+        intentId: input.intentId,
+        amountMinor: input.amountMinor,
+        currency: input.currency,
+        purpose: input.purpose,
+        category: input.category,
+        counterparty: input.counterparty,
+        cart: input.cart,
+        providerPresentation: input.providerPresentation
+      },
+      { idempotent: true }
+    );
+  }
+  /** Atomically consume the Conto authorization for one exact browser action. */
+  async authorizeCheckoutAction(executionId, browserSessionId, action) {
+    try {
+      return await this.request(
+        "POST",
+        `/api/sdk/commerce-executions/${encodeURIComponent(executionId)}/authorize-action`,
+        { browserSessionId, action }
+      );
+    } catch (error) {
+      rethrowAmbiguousCommerceMutation(error, executionId, "authorize");
+    }
+  }
+  /** Claim a durable browser action for one stable privileged-runtime attempt. */
+  async claimBrowserAction(authorizationId, dispatchAttemptId, browserSessionId, action) {
+    return this.request(
+      "POST",
+      `/api/sdk/browser-actions/${encodeURIComponent(authorizationId)}/claim`,
+      { dispatchAttemptId, browserSessionId, action },
+      { idempotent: true }
+    );
+  }
+  /** Finalize the exact dispatch attempt; this never performs the browser side effect. */
+  async finalizeBrowserAction(authorizationId, input) {
+    return this.request(
+      "POST",
+      `/api/sdk/browser-actions/${encodeURIComponent(authorizationId)}/finalize`,
+      input,
+      { idempotent: true }
+    );
+  }
+  /**
+   * Own the complete privileged-browser enforcement sequence. The stable
+   * dispatchAttemptId must be persisted by the runtime before this call.
+   */
+  async runGuardedCheckout(input, runtime) {
+    const begun = await this.beginCommerceExecution(input);
+    if (!["READY", "PROCESSING"].includes(begun.execution.status)) {
+      throw new ContoError("Checkout action is not ready", {
+        code: "COMMERCE_EXECUTION_NOT_READY",
+        status: 409
+      });
+    }
+    const authorized = await this.authorizeCheckoutAction(
+      begun.execution.id,
+      input.browserSessionId,
+      input.action
+    );
+    await this.claimBrowserAction(
+      authorized.authorization.authorizationId,
+      runtime.dispatchAttemptId,
+      input.browserSessionId,
+      input.action
+    );
+    let dispatched;
+    try {
+      dispatched = await runtime.execute(authorized.authorization);
+    } catch (error) {
+      try {
+        await this.finalizeBrowserAction(authorized.authorization.authorizationId, {
+          dispatchAttemptId: runtime.dispatchAttemptId,
+          outcome: "INDETERMINATE"
+        });
+      } catch {
+        throw new ContoError("Browser action failed and its final state is indeterminate", {
+          code: "BROWSER_ACTION_DISPATCH_INDETERMINATE",
+          status: 0,
+          retryGuidance: "Do not execute the browser action again. Reconcile the merchant page or payment provider before taking another action."
+        });
+      }
+      throw error;
+    }
+    if (!dispatched || !isValidBrowserActionObservation(dispatched.observation)) {
+      try {
+        await this.finalizeBrowserAction(authorized.authorization.authorizationId, {
+          dispatchAttemptId: runtime.dispatchAttemptId,
+          outcome: "INDETERMINATE"
+        });
+      } catch {
+      }
+      throw new ContoError("Privileged browser executor returned an invalid observation", {
+        code: "BROWSER_ACTION_OBSERVATION_INVALID",
+        status: 0,
+        retryGuidance: "Do not execute the browser action again. Reconcile the merchant page, then record a valid observation or resolve the indeterminate attempt."
+      });
+    }
+    try {
+      await this.finalizeBrowserAction(authorized.authorization.authorizationId, {
+        dispatchAttemptId: runtime.dispatchAttemptId,
+        outcome: "CONSUMED",
+        observation: dispatched.observation
+      });
+    } catch {
+      throw new BrowserActionFinalizationPendingError({
+        authorizationId: authorized.authorization.authorizationId,
+        dispatchAttemptId: runtime.dispatchAttemptId,
+        result: dispatched.result,
+        observation: dispatched.observation
+      });
+    }
+    return {
+      ...authorized,
+      dispatchAttemptId: runtime.dispatchAttemptId,
+      result: dispatched.result,
+      observation: dispatched.observation
+    };
+  }
+  /**
+   * Reference privileged-driver integration. Only this wrapper should be
+   * exposed as the agent's payment-sensitive browser tool.
+   */
+  async runGuardedCheckoutWithDriver(input, runtime) {
+    return this.runGuardedCheckout(input, {
+      dispatchAttemptId: runtime.dispatchAttemptId,
+      execute: (authorization) => runtime.driver.dispatch({
+        authorization,
+        browserSessionId: input.browserSessionId,
+        action: input.action
+      })
+    });
+  }
+  /**
+   * Policy-check and authorize an exact action before invoking a legacy callback.
+   * @deprecated Use runGuardedCheckout so the durable claim and final
+   * observation cannot be omitted.
+   */
+  async guardCheckout(input, executor) {
+    const begun = await this.beginCommerceExecution(input);
+    if (begun.execution.status !== "READY") {
+      throw new ContoError("Checkout action is not ready", {
+        code: "COMMERCE_EXECUTION_NOT_READY",
+        status: 409
+      });
+    }
+    const authorized = await this.authorizeCheckoutAction(
+      begun.execution.id,
+      input.browserSessionId,
+      input.action
+    );
+    const result = await executor(authorized.authorization);
+    return { ...authorized, result };
+  }
+  /** Read one agent-scoped commerce execution and its normalized evidence. */
+  async getCommerceExecution(executionId) {
+    return this.request(
+      "GET",
+      `/api/sdk/commerce-executions/${encodeURIComponent(executionId)}`
+    );
+  }
+  /**
+   * Observe Link state and reconcile terminal accounting. This operation is
+   * safe to retry because it does not request another checkout execution.
+   */
+  async refreshCommerceExecution(executionId) {
+    return this.request(
+      "POST",
+      `/api/sdk/commerce-executions/${encodeURIComponent(executionId)}/refresh`,
+      {},
+      { idempotent: true }
+    );
+  }
+  /**
+   * Execute the approved provider-direct or server-only checkout handoff. Transport retries are
+   * deliberately disabled. Read or refresh the execution after an ambiguous
+   * failure before taking another execution action.
+   */
+  async executeCommerceExecution(executionId) {
+    try {
+      return await this.request(
+        "POST",
+        `/api/sdk/commerce-executions/${encodeURIComponent(executionId)}/execute`,
+        {}
+      );
+    } catch (error) {
+      rethrowAmbiguousCommerceMutation(error, executionId, "execute");
+    }
+  }
+  /**
+   * Request cancellation and release reserved spend after Link confirms it.
+   * Transport retries are disabled because a lost provider response requires
+   * reconciliation.
+   */
+  async cancelCommerceExecution(executionId) {
+    try {
+      return await this.request(
+        "POST",
+        `/api/sdk/commerce-executions/${encodeURIComponent(executionId)}/cancel`,
+        {}
+      );
+    } catch (error) {
+      rethrowAmbiguousCommerceMutation(error, executionId, "cancel");
+    }
+  }
+  /** Read credentials, linked wallets, effective policies, and scopes without creating a payment. */
+  async setup() {
+    return this.request("GET", "/api/sdk/setup");
+  }
+  /** Make an authenticated request to the Conto API */
   async request(method, path, body, options = {}) {
     const url = `${this.baseUrl}${path}`;
     const controller = new AbortController();
@@ -900,7 +1376,8 @@ var ControlledExternalCardPaymentTool = class {
     this.executor = executor;
   }
   async pay(input) {
-    const approval = await this.cardsClient.approve(input);
+    const idempotencyKey = input.idempotencyKey.trim();
+    const approval = await this.cardsClient.approve({ ...input, idempotencyKey });
     if (!approval.approved || !approval.approvalToken) {
       const executionAlreadyClaimed = approval.decision === "EXECUTING" || approval.decision === "CONFIRMING";
       throw new ContoError("External card payment was not approved", {
@@ -933,6 +1410,7 @@ var ControlledExternalCardPaymentTool = class {
     try {
       execution = await this.executor({
         requestId: approval.requestId,
+        idempotencyKey,
         cardId: input.cardId,
         amount: input.amount,
         currency: input.currency || "USD",
@@ -957,7 +1435,7 @@ var ControlledExternalCardPaymentTool = class {
       Sentry2.captureException(outcomeError, {
         extra: {
           requestId: approval.requestId,
-          executorError: error instanceof Error ? error.message : String(error)
+          executorErrorName: error instanceof Error ? error.name : typeof error
         }
       });
       throw outcomeError;
@@ -981,7 +1459,7 @@ var ControlledExternalCardPaymentTool = class {
       Sentry2.captureException(pending, {
         extra: {
           requestId: approval.requestId,
-          confirmationError: error instanceof Error ? error.message : String(error)
+          confirmationErrorName: error instanceof Error ? error.name : typeof error
         }
       });
       throw pending;
@@ -993,10 +1471,101 @@ var ControlledExternalCardPaymentTool = class {
     };
   }
 };
+var ConnectedCardsClient = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Draw one single-use card credential against a verified mandate.
+   *
+   * On an APPROVED, minted draw the result carries live card material in
+   * `credential`, returned exactly ONCE.
+   *
+   * CREDENTIAL SAFETY (load-bearing): the credential is the real, usable card.
+   * It is revealed a single time and cannot be re-fetched. Use it in-process at
+   * the intended merchant checkout only. Never log, print, serialize, persist,
+   * cache, or forward it, and never place it in an error, a monitoring event,
+   * or any other sink. See {@link ConnectedCardCredential}.
+   *
+   * Transport-level retry is deliberately OFF for this call. The server is
+   * idempotent on `idempotencyKey`, so an automatic retry after a successful
+   * mint would replay the draw and return the decision WITHOUT the credential,
+   * silently losing the one-shot card material. If a `draw` fails ambiguously,
+   * do not blindly retry: check the outcome, and reuse the same
+   * `idempotencyKey` only to reconcile the same draw.
+   *
+   * @example
+   * ```typescript
+   * const draw = await conto.connectedCards.draw({
+   *   cardId: 'cmm59z8fj000l49h7bjqza11p',
+   *   mandateId: 'cmm5a1b2c000m49h7defgh22q',
+   *   idempotencyKey: 'checkout_01J8...',
+   *   amountMinor: 4999,
+   *   merchant: { merchantName: 'Example Store', merchantCategory: '5311' },
+   * });
+   * if (draw.decision === 'APPROVED' && draw.credential) {
+   *   // Keep the credential in memory, acknowledge receipt, then use it at checkout.
+   *   await conto.connectedCards.acknowledgeDelivery(draw.requestId);
+   *   // Do not log or store draw.credential.
+   * }
+   * ```
+   */
+  async draw(input) {
+    const idempotencyKey = input.idempotencyKey?.trim();
+    if (!idempotencyKey || idempotencyKey.length < 8 || idempotencyKey.length > 128) {
+      throw new ContoError("idempotencyKey must contain 8 to 128 characters", {
+        code: "INVALID_IDEMPOTENCY_KEY",
+        status: 0,
+        retryGuidance: "Generate one stable identifier per draw and reuse it only to reconcile the same draw."
+      });
+    }
+    return this.client.request("POST", "/api/sdk/connected-cards/draws", {
+      ...input,
+      idempotencyKey,
+      currency: input.currency ?? "USD"
+    });
+  }
+  /**
+   * List the connected cards and active mandates this agent may draw against.
+   *
+   * The response is masked: no PAN and no provider tokens. This is a read-only
+   * GET, so transport retry on transient failures is safe.
+   */
+  /** Record receipt after a fresh draw. Does not confirm checkout or payment settlement. */
+  async acknowledgeDelivery(requestId) {
+    return this.client.request(
+      "POST",
+      `/api/sdk/connected-cards/draws/${encodeURIComponent(requestId)}/acknowledge`,
+      {},
+      { idempotent: true }
+    );
+  }
+  async list() {
+    return this.client.request("GET", "/api/sdk/connected-cards");
+  }
+};
 var PaymentsClient = class {
   constructor(client) {
     this.client = client;
   }
+  /** Authorize an externally signed transfer. This write is not automatically retried. */
+  async approve(input) {
+    return this.client.request(
+      "POST",
+      "/api/sdk/payments/approve",
+      { ...input },
+      { maxRetries: 0 }
+    );
+  }
+  /** Record an existing transfer. Never sends funds; reconcile conflicts using status(). */
+  async confirm(requestId, input) {
+    return this.client.request(
+      "POST",
+      `/api/sdk/payments/${encodeURIComponent(requestId)}/confirm`,
+      { ...input },
+      { maxRetries: 0 }
+    );
+  }
   /**
    * Request authorization for a payment.
    *
@@ -1026,6 +1595,13 @@ var PaymentsClient = class {
    * ```
    */
   async request(input) {
+    if (typeof input.amount !== "number" || !Number.isFinite(input.amount) || input.amount <= 0) {
+      throw new ContoError("amount must be a positive finite number", {
+        code: "INVALID_AMOUNT",
+        status: 0,
+        retryGuidance: "Provide a positive amount before requesting a payment."
+      });
+    }
     const requestInput = {
       ...input,
       idempotencyKey: input.idempotencyKey ?? generatedIdempotencyKey("conto_payment")
@@ -1093,7 +1669,7 @@ var PaymentsClient = class {
   async status(requestId) {
     return this.client.request(
       "GET",
-      `/api/sdk/payments/${requestId}`,
+      `/api/sdk/payments/${encodeURIComponent(requestId)}`,
       void 0
     );
   }
@@ -1130,6 +1706,7 @@ var PaymentsClient = class {
       throw new ContoError("Payment was denied.", {
         code: "PAYMENT_DENIED",
         status: 403,
+        reasons: customerPaymentReasons(request.reasons),
         requestId: request.requestId,
         retryGuidance: "Review the payment request before trying again."
       });
@@ -1147,6 +1724,7 @@ var PaymentsClient = class {
         code: "ACTION_REQUIRED",
         status: 402,
         requestId: request.requestId,
+        actionUrl: request.actionUrl,
         retryGuidance: request.actionUrl ? `Complete the required action at ${request.actionUrl}, then check the payment status.` : "Complete the required action, then check the payment status."
       });
     }
@@ -1247,7 +1825,10 @@ var MppClient = class {
 };
 var index_default = Conto;
 export {
+  BrowserActionFinalizationPendingError,
+  BrowserCheckoutTargetVerificationError,
   CardsClient,
+  ConnectedCardsClient,
   Conto,
   ContoAdmin,
   ContoAdminError,
@@ -1255,5 +1836,8 @@ export {
   ControlledExternalCardPaymentTool,
   ExternalCardConfirmationPendingError,
   Conto as Giro,
-  index_default as default
+  canonicalizeBrowserCheckoutTarget,
+  createVerifiedBrowserCheckoutDriver,
+  index_default as default,
+  fingerprintBrowserCheckoutTarget
 };