@conto_finance/sdk 0.1.0 → 0.3.1

package/dist/index.mjs

@@ -33,7 +33,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@conto_finance/sdk",
-      version: "0.1.0",
+      version: "0.3.1",
       description: "Conto SDK for AI agent payment authorization",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
@@ -49,7 +49,7 @@ var require_package = __commonJS({
         access: "public"
       },
       engines: {
-        node: ">=18"
+        node: ">=20.19.0"
       },
       files: [
         "dist"
@@ -58,7 +58,10 @@ var require_package = __commonJS({
         build: "tsup src/index.ts --format cjs,esm --dts",
         dev: "tsup src/index.ts --format cjs,esm --dts --watch",
         lint: "tsc --noEmit",
-        prepublishOnly: "npm run build"
+        "test:contract": "npm run build && node --test test/contract.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",
@@ -80,13 +83,13 @@ var require_package = __commonJS({
         url: "https://github.com/conto-finance/conto/issues"
       },
       dependencies: {
-        "@sentry/node": "^10.56.0"
+        "@sentry/node": "^10.63.0"
       },
       overrides: {
         esbuild: "0.28.1"
       },
       devDependencies: {
-        "@types/node": "^22.19.18",
+        "@types/node": "22.19.18",
         tsup: "^8.5.1",
         typescript: "^5.9.3"
       }
@@ -109,10 +112,165 @@ var require_package_version = __commonJS({
 // src/index.ts
 var import_package_version2 = __toESM(require_package_version());
 import * as Sentry2 from "@sentry/node";
+import { randomUUID } from "crypto";
+
+// src/http.ts
+var MAX_RETRY_DELAY_MS = 3e4;
+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,
+    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/admin.ts
 var import_package_version = __toESM(require_package_version());
 import * as Sentry from "@sentry/node";
+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) {
@@ -133,74 +291,157 @@ var ContoAdmin = class {
     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");
-  }
   /** 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 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;
@@ -241,19 +482,15 @@ var AgentsClient = class {
   }
   /** Freeze an agent, blocking all transactions */
   async freeze(agentId, input) {
-    return this.client.request(
-      "POST",
-      `/api/agents/${agentId}/freeze`,
-      input
-    );
+    return this.client.request("POST", `/api/agents/${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
-    );
+    return this.client.request("POST", `/api/agents/${agentId}/unfreeze`, {
+      ...input.unfreezeWallets !== void 0 && { unfreezeWallets: input.unfreezeWallets }
+    });
   }
   /** List wallets linked to an agent */
   async listWallets(agentId) {
@@ -285,10 +522,9 @@ var AgentsClient = class {
     );
   }
   /** Assign a policy to an agent */
-  async assignPolicy(agentId, policyId, overrides) {
+  async assignPolicy(agentId, policyId) {
     return this.client.request("POST", `/api/agents/${agentId}/policies`, {
-      policyId,
-      ...overrides && { overrides }
+      policyId
     });
   }
   /** Unassign a policy from an agent */
@@ -333,7 +569,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",
@@ -473,6 +709,60 @@ if (process.env.SENTRY_DSN) {
     enableLogs: true
   });
 }
+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;
+  }
+};
+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;
+  }
+};
+function generatedIdempotencyKey(prefix) {
+  return `${prefix}_${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;
+}
 var Conto = class {
   constructor(config) {
     if (!config.apiKey) {
@@ -485,70 +775,222 @@ var Conto = class {
     this.baseUrl = (config.baseUrl || "https://conto.finance").replace(/\/$/, "");
     this.timeout = config.timeout || 3e4;
     this.payments = new PaymentsClient(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.cards = new CardsClient(this);
+    this.x402 = new X402Client(this);
+    this.mpp = new MppClient(this);
   }
   /** Make an authenticated request to the Giro API */
-  async request(method, path, body) {
+  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 approval = await this.cardsClient.approve(input);
+    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,
+        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,
+          executorError: error instanceof Error ? error.message : String(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,
+          confirmationError: error instanceof Error ? error.message : String(error)
+        }
+      });
+      throw pending;
+    }
+    return {
+      approval,
+      confirmation,
+      receipt: execution.receipt
+    };
   }
 };
 var PaymentsClient = class {
@@ -584,10 +1026,15 @@ var PaymentsClient = class {
    * ```
    */
   async request(input) {
+    const requestInput = {
+      ...input,
+      idempotencyKey: input.idempotencyKey ?? generatedIdempotencyKey("conto_payment")
+    };
     return this.client.request(
       "POST",
       "/api/sdk/payments/request",
-      input
+      requestInput,
+      { idempotent: true }
     );
   }
   /**
@@ -601,16 +1048,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.
@@ -620,8 +1085,8 @@ 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);
    * }
    * ```
    */
@@ -646,7 +1111,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');
@@ -660,24 +1127,133 @@ 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,
+        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,
+        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;
 export {
+  CardsClient,
   Conto,
   ContoAdmin,
+  ContoAdminError,
+  ContoError,
+  ControlledExternalCardPaymentTool,
+  ExternalCardConfirmationPendingError,
   Conto as Giro,
   index_default as default
 };