@conto_finance/sdk 0.5.0 → 0.5.2

package/README.md

@@ -1,7 +1,7 @@
 # @conto_finance/sdk
 
 Conto is a buyer-side control layer. Integrate it in the agent owner's runtime or payment tools;
-the owner or budget holder sets policy before the agent pays. Merchants do not install Conto.
+the owner or budget holder sets policy before the agent pays.
 See [buyer-side control](https://conto.finance/docs/guides/buyer-side-control) for the authorization
 and execution boundary.
 
@@ -99,35 +99,10 @@ await admin.cards.resumeForAgent('agent_id', card.id);
 await admin.cards.revokeFromAgent('agent_id', card.id);
 ```
 
-The policy overlay stops at approval, claiming, and reconciliation. For a
-customer-hosted payment tool that gates access to customer payment code, use the
-separate
-[`@conto_finance/card-access`](https://conto.finance/docs/card-access/overview) product
-package.
-
-```typescript
-import { ContoCardAccess } from '@conto_finance/card-access';
-
-const cardAccess = new ContoCardAccess({
-  policy: conto.cards,
-  integrationId: 'procurement-agent-production',
-  deployment: {
-    credentialCustody: 'CUSTOMER',
-    agentHasRawCredentialAccess: false,
-    uncontrolledAgentPaymentPath: false,
-  },
-  executor: customerHostedExecutor,
-});
-```
-
-Card Access claims each approved request exactly once before the executor can run. A
-duplicate or uncertain claim cannot invoke the executor again. It remains
-bypassable if another person or tool can access the card, and results are
-self-reported rather than issuer-verified. The executor receives the normalized
-purchase `idempotencyKey`; pass it to the payment processor so ambiguous
-processor responses cannot create duplicate charges. The legacy `conto.cards.controlled()`
-helper remains available for compatibility, but new customer-hosted enforcement
-should use the standalone Card Access package. Use
+The policy overlay stops at approval, claiming, and reconciliation. For
+connected cards, see
+[Connected cards](https://conto.finance/docs/guides/connected-cards).
+The legacy `conto.cards.controlled()` helper remains available for compatibility. Use
 `admin.cards.listRequests({ status: 'EXECUTING' })` for reconciliation and
 `admin.cards.pause(card.id)` to revoke unclaimed grants and stop new approvals
 in the Conto-controlled path.
@@ -276,7 +251,7 @@ requirements.
 For browser checkouts on supported rails (Link, card, Shop Pay, or PayPal), use
 `runGuardedCheckout` with `executionMethod: 'BROWSER_CHECKOUT'`. Other rails and checkout flows are
 not covered. It binds and atomically authorizes one exact Link, card,
-Shop Pay, or PayPal browser action without requiring merchant or private provider integration. The
+Shop Pay, or PayPal browser action without requiring private provider integration. The
 privileged browser executor must be available only through this wrapper; an unrestricted click or
 payment tool would bypass the control. Persist its stable dispatch attempt before calling the helper; it owns authorization,
 one-use claim, the privileged callback, and finalization. See `docs/AGENT_CHECKOUT_GUARD.md` for the

package/dist/browserbase.d.mts

@@ -130,12 +130,23 @@ declare class BrowserbaseSessionError extends Error {
     readonly code: BrowserbaseSessionErrorCode;
     constructor(code: BrowserbaseSessionErrorCode, message: string);
 }
+interface BrowserbaseSessionManager {
+    createSession(): Promise<BrowserbaseOwnedSession>;
+    attachSession(input: BrowserbaseSessionHandoff): Promise<BrowserbaseAttachedSession>;
+    connectUrlForSession(browserSessionId: string): Promise<string | null>;
+    liveViewForSession(browserSessionId: string): Promise<BrowserbaseOwnedLiveView>;
+    revokeSession(browserSessionId: string, lifecycleOwner: BrowserbaseSessionLifecycleOwner): Promise<boolean>;
+    releaseProviderSession(browserSessionId: string): Promise<void>;
+    releaseContextLease(browserSessionId: string): Promise<boolean>;
+}
 /** Creates a short-lived assertion after the trusted agent host creates its Browserbase session. */
 declare function createBrowserbaseSessionHandoffAssertion(input: BrowserbaseSessionHandoffAssertionInput, keyValue: Uint8Array): string;
+/** Server-only capability. Never expose connect URLs or this manager as agent tools. */
+declare function createBrowserbaseSessionManager(config: BrowserbaseSessionConfig): BrowserbaseSessionManager;
 /**
  * Creates the recommended Browserbase deployment boundary. Provider lifecycle, ownership checks,
  * remote connection resolution, guarded execution, and cleanup remain in one privileged object.
  */
 declare function createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost(config: BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig): BrowserbaseGuardedPlaywrightCheckoutRuntimeHost;
 
-export { BROWSERBASE_CONNECT_ORIGINS, type BrowserbaseAttachedSession, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHost, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig, type BrowserbaseOwnedLiveView, type BrowserbaseOwnedSession, type BrowserbaseSessionBinding, type BrowserbaseSessionBindingState, type BrowserbaseSessionBindingStore, type BrowserbaseSessionConfig, BrowserbaseSessionError, type BrowserbaseSessionErrorCode, type BrowserbaseSessionHandoff, type BrowserbaseSessionHandoffAssertionInput, type BrowserbaseSessionLifecycleOwner, type BrowserbaseSessionStatus, createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost, createBrowserbaseSessionHandoffAssertion };
+export { BROWSERBASE_CONNECT_ORIGINS, type BrowserbaseAttachedSession, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHost, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig, type BrowserbaseOwnedLiveView, type BrowserbaseOwnedSession, type BrowserbaseSessionBinding, type BrowserbaseSessionBindingState, type BrowserbaseSessionBindingStore, type BrowserbaseSessionConfig, BrowserbaseSessionError, type BrowserbaseSessionErrorCode, type BrowserbaseSessionHandoff, type BrowserbaseSessionHandoffAssertionInput, type BrowserbaseSessionLifecycleOwner, type BrowserbaseSessionManager, type BrowserbaseSessionStatus, createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost, createBrowserbaseSessionHandoffAssertion, createBrowserbaseSessionManager };

package/dist/browserbase.d.ts

@@ -130,12 +130,23 @@ declare class BrowserbaseSessionError extends Error {
     readonly code: BrowserbaseSessionErrorCode;
     constructor(code: BrowserbaseSessionErrorCode, message: string);
 }
+interface BrowserbaseSessionManager {
+    createSession(): Promise<BrowserbaseOwnedSession>;
+    attachSession(input: BrowserbaseSessionHandoff): Promise<BrowserbaseAttachedSession>;
+    connectUrlForSession(browserSessionId: string): Promise<string | null>;
+    liveViewForSession(browserSessionId: string): Promise<BrowserbaseOwnedLiveView>;
+    revokeSession(browserSessionId: string, lifecycleOwner: BrowserbaseSessionLifecycleOwner): Promise<boolean>;
+    releaseProviderSession(browserSessionId: string): Promise<void>;
+    releaseContextLease(browserSessionId: string): Promise<boolean>;
+}
 /** Creates a short-lived assertion after the trusted agent host creates its Browserbase session. */
 declare function createBrowserbaseSessionHandoffAssertion(input: BrowserbaseSessionHandoffAssertionInput, keyValue: Uint8Array): string;
+/** Server-only capability. Never expose connect URLs or this manager as agent tools. */
+declare function createBrowserbaseSessionManager(config: BrowserbaseSessionConfig): BrowserbaseSessionManager;
 /**
  * Creates the recommended Browserbase deployment boundary. Provider lifecycle, ownership checks,
  * remote connection resolution, guarded execution, and cleanup remain in one privileged object.
  */
 declare function createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost(config: BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig): BrowserbaseGuardedPlaywrightCheckoutRuntimeHost;
 
-export { BROWSERBASE_CONNECT_ORIGINS, type BrowserbaseAttachedSession, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHost, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig, type BrowserbaseOwnedLiveView, type BrowserbaseOwnedSession, type BrowserbaseSessionBinding, type BrowserbaseSessionBindingState, type BrowserbaseSessionBindingStore, type BrowserbaseSessionConfig, BrowserbaseSessionError, type BrowserbaseSessionErrorCode, type BrowserbaseSessionHandoff, type BrowserbaseSessionHandoffAssertionInput, type BrowserbaseSessionLifecycleOwner, type BrowserbaseSessionStatus, createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost, createBrowserbaseSessionHandoffAssertion };
+export { BROWSERBASE_CONNECT_ORIGINS, type BrowserbaseAttachedSession, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHost, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig, type BrowserbaseOwnedLiveView, type BrowserbaseOwnedSession, type BrowserbaseSessionBinding, type BrowserbaseSessionBindingState, type BrowserbaseSessionBindingStore, type BrowserbaseSessionConfig, BrowserbaseSessionError, type BrowserbaseSessionErrorCode, type BrowserbaseSessionHandoff, type BrowserbaseSessionHandoffAssertionInput, type BrowserbaseSessionLifecycleOwner, type BrowserbaseSessionManager, type BrowserbaseSessionStatus, createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost, createBrowserbaseSessionHandoffAssertion, createBrowserbaseSessionManager };

package/dist/browserbase.js

@@ -23,7 +23,8 @@ __export(browserbase_exports, {
   BROWSERBASE_CONNECT_ORIGINS: () => BROWSERBASE_CONNECT_ORIGINS,
   BrowserbaseSessionError: () => BrowserbaseSessionError,
   createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost: () => createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost,
-  createBrowserbaseSessionHandoffAssertion: () => createBrowserbaseSessionHandoffAssertion
+  createBrowserbaseSessionHandoffAssertion: () => createBrowserbaseSessionHandoffAssertion,
+  createBrowserbaseSessionManager: () => createBrowserbaseSessionManager
 });
 module.exports = __toCommonJS(browserbase_exports);
 var import_node_crypto3 = require("crypto");
@@ -1572,7 +1573,9 @@ function parseProviderSession(value, expectedProjectId, expectedSessionId) {
     status,
     createdAt,
     expiresAt,
-    connectUrl: secureConnectUrl(record.connectUrl)
+    // Completed sessions need not retain a connection capability. Validate it
+    // only for active states; identity and timestamps above still must match.
+    connectUrl: status === "PENDING" || status === "RUNNING" ? secureConnectUrl(record.connectUrl) : null
   });
 }
 async function readProviderJson(response) {
@@ -1668,11 +1671,13 @@ function createBrowserbaseSessionManager(config) {
           projectId,
           timeout: durationSeconds,
           keepAlive: true,
-          ...contextId ? {
-            browserSettings: {
-              context: { id: contextId, persist: true }
-            }
-          } : {}
+          proxies: false,
+          browserSettings: {
+            recordSession: false,
+            logSession: false,
+            solveCaptchas: false,
+            ...contextId ? { context: { id: contextId, persist: true } } : {}
+          }
         })
       });
       if (response.status !== 201) {
@@ -1981,5 +1986,6 @@ function createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost(config) {
   BROWSERBASE_CONNECT_ORIGINS,
   BrowserbaseSessionError,
   createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost,
-  createBrowserbaseSessionHandoffAssertion
+  createBrowserbaseSessionHandoffAssertion,
+  createBrowserbaseSessionManager
 });

package/dist/browserbase.mjs

@@ -196,7 +196,9 @@ function parseProviderSession(value, expectedProjectId, expectedSessionId) {
     status,
     createdAt,
     expiresAt,
-    connectUrl: secureConnectUrl(record.connectUrl)
+    // Completed sessions need not retain a connection capability. Validate it
+    // only for active states; identity and timestamps above still must match.
+    connectUrl: status === "PENDING" || status === "RUNNING" ? secureConnectUrl(record.connectUrl) : null
   });
 }
 async function readProviderJson(response) {
@@ -292,11 +294,13 @@ function createBrowserbaseSessionManager(config) {
           projectId,
           timeout: durationSeconds,
           keepAlive: true,
-          ...contextId ? {
-            browserSettings: {
-              context: { id: contextId, persist: true }
-            }
-          } : {}
+          proxies: false,
+          browserSettings: {
+            recordSession: false,
+            logSession: false,
+            solveCaptchas: false,
+            ...contextId ? { context: { id: contextId, persist: true } } : {}
+          }
         })
       });
       if (response.status !== 201) {
@@ -604,5 +608,6 @@ export {
   BROWSERBASE_CONNECT_ORIGINS,
   BrowserbaseSessionError,
   createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost,
-  createBrowserbaseSessionHandoffAssertion
+  createBrowserbaseSessionHandoffAssertion,
+  createBrowserbaseSessionManager
 };

package/dist/index.d.mts

@@ -65,7 +65,7 @@ interface PaginatedResponse<T> {
     limit: number;
     offset: number;
 }
-type AgentType = 'OPENAI_ASSISTANT' | 'ANTHROPIC_CLAUDE' | 'LANGCHAIN' | 'AUTOGPT' | 'CUSTOM';
+type AgentType = 'OPENAI_ASSISTANT' | 'ANTHROPIC_CLAUDE' | 'AUTOGPT' | 'CUSTOM';
 type AgentStatus = 'ACTIVE' | 'PAUSED' | 'SUSPENDED' | 'REVOKED' | 'FROZEN' | 'DELETED';
 type AgentEnvironment = 'DEV' | 'STAGING' | 'PROD';
 type AgentRiskTier = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
@@ -1164,6 +1164,11 @@ interface PaymentRequestResult {
 interface PaymentExecuteResult {
     /** Payment request ID */
     requestId: string;
+    /**
+     * True when the payment had already been executed, for example by an
+     * approver in Conto. The receipt is the existing one; nothing was sent again.
+     */
+    alreadyExecuted?: boolean;
     /** Customer-facing execution state */
     status: 'processing' | 'completed';
     /** Amount sent */
@@ -1196,6 +1201,8 @@ interface PaymentStatusResult {
     category: string | null;
     expiresAt: string | null;
     createdAt: string;
+    /** Customer-facing reasons for a declined payment or a pending review. */
+    reasons?: string[];
     action: null;
     transaction: {
         /** Stable Conto transaction ID */
@@ -1855,11 +1862,17 @@ interface ProtocolPreAuthorizeResult {
     authorized: boolean;
     decision: 'approved' | 'declined' | 'review_required';
     message: string;
+    /**
+     * Present when not authorized. Fixed reasons the agent can act on, such as a
+     * spending limit or a service that is not allowed. Never includes rule values.
+     */
+    reasons?: string[];
+    /** Present when not authorized. Codes for `reasons`, for example `SPENDING_LIMIT`. */
+    reasonCodes?: string[];
     /**
      * Present when authorized. Pass grantId and grantSignature to record(). A
      * record without a valid, unexpired grant is accepted but treated as a policy
-     * bypass: the payment is flagged and the owner is alerted. The organization
-     * can also have the agent frozen automatically.
+     * bypass: the payment is flagged and the owner is alerted.
      */
     grantId?: string;
     grantSignature?: string;
@@ -2265,7 +2278,7 @@ declare class ControlledExternalCardPaymentTool<TReceipt = unknown> {
     pay(input: ExternalCardApprovalInput): Promise<ControlledExternalCardPaymentResult<TReceipt>>;
 }
 /**
- * Agent client for connected cards (gated pilot).
+ * Agent client for connected cards (Builder and Enterprise plans).
  *
  * A connected card is a customer card enrolled through the provider and
  * delegated to this agent. `draw` mints one single-use credential against a
@@ -2273,7 +2286,7 @@ declare class ControlledExternalCardPaymentTool<TReceipt = unknown> {
  * draw against. This is a separate rail from {@link CardsClient}: it does not
  * share endpoints, scopes, or types with the external-card policy overlay.
  *
- * These methods return 404 until the tenant is enabled for the pilot.
+ * On plans without connected cards, these methods return an upgrade error.
  */
 declare class ConnectedCardsClient {
     private client;
@@ -2368,7 +2381,9 @@ declare class PaymentsClient {
      * Execute an approved payment.
      *
      * This sends the onchain transaction. Only works for payments
-     * with status 'APPROVED'.
+     * with status 'APPROVED'. If an approver already executed the payment by
+     * approving it in Conto, this returns the existing receipt with
+     * `alreadyExecuted: true` and sends nothing.
      *
      * @param requestId - The requestId from a successful payment request
      *

package/dist/index.d.ts

@@ -65,7 +65,7 @@ interface PaginatedResponse<T> {
     limit: number;
     offset: number;
 }
-type AgentType = 'OPENAI_ASSISTANT' | 'ANTHROPIC_CLAUDE' | 'LANGCHAIN' | 'AUTOGPT' | 'CUSTOM';
+type AgentType = 'OPENAI_ASSISTANT' | 'ANTHROPIC_CLAUDE' | 'AUTOGPT' | 'CUSTOM';
 type AgentStatus = 'ACTIVE' | 'PAUSED' | 'SUSPENDED' | 'REVOKED' | 'FROZEN' | 'DELETED';
 type AgentEnvironment = 'DEV' | 'STAGING' | 'PROD';
 type AgentRiskTier = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
@@ -1164,6 +1164,11 @@ interface PaymentRequestResult {
 interface PaymentExecuteResult {
     /** Payment request ID */
     requestId: string;
+    /**
+     * True when the payment had already been executed, for example by an
+     * approver in Conto. The receipt is the existing one; nothing was sent again.
+     */
+    alreadyExecuted?: boolean;
     /** Customer-facing execution state */
     status: 'processing' | 'completed';
     /** Amount sent */
@@ -1196,6 +1201,8 @@ interface PaymentStatusResult {
     category: string | null;
     expiresAt: string | null;
     createdAt: string;
+    /** Customer-facing reasons for a declined payment or a pending review. */
+    reasons?: string[];
     action: null;
     transaction: {
         /** Stable Conto transaction ID */
@@ -1855,11 +1862,17 @@ interface ProtocolPreAuthorizeResult {
     authorized: boolean;
     decision: 'approved' | 'declined' | 'review_required';
     message: string;
+    /**
+     * Present when not authorized. Fixed reasons the agent can act on, such as a
+     * spending limit or a service that is not allowed. Never includes rule values.
+     */
+    reasons?: string[];
+    /** Present when not authorized. Codes for `reasons`, for example `SPENDING_LIMIT`. */
+    reasonCodes?: string[];
     /**
      * Present when authorized. Pass grantId and grantSignature to record(). A
      * record without a valid, unexpired grant is accepted but treated as a policy
-     * bypass: the payment is flagged and the owner is alerted. The organization
-     * can also have the agent frozen automatically.
+     * bypass: the payment is flagged and the owner is alerted.
      */
     grantId?: string;
     grantSignature?: string;
@@ -2265,7 +2278,7 @@ declare class ControlledExternalCardPaymentTool<TReceipt = unknown> {
     pay(input: ExternalCardApprovalInput): Promise<ControlledExternalCardPaymentResult<TReceipt>>;
 }
 /**
- * Agent client for connected cards (gated pilot).
+ * Agent client for connected cards (Builder and Enterprise plans).
  *
  * A connected card is a customer card enrolled through the provider and
  * delegated to this agent. `draw` mints one single-use credential against a
@@ -2273,7 +2286,7 @@ declare class ControlledExternalCardPaymentTool<TReceipt = unknown> {
  * draw against. This is a separate rail from {@link CardsClient}: it does not
  * share endpoints, scopes, or types with the external-card policy overlay.
  *
- * These methods return 404 until the tenant is enabled for the pilot.
+ * On plans without connected cards, these methods return an upgrade error.
  */
 declare class ConnectedCardsClient {
     private client;
@@ -2368,7 +2381,9 @@ declare class PaymentsClient {
      * Execute an approved payment.
      *
      * This sends the onchain transaction. Only works for payments
-     * with status 'APPROVED'.
+     * with status 'APPROVED'. If an approver already executed the payment by
+     * approving it in Conto, this returns the existing receipt with
+     * `alreadyExecuted: true` and sends nothing.
      *
      * @param requestId - The requestId from a successful payment request
      *

package/dist/index.js

@@ -39,7 +39,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@conto_finance/sdk",
-      version: "0.5.0",
+      version: "0.5.2",
       description: "Conto SDK for AI agent payment authorization",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
@@ -172,7 +172,10 @@ var PUBLIC_PAYMENT_REASONS = /* @__PURE__ */ new Set([
   "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."
+  "This payment requires approval before it can proceed.",
+  "No usable wallet is linked to this agent.",
+  "This payee needs review before payments to it can proceed automatically.",
+  "A reviewer declined this payment."
 ]);
 function customerPaymentReasons(value) {
   return Array.isArray(value) ? [
@@ -352,9 +355,11 @@ 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;
+  const reasons = customerPaymentReasons(body.reasons);
   return {
     code,
     status: response.status,
+    ...reasons.length > 0 ? { reasons } : {},
     fieldErrors: customerFieldErrors(body, response.status),
     requestId: safeRequestId(
       response.headers.get("x-request-id"),
@@ -1705,6 +1710,27 @@ var ConnectedCardsClient = class {
     return this.client.request("GET", "/api/sdk/connected-cards");
   }
 };
+function approvalRetryGuidance(requestId) {
+  const id = JSON.stringify(requestId);
+  return `An approver in Conto executes the payment when they approve it. After approval, call payments.execute(${id}) or payments.status(${id}) to get the receipt. Do not request the payment again.`;
+}
+function executeRetryGuidance(code, requestId) {
+  const id = JSON.stringify(requestId);
+  switch (code) {
+    case "APPROVAL_PENDING":
+      return approvalRetryGuidance(requestId);
+    case "POLICY_DENIED_AT_EXECUTION":
+    case "PAYMENT_DENIED":
+      return "This payment was declined and will not execute. Do not retry it; review the reasons before requesting a new payment.";
+    case "POLICY_REAPPROVAL_REQUIRED":
+      return "This payment now needs approval and will not execute. Request a new payment and wait for approval.";
+    case "PAYMENT_PROCESSING":
+    case "NEEDS_RECONCILIATION":
+      return `Do not execute again. Check payments.status(${id}) for the outcome.`;
+    default:
+      return void 0;
+  }
+}
 var PaymentsClient = class {
   constructor(client) {
     this.client = client;
@@ -1778,7 +1804,9 @@ var PaymentsClient = class {
    * Execute an approved payment.
    *
    * This sends the onchain transaction. Only works for payments
-   * with status 'APPROVED'.
+   * with status 'APPROVED'. If an approver already executed the payment by
+   * approving it in Conto, this returns the existing receipt with
+   * `alreadyExecuted: true` and sends nothing.
    *
    * @param requestId - The requestId from a successful payment request
    *
@@ -1800,18 +1828,17 @@ var PaymentsClient = class {
         {}
       );
     } 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;
+      if (!(error instanceof ContoError)) throw error;
+      const retryGuidance = error.status === 0 ? `Check payments.status(${JSON.stringify(requestId)}) before attempting execution again.` : executeRetryGuidance(error.code, requestId);
+      if (!retryGuidance) throw error;
+      throw new ContoError(error.message, {
+        code: error.code,
+        status: error.status,
+        requestId: error.requestId,
+        retryAfter: error.retryAfter,
+        reasons: error.reasons,
+        retryGuidance
+      });
     }
   }
   /**
@@ -1876,8 +1903,9 @@ var PaymentsClient = class {
       throw new ContoError("Payment requires manual approval", {
         code: "REQUIRES_APPROVAL",
         status: 202,
+        reasons: customerPaymentReasons(request.reasons),
         requestId: request.requestId,
-        retryGuidance: "Wait for approval, then execute the same request ID."
+        retryGuidance: approvalRetryGuidance(request.requestId)
       });
     }
     if (request.status === "PROCESSING") {

package/dist/index.mjs

@@ -14,7 +14,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@conto_finance/sdk",
-      version: "0.5.0",
+      version: "0.5.2",
       description: "Conto SDK for AI agent payment authorization",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
@@ -128,7 +128,10 @@ var PUBLIC_PAYMENT_REASONS = /* @__PURE__ */ new Set([
   "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."
+  "This payment requires approval before it can proceed.",
+  "No usable wallet is linked to this agent.",
+  "This payee needs review before payments to it can proceed automatically.",
+  "A reviewer declined this payment."
 ]);
 function customerPaymentReasons(value) {
   return Array.isArray(value) ? [
@@ -308,9 +311,11 @@ 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;
+  const reasons = customerPaymentReasons(body.reasons);
   return {
     code,
     status: response.status,
+    ...reasons.length > 0 ? { reasons } : {},
     fieldErrors: customerFieldErrors(body, response.status),
     requestId: safeRequestId(
       response.headers.get("x-request-id"),
@@ -1544,6 +1549,27 @@ var ConnectedCardsClient = class {
     return this.client.request("GET", "/api/sdk/connected-cards");
   }
 };
+function approvalRetryGuidance(requestId) {
+  const id = JSON.stringify(requestId);
+  return `An approver in Conto executes the payment when they approve it. After approval, call payments.execute(${id}) or payments.status(${id}) to get the receipt. Do not request the payment again.`;
+}
+function executeRetryGuidance(code, requestId) {
+  const id = JSON.stringify(requestId);
+  switch (code) {
+    case "APPROVAL_PENDING":
+      return approvalRetryGuidance(requestId);
+    case "POLICY_DENIED_AT_EXECUTION":
+    case "PAYMENT_DENIED":
+      return "This payment was declined and will not execute. Do not retry it; review the reasons before requesting a new payment.";
+    case "POLICY_REAPPROVAL_REQUIRED":
+      return "This payment now needs approval and will not execute. Request a new payment and wait for approval.";
+    case "PAYMENT_PROCESSING":
+    case "NEEDS_RECONCILIATION":
+      return `Do not execute again. Check payments.status(${id}) for the outcome.`;
+    default:
+      return void 0;
+  }
+}
 var PaymentsClient = class {
   constructor(client) {
     this.client = client;
@@ -1617,7 +1643,9 @@ var PaymentsClient = class {
    * Execute an approved payment.
    *
    * This sends the onchain transaction. Only works for payments
-   * with status 'APPROVED'.
+   * with status 'APPROVED'. If an approver already executed the payment by
+   * approving it in Conto, this returns the existing receipt with
+   * `alreadyExecuted: true` and sends nothing.
    *
    * @param requestId - The requestId from a successful payment request
    *
@@ -1639,18 +1667,17 @@ var PaymentsClient = class {
         {}
       );
     } 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;
+      if (!(error instanceof ContoError)) throw error;
+      const retryGuidance = error.status === 0 ? `Check payments.status(${JSON.stringify(requestId)}) before attempting execution again.` : executeRetryGuidance(error.code, requestId);
+      if (!retryGuidance) throw error;
+      throw new ContoError(error.message, {
+        code: error.code,
+        status: error.status,
+        requestId: error.requestId,
+        retryAfter: error.retryAfter,
+        reasons: error.reasons,
+        retryGuidance
+      });
     }
   }
   /**
@@ -1715,8 +1742,9 @@ var PaymentsClient = class {
       throw new ContoError("Payment requires manual approval", {
         code: "REQUIRES_APPROVAL",
         status: 202,
+        reasons: customerPaymentReasons(request.reasons),
         requestId: request.requestId,
-        retryGuidance: "Wait for approval, then execute the same request ID."
+        retryGuidance: approvalRetryGuidance(request.requestId)
       });
     }
     if (request.status === "PROCESSING") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conto_finance/sdk",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Conto SDK for AI agent payment authorization",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",