@conto_finance/sdk 0.1.0 → 0.4.0

package/dist/index.js

@@ -39,7 +39,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@conto_finance/sdk",
-      version: "0.1.0",
+      version: "0.4.0",
       description: "Conto SDK for AI agent payment authorization",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
@@ -49,22 +49,41 @@ 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: {
         access: "public"
       },
       engines: {
-        node: ">=18"
+        node: ">=20.19.0"
       },
       files: [
         "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",
-        prepublishOnly: "npm run build"
+        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"
       },
       keywords: [
         "conto",
@@ -81,18 +100,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.56.0"
+        "@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",
+        "@types/node": "22.19.18",
+        "playwright-core": "1.61.0",
         tsup: "^8.5.1",
         typescript: "^5.9.3"
       }
@@ -115,18 +143,361 @@ var require_package_version = __commonJS({
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BrowserActionFinalizationPendingError: () => BrowserActionFinalizationPendingError,
+  BrowserCheckoutTargetVerificationError: () => BrowserCheckoutTargetVerificationError,
+  CardsClient: () => CardsClient,
+  ConnectedCardsClient: () => ConnectedCardsClient,
   Conto: () => Conto,
   ContoAdmin: () => ContoAdmin,
+  ContoAdminError: () => ContoAdminError,
+  ContoError: () => ContoError,
+  ControlledExternalCardPaymentTool: () => ControlledExternalCardPaymentTool,
+  ExternalCardConfirmationPendingError: () => ExternalCardConfirmationPendingError,
   Giro: () => Conto,
-  default: () => index_default
+  canonicalizeBrowserCheckoutTarget: () => canonicalizeBrowserCheckoutTarget,
+  createVerifiedBrowserCheckoutDriver: () => createVerifiedBrowserCheckoutDriver,
+  default: () => index_default,
+  fingerprintBrowserCheckoutTarget: () => fingerprintBrowserCheckoutTarget
 });
 module.exports = __toCommonJS(index_exports);
 var Sentry2 = __toESM(require("@sentry/node"));
+var import_node_crypto2 = require("crypto");
 var import_package_version2 = __toESM(require_package_version());
 
+// 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";
+  return error;
+}
+function wait(ms, signal) {
+  if (signal?.aborted) return Promise.reject(abortError());
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timeout);
+      reject(abortError());
+    };
+    const timeout = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function parseRetryAfter(value) {
+  if (!value) return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.ceil(seconds);
+  const date = Date.parse(value);
+  if (!Number.isFinite(date)) return void 0;
+  return Math.max(0, Math.ceil((date - Date.now()) / 1e3));
+}
+function retryDelayMs(response, attempt) {
+  const retryAfter = parseRetryAfter(response.headers.get("retry-after"));
+  if (retryAfter !== void 0) {
+    return Math.min(retryAfter * 1e3, MAX_RETRY_DELAY_MS);
+  }
+  return Math.min(1e3 * 2 ** attempt, 1e4);
+}
+async function fetchWithRetry(url, options, policy) {
+  const maxRetries = policy.maxRetries ?? 3;
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const response = await fetch(url, options);
+      const transient = response.status === 429 || response.status >= 500;
+      if (policy.retryable && transient && attempt < maxRetries) {
+        await wait(retryDelayMs(response, attempt), options.signal);
+        continue;
+      }
+      return response;
+    } catch (error) {
+      const normalized = error instanceof Error ? error : new Error(String(error));
+      if (normalized.name === "AbortError" || options.signal?.aborted) throw normalized;
+      lastError = normalized;
+      if (!policy.retryable || attempt >= maxRetries) throw normalized;
+      await wait(Math.min(1e3 * 2 ** attempt, 1e4), options.signal);
+    }
+  }
+  throw lastError ?? new Error("Request failed after retries");
+}
+async function readResponseData(response) {
+  if (typeof response.text !== "function") return response.json();
+  const text = await response.text();
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { error: text };
+  }
+}
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function fallbackCode(status) {
+  if (status === 400 || status === 422) return "INVALID_REQUEST";
+  if (status === 401) return "AUTH_FAILED";
+  if (status === 403) return "FORBIDDEN";
+  if (status === 404) return "NOT_FOUND";
+  if (status === 409) return "CONFLICT";
+  if (status === 429) return "RATE_LIMITED";
+  if (status >= 500) return "SERVER_ERROR";
+  return "REQUEST_FAILED";
+}
+function safeErrorCode(value, status) {
+  return typeof value === "string" && /^[A-Z][A-Z0-9_]{0,63}$/.test(value) ? value : fallbackCode(status);
+}
+function safeRequestId(...values) {
+  return values.find(
+    (value) => typeof value === "string" && value.length > 0 && value.length <= 200 && /^[A-Za-z0-9._:@/-]+$/.test(value)
+  );
+}
+function safeActionUrl(value, code) {
+  if (code !== "ACTION_REQUIRED" || typeof value !== "string" || value.length > 2048) {
+    return void 0;
+  }
+  if (value.startsWith("/") && !value.startsWith("//")) return value;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function safeErrorMessage(status) {
+  if (status === 400 || status === 422) return "The request was invalid.";
+  if (status === 401) return "Authentication failed.";
+  if (status === 403) return "The request is not permitted.";
+  if (status === 404) return "The requested resource was not found.";
+  if (status === 409) return "The request conflicts with the current resource state.";
+  if (status === 429) return "Too many requests.";
+  if (status >= 500) return "The service is temporarily unavailable.";
+  return "The request could not be completed.";
+}
+function fallbackRetryGuidance(status) {
+  if (status === 400 || status === 422) return "Review the request before trying again.";
+  if (status === 401) return "Verify the API key and that it is intended for this client.";
+  if (status === 403) return "Verify credentials and permissions before trying again.";
+  if (status === 404) return "Verify the resource identifier before trying again.";
+  if (status === 409) return "Check the current resource state before trying again.";
+  if (status === 429) return "Wait for retryAfter seconds before retrying.";
+  if (status >= 500)
+    return "Retry only if this operation is read-only or protected by idempotency.";
+  return void 0;
+}
+function responseErrorMessage(_data, status) {
+  return safeErrorMessage(status);
+}
+function responseErrorMetadata(response, data) {
+  const body = record(data);
+  const code = safeErrorCode(body.code, response.status);
+  const bodyRetryAfter = typeof body.retryAfter === "number" || typeof body.retryAfter === "string" ? parseRetryAfter(String(body.retryAfter)) : void 0;
+  return {
+    code,
+    status: response.status,
+    fieldErrors: customerFieldErrors(body, response.status),
+    requestId: safeRequestId(
+      response.headers.get("x-request-id"),
+      response.headers.get("x-correlation-id"),
+      body.requestId
+    ),
+    retryAfter: parseRetryAfter(response.headers.get("retry-after")) ?? bodyRetryAfter,
+    retryGuidance: fallbackRetryGuidance(response.status),
+    actionUrl: safeActionUrl(body.actionUrl, code)
+  };
+}
+
+// src/browser-checkout.ts
+var import_node_crypto = require("crypto");
+var MAX_URL_LENGTH = 2048;
+var MAX_LOCATOR_LENGTH = 1024;
+var MAX_TEXT_LENGTH = 500;
+var BrowserCheckoutTargetVerificationError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "BrowserCheckoutTargetVerificationError";
+  }
+};
+function invalid(message) {
+  throw new BrowserCheckoutTargetVerificationError("BROWSER_CHECKOUT_TARGET_INVALID", message);
+}
+function canonicalHttpsUrl(value, field) {
+  if (typeof value !== "string" || !value || value.length > MAX_URL_LENGTH) {
+    invalid(`${field} is invalid.`);
+  }
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    invalid(`${field} is invalid.`);
+  }
+  if (url.protocol !== "https:" || url.username || url.password) {
+    invalid(`${field} must use HTTPS without credentials.`);
+  }
+  url.hostname = url.hostname.toLowerCase();
+  url.hash = "";
+  return url.toString();
+}
+function canonicalText(value, field, options = {}) {
+  if (value === void 0) {
+    if (options.required) invalid(`${field} is required.`);
+    return null;
+  }
+  if (typeof value !== "string") invalid(`${field} is invalid.`);
+  const trimmed = value.trim();
+  const normalized = options.collapseWhitespace === false ? trimmed : trimmed.replace(/\s+/g, " ");
+  if (options.required && !normalized || normalized.length > (options.maxLength ?? MAX_TEXT_LENGTH)) {
+    invalid(`${field} is invalid.`);
+  }
+  return normalized || null;
+}
+function canonicalizeBrowserCheckoutTarget(snapshot) {
+  if (!snapshot || typeof snapshot !== "object") {
+    invalid("The browser checkout target is invalid.");
+  }
+  if (typeof snapshot.disabled !== "boolean") {
+    invalid("target.disabled is invalid.");
+  }
+  const tagName = canonicalText(snapshot.tagName, "target.tagName", {
+    required: true,
+    maxLength: 80
+  });
+  return Object.freeze({
+    pageUrl: canonicalHttpsUrl(snapshot.pageUrl, "target.pageUrl"),
+    locator: canonicalText(snapshot.locator, "target.locator", {
+      collapseWhitespace: false,
+      required: true,
+      maxLength: MAX_LOCATOR_LENGTH
+    }) ?? "",
+    tagName: (tagName ?? "").toLowerCase(),
+    role: canonicalText(snapshot.role, "target.role", { maxLength: 80 })?.toLowerCase() ?? null,
+    accessibleName: canonicalText(snapshot.accessibleName, "target.accessibleName"),
+    targetUrl: snapshot.targetUrl ? canonicalHttpsUrl(snapshot.targetUrl, "target.targetUrl") : null,
+    formAction: snapshot.formAction ? canonicalHttpsUrl(snapshot.formAction, "target.formAction") : null,
+    opensNewPage: snapshot.opensNewPage === true,
+    disabled: snapshot.disabled
+  });
+}
+function fingerprintBrowserCheckoutTarget(snapshot) {
+  const canonical = canonicalizeBrowserCheckoutTarget(snapshot);
+  const digest = (0, import_node_crypto.createHash)("sha256").update(JSON.stringify(canonical)).digest("hex");
+  return `browser_target_sha256_${digest}`;
+}
+function createVerifiedBrowserCheckoutDriver(resolver) {
+  if (!resolver || typeof resolver.resolve !== "function") {
+    invalid("A browser checkout target resolver is required.");
+  }
+  return Object.freeze({
+    async dispatch(input) {
+      const target = await resolver.resolve(input);
+      if (!target) {
+        throw new BrowserCheckoutTargetVerificationError(
+          "BROWSER_CHECKOUT_TARGET_NOT_FOUND",
+          "The approved browser checkout target was not found."
+        );
+      }
+      if (typeof target.dispatch !== "function") {
+        invalid("The resolved browser checkout target cannot be dispatched.");
+      }
+      const canonical = canonicalizeBrowserCheckoutTarget(target.snapshot);
+      const approvedPageUrl = canonicalHttpsUrl(input.action.pageUrl, "action.pageUrl");
+      const approvedTargetUrl = input.action.targetUrl ? canonicalHttpsUrl(input.action.targetUrl, "action.targetUrl") : null;
+      const observedDestinations = [canonical.targetUrl, canonical.formAction].filter(
+        (value) => value !== null
+      );
+      const destinationsAreBound = approvedTargetUrl === null ? observedDestinations.length === 0 : observedDestinations.length > 0 && observedDestinations.every((value) => value === approvedTargetUrl);
+      if (canonical.pageUrl !== approvedPageUrl || !destinationsAreBound || fingerprintBrowserCheckoutTarget(target.snapshot) !== input.action.targetFingerprint.trim()) {
+        throw new BrowserCheckoutTargetVerificationError(
+          "BROWSER_CHECKOUT_TARGET_CHANGED",
+          "The browser checkout target changed after Conto authorization."
+        );
+      }
+      if (canonical.disabled) {
+        throw new BrowserCheckoutTargetVerificationError(
+          "BROWSER_CHECKOUT_TARGET_DISABLED",
+          "The approved browser checkout target is disabled."
+        );
+      }
+      return target.dispatch();
+    }
+  });
+}
+
 // src/admin.ts
 var Sentry = __toESM(require("@sentry/node"));
 var import_package_version = __toESM(require_package_version());
+var ContoAdminError = class extends Error {
+  constructor(message, metadata) {
+    super(message);
+    this.name = "ContoAdminError";
+    this.code = metadata.code;
+    this.status = metadata.status;
+    this.requestId = metadata.requestId;
+    this.retryAfter = metadata.retryAfter;
+    this.retryGuidance = metadata.retryGuidance;
+  }
+};
 var ContoAdmin = class {
   constructor(config) {
     if (!config.orgApiKey) {
@@ -144,77 +515,178 @@ 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);
-  }
-  async fetchWithRetry(url, options, maxRetries = 3) {
-    let lastError = null;
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
-      try {
-        const response = await fetch(url, options);
-        if (response.status === 429 || response.status >= 500 && attempt < maxRetries) {
-          const retryAfter = response.headers.get("retry-after");
-          const delay = retryAfter ? parseInt(retryAfter, 10) * 1e3 : Math.min(1e3 * 2 ** attempt, 1e4);
-          await new Promise((resolve) => setTimeout(resolve, delay));
-          continue;
-        }
-        return response;
-      } catch (err) {
-        lastError = err instanceof Error ? err : new Error(String(err));
-        if (attempt < maxRetries) {
-          const delay = Math.min(1e3 * 2 ** attempt, 1e4);
-          await new Promise((resolve) => setTimeout(resolve, delay));
-          continue;
-        }
-      }
-    }
-    throw lastError || new Error("Request failed after retries");
+    this.paymentRails = new PaymentRailsClient(this);
   }
   /** Make an authenticated request to the Conto API */
   async request(method, path, body) {
     const url = `${this.baseUrl}${path}`;
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    const normalizedMethod = method.toUpperCase();
+    const retryable = ["GET", "HEAD", "OPTIONS"].includes(normalizedMethod);
     try {
-      const response = await this.fetchWithRetry(url, {
-        method,
-        headers: {
-          Authorization: `Bearer ${this.orgApiKey}`,
-          "Content-Type": "application/json",
-          "User-Agent": `@conto_finance/sdk-admin/${import_package_version.SDK_PACKAGE_VERSION}`
+      const response = await fetchWithRetry(
+        url,
+        {
+          method: normalizedMethod,
+          headers: {
+            Authorization: `Bearer ${this.orgApiKey}`,
+            "Content-Type": "application/json",
+            "User-Agent": `@conto_finance/sdk-admin/${import_package_version.SDK_PACKAGE_VERSION}`
+          },
+          body: body ? JSON.stringify(body) : void 0,
+          signal: controller.signal
         },
-        body: body ? JSON.stringify(body) : void 0,
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      const data = await response.json();
+        { retryable }
+      );
+      const data = await readResponseData(response);
       if (!response.ok) {
-        const errorMessage = typeof data.error === "string" ? data.error : "Request failed";
-        const error = new Error(errorMessage);
-        error.code = typeof data.code === "string" ? data.code : "UNKNOWN_ERROR";
-        error.status = response.status;
-        throw error;
+        throw new ContoAdminError(
+          responseErrorMessage(data, response.status),
+          responseErrorMetadata(response, data)
+        );
       }
       return data;
     } catch (error) {
-      clearTimeout(timeoutId);
+      if (error instanceof ContoAdminError) throw error;
       if (error instanceof Error && error.name === "AbortError") {
-        const timeoutError = new Error("Request timeout");
-        timeoutError.code = "TIMEOUT";
-        timeoutError.status = 0;
+        const timeoutError = new ContoAdminError("Request timeout", {
+          code: "TIMEOUT",
+          status: 0,
+          retryGuidance: retryable ? "The request is safe to retry." : "Do not retry automatically; inspect the resource before trying again."
+        });
         Sentry.captureException(timeoutError, { extra: { method, path } });
         throw timeoutError;
       }
-      if (error instanceof Error) {
-        Sentry.captureException(error, { extra: { method, path } });
-      }
-      throw error;
+      const networkError = new ContoAdminError("Network request failed", {
+        code: "NETWORK_ERROR",
+        status: 0,
+        retryGuidance: retryable ? "The request is safe to retry." : "Do not retry automatically; inspect the resource before trying again."
+      });
+      Sentry.captureException(networkError, { extra: { method, path } });
+      throw networkError;
+    } finally {
+      clearTimeout(timeoutId);
     }
   }
 };
+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;
+  }
+  /** List masked external-card aliases. No card credentials are returned. */
+  async list() {
+    return this.client.request("GET", "/api/external-cards");
+  }
+  /** Register a masked alias for a customer card. Never pass PAN or CVC. */
+  async register(input) {
+    return this.client.request(
+      "POST",
+      "/api/external-cards",
+      input
+    );
+  }
+  /** Assign a card alias and cooperative policy controls to an agent. */
+  async assignToAgent(agentId, input) {
+    return this.client.request(
+      "POST",
+      `/api/agents/${encodeURIComponent(agentId)}/external-cards`,
+      input
+    );
+  }
+  async listForAgent(agentId) {
+    return this.client.request("GET", `/api/agents/${encodeURIComponent(agentId)}/external-cards`);
+  }
+  /** Update limits, merchant rules, hours, and optional start or end dates. */
+  async updateAgentAssignment(agentId, cardId, input) {
+    return this.client.request(
+      "PATCH",
+      `/api/agents/${encodeURIComponent(agentId)}/external-cards/${encodeURIComponent(cardId)}`,
+      { action: "UPDATE", ...input }
+    );
+  }
+  /** Pause an assignment and cancel its unused approvals. */
+  async pauseForAgent(agentId, cardId) {
+    return this.client.request(
+      "PATCH",
+      `/api/agents/${encodeURIComponent(agentId)}/external-cards/${encodeURIComponent(cardId)}`,
+      { action: "PAUSE" }
+    );
+  }
+  /** Resume a paused assignment when its alias and date range permit it. */
+  async resumeForAgent(agentId, cardId) {
+    return this.client.request(
+      "PATCH",
+      `/api/agents/${encodeURIComponent(agentId)}/external-cards/${encodeURIComponent(cardId)}`,
+      { action: "RESUME" }
+    );
+  }
+  /**
+   * Revoke an agent's overlay assignment. Unused grants are cancelled; claimed
+   * executions remain visible for reconciliation.
+   */
+  async revokeFromAgent(agentId, cardId) {
+    return this.client.request(
+      "DELETE",
+      `/api/agents/${encodeURIComponent(agentId)}/external-cards/${encodeURIComponent(cardId)}`
+    );
+  }
+  /** List overlay requests, including executions that need receipt reconciliation. */
+  async listRequests(input = {}) {
+    const query = new URLSearchParams();
+    if (input.status) query.set("status", input.status);
+    if (input.limit !== void 0) query.set("limit", String(input.limit));
+    const suffix = query.toString();
+    return this.client.request("GET", `/api/external-cards/requests${suffix ? `?${suffix}` : ""}`);
+  }
+  /**
+   * Resolve a claimed execution after checking the customer's processor or
+   * receipt. Resolving NOT_EXECUTED releases the reserved policy amount.
+   */
+  async resolveRequest(requestId, input) {
+    return this.client.request(
+      "POST",
+      `/api/external-cards/requests/${encodeURIComponent(requestId)}/resolve`,
+      input
+    );
+  }
+  /** Pause the Conto-controlled path and revoke live overlay grants. */
+  async pause(cardId) {
+    return this.setState(cardId, "PAUSED");
+  }
+  /** Resume the Conto-controlled path. This does not activate a card at its issuer. */
+  async resume(cardId) {
+    return this.setState(cardId, "ACTIVE");
+  }
+  async setState(cardId, state) {
+    return this.client.request("PATCH", `/api/external-cards/${encodeURIComponent(cardId)}/state`, {
+      state
+    });
+  }
+};
 var AgentsClient = class {
   constructor(client) {
     this.client = client;
@@ -239,48 +711,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
+      `/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
+      `/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
     );
   }
@@ -288,39 +767,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, overrides) {
-    return this.client.request("POST", `/api/agents/${agentId}/policies`, {
-      policyId,
-      ...overrides && { overrides }
-    });
+  async assignPolicy(agentId, 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
     );
   }
@@ -328,7 +813,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)}`
     );
   }
 };
@@ -347,7 +832,7 @@ var WalletsClient = class {
     const qs = query.toString() ? `?${query.toString()}` : "";
     return this.client.request("GET", `/api/wallets${qs}`);
   }
-  /** Create a new wallet or attach an existing provider/self-custodied wallet */
+  /** Create a managed wallet or register an external address. */
   async create(input) {
     return this.client.request(
       "POST",
@@ -357,25 +842,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`,
       {}
     );
   }
@@ -383,7 +871,7 @@ var WalletsClient = class {
   async refreshBalance(walletId) {
     return this.client.request(
       "POST",
-      `/api/wallets/${walletId}/refresh-balance`,
+      `/api/wallets/${encodeURIComponent(walletId)}/refresh-balance`,
       {}
     );
   }
@@ -410,43 +898,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
     );
   }
@@ -454,14 +952,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 ?? {}
     );
   }
 };
@@ -487,6 +1022,107 @@ 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);
+    this.name = "ContoError";
+    this.code = metadata.code;
+    this.status = metadata.status;
+    this.requestId = metadata.requestId;
+    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 {
+  constructor(requestId, confirmationInput, receipt) {
+    super("External card execution completed but confirmation is pending", {
+      code: "CARD_CONFIRMATION_PENDING",
+      status: 0,
+      requestId,
+      retryGuidance: "Persist the receipt and confirmation input, then retry cards.confirm(). Do not execute the card payment again."
+    });
+    this.name = "ExternalCardConfirmationPendingError";
+    this.confirmationInput = confirmationInput;
+    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}_${(0, import_node_crypto2.randomUUID)()}`;
+}
+function requireFinancialIdentifier(value, field) {
+  if (!value || value.trim().length === 0) {
+    throw new ContoError(`${field} is required for this financial write`, {
+      code: "IDEMPOTENCY_KEY_REQUIRED",
+      status: 0,
+      retryGuidance: `Generate a stable unique ${field} and reuse it when reconciling or retrying this operation.`
+    });
+  }
+  if (value.length > 255) {
+    throw new ContoError(`${field} must be 255 characters or fewer`, {
+      code: "INVALID_IDEMPOTENCY_KEY",
+      status: 0
+    });
+  }
+  return value;
+}
+function withQuery(path, query) {
+  if (!query) return path;
+  const searchParams = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === void 0 || value === null || value === "") continue;
+    searchParams.set(key, String(value));
+  }
+  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) {
@@ -497,78 +1133,600 @@ 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);
   }
-  async fetchWithRetry(url, options, maxRetries = 3) {
-    let lastError = null;
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+  /**
+   * 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 {
-        const response = await fetch(url, options);
-        if (response.status === 429 || response.status >= 500 && attempt < maxRetries) {
-          const retryAfter = response.headers.get("retry-after");
-          const delay = retryAfter ? parseInt(retryAfter, 10) * 1e3 : Math.min(1e3 * 2 ** attempt, 1e4);
-          await new Promise((resolve) => setTimeout(resolve, delay));
-          continue;
-        }
-        return response;
-      } catch (err) {
-        lastError = err instanceof Error ? err : new Error(String(err));
-        if (attempt < maxRetries) {
-          const delay = Math.min(1e3 * 2 ** attempt, 1e4);
-          await new Promise((resolve) => setTimeout(resolve, delay));
-          continue;
-        }
+        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;
     }
-    throw lastError || new Error("Request failed after retries");
+    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
+    };
   }
-  /** Make an authenticated request to the Giro API */
-  async request(method, path, body) {
+  /**
+   * 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();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    const normalizedMethod = method.toUpperCase();
+    const retryable = options.idempotent === true || ["GET", "HEAD", "OPTIONS"].includes(normalizedMethod);
     try {
-      const response = await this.fetchWithRetry(url, {
-        method,
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          "Content-Type": "application/json",
-          "User-Agent": `@conto_finance/sdk/${import_package_version2.SDK_PACKAGE_VERSION}`
+      const response = await fetchWithRetry(
+        url,
+        {
+          method: normalizedMethod,
+          headers: {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+            "User-Agent": `@conto_finance/sdk/${import_package_version2.SDK_PACKAGE_VERSION}`
+          },
+          body: body ? JSON.stringify(body) : void 0,
+          signal: controller.signal
         },
-        body: body ? JSON.stringify(body) : void 0,
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      const data = await response.json();
+        { retryable, maxRetries: options.maxRetries }
+      );
+      const data = await readResponseData(response);
       if (!response.ok) {
-        const errorMessage = typeof data.error === "string" ? data.error : "Request failed";
-        const error = new Error(errorMessage);
-        error.code = typeof data.code === "string" ? data.code : "UNKNOWN_ERROR";
-        error.status = response.status;
-        throw error;
+        throw new ContoError(
+          responseErrorMessage(data, response.status),
+          responseErrorMetadata(response, data)
+        );
       }
       return data;
     } catch (error) {
-      clearTimeout(timeoutId);
+      if (error instanceof ContoError) throw error;
       if (error instanceof Error && error.name === "AbortError") {
-        const timeoutError = new Error("Request timeout");
-        timeoutError.code = "TIMEOUT";
-        timeoutError.status = 0;
+        const timeoutError = new ContoError("Request timeout", {
+          code: "TIMEOUT",
+          status: 0,
+          retryGuidance: retryable ? "The request is safe to retry." : "Do not retry automatically; check operation status before trying again."
+        });
         Sentry2.captureException(timeoutError, { extra: { method, path } });
         throw timeoutError;
       }
-      if (error instanceof Error) {
-        Sentry2.captureException(error, { extra: { method, path } });
-      }
-      throw error;
+      const networkError = new ContoError("Network request failed", {
+        code: "NETWORK_ERROR",
+        status: 0,
+        retryGuidance: retryable ? "The request is safe to retry." : "Do not retry automatically; check operation status before trying again."
+      });
+      Sentry2.captureException(networkError, { extra: { method, path } });
+      throw networkError;
+    } finally {
+      clearTimeout(timeoutId);
     }
   }
 };
+var CardsClient = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async approve(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 purchase intent and reuse it for retries."
+      });
+    }
+    return this.client.request(
+      "POST",
+      "/api/sdk/external-cards/approve",
+      {
+        ...input,
+        idempotencyKey,
+        currency: input.currency || "USD"
+      },
+      { idempotent: true }
+    );
+  }
+  async confirm(requestId, input) {
+    return this.client.request(
+      "POST",
+      `/api/sdk/external-cards/${encodeURIComponent(requestId)}/confirm`,
+      input,
+      { idempotent: true }
+    );
+  }
+  /**
+   * Atomically claim the approved intent before customer code accesses or uses
+   * the card credential. A request can be claimed only once.
+   */
+  async begin(requestId, input) {
+    return this.client.request(
+      "POST",
+      `/api/sdk/external-cards/${encodeURIComponent(requestId)}/begin`,
+      input,
+      { idempotent: true }
+    );
+  }
+  /** Read execution and reconciliation state without exposing card credentials. */
+  async status(requestId) {
+    return this.client.request(
+      "GET",
+      `/api/sdk/external-cards/${encodeURIComponent(requestId)}`
+    );
+  }
+  /**
+   * Create a reference payment tool whose executor callback is unreachable
+   * until Conto has returned a live approval grant.
+   *
+   * @deprecated Use the separate `@conto_finance/card-access` product package for
+   * customer-hosted card enforcement. This helper remains for compatibility.
+   */
+  controlled(executor) {
+    return new ControlledExternalCardPaymentTool(this, executor);
+  }
+};
+var ControlledExternalCardPaymentTool = class {
+  constructor(cardsClient, executor) {
+    this.cardsClient = cardsClient;
+    this.executor = executor;
+  }
+  async pay(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", {
+        code: executionAlreadyClaimed ? "CARD_EXECUTION_RECONCILIATION_REQUIRED" : approval.decision === "COMPLETED" ? "CARD_PAYMENT_ALREADY_COMPLETED" : approval.decision === "REQUIRES_APPROVAL" ? "REQUIRES_APPROVAL" : "CARD_PAYMENT_DENIED",
+        status: executionAlreadyClaimed || approval.decision === "COMPLETED" ? 409 : approval.decision === "REQUIRES_APPROVAL" ? 202 : 403,
+        requestId: approval.requestId,
+        retryGuidance: executionAlreadyClaimed ? "Do not execute the payment again. Check cards.status() and confirm or reconcile the existing request." : approval.decision === "COMPLETED" ? "The purchase intent is already complete. Use cards.status() to read its transaction." : approval.decision === "REQUIRES_APPROVAL" ? "Wait for review; do not access or use the card credential." : "Review the purchase intent; do not access or use the card credential."
+      });
+    }
+    if (!approval.expiresAt || Date.parse(approval.expiresAt) <= Date.now()) {
+      throw new ContoError("External card approval has expired", {
+        code: "CARD_APPROVAL_EXPIRED",
+        status: 400,
+        requestId: approval.requestId,
+        retryGuidance: "Request a new approval before accessing or using the card credential."
+      });
+    }
+    const claim = await this.cardsClient.begin(approval.requestId, {
+      approvalToken: approval.approvalToken
+    });
+    if (!claim.claimed) {
+      throw new ContoError("External card execution was already claimed", {
+        code: "CARD_EXECUTION_RECONCILIATION_REQUIRED",
+        status: 409,
+        requestId: approval.requestId,
+        retryGuidance: "Do not execute the payment again. Check cards.status() and confirm or reconcile the existing request."
+      });
+    }
+    let execution;
+    try {
+      execution = await this.executor({
+        requestId: approval.requestId,
+        idempotencyKey,
+        cardId: input.cardId,
+        amount: input.amount,
+        currency: input.currency || "USD",
+        merchantName: input.merchantName,
+        merchantId: input.merchantId,
+        merchantCategory: input.merchantCategory,
+        merchantAddress: input.merchantAddress,
+        merchantCountry: input.merchantCountry,
+        purpose: input.purpose,
+        context: input.context
+      });
+    } catch (error) {
+      const outcomeError = new ContoError(
+        "External card executor failed after execution was claimed",
+        {
+          code: "CARD_EXECUTION_OUTCOME_UNKNOWN",
+          status: 0,
+          requestId: approval.requestId,
+          retryGuidance: "Do not execute the payment again. Verify the customer card outcome, then reconcile this request."
+        }
+      );
+      Sentry2.captureException(outcomeError, {
+        extra: {
+          requestId: approval.requestId,
+          executorErrorName: error instanceof Error ? error.name : typeof error
+        }
+      });
+      throw outcomeError;
+    }
+    const confirmationInput = {
+      approvalToken: approval.approvalToken,
+      externalTxId: execution.externalTxId,
+      authorizationCode: execution.authorizationCode,
+      actualAmount: execution.actualAmount,
+      merchantDetails: execution.merchantDetails
+    };
+    let confirmation;
+    try {
+      confirmation = await this.cardsClient.confirm(approval.requestId, confirmationInput);
+    } catch (error) {
+      const pending = new ExternalCardConfirmationPendingError(
+        approval.requestId,
+        confirmationInput,
+        execution.receipt
+      );
+      Sentry2.captureException(pending, {
+        extra: {
+          requestId: approval.requestId,
+          confirmationErrorName: error instanceof Error ? error.name : typeof error
+        }
+      });
+      throw pending;
+    }
+    return {
+      approval,
+      confirmation,
+      receipt: execution.receipt
+    };
+  }
+};
+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.
    *
@@ -598,10 +1756,22 @@ 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")
+    };
     return this.client.request(
       "POST",
       "/api/sdk/payments/request",
-      input
+      requestInput,
+      { idempotent: true }
     );
   }
   /**
@@ -615,16 +1785,34 @@ var PaymentsClient = class {
    * @example
    * ```typescript
    * const result = await conto.payments.execute(request.requestId);
-   * console.log(`Transaction: ${result.txHash}`);
-   * console.log(`Explorer: ${result.explorerUrl}`);
+   * console.log(`Status: ${result.status}`);
+   * console.log(`Conto transaction: ${result.receipt.transactionId}`);
+   * console.log(`Settlement mode: ${result.receipt.settlementMode}`);
+   * console.log(`Transaction: ${result.receipt.txHash}`);
+   * if (result.receipt.explorerUrl) console.log(`Explorer: ${result.receipt.explorerUrl}`);
    * ```
    */
   async execute(requestId) {
-    return this.client.request(
-      "POST",
-      `/api/sdk/payments/${requestId}/execute`,
-      {}
-    );
+    try {
+      return await this.client.request(
+        "POST",
+        `/api/sdk/payments/${encodeURIComponent(requestId)}/execute`,
+        {}
+      );
+    } catch (error) {
+      if (error instanceof ContoError && error.status === 0) {
+        throw new ContoError(error.message, {
+          code: error.code,
+          status: error.status,
+          requestId: error.requestId,
+          retryAfter: error.retryAfter,
+          retryGuidance: `Check payments.status(${JSON.stringify(
+            requestId
+          )}) before attempting execution again.`
+        });
+      }
+      throw error;
+    }
   }
   /**
    * Get the status of a payment request.
@@ -634,15 +1822,15 @@ var PaymentsClient = class {
    * @example
    * ```typescript
    * const status = await conto.payments.status(requestId);
-   * if (status.transaction?.status === 'CONFIRMED') {
-   *   console.log('Payment confirmed at block', status.transaction.blockNumber);
+   * if (status.transaction?.status === 'completed') {
+   *   console.log('Payment confirmed', status.transaction.txHash);
    * }
    * ```
    */
   async status(requestId) {
     return this.client.request(
       "GET",
-      `/api/sdk/payments/${requestId}`,
+      `/api/sdk/payments/${encodeURIComponent(requestId)}`,
       void 0
     );
   }
@@ -660,7 +1848,9 @@ var PaymentsClient = class {
    *     recipientAddress: '0x...',
    *     purpose: 'Service fee'
    *   });
-   *   console.log(`Paid! TX: ${result.txHash}`);
+   *   console.log(`Payment status: ${result.status}`);
+   *   console.log(`Conto transaction: ${result.receipt.transactionId}`);
+   *   console.log(`Transaction: ${result.receipt.txHash}`);
    * } catch (error) {
    *   if (error.code === 'REQUIRES_APPROVAL') {
    *     console.log('Payment needs human approval');
@@ -674,24 +1864,141 @@ var PaymentsClient = class {
     const { autoExecute: _autoExecute, ...requestInput } = input;
     const request = await this.request(requestInput);
     if (request.status === "DENIED") {
-      const error = new Error(`Payment denied: ${request.reasons.join(", ")}`);
-      error.code = "PAYMENT_DENIED";
-      error.status = 403;
-      throw error;
+      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."
+      });
     }
     if (request.status === "REQUIRES_APPROVAL") {
-      const error = new Error("Payment requires manual approval");
-      error.code = "REQUIRES_APPROVAL";
-      error.status = 202;
-      throw error;
+      throw new ContoError("Payment requires manual approval", {
+        code: "REQUIRES_APPROVAL",
+        status: 202,
+        requestId: request.requestId,
+        retryGuidance: "Wait for approval, then execute the same request ID."
+      });
+    }
+    if (request.status === "ACTION_REQUIRED") {
+      throw new ContoError("Payment requires an additional action", {
+        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."
+      });
+    }
+    if (request.status === "PROCESSING") {
+      throw new ContoError("Payment is processing", {
+        code: "PAYMENT_PROCESSING",
+        status: 202,
+        requestId: request.requestId,
+        retryGuidance: "Check the payment status before taking another payment action."
+      });
     }
     return this.execute(request.requestId);
   }
 };
+var X402Client = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async preAuthorize(input) {
+    return this.client.request(
+      "POST",
+      "/api/sdk/x402/pre-authorize",
+      input,
+      { idempotent: true }
+    );
+  }
+  async record(input) {
+    const paymentId = requireFinancialIdentifier(input.paymentId, "paymentId");
+    const requestInput = {
+      ...input,
+      paymentId
+    };
+    return this.client.request(
+      "POST",
+      "/api/sdk/x402/record",
+      requestInput
+    );
+  }
+  async budget(options) {
+    return this.client.request(
+      "GET",
+      withQuery("/api/sdk/x402/budget", { sessionId: options?.sessionId }),
+      void 0
+    );
+  }
+  async services(options) {
+    return this.client.request(
+      "GET",
+      withQuery("/api/sdk/x402/services", {
+        period: options?.period,
+        limit: options?.limit
+      }),
+      void 0
+    );
+  }
+};
+var MppClient = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async preAuthorize(input) {
+    return this.client.request(
+      "POST",
+      "/api/sdk/mpp/pre-authorize",
+      input,
+      { idempotent: true }
+    );
+  }
+  async record(input) {
+    const credentialId = requireFinancialIdentifier(input.credentialId, "credentialId");
+    const requestInput = {
+      ...input,
+      credentialId
+    };
+    return this.client.request(
+      "POST",
+      "/api/sdk/mpp/record",
+      requestInput
+    );
+  }
+  async budget(options) {
+    return this.client.request(
+      "GET",
+      withQuery("/api/sdk/mpp/budget", { sessionId: options?.sessionId }),
+      void 0
+    );
+  }
+  async services(options) {
+    return this.client.request(
+      "GET",
+      withQuery("/api/sdk/mpp/services", {
+        period: options?.period,
+        limit: options?.limit
+      }),
+      void 0
+    );
+  }
+};
 var index_default = Conto;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BrowserActionFinalizationPendingError,
+  BrowserCheckoutTargetVerificationError,
+  CardsClient,
+  ConnectedCardsClient,
   Conto,
   ContoAdmin,
-  Giro
+  ContoAdminError,
+  ContoError,
+  ControlledExternalCardPaymentTool,
+  ExternalCardConfirmationPendingError,
+  Giro,
+  canonicalizeBrowserCheckoutTarget,
+  createVerifiedBrowserCheckoutDriver,
+  fingerprintBrowserCheckoutTarget
 });