@conto_finance/sdk 0.4.0 → 0.5.0

package/README.md

@@ -1,5 +1,10 @@
 # @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.
+See [buyer-side control](https://conto.finance/docs/guides/buyer-side-control) for the authorization
+and execution boundary.
+
 TypeScript SDK for Conto. Use it when you control the agent runtime and want typed access to
 payment requests, payment execution, and organization-level provisioning.
 
@@ -144,14 +149,16 @@ const result = await conto.payments.pay({
 ```typescript
 const paymentId = crypto.randomUUID();
 
-await conto.x402.preAuthorize({
+const decision = await conto.x402.preAuthorize({
   amount: 0.01,
   recipientAddress: '0x...',
   resourceUrl: 'https://api.example.com/v1/search',
   paymentId,
   sessionId: 'session_123',
 });
+if (!decision.authorized) throw new Error(decision.message);
 
+// Sign and settle the x402 payment, then record it with the grant.
 await conto.x402.record({
   amount: 0.01,
   recipientAddress: '0x...',
@@ -159,18 +166,53 @@ await conto.x402.record({
   paymentId,
   txHash: '0x...',
   sessionId: 'session_123',
+  grantId: decision.grantId,
+  grantSignature: decision.grantSignature,
 });
 
 const budget = await conto.x402.budget();
 ```
 
+An approved `preAuthorize` returns a single-use grant (`grantId`, `grantSignature`,
+`grantExpiresAt`) for that wallet, recipient, and amount, and reserves the amount against the
+agent's spend limits for 10 minutes. Pass the grant to `record`. A record without a valid,
+unexpired grant is still accepted because the payment already settled, but Conto flags it as a
+policy bypass and raises a critical alert. Organizations can also have the agent frozen
+automatically. The record response then includes `policyBypass: true`, `bypassReason`, and
+`agentFrozen`.
+
+For a Privy-managed EVM wallet, `conto.x402.pay` replaces `preAuthorize`. Pass the same fields
+plus the accepted 402 requirements; when approved, Conto signs the payment and returns the header
+to retry with:
+
+```typescript
+const paid = await conto.x402.pay({
+  amount: 0.01,
+  recipientAddress: requirements.payTo,
+  resourceUrl: 'https://api.example.com/v1/search',
+  paymentId,
+  paymentRequirements: requirements, // accepted entry from the 402 challenge
+});
+if (!paid.authorized) throw new Error(paid.message);
+
+const response = await fetch('https://api.example.com/v1/search', {
+  headers: { [paid.paymentHeaderName!]: paid.xPaymentHeader! },
+});
+// Then record with paid.grantId, paid.grantSignature, and the settlement txHash.
+```
+
+`pay` is not retried automatically: each grant is signed once, and a repeat returns
+`GRANT_ALREADY_SIGNED`. External wallets get `MANAGED_SIGNING_UNAVAILABLE`.
+
 The MPP client mirrors the same shape with `conto.mpp.preAuthorize`, `conto.mpp.record`,
-`conto.mpp.budget`, and `conto.mpp.services`.
+`conto.mpp.budget`, and `conto.mpp.services`. An MPP session grant is a ceiling: several
+`record` calls with the same `sessionId` may draw it down until it is used up or expires.
 
-## Stripe Link Checkout Commerce
+## Stripe Link Checkout Commerce (test only)
 
-For a merchant Conto controls, `LINK_CHECKOUT` evaluates policy before creating an ordinary
-Stripe-hosted Checkout Session with card and Link enabled. It needs no private Link SDK permission,
+`LINK_CHECKOUT` is test-only and works only with a merchant enrolled with Conto. It is not a
+general merchant integration. It evaluates policy before creating an ordinary Stripe-hosted
+Checkout Session with card and Link enabled. It needs no private Link SDK permission,
 Link connection, saved payment-method ID, SPT, or LPT.
 
 Commerce execution responses separate the provider-neutral `executionChannel`, optional
@@ -224,15 +266,16 @@ fallback, surfaced as `actualPaymentMethod: 'CARD'`; it is a valid payment but n
 The read-only `getCommerceExecution` projection redacts action URLs; use the initial begin result or
 the `payments:confirm` refresh path while action remains required.
 The server resolves the exact merchant name, Stripe account, and return URLs from configuration, so
-the caller cannot redirect the approved purchase. This path controls only that merchant's Conto
-channel, not unrelated Checkout pages or the consumer's Link wallet. See
+the caller cannot redirect the approved purchase. This path covers only that enrolled merchant's
+Conto channel, not unrelated Checkout pages or the consumer's Link wallet. See
 `docs/STRIPE_LINK_CHECKOUT_ADAPTER.md` for configuration, webhook, drill, and reconciliation
 requirements.
 
 ## Agent checkout guard
 
-For arbitrary third-party merchants, use `runGuardedCheckout` with
-`executionMethod: 'BROWSER_CHECKOUT'`. It binds and atomically authorizes one exact Link, card,
+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
 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,
@@ -502,7 +545,9 @@ The SDK automatically adds an idempotency key to wallet payment authorization
 requests. Provide your own stable `idempotencyKey` when a retry may happen in
 another process or job attempt. External-card approvals always require a stable
 caller-supplied `idempotencyKey`; card approval and confirmation are safe to
-retry. x402 and MPP pre-authorization calls are non-mutating policy checks.
+retry. x402 and MPP pre-authorization calls issue a grant and reserve spend. A retry
+with the same `paymentId` (x402) or `challengeId`/`credentialId` (MPP) returns the
+same live grant instead of reserving again.
 Record calls require an explicit stable `paymentId` or `credentialId` so an
 ambiguous failure can be reconciled safely.
 

package/dist/browserbase.d.mts

@@ -2,6 +2,8 @@ import { Browser } from 'playwright-core';
 import { GuardedPlaywrightCheckoutHttpHandler, PlaywrightSessionObservation, GuardedPlaywrightCheckoutClient, PlaywrightCdpSessionRegistryConfig, EncryptedPlaywrightCheckoutTargetStoreConfig, GuardedPlaywrightCheckoutRuntimeConfig } from './playwright.mjs';
 import './index.mjs';
 
+/** Exact provider endpoints verified against Browserbase's session API; never use a wildcard. */
+declare const BROWSERBASE_CONNECT_ORIGINS: readonly string[];
 type BrowserbaseSessionStatus = 'PENDING' | 'RUNNING' | 'ERROR' | 'TIMED_OUT' | 'COMPLETED';
 type BrowserbaseSessionBindingState = 'ACTIVE' | 'REVOKED';
 type BrowserbaseSessionLifecycleOwner = 'CONTO_RUNTIME' | 'AGENT_HOST';
@@ -136,4 +138,4 @@ declare function createBrowserbaseSessionHandoffAssertion(input: BrowserbaseSess
  */
 declare function createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost(config: BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig): BrowserbaseGuardedPlaywrightCheckoutRuntimeHost;
 
-export { 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 BrowserbaseSessionStatus, createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost, createBrowserbaseSessionHandoffAssertion };

package/dist/browserbase.d.ts

@@ -2,6 +2,8 @@ import { Browser } from 'playwright-core';
 import { GuardedPlaywrightCheckoutHttpHandler, PlaywrightSessionObservation, GuardedPlaywrightCheckoutClient, PlaywrightCdpSessionRegistryConfig, EncryptedPlaywrightCheckoutTargetStoreConfig, GuardedPlaywrightCheckoutRuntimeConfig } from './playwright.js';
 import './index.js';
 
+/** Exact provider endpoints verified against Browserbase's session API; never use a wildcard. */
+declare const BROWSERBASE_CONNECT_ORIGINS: readonly string[];
 type BrowserbaseSessionStatus = 'PENDING' | 'RUNNING' | 'ERROR' | 'TIMED_OUT' | 'COMPLETED';
 type BrowserbaseSessionBindingState = 'ACTIVE' | 'REVOKED';
 type BrowserbaseSessionLifecycleOwner = 'CONTO_RUNTIME' | 'AGENT_HOST';
@@ -136,4 +138,4 @@ declare function createBrowserbaseSessionHandoffAssertion(input: BrowserbaseSess
  */
 declare function createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost(config: BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig): BrowserbaseGuardedPlaywrightCheckoutRuntimeHost;
 
-export { 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 BrowserbaseSessionStatus, createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost, createBrowserbaseSessionHandoffAssertion };

package/dist/browserbase.js

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/browserbase.ts
 var browserbase_exports = {};
 __export(browserbase_exports, {
+  BROWSERBASE_CONNECT_ORIGINS: () => BROWSERBASE_CONNECT_ORIGINS,
   BrowserbaseSessionError: () => BrowserbaseSessionError,
   createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost: () => createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost,
   createBrowserbaseSessionHandoffAssertion: () => createBrowserbaseSessionHandoffAssertion
@@ -1382,7 +1383,10 @@ function createGuardedPlaywrightCheckoutHttpHandler(config) {
 
 // src/browserbase.ts
 var BROWSERBASE_API_ORIGIN = "https://api.browserbase.com";
-var BROWSERBASE_CONNECT_ORIGIN = "wss://connect.browserbase.com";
+var BROWSERBASE_CONNECT_ORIGINS = Object.freeze([
+  "wss://connect.browserbase.com",
+  "wss://connect.usw2.browserbase.com"
+]);
 var BROWSERBASE_LIVE_VIEW_DOMAIN = "browserbase.com";
 var DEFAULT_SESSION_TIMEOUT_SECONDS = 900;
 var MIN_SESSION_TIMEOUT_SECONDS = 60;
@@ -1508,7 +1512,7 @@ function secureConnectUrl(value) {
   const normalized = providerText(value, "connectUrl", 4096);
   try {
     const url = new URL(normalized);
-    if (url.protocol !== "wss:" || url.origin !== BROWSERBASE_CONNECT_ORIGIN || url.username || url.password || url.hash) {
+    if (url.protocol !== "wss:" || !BROWSERBASE_CONNECT_ORIGINS.includes(url.origin) || url.username || url.password || url.hash) {
       throw new Error("unsafe Browserbase connect URL");
     }
     return url.toString();
@@ -1911,7 +1915,7 @@ function createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost(config) {
   const host = createGuardedPlaywrightCheckoutRuntimeHost({
     conto: config.conto,
     browserSessions: {
-      allowedConnectOrigins: [BROWSERBASE_CONNECT_ORIGIN],
+      allowedConnectOrigins: BROWSERBASE_CONNECT_ORIGINS,
       connectUrlForSession: manager.connectUrlForSession,
       connectOverCDP: config.connectOverCDP,
       selectPage: config.selectPage,
@@ -1974,6 +1978,7 @@ function createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost(config) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BROWSERBASE_CONNECT_ORIGINS,
   BrowserbaseSessionError,
   createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost,
   createBrowserbaseSessionHandoffAssertion

package/dist/browserbase.mjs

@@ -7,7 +7,10 @@ import "./chunk-B7F5QLE5.mjs";
 // src/browserbase.ts
 import { createHmac, timingSafeEqual } from "crypto";
 var BROWSERBASE_API_ORIGIN = "https://api.browserbase.com";
-var BROWSERBASE_CONNECT_ORIGIN = "wss://connect.browserbase.com";
+var BROWSERBASE_CONNECT_ORIGINS = Object.freeze([
+  "wss://connect.browserbase.com",
+  "wss://connect.usw2.browserbase.com"
+]);
 var BROWSERBASE_LIVE_VIEW_DOMAIN = "browserbase.com";
 var DEFAULT_SESSION_TIMEOUT_SECONDS = 900;
 var MIN_SESSION_TIMEOUT_SECONDS = 60;
@@ -133,7 +136,7 @@ function secureConnectUrl(value) {
   const normalized = providerText(value, "connectUrl", 4096);
   try {
     const url = new URL(normalized);
-    if (url.protocol !== "wss:" || url.origin !== BROWSERBASE_CONNECT_ORIGIN || url.username || url.password || url.hash) {
+    if (url.protocol !== "wss:" || !BROWSERBASE_CONNECT_ORIGINS.includes(url.origin) || url.username || url.password || url.hash) {
       throw new Error("unsafe Browserbase connect URL");
     }
     return url.toString();
@@ -536,7 +539,7 @@ function createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost(config) {
   const host = createGuardedPlaywrightCheckoutRuntimeHost({
     conto: config.conto,
     browserSessions: {
-      allowedConnectOrigins: [BROWSERBASE_CONNECT_ORIGIN],
+      allowedConnectOrigins: BROWSERBASE_CONNECT_ORIGINS,
       connectUrlForSession: manager.connectUrlForSession,
       connectOverCDP: config.connectOverCDP,
       selectPage: config.selectPage,
@@ -598,6 +601,7 @@ function createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost(config) {
   });
 }
 export {
+  BROWSERBASE_CONNECT_ORIGINS,
   BrowserbaseSessionError,
   createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost,
   createBrowserbaseSessionHandoffAssertion

package/dist/index.d.mts

@@ -1131,7 +1131,7 @@ interface PaymentRequestResult {
     /** Unique request ID - use this to execute or check status */
     requestId: string;
     /** Current status */
-    status: 'APPROVED' | 'DENIED' | 'REQUIRES_APPROVAL' | 'ACTION_REQUIRED' | 'PROCESSING';
+    status: 'APPROVED' | 'DENIED' | 'REQUIRES_APPROVAL' | 'PROCESSING';
     /** Requested amount */
     amount: number;
     /** Currency selected for the payment */
@@ -1187,7 +1187,7 @@ interface PaymentStatusResult {
     requestId: string;
     /** Unknown for legacy records without execution evidence, or before execution. */
     settlementMode: 'live' | 'test' | 'unknown';
-    status: 'approved' | 'declined' | 'review_required' | 'action_required' | 'reconciliation_required' | 'processing' | 'completed' | 'failed' | 'expired';
+    status: 'approved' | 'declined' | 'review_required' | 'reconciliation_required' | 'processing' | 'completed' | 'failed' | 'expired';
     amount: number;
     currency: string;
     recipient: string;
@@ -1196,10 +1196,7 @@ interface PaymentStatusResult {
     category: string | null;
     expiresAt: string | null;
     createdAt: string;
-    action: {
-        type: 'complete_verification';
-        url: string;
-    } | null;
+    action: null;
     transaction: {
         /** Stable Conto transaction ID */
         id: string;
@@ -1858,6 +1855,31 @@ interface ProtocolPreAuthorizeResult {
     authorized: boolean;
     decision: 'approved' | 'declined' | 'review_required';
     message: 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.
+     */
+    grantId?: string;
+    grantSignature?: string;
+    /** ISO timestamp. Record the payment before this time. */
+    grantExpiresAt?: string;
+}
+interface ProtocolRecordGrant {
+    /** grantId from the approved preAuthorize() response. */
+    grantId?: string;
+    /** grantSignature from the approved preAuthorize() response. */
+    grantSignature?: string;
+}
+interface ProtocolRecordGrantResult {
+    /** Grant consumed by this record. */
+    grantId?: string;
+    /** True when the payment was recorded without a valid grant. */
+    policyBypass?: true;
+    bypassReason?: 'GRANT_MISSING' | 'GRANT_INVALID' | 'GRANT_EXPIRED';
+    /** True when the organization freezes agents on bypass and this record froze it. */
+    agentFrozen?: boolean;
 }
 interface X402PreAuthorizeInput {
     amount: number;
@@ -1884,7 +1906,55 @@ interface X402PreAuthorizeResult extends ProtocolPreAuthorizeResult {
         sessionId?: string;
     };
 }
-interface X402RecordInput {
+/** The accepted entry from a 402 challenge (x402 "exact" scheme on EVM). */
+interface X402PaymentRequirements {
+    scheme: 'exact' | (string & {});
+    /** Network as the challenge sent it: CAIP-2 (eip155:8453) or an x402 v1 name (base). */
+    network: string;
+    /** v1: amount in token base units, as an integer string. */
+    maxAmountRequired?: string;
+    /** v2: amount in token base units, as an integer string. */
+    amount?: string;
+    /** Token contract. Conto signs only for managed USDC. */
+    asset: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    resource?: string;
+    /** EIP-712 domain of the token. */
+    extra?: {
+        name?: string;
+        version?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+interface X402PayInput extends X402PreAuthorizeInput {
+    /** x402 protocol version of the challenge. Defaults to 1. */
+    x402Version?: 1 | 2;
+    paymentRequirements: X402PaymentRequirements;
+}
+interface X402Authorization {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+}
+interface X402PayResult extends ProtocolPreAuthorizeResult {
+    x402: {
+        serviceDomain?: string;
+        amount: number;
+        sessionId?: string;
+    };
+    /** Present when authorized: send as this header when retrying the resource request. */
+    paymentHeaderName?: 'X-PAYMENT' | 'PAYMENT-SIGNATURE';
+    /** Present when authorized: base64 payment payload signed by Conto. */
+    xPaymentHeader?: string;
+    /** Present when authorized: the EIP-3009 authorization Conto signed. */
+    authorization?: X402Authorization;
+}
+interface X402RecordInput extends ProtocolRecordGrant {
     amount: number;
     currency?: string;
     recipientAddress: string;
@@ -1908,7 +1978,7 @@ interface X402RecordInput {
         paymentId: string;
     }>;
 }
-interface X402RecordResult {
+interface X402RecordResult extends ProtocolRecordGrantResult {
     recorded: true;
     confirmed: true;
     txHash: string;
@@ -1939,7 +2009,7 @@ interface MppPreAuthorizeResult extends ProtocolPreAuthorizeResult {
         sessionId?: string;
     };
 }
-interface MppRecordInput {
+interface MppRecordInput extends ProtocolRecordGrant {
     amount: number;
     currency?: string;
     recipientAddress: string;
@@ -1965,7 +2035,7 @@ interface MppRecordInput {
         credentialId: string;
     }>;
 }
-interface MppRecordResult {
+interface MppRecordResult extends ProtocolRecordGrantResult {
     recorded: true;
     txHash?: string;
     explorerUrl?: string;
@@ -2359,6 +2429,16 @@ declare class X402Client {
     private client;
     constructor(client: Conto);
     preAuthorize(input: X402PreAuthorizeInput): Promise<X402PreAuthorizeResult>;
+    /**
+     * Conto-signed x402 for Privy-managed EVM wallets. Conto evaluates the
+     * payment exactly like preAuthorize() and, only when approved, signs the
+     * EIP-3009 authorization for the approved payee and amount. Retry the
+     * resource request with `paymentHeaderName: xPaymentHeader`, then call
+     * record() with the returned grant. Not retried automatically: a grant is
+     * signed at most once, and a repeat returns 409 GRANT_ALREADY_SIGNED.
+     * External wallets get 409 MANAGED_SIGNING_UNAVAILABLE; use preAuthorize().
+     */
+    pay(input: X402PayInput): Promise<X402PayResult>;
     record(input: X402RecordInput): Promise<X402RecordResult>;
     budget(options?: {
         sessionId?: string;
@@ -2382,4 +2462,4 @@ declare class MppClient {
     }): Promise<ProtocolServicesResult>;
 }
 
-export { type AdminExternalCardOverlayEnforcement, type Agent, type AgentCheckoutAction, type AgentCheckoutActionKind, type AgentExternalCard, type AgentSetupResult, type AgentStatus, type AgentType, type AgentWalletLink, type ApprovedExternalCardExecution, type AssignExternalCardInput, type AssignedPolicy, type AuthorizeCheckoutActionResult, type BeginCommerceExecutionInput, type BrowserActionClaimResult, type BrowserActionDispatchObservationInput, BrowserActionFinalizationPendingError, type BrowserActionFinalizeResult, type BrowserCheckoutAction, type BrowserCheckoutTargetResolver, type BrowserCheckoutTargetSnapshot, type BrowserCheckoutTargetVerificationCode, BrowserCheckoutTargetVerificationError, type CanonicalBrowserCheckoutTargetSnapshot, CardsClient, type ChainType, type CheckoutActionAuthorization, type CommerceCheckoutMethod, type CommerceContextRequirement, type CommerceExecution, type CommerceExecutionAdapterKind, type CommerceExecutionArtifactKind, type CommerceExecutionChannel, type CommerceExecutionConstraint, type CommerceExecutionConstraintCoverage, type CommerceExecutionConstraintCoverageLevel, type CommerceExecutionDeliveryMode, type CommerceExecutionEvidence, type CommerceExecutionProvider, type CommerceExecutionResult, type CommerceExecutionSourceKind, type CommerceExecutionStatus, type CommerceFactConfidence, type CommerceFactProvenanceInput, type CommerceFactSource, type CommerceFulfillmentInput, type CommerceLineItemInput, type CommerceProposalFactKey, type CommerceProposalMissingFact, type CommerceProposalResolution, type CommerceProposalState, type CommerceSettlementRail, type CommerceTotalInput, type CommerceTotalType, type ComparePolicyVersionsResponse, type ConnectedCardBrief, type ConnectedCardCredential, type ConnectedCardDrawInput, type ConnectedCardDrawMerchant, type ConnectedCardDrawResult, type ConnectedCardDrawable, type ConnectedCardListResult, type ConnectedCardMandate, type ConnectedCardMandateMerchant, type ConnectedCardReference, ConnectedCardsClient, Conto, ContoAdmin, type ContoAdminConfig, ContoAdminError, type ContoConfig, ContoError, type ContoRequestOptions, type ControlledExternalCardPaymentResult, ControlledExternalCardPaymentTool, type CreateAgentInput, type CreatePolicyInput, type CreatePolicyRuleInput, type CreateSdkKeyInput, type CreateSdkKeyResult, type CreateWalletInput, type CustodyType, type CustomerCustodyMode, type CustomerWalletControlModel, type CustomerWalletKeyAccess, type DelegationType, type ExecuteCommerceExecutionResult, type ExternalCard, type ExternalCardApprovalInput, type ExternalCardApprovalResult, type ExternalCardConfirmationInput, ExternalCardConfirmationPendingError, type ExternalCardConfirmationResult, type ExternalCardExecutionClaimResult, type ExternalCardExecutionResult, type ExternalCardExecutor, type ExternalCardOverlayEnforcement, type ExternalCardRequestStatusResult, type ExternalWalletApprovalInput, type ExternalWalletApprovalResult, type ExternalWalletConfirmationInput, type ExternalWalletConfirmationResult, type FreezeAgentInput, Conto as Giro, type ContoConfig as GiroConfig, ContoError as GiroError, type GuardCheckoutResult, type GuardedBrowserDispatchResult, type GuardedCheckoutInput, type LinkWalletInput, type ListAgentsParams, type ListAgentsResponse, type ListPoliciesParams, type ListPoliciesResponse, type ListPolicyVersionsResponse, type ListStripeLinkPaymentMethodsResult, type ListWalletsParams, type ListWalletsResponse, type MppBudgetResult, type MppPreAuthorizeInput, type MppPreAuthorizeResult, type MppRecordInput, type MppRecordResult, type NormalizeCommerceProposalInput, type OrganizationMember, type PaginatedResponse, type PaginationParams, type PauseExternalCardAssignmentResult, type PaymentExecuteResult, type PaymentRequestInput, type PaymentRequestResult, type PaymentStatusResult, type Policy, type PolicyRule, type PolicyType, type PolicyVersionChangeType, type PolicyVersionDetail, type PolicyVersionDiff, type PolicyVersionFieldChange, type PolicyVersionSnapshot, type PolicyVersionSnapshotRule, type PolicyVersionSummary, type PrivilegedBrowserCheckoutDriver, type ProtocolBudgetResult, type ProtocolPreAuthorizeResult, type ProtocolServiceSummary, type ProtocolServicesResult, type ProvisionWalletResult, type RefreshBalanceResult, type RegisterExternalCardInput, type RollbackPolicyVersionResponse, type RuleAction, type RuleOperator, type RuleType, type RunGuardedCheckoutResult, type SdkKey, type SdkKeyType, type StripeLinkCheckoutReadiness, type StripeLinkCheckoutReadinessResult, type StripeLinkCheckoutReadinessStatus, type StripeLinkCheckoutVerification, type StripeLinkPaymentMethod, type UnfreezeAgentInput, type UpdateAgentInput, type UpdateExternalCardAssignmentInput, type UpdatePolicyInput, type UpdatePolicyRuleInput, type UpdateWalletInput, type VerifiedBrowserCheckoutTarget, type Wallet, type WalletChainBalanceSnapshot, type WalletStatus, type WalletType, type X402BudgetResult, type X402PreAuthorizeInput, type X402PreAuthorizeResult, type X402RecordInput, type X402RecordResult, canonicalizeBrowserCheckoutTarget, createVerifiedBrowserCheckoutDriver, Conto as default, fingerprintBrowserCheckoutTarget };
+export { type AdminExternalCardOverlayEnforcement, type Agent, type AgentCheckoutAction, type AgentCheckoutActionKind, type AgentExternalCard, type AgentSetupResult, type AgentStatus, type AgentType, type AgentWalletLink, type ApprovedExternalCardExecution, type AssignExternalCardInput, type AssignedPolicy, type AuthorizeCheckoutActionResult, type BeginCommerceExecutionInput, type BrowserActionClaimResult, type BrowserActionDispatchObservationInput, BrowserActionFinalizationPendingError, type BrowserActionFinalizeResult, type BrowserCheckoutAction, type BrowserCheckoutTargetResolver, type BrowserCheckoutTargetSnapshot, type BrowserCheckoutTargetVerificationCode, BrowserCheckoutTargetVerificationError, type CanonicalBrowserCheckoutTargetSnapshot, CardsClient, type ChainType, type CheckoutActionAuthorization, type CommerceCheckoutMethod, type CommerceContextRequirement, type CommerceExecution, type CommerceExecutionAdapterKind, type CommerceExecutionArtifactKind, type CommerceExecutionChannel, type CommerceExecutionConstraint, type CommerceExecutionConstraintCoverage, type CommerceExecutionConstraintCoverageLevel, type CommerceExecutionDeliveryMode, type CommerceExecutionEvidence, type CommerceExecutionProvider, type CommerceExecutionResult, type CommerceExecutionSourceKind, type CommerceExecutionStatus, type CommerceFactConfidence, type CommerceFactProvenanceInput, type CommerceFactSource, type CommerceFulfillmentInput, type CommerceLineItemInput, type CommerceProposalFactKey, type CommerceProposalMissingFact, type CommerceProposalResolution, type CommerceProposalState, type CommerceSettlementRail, type CommerceTotalInput, type CommerceTotalType, type ComparePolicyVersionsResponse, type ConnectedCardBrief, type ConnectedCardCredential, type ConnectedCardDrawInput, type ConnectedCardDrawMerchant, type ConnectedCardDrawResult, type ConnectedCardDrawable, type ConnectedCardListResult, type ConnectedCardMandate, type ConnectedCardMandateMerchant, type ConnectedCardReference, ConnectedCardsClient, Conto, ContoAdmin, type ContoAdminConfig, ContoAdminError, type ContoConfig, ContoError, type ContoRequestOptions, type ControlledExternalCardPaymentResult, ControlledExternalCardPaymentTool, type CreateAgentInput, type CreatePolicyInput, type CreatePolicyRuleInput, type CreateSdkKeyInput, type CreateSdkKeyResult, type CreateWalletInput, type CustodyType, type CustomerCustodyMode, type CustomerWalletControlModel, type CustomerWalletKeyAccess, type DelegationType, type ExecuteCommerceExecutionResult, type ExternalCard, type ExternalCardApprovalInput, type ExternalCardApprovalResult, type ExternalCardConfirmationInput, ExternalCardConfirmationPendingError, type ExternalCardConfirmationResult, type ExternalCardExecutionClaimResult, type ExternalCardExecutionResult, type ExternalCardExecutor, type ExternalCardOverlayEnforcement, type ExternalCardRequestStatusResult, type ExternalWalletApprovalInput, type ExternalWalletApprovalResult, type ExternalWalletConfirmationInput, type ExternalWalletConfirmationResult, type FreezeAgentInput, Conto as Giro, type ContoConfig as GiroConfig, ContoError as GiroError, type GuardCheckoutResult, type GuardedBrowserDispatchResult, type GuardedCheckoutInput, type LinkWalletInput, type ListAgentsParams, type ListAgentsResponse, type ListPoliciesParams, type ListPoliciesResponse, type ListPolicyVersionsResponse, type ListStripeLinkPaymentMethodsResult, type ListWalletsParams, type ListWalletsResponse, type MppBudgetResult, type MppPreAuthorizeInput, type MppPreAuthorizeResult, type MppRecordInput, type MppRecordResult, type NormalizeCommerceProposalInput, type OrganizationMember, type PaginatedResponse, type PaginationParams, type PauseExternalCardAssignmentResult, type PaymentExecuteResult, type PaymentRequestInput, type PaymentRequestResult, type PaymentStatusResult, type Policy, type PolicyRule, type PolicyType, type PolicyVersionChangeType, type PolicyVersionDetail, type PolicyVersionDiff, type PolicyVersionFieldChange, type PolicyVersionSnapshot, type PolicyVersionSnapshotRule, type PolicyVersionSummary, type PrivilegedBrowserCheckoutDriver, type ProtocolBudgetResult, type ProtocolPreAuthorizeResult, type ProtocolRecordGrant, type ProtocolRecordGrantResult, type ProtocolServiceSummary, type ProtocolServicesResult, type ProvisionWalletResult, type RefreshBalanceResult, type RegisterExternalCardInput, type RollbackPolicyVersionResponse, type RuleAction, type RuleOperator, type RuleType, type RunGuardedCheckoutResult, type SdkKey, type SdkKeyType, type StripeLinkCheckoutReadiness, type StripeLinkCheckoutReadinessResult, type StripeLinkCheckoutReadinessStatus, type StripeLinkCheckoutVerification, type StripeLinkPaymentMethod, type UnfreezeAgentInput, type UpdateAgentInput, type UpdateExternalCardAssignmentInput, type UpdatePolicyInput, type UpdatePolicyRuleInput, type UpdateWalletInput, type VerifiedBrowserCheckoutTarget, type Wallet, type WalletChainBalanceSnapshot, type WalletStatus, type WalletType, type X402Authorization, type X402BudgetResult, type X402PayInput, type X402PayResult, type X402PaymentRequirements, type X402PreAuthorizeInput, type X402PreAuthorizeResult, type X402RecordInput, type X402RecordResult, canonicalizeBrowserCheckoutTarget, createVerifiedBrowserCheckoutDriver, Conto as default, fingerprintBrowserCheckoutTarget };

package/dist/index.d.ts

@@ -1131,7 +1131,7 @@ interface PaymentRequestResult {
     /** Unique request ID - use this to execute or check status */
     requestId: string;
     /** Current status */
-    status: 'APPROVED' | 'DENIED' | 'REQUIRES_APPROVAL' | 'ACTION_REQUIRED' | 'PROCESSING';
+    status: 'APPROVED' | 'DENIED' | 'REQUIRES_APPROVAL' | 'PROCESSING';
     /** Requested amount */
     amount: number;
     /** Currency selected for the payment */
@@ -1187,7 +1187,7 @@ interface PaymentStatusResult {
     requestId: string;
     /** Unknown for legacy records without execution evidence, or before execution. */
     settlementMode: 'live' | 'test' | 'unknown';
-    status: 'approved' | 'declined' | 'review_required' | 'action_required' | 'reconciliation_required' | 'processing' | 'completed' | 'failed' | 'expired';
+    status: 'approved' | 'declined' | 'review_required' | 'reconciliation_required' | 'processing' | 'completed' | 'failed' | 'expired';
     amount: number;
     currency: string;
     recipient: string;
@@ -1196,10 +1196,7 @@ interface PaymentStatusResult {
     category: string | null;
     expiresAt: string | null;
     createdAt: string;
-    action: {
-        type: 'complete_verification';
-        url: string;
-    } | null;
+    action: null;
     transaction: {
         /** Stable Conto transaction ID */
         id: string;
@@ -1858,6 +1855,31 @@ interface ProtocolPreAuthorizeResult {
     authorized: boolean;
     decision: 'approved' | 'declined' | 'review_required';
     message: 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.
+     */
+    grantId?: string;
+    grantSignature?: string;
+    /** ISO timestamp. Record the payment before this time. */
+    grantExpiresAt?: string;
+}
+interface ProtocolRecordGrant {
+    /** grantId from the approved preAuthorize() response. */
+    grantId?: string;
+    /** grantSignature from the approved preAuthorize() response. */
+    grantSignature?: string;
+}
+interface ProtocolRecordGrantResult {
+    /** Grant consumed by this record. */
+    grantId?: string;
+    /** True when the payment was recorded without a valid grant. */
+    policyBypass?: true;
+    bypassReason?: 'GRANT_MISSING' | 'GRANT_INVALID' | 'GRANT_EXPIRED';
+    /** True when the organization freezes agents on bypass and this record froze it. */
+    agentFrozen?: boolean;
 }
 interface X402PreAuthorizeInput {
     amount: number;
@@ -1884,7 +1906,55 @@ interface X402PreAuthorizeResult extends ProtocolPreAuthorizeResult {
         sessionId?: string;
     };
 }
-interface X402RecordInput {
+/** The accepted entry from a 402 challenge (x402 "exact" scheme on EVM). */
+interface X402PaymentRequirements {
+    scheme: 'exact' | (string & {});
+    /** Network as the challenge sent it: CAIP-2 (eip155:8453) or an x402 v1 name (base). */
+    network: string;
+    /** v1: amount in token base units, as an integer string. */
+    maxAmountRequired?: string;
+    /** v2: amount in token base units, as an integer string. */
+    amount?: string;
+    /** Token contract. Conto signs only for managed USDC. */
+    asset: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    resource?: string;
+    /** EIP-712 domain of the token. */
+    extra?: {
+        name?: string;
+        version?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+interface X402PayInput extends X402PreAuthorizeInput {
+    /** x402 protocol version of the challenge. Defaults to 1. */
+    x402Version?: 1 | 2;
+    paymentRequirements: X402PaymentRequirements;
+}
+interface X402Authorization {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+}
+interface X402PayResult extends ProtocolPreAuthorizeResult {
+    x402: {
+        serviceDomain?: string;
+        amount: number;
+        sessionId?: string;
+    };
+    /** Present when authorized: send as this header when retrying the resource request. */
+    paymentHeaderName?: 'X-PAYMENT' | 'PAYMENT-SIGNATURE';
+    /** Present when authorized: base64 payment payload signed by Conto. */
+    xPaymentHeader?: string;
+    /** Present when authorized: the EIP-3009 authorization Conto signed. */
+    authorization?: X402Authorization;
+}
+interface X402RecordInput extends ProtocolRecordGrant {
     amount: number;
     currency?: string;
     recipientAddress: string;
@@ -1908,7 +1978,7 @@ interface X402RecordInput {
         paymentId: string;
     }>;
 }
-interface X402RecordResult {
+interface X402RecordResult extends ProtocolRecordGrantResult {
     recorded: true;
     confirmed: true;
     txHash: string;
@@ -1939,7 +2009,7 @@ interface MppPreAuthorizeResult extends ProtocolPreAuthorizeResult {
         sessionId?: string;
     };
 }
-interface MppRecordInput {
+interface MppRecordInput extends ProtocolRecordGrant {
     amount: number;
     currency?: string;
     recipientAddress: string;
@@ -1965,7 +2035,7 @@ interface MppRecordInput {
         credentialId: string;
     }>;
 }
-interface MppRecordResult {
+interface MppRecordResult extends ProtocolRecordGrantResult {
     recorded: true;
     txHash?: string;
     explorerUrl?: string;
@@ -2359,6 +2429,16 @@ declare class X402Client {
     private client;
     constructor(client: Conto);
     preAuthorize(input: X402PreAuthorizeInput): Promise<X402PreAuthorizeResult>;
+    /**
+     * Conto-signed x402 for Privy-managed EVM wallets. Conto evaluates the
+     * payment exactly like preAuthorize() and, only when approved, signs the
+     * EIP-3009 authorization for the approved payee and amount. Retry the
+     * resource request with `paymentHeaderName: xPaymentHeader`, then call
+     * record() with the returned grant. Not retried automatically: a grant is
+     * signed at most once, and a repeat returns 409 GRANT_ALREADY_SIGNED.
+     * External wallets get 409 MANAGED_SIGNING_UNAVAILABLE; use preAuthorize().
+     */
+    pay(input: X402PayInput): Promise<X402PayResult>;
     record(input: X402RecordInput): Promise<X402RecordResult>;
     budget(options?: {
         sessionId?: string;
@@ -2382,4 +2462,4 @@ declare class MppClient {
     }): Promise<ProtocolServicesResult>;
 }
 
-export { type AdminExternalCardOverlayEnforcement, type Agent, type AgentCheckoutAction, type AgentCheckoutActionKind, type AgentExternalCard, type AgentSetupResult, type AgentStatus, type AgentType, type AgentWalletLink, type ApprovedExternalCardExecution, type AssignExternalCardInput, type AssignedPolicy, type AuthorizeCheckoutActionResult, type BeginCommerceExecutionInput, type BrowserActionClaimResult, type BrowserActionDispatchObservationInput, BrowserActionFinalizationPendingError, type BrowserActionFinalizeResult, type BrowserCheckoutAction, type BrowserCheckoutTargetResolver, type BrowserCheckoutTargetSnapshot, type BrowserCheckoutTargetVerificationCode, BrowserCheckoutTargetVerificationError, type CanonicalBrowserCheckoutTargetSnapshot, CardsClient, type ChainType, type CheckoutActionAuthorization, type CommerceCheckoutMethod, type CommerceContextRequirement, type CommerceExecution, type CommerceExecutionAdapterKind, type CommerceExecutionArtifactKind, type CommerceExecutionChannel, type CommerceExecutionConstraint, type CommerceExecutionConstraintCoverage, type CommerceExecutionConstraintCoverageLevel, type CommerceExecutionDeliveryMode, type CommerceExecutionEvidence, type CommerceExecutionProvider, type CommerceExecutionResult, type CommerceExecutionSourceKind, type CommerceExecutionStatus, type CommerceFactConfidence, type CommerceFactProvenanceInput, type CommerceFactSource, type CommerceFulfillmentInput, type CommerceLineItemInput, type CommerceProposalFactKey, type CommerceProposalMissingFact, type CommerceProposalResolution, type CommerceProposalState, type CommerceSettlementRail, type CommerceTotalInput, type CommerceTotalType, type ComparePolicyVersionsResponse, type ConnectedCardBrief, type ConnectedCardCredential, type ConnectedCardDrawInput, type ConnectedCardDrawMerchant, type ConnectedCardDrawResult, type ConnectedCardDrawable, type ConnectedCardListResult, type ConnectedCardMandate, type ConnectedCardMandateMerchant, type ConnectedCardReference, ConnectedCardsClient, Conto, ContoAdmin, type ContoAdminConfig, ContoAdminError, type ContoConfig, ContoError, type ContoRequestOptions, type ControlledExternalCardPaymentResult, ControlledExternalCardPaymentTool, type CreateAgentInput, type CreatePolicyInput, type CreatePolicyRuleInput, type CreateSdkKeyInput, type CreateSdkKeyResult, type CreateWalletInput, type CustodyType, type CustomerCustodyMode, type CustomerWalletControlModel, type CustomerWalletKeyAccess, type DelegationType, type ExecuteCommerceExecutionResult, type ExternalCard, type ExternalCardApprovalInput, type ExternalCardApprovalResult, type ExternalCardConfirmationInput, ExternalCardConfirmationPendingError, type ExternalCardConfirmationResult, type ExternalCardExecutionClaimResult, type ExternalCardExecutionResult, type ExternalCardExecutor, type ExternalCardOverlayEnforcement, type ExternalCardRequestStatusResult, type ExternalWalletApprovalInput, type ExternalWalletApprovalResult, type ExternalWalletConfirmationInput, type ExternalWalletConfirmationResult, type FreezeAgentInput, Conto as Giro, type ContoConfig as GiroConfig, ContoError as GiroError, type GuardCheckoutResult, type GuardedBrowserDispatchResult, type GuardedCheckoutInput, type LinkWalletInput, type ListAgentsParams, type ListAgentsResponse, type ListPoliciesParams, type ListPoliciesResponse, type ListPolicyVersionsResponse, type ListStripeLinkPaymentMethodsResult, type ListWalletsParams, type ListWalletsResponse, type MppBudgetResult, type MppPreAuthorizeInput, type MppPreAuthorizeResult, type MppRecordInput, type MppRecordResult, type NormalizeCommerceProposalInput, type OrganizationMember, type PaginatedResponse, type PaginationParams, type PauseExternalCardAssignmentResult, type PaymentExecuteResult, type PaymentRequestInput, type PaymentRequestResult, type PaymentStatusResult, type Policy, type PolicyRule, type PolicyType, type PolicyVersionChangeType, type PolicyVersionDetail, type PolicyVersionDiff, type PolicyVersionFieldChange, type PolicyVersionSnapshot, type PolicyVersionSnapshotRule, type PolicyVersionSummary, type PrivilegedBrowserCheckoutDriver, type ProtocolBudgetResult, type ProtocolPreAuthorizeResult, type ProtocolServiceSummary, type ProtocolServicesResult, type ProvisionWalletResult, type RefreshBalanceResult, type RegisterExternalCardInput, type RollbackPolicyVersionResponse, type RuleAction, type RuleOperator, type RuleType, type RunGuardedCheckoutResult, type SdkKey, type SdkKeyType, type StripeLinkCheckoutReadiness, type StripeLinkCheckoutReadinessResult, type StripeLinkCheckoutReadinessStatus, type StripeLinkCheckoutVerification, type StripeLinkPaymentMethod, type UnfreezeAgentInput, type UpdateAgentInput, type UpdateExternalCardAssignmentInput, type UpdatePolicyInput, type UpdatePolicyRuleInput, type UpdateWalletInput, type VerifiedBrowserCheckoutTarget, type Wallet, type WalletChainBalanceSnapshot, type WalletStatus, type WalletType, type X402BudgetResult, type X402PreAuthorizeInput, type X402PreAuthorizeResult, type X402RecordInput, type X402RecordResult, canonicalizeBrowserCheckoutTarget, createVerifiedBrowserCheckoutDriver, Conto as default, fingerprintBrowserCheckoutTarget };
+export { type AdminExternalCardOverlayEnforcement, type Agent, type AgentCheckoutAction, type AgentCheckoutActionKind, type AgentExternalCard, type AgentSetupResult, type AgentStatus, type AgentType, type AgentWalletLink, type ApprovedExternalCardExecution, type AssignExternalCardInput, type AssignedPolicy, type AuthorizeCheckoutActionResult, type BeginCommerceExecutionInput, type BrowserActionClaimResult, type BrowserActionDispatchObservationInput, BrowserActionFinalizationPendingError, type BrowserActionFinalizeResult, type BrowserCheckoutAction, type BrowserCheckoutTargetResolver, type BrowserCheckoutTargetSnapshot, type BrowserCheckoutTargetVerificationCode, BrowserCheckoutTargetVerificationError, type CanonicalBrowserCheckoutTargetSnapshot, CardsClient, type ChainType, type CheckoutActionAuthorization, type CommerceCheckoutMethod, type CommerceContextRequirement, type CommerceExecution, type CommerceExecutionAdapterKind, type CommerceExecutionArtifactKind, type CommerceExecutionChannel, type CommerceExecutionConstraint, type CommerceExecutionConstraintCoverage, type CommerceExecutionConstraintCoverageLevel, type CommerceExecutionDeliveryMode, type CommerceExecutionEvidence, type CommerceExecutionProvider, type CommerceExecutionResult, type CommerceExecutionSourceKind, type CommerceExecutionStatus, type CommerceFactConfidence, type CommerceFactProvenanceInput, type CommerceFactSource, type CommerceFulfillmentInput, type CommerceLineItemInput, type CommerceProposalFactKey, type CommerceProposalMissingFact, type CommerceProposalResolution, type CommerceProposalState, type CommerceSettlementRail, type CommerceTotalInput, type CommerceTotalType, type ComparePolicyVersionsResponse, type ConnectedCardBrief, type ConnectedCardCredential, type ConnectedCardDrawInput, type ConnectedCardDrawMerchant, type ConnectedCardDrawResult, type ConnectedCardDrawable, type ConnectedCardListResult, type ConnectedCardMandate, type ConnectedCardMandateMerchant, type ConnectedCardReference, ConnectedCardsClient, Conto, ContoAdmin, type ContoAdminConfig, ContoAdminError, type ContoConfig, ContoError, type ContoRequestOptions, type ControlledExternalCardPaymentResult, ControlledExternalCardPaymentTool, type CreateAgentInput, type CreatePolicyInput, type CreatePolicyRuleInput, type CreateSdkKeyInput, type CreateSdkKeyResult, type CreateWalletInput, type CustodyType, type CustomerCustodyMode, type CustomerWalletControlModel, type CustomerWalletKeyAccess, type DelegationType, type ExecuteCommerceExecutionResult, type ExternalCard, type ExternalCardApprovalInput, type ExternalCardApprovalResult, type ExternalCardConfirmationInput, ExternalCardConfirmationPendingError, type ExternalCardConfirmationResult, type ExternalCardExecutionClaimResult, type ExternalCardExecutionResult, type ExternalCardExecutor, type ExternalCardOverlayEnforcement, type ExternalCardRequestStatusResult, type ExternalWalletApprovalInput, type ExternalWalletApprovalResult, type ExternalWalletConfirmationInput, type ExternalWalletConfirmationResult, type FreezeAgentInput, Conto as Giro, type ContoConfig as GiroConfig, ContoError as GiroError, type GuardCheckoutResult, type GuardedBrowserDispatchResult, type GuardedCheckoutInput, type LinkWalletInput, type ListAgentsParams, type ListAgentsResponse, type ListPoliciesParams, type ListPoliciesResponse, type ListPolicyVersionsResponse, type ListStripeLinkPaymentMethodsResult, type ListWalletsParams, type ListWalletsResponse, type MppBudgetResult, type MppPreAuthorizeInput, type MppPreAuthorizeResult, type MppRecordInput, type MppRecordResult, type NormalizeCommerceProposalInput, type OrganizationMember, type PaginatedResponse, type PaginationParams, type PauseExternalCardAssignmentResult, type PaymentExecuteResult, type PaymentRequestInput, type PaymentRequestResult, type PaymentStatusResult, type Policy, type PolicyRule, type PolicyType, type PolicyVersionChangeType, type PolicyVersionDetail, type PolicyVersionDiff, type PolicyVersionFieldChange, type PolicyVersionSnapshot, type PolicyVersionSnapshotRule, type PolicyVersionSummary, type PrivilegedBrowserCheckoutDriver, type ProtocolBudgetResult, type ProtocolPreAuthorizeResult, type ProtocolRecordGrant, type ProtocolRecordGrantResult, type ProtocolServiceSummary, type ProtocolServicesResult, type ProvisionWalletResult, type RefreshBalanceResult, type RegisterExternalCardInput, type RollbackPolicyVersionResponse, type RuleAction, type RuleOperator, type RuleType, type RunGuardedCheckoutResult, type SdkKey, type SdkKeyType, type StripeLinkCheckoutReadiness, type StripeLinkCheckoutReadinessResult, type StripeLinkCheckoutReadinessStatus, type StripeLinkCheckoutVerification, type StripeLinkPaymentMethod, type UnfreezeAgentInput, type UpdateAgentInput, type UpdateExternalCardAssignmentInput, type UpdatePolicyInput, type UpdatePolicyRuleInput, type UpdateWalletInput, type VerifiedBrowserCheckoutTarget, type Wallet, type WalletChainBalanceSnapshot, type WalletStatus, type WalletType, type X402Authorization, type X402BudgetResult, type X402PayInput, type X402PayResult, type X402PaymentRequirements, type X402PreAuthorizeInput, type X402PreAuthorizeResult, type X402RecordInput, type X402RecordResult, canonicalizeBrowserCheckoutTarget, createVerifiedBrowserCheckoutDriver, Conto as default, fingerprintBrowserCheckoutTarget };

package/dist/index.js

@@ -39,7 +39,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@conto_finance/sdk",
-      version: "0.4.0",
+      version: "0.5.0",
       description: "Conto SDK for AI agent payment authorization",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
@@ -1880,15 +1880,6 @@ var PaymentsClient = class {
         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",
@@ -1912,6 +1903,22 @@ var X402Client = class {
       { idempotent: true }
     );
   }
+  /**
+   * Conto-signed x402 for Privy-managed EVM wallets. Conto evaluates the
+   * payment exactly like preAuthorize() and, only when approved, signs the
+   * EIP-3009 authorization for the approved payee and amount. Retry the
+   * resource request with `paymentHeaderName: xPaymentHeader`, then call
+   * record() with the returned grant. Not retried automatically: a grant is
+   * signed at most once, and a repeat returns 409 GRANT_ALREADY_SIGNED.
+   * External wallets get 409 MANAGED_SIGNING_UNAVAILABLE; use preAuthorize().
+   */
+  async pay(input) {
+    return this.client.request(
+      "POST",
+      "/api/sdk/x402/pay",
+      input
+    );
+  }
   async record(input) {
     const paymentId = requireFinancialIdentifier(input.paymentId, "paymentId");
     const requestInput = {

package/dist/index.mjs

@@ -14,7 +14,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@conto_finance/sdk",
-      version: "0.4.0",
+      version: "0.5.0",
       description: "Conto SDK for AI agent payment authorization",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
@@ -1719,15 +1719,6 @@ var PaymentsClient = class {
         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",
@@ -1751,6 +1742,22 @@ var X402Client = class {
       { idempotent: true }
     );
   }
+  /**
+   * Conto-signed x402 for Privy-managed EVM wallets. Conto evaluates the
+   * payment exactly like preAuthorize() and, only when approved, signs the
+   * EIP-3009 authorization for the approved payee and amount. Retry the
+   * resource request with `paymentHeaderName: xPaymentHeader`, then call
+   * record() with the returned grant. Not retried automatically: a grant is
+   * signed at most once, and a repeat returns 409 GRANT_ALREADY_SIGNED.
+   * External wallets get 409 MANAGED_SIGNING_UNAVAILABLE; use preAuthorize().
+   */
+  async pay(input) {
+    return this.client.request(
+      "POST",
+      "/api/sdk/x402/pay",
+      input
+    );
+  }
   async record(input) {
     const paymentId = requireFinancialIdentifier(input.paymentId, "paymentId");
     const requestInput = {

package/package.json

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