@conto_finance/sdk 0.3.1 → 0.5.0

package/dist/index.d.mts

@@ -5,6 +5,11 @@ interface ApiErrorMetadata {
     retryAfter?: number;
     retryGuidance?: string;
     actionUrl?: string;
+    fieldErrors?: Array<{
+        field: string;
+        message: string;
+    }>;
+    reasons?: string[];
 }
 
 /**
@@ -68,6 +73,8 @@ type AgentAttestationMode = 'KEY_ONLY' | 'SIGNED_REQUEST' | 'SIGNED_REQUEST_WITH
 type DelegationType = 'FULL' | 'LIMITED' | 'VIEW_ONLY' | 'PREAPPROVED' | 'ALLOWLIST';
 type ChainType = 'EVM' | 'SOLANA';
 type CustomerCustodyMode = 'MANAGED' | 'EXTERNAL' | 'SMART_CONTRACT';
+type CustomerWalletControlModel = 'CONTO_MANAGED' | 'ORGANIZATION_CONTROLLED' | 'EXTERNAL' | 'CONTRACT_ENFORCED';
+type CustomerWalletKeyAccess = 'NO_SELF_SERVICE_EXPORT' | 'OWNER_AUTHORIZED_EXPORT' | 'EXPORT_RECONCILIATION_REQUIRED' | 'CUSTOMER_CONTROLLED' | 'CONTRACT_ADMINISTRATED' | 'EXPORTED';
 /** @deprecated Use CustomerCustodyMode. */
 type CustodyType = CustomerCustodyMode;
 type WalletType = 'EOA' | 'SMART_WALLET' | 'MULTISIG';
@@ -190,6 +197,8 @@ interface AgentWalletLink {
         usdcBalance: number;
         status: string;
         custodyMode?: CustomerCustodyMode;
+        controlModel?: CustomerWalletControlModel;
+        keyAccess?: CustomerWalletKeyAccess;
     };
     createdAt: string;
     updatedAt: string;
@@ -439,6 +448,8 @@ interface Wallet {
     chainId: string;
     walletType: WalletType;
     custodyMode: CustomerCustodyMode;
+    controlModel: CustomerWalletControlModel;
+    keyAccess: CustomerWalletKeyAccess;
     usdcBalance: number;
     status: WalletStatus;
     createdAt: string;
@@ -450,6 +461,8 @@ interface CreateWalletInput {
     chainType?: ChainType;
     chainId?: string;
     custodyMode?: Extract<CustomerCustodyMode, 'MANAGED' | 'EXTERNAL'>;
+    /** Root authority for a newly created managed wallet. */
+    controlModel?: Extract<CustomerWalletControlModel, 'CONTO_MANAGED' | 'ORGANIZATION_CONTROLLED'>;
     walletType?: WalletType;
     address?: string;
 }
@@ -476,6 +489,8 @@ interface ProvisionWalletResult {
         chainId: string;
         chainType: string;
         custodyMode: CustomerCustodyMode;
+        controlModel?: CustomerWalletControlModel;
+        keyAccess?: CustomerWalletKeyAccess;
         balance: number;
         currency: string;
     };
@@ -569,6 +584,94 @@ interface UpdatePolicyRuleInput {
     value?: string;
     action?: RuleAction;
 }
+type PolicyVersionChangeType = 'CREATED' | 'UPDATED' | 'RULES_CHANGED' | 'ROLLED_BACK';
+interface PolicyVersionSnapshotRule {
+    ruleType: string;
+    operator: string;
+    value: string;
+    action: string;
+}
+interface PolicyVersionSnapshot {
+    name: string;
+    description: string | null;
+    policyType: string;
+    scope: 'organization' | 'assigned';
+    priority: number;
+    isActive: boolean;
+    rules: PolicyVersionSnapshotRule[];
+}
+interface PolicyVersionSummary {
+    version: number;
+    changeType: PolicyVersionChangeType;
+    note: string | null;
+    createdBy: string | null;
+    createdByType: string | null;
+    createdAt: string;
+    rulesCount: number;
+}
+interface PolicyVersionDetail extends Omit<PolicyVersionSummary, 'rulesCount'> {
+    snapshot: PolicyVersionSnapshot;
+}
+interface ListPolicyVersionsResponse {
+    versions: PolicyVersionSummary[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface PolicyVersionFieldChange {
+    field: string;
+    from: unknown;
+    to: unknown;
+}
+interface PolicyVersionDiff {
+    fields: PolicyVersionFieldChange[];
+    rulesAdded: PolicyVersionSnapshotRule[];
+    rulesRemoved: PolicyVersionSnapshotRule[];
+    unchanged: boolean;
+}
+interface ComparePolicyVersionsResponse {
+    from: number;
+    to: number;
+    diff: PolicyVersionDiff;
+}
+interface RollbackPolicyVersionResponse extends Policy {
+    restoredFromVersion: number;
+    newVersion: number | null;
+}
+type StripeLinkCheckoutReadinessStatus = 'NOT_READY' | 'READY_FOR_VERIFICATION' | 'VERIFIED' | 'VERIFICATION_FAILED';
+type StripeLinkCheckoutVerification = 'NOT_RUN' | 'NOT_READY' | 'VERIFIED' | 'ACCOUNT_MISMATCH' | 'PROVIDER_UNAVAILABLE';
+/**
+ * Non-identifying readiness projection for the configured Stripe Link
+ * Checkout adapter. Merchant/account identifiers, URLs, credentials, hashes,
+ * Stripe objects, and raw provider errors are intentionally absent.
+ */
+interface StripeLinkCheckoutReadiness {
+    readonly status: StripeLinkCheckoutReadinessStatus;
+    readonly mode: 'TEST' | 'LIVE' | null;
+    readonly checks: {
+        readonly providerEnabled: boolean;
+        readonly checkoutEnabled: boolean;
+        readonly organizationAllowed: boolean;
+        readonly configurationValid: boolean;
+        readonly accountVerified: boolean;
+    };
+    readonly canVerify: boolean;
+    readonly verifiedAt: string | null;
+    readonly verification: StripeLinkCheckoutVerification;
+    readonly scope: {
+        readonly configuredMerchantCheckoutOnly: true;
+        readonly statement: string;
+    };
+    readonly link: {
+        readonly eligibilityGuaranteed: false;
+        readonly displayGuaranteed: false;
+        readonly selectionGuaranteed: false;
+        readonly statement: string;
+    };
+}
+interface StripeLinkCheckoutReadinessResult {
+    readonly readiness: StripeLinkCheckoutReadiness;
+}
 declare class ContoAdmin {
     private orgApiKey;
     private baseUrl;
@@ -578,10 +681,22 @@ declare class ContoAdmin {
     cards: AdminCardsClient;
     policies: PoliciesClient;
     team: TeamClient;
+    paymentRails: PaymentRailsClient;
     constructor(config: ContoAdminConfig);
     /** Make an authenticated request to the Conto API */
     request<T>(method: string, path: string, body?: Record<string, unknown>): Promise<T>;
 }
+declare class PaymentRailsClient {
+    private client;
+    constructor(client: ContoAdmin);
+    /** Read gate and configuration readiness without calling Stripe. */
+    getStripeLinkCheckoutReadiness(): Promise<StripeLinkCheckoutReadinessResult>;
+    /**
+     * Ask Conto to verify that its configured Stripe credential resolves to its
+     * configured merchant account. This call never returns either identifier.
+     */
+    verifyStripeLinkCheckoutAccount(): Promise<StripeLinkCheckoutReadinessResult>;
+}
 declare class AdminCardsClient {
     private client;
     constructor(client: ContoAdmin);
@@ -752,6 +867,20 @@ declare class PoliciesClient {
         success: boolean;
         deletedCount: number;
     }>;
+    /** List the version history for a policy (newest first). */
+    listVersions(policyId: string, params?: PaginationParams): Promise<ListPolicyVersionsResponse>;
+    /** Get a single version's snapshot. */
+    getVersion(policyId: string, version: number): Promise<PolicyVersionDetail>;
+    /** Diff two versions of a policy. */
+    compareVersions(policyId: string, from: number, to: number): Promise<ComparePolicyVersionsResponse>;
+    /**
+     * Restore an earlier version. Appends a new ROLLED_BACK version. If the
+     * organization requires governance approval for policy changes, the API
+     * returns a pending-approval response instead of applying the rollback.
+     */
+    rollbackVersion(policyId: string, version: number, options?: {
+        note?: string;
+    }): Promise<RollbackPolicyVersionResponse>;
 }
 declare class TeamClient {
     private client;
@@ -762,6 +891,68 @@ declare class TeamClient {
     }>;
 }
 
+type BrowserCheckoutTargetVerificationCode = 'BROWSER_CHECKOUT_TARGET_INVALID' | 'BROWSER_CHECKOUT_TARGET_NOT_FOUND' | 'BROWSER_CHECKOUT_TARGET_CHANGED' | 'BROWSER_CHECKOUT_TARGET_DISABLED';
+declare class BrowserCheckoutTargetVerificationError extends Error {
+    readonly code: BrowserCheckoutTargetVerificationCode;
+    constructor(code: BrowserCheckoutTargetVerificationCode, message: string);
+}
+/**
+ * Credential-free description of one payment-sensitive DOM target. The
+ * snapshot is created during proposal discovery and recomputed by the
+ * privileged browser process immediately before dispatch.
+ */
+interface BrowserCheckoutTargetSnapshot {
+    /** Current top-level page URL. Fragments are ignored. */
+    pageUrl: string;
+    /** Runtime-owned exact locator identity, such as a stable DOM path. */
+    locator: string;
+    tagName: string;
+    role?: string;
+    accessibleName?: string;
+    /** Resolved navigation target for anchors or controls, when present. */
+    targetUrl?: string;
+    /** Resolved form submission target, when present. */
+    formAction?: string;
+    /** Whether the exact control declares a new browsing context such as target=_blank. */
+    opensNewPage?: boolean;
+    disabled: boolean;
+}
+interface VerifiedBrowserCheckoutTarget<T> {
+    snapshot: BrowserCheckoutTargetSnapshot;
+    /** Performs the one payment-sensitive side effect and observes its result. */
+    dispatch(): Promise<GuardedBrowserDispatchResult<T>>;
+}
+/** Port implemented inside the isolated browser process. */
+interface BrowserCheckoutTargetResolver<T> {
+    resolve(input: {
+        authorization: CheckoutActionAuthorization;
+        browserSessionId: string;
+        action: AgentCheckoutAction | BrowserCheckoutAction;
+    }): Promise<VerifiedBrowserCheckoutTarget<T> | null>;
+}
+interface CanonicalBrowserCheckoutTargetSnapshot {
+    pageUrl: string;
+    locator: string;
+    tagName: string;
+    role: string | null;
+    accessibleName: string | null;
+    targetUrl: string | null;
+    formAction: string | null;
+    opensNewPage: boolean;
+    disabled: boolean;
+}
+declare function canonicalizeBrowserCheckoutTarget(snapshot: BrowserCheckoutTargetSnapshot): CanonicalBrowserCheckoutTargetSnapshot;
+/**
+ * Generates the exact opaque fingerprint sent as action.targetFingerprint.
+ * The raw DOM locator and target details stay inside the customer runtime.
+ */
+declare function fingerprintBrowserCheckoutTarget(snapshot: BrowserCheckoutTargetSnapshot): string;
+/**
+ * Creates a driver that re-resolves and verifies the exact DOM target after
+ * Conto's one-use claim and before the payment-sensitive browser side effect.
+ */
+declare function createVerifiedBrowserCheckoutDriver<T>(resolver: BrowserCheckoutTargetResolver<T>): PrivilegedBrowserCheckoutDriver<T>;
+
 /**
  * Conto SDK
  *
@@ -837,11 +1028,110 @@ interface PaymentRequestInput {
     /** Client-supplied key for idempotent retries */
     idempotencyKey?: string;
 }
+interface AgentSetupResult {
+    agent: {
+        id: string;
+        name: string;
+        status: 'active' | 'paused' | 'unavailable';
+        lastActiveAt: string | null;
+        createdAt: string;
+    };
+    wallets: Array<{
+        id: string;
+        address: string;
+        custodyMode: CustomerCustodyMode;
+        chainId: string;
+        chainName: string;
+        chainType: string;
+        isTestnet: boolean;
+        balance: number;
+        currency: string;
+        status: 'active' | 'paused' | 'unavailable';
+        limits: {
+            perTransaction: number | null;
+            daily: number | null;
+            weekly: number | null;
+            monthly: number | null;
+        };
+        spent: {
+            today: number;
+            thisWeek: number;
+            thisMonth: number;
+        };
+    }>;
+    policies: Array<{
+        id: string;
+        name: string;
+        description: string | null;
+        scope: 'organization' | 'assigned';
+        appliesVia: string[];
+        walletIds: string[];
+    }>;
+    counterparties: Array<{
+        id: string;
+        name: string;
+        address: string;
+        category: string;
+        trustScore: number;
+        trustLevel: 'trusted' | 'verified' | 'blocked' | 'unverified';
+        transactionCount: number;
+        totalVolume: number;
+    }>;
+    scopes: string[];
+}
+interface ExternalWalletApprovalInput {
+    amount: number;
+    senderAddress: string;
+    recipientAddress: string;
+    /** Numeric chain ID accepted by the external approval endpoint. */
+    chainId: number | `${number}`;
+    recipientName?: string;
+    purpose?: string;
+    category?: string;
+    context?: PaymentRequestInput['context'];
+}
+interface ExternalWalletApprovalResult {
+    approved: boolean;
+    decision: 'approved' | 'review_required' | 'declined';
+    status: 'ready_to_send' | 'review_required' | 'declined';
+    /** Budget denials can occur before a request is created. */
+    approvalId?: string;
+    approvalToken?: string;
+    expiresAt?: string;
+    confirmUrl?: string;
+    statusUrl?: string;
+    approvalRequestId?: string;
+    reasons: string[];
+    reasonCodes: string[];
+    requiresHumanApproval: boolean;
+    network?: {
+        type: 'evm' | 'solana';
+        id: string;
+    };
+}
+interface ExternalWalletConfirmationInput {
+    txHash: string;
+    approvalToken?: string;
+}
+interface ExternalWalletConfirmationResult {
+    accepted: true;
+    confirmed: false;
+    requestId: string;
+    transactionId: string;
+    status: 'processing';
+    txHash: string;
+    network: {
+        type: 'evm' | 'solana';
+        id: string;
+    };
+    explorerUrl: string;
+    statusUrl: string;
+}
 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 */
@@ -864,7 +1154,8 @@ interface PaymentRequestResult {
     receipt?: {
         /** Stable Conto transaction ID for status checks and reconciliation */
         transactionId: string;
-        txHash: string;
+        /** Present only for an onchain transfer. Simulations use transactionId. */
+        txHash?: string;
         /** Whether this receipt represents live settlement or a test-mode payment */
         settlementMode: 'live' | 'test';
         explorerUrl?: string;
@@ -885,7 +1176,8 @@ interface PaymentExecuteResult {
     receipt: {
         /** Stable Conto transaction ID for status checks and reconciliation */
         transactionId: string;
-        txHash: string;
+        /** Present only for an onchain transfer. Simulations use transactionId. */
+        txHash?: string;
         /** Whether this receipt represents live settlement or a test-mode payment */
         settlementMode: 'live' | 'test';
         explorerUrl?: string;
@@ -893,7 +1185,9 @@ interface PaymentExecuteResult {
 }
 interface PaymentStatusResult {
     requestId: string;
-    status: 'approved' | 'declined' | 'review_required' | 'action_required' | 'reconciliation_required' | 'processing' | 'completed' | 'failed' | 'expired';
+    /** Unknown for legacy records without execution evidence, or before execution. */
+    settlementMode: 'live' | 'test' | 'unknown';
+    status: 'approved' | 'declined' | 'review_required' | 'reconciliation_required' | 'processing' | 'completed' | 'failed' | 'expired';
     amount: number;
     currency: string;
     recipient: string;
@@ -902,13 +1196,11 @@ 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;
+        settlementMode: 'live' | 'test' | 'unknown';
         txHash: string | null;
         status: 'processing' | 'completed' | 'failed';
         confirmedAt: string | null;
@@ -1039,6 +1331,8 @@ interface ExternalCardConfirmationResult {
  */
 interface ApprovedExternalCardExecution {
     requestId: string;
+    /** Stable purchase key to pass through to the customer payment processor. */
+    idempotencyKey: string;
     cardId: string;
     amount: number;
     currency: 'USD';
@@ -1063,10 +1357,529 @@ interface ControlledExternalCardPaymentResult<TReceipt = unknown> {
     confirmation: ExternalCardConfirmationResult;
     receipt: TReceipt;
 }
+interface ConnectedCardDrawMerchant {
+    /** Merchant name for policy evaluation. */
+    merchantName?: string;
+    /** Network merchant identifier. */
+    merchantId?: string;
+    /** Four-digit MCC string (e.g. "5411"). */
+    merchantCategory?: string;
+    /** Two- or three-letter country code. */
+    merchantCountry?: string;
+}
+interface ConnectedCardDrawInput {
+    /** Connected card id delegated to this agent. */
+    cardId: string;
+    /** Verified mandate id the draw is charged against. */
+    mandateId: string;
+    /**
+     * Stable 8 to 128 character key. The server is idempotent on this key: a
+     * replay of the same key returns the decision WITHOUT the credential, so
+     * reuse it only to reconcile the exact same draw, never to fetch the card
+     * material again.
+     */
+    idempotencyKey: string;
+    /** Integer amount in minor units (cents), greater than zero. */
+    amountMinor: number;
+    /** Only USD is supported. Defaults to USD. */
+    currency?: 'USD';
+    merchant: ConnectedCardDrawMerchant;
+}
+/**
+ * Live single-use card material returned by {@link ConnectedCardsClient.draw}.
+ *
+ * CREDENTIAL SAFETY (this is the product boundary): these fields are the real,
+ * usable card. They are returned exactly ONCE, on the successful mint, and can
+ * never be re-fetched. A replay of the same idempotencyKey returns the decision
+ * with no `credential`. Use these fields in-process at the intended merchant
+ * checkout only. Never log, print, serialize, persist, cache, or send them
+ * anywhere else. Do not place this object in an error, a Sentry breadcrumb, an
+ * analytics event, or any structured output that a host might record.
+ */
+interface ConnectedCardCredential {
+    /** The card number (PAN). Live card material. */
+    number: string;
+    /** The card security value. Live card material. */
+    securityValue: string;
+    expirationMonth: string;
+    expirationYear: string;
+    cardholderName?: string;
+}
+interface ConnectedCardDrawResult {
+    requestId: string;
+    /** True when this draw has issued a credential, including a replay without the secret. */
+    minted: boolean;
+    /** True when this call replayed a prior draw for the same idempotencyKey. */
+    replayed: boolean;
+    decision: 'APPROVED' | 'DENIED' | 'REQUIRES_APPROVAL';
+    reasons: string[];
+    /** Present when the draw outcome is ambiguous and needs reconciliation. */
+    reconciliationRequired?: boolean;
+    /**
+     * Live single-use card material. Present ONLY on a successful mint and
+     * returned exactly once. Absent on a replay, a denial, or a review decision.
+     * See {@link ConnectedCardCredential} for the handling rules.
+     */
+    credential?: ConnectedCardCredential;
+    /** Provider expiration of the one-time credential; present with a fresh credential. */
+    credentialExpiresAt?: string;
+}
+interface ConnectedCardMandateMerchant {
+    name: string | null;
+    categoryCode: string | null;
+    countryCode: string | null;
+    checkoutOrigin: string | null;
+}
+interface ConnectedCardMandate {
+    id: string;
+    providerReferenceId: string;
+    bindingId: string;
+    status: string;
+    verificationStatus: string;
+    amountMinor: number;
+    currency: string;
+    description: string;
+    merchant: ConnectedCardMandateMerchant;
+    expiresAt: string;
+    verifiedAt: string | null;
+    exhaustedAt: string | null;
+    revokedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ConnectedCardBrief {
+    last4: string;
+    brand: string | null;
+    fundingType: string;
+    cardType: string;
+    status: string;
+    spendLimitDaily: number | null;
+    spendLimitWeekly: number | null;
+    spendLimitMonthly: number | null;
+    spendLimitPerTx: number | null;
+}
+interface ConnectedCardReference {
+    id: string;
+    provider: string;
+    lifecycleState: string;
+    railStatus: string | null;
+}
+interface ConnectedCardDrawable {
+    bindingId: string;
+    agentId: string;
+    status: string;
+    cardId: string;
+    reference: ConnectedCardReference;
+    card: ConnectedCardBrief;
+    mandates: ConnectedCardMandate[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface ConnectedCardListResult {
+    /** Masked drawable cards and their active mandates. No PAN or provider token. */
+    cards: ConnectedCardDrawable[];
+}
+interface StripeLinkPaymentMethod {
+    id: string;
+    type: string;
+    isDefault: boolean;
+    displayLabel: string;
+    last4?: string;
+    eligibleCredentialTypes: string[];
+}
+interface ListStripeLinkPaymentMethodsResult {
+    /** Authenticated tenant context, returned so operators can verify a target before writes. */
+    organizationId: string;
+    connectionId: string;
+    /** Masked Link payment methods eligible for the bound agent. */
+    paymentMethods: StripeLinkPaymentMethod[];
+}
+type CommerceTotalType = 'subtotal' | 'tax' | 'total' | 'items_base_amount' | 'items_discount' | 'discount' | 'fulfillment' | 'shipping' | 'fee' | 'gift_wrap' | 'tip' | 'store_credit';
+interface CommerceLineItemInput {
+    name: string;
+    quantity: number;
+    unitAmountMinor: number;
+    description?: string;
+    sku?: string;
+    productUrl?: string;
+}
+interface CommerceTotalInput {
+    type: CommerceTotalType;
+    label: string;
+    amountMinor: number;
+}
+interface CommerceFulfillmentInput {
+    recipient?: string;
+    addressLine1?: string;
+    addressLine2?: string;
+    locality?: string;
+    region?: string;
+    postalCode?: string;
+    countryCode?: string;
+}
+/** Exact Stripe Link purchase intent evaluated and bound by Conto policy. */
+interface BeginCommerceExecutionCommonInput {
+    /** Stable key for this exact intent. Reuse it when reconciling or retrying begin. */
+    idempotencyKey: string;
+    intentId?: string;
+    /** Integer amount in minor units (cents). */
+    amountMinor: number;
+    currency: 'USD';
+    purpose: string;
+    /** Optional semantic policy category, such as OFFICE_SUPPLIES. */
+    category?: string;
+    cart: {
+        lineItems: CommerceLineItemInput[];
+        totals: CommerceTotalInput[];
+        fulfillment?: CommerceFulfillmentInput;
+    };
+    providerPresentation: {
+        approvalSummary: string;
+        lineItemLabels: string[];
+    };
+}
+type AgentCheckoutActionKind = 'INITIATE_CHECKOUT' | 'OPEN_LINK' | 'CONFIRM_PAYMENT' | 'PLACE_ORDER';
+interface BrowserCheckoutAction {
+    kind: AgentCheckoutActionKind;
+    checkoutMethod: CommerceCheckoutMethod;
+    pageUrl: string;
+    /** Runtime-generated fingerprint of the exact DOM/action target. */
+    targetFingerprint: string;
+    targetUrl?: string;
+    targetLabel?: string;
+}
+interface AgentCheckoutAction extends Omit<BrowserCheckoutAction, 'checkoutMethod'> {
+    /** @deprecated Compatibility marker for executionMethod: 'AGENT_CHECKOUT'. */
+    provider: 'STRIPE_LINK';
+    checkoutMethod?: CommerceCheckoutMethod;
+}
+type BeginConnectedLinkExecutionInput = BeginCommerceExecutionCommonInput & {
+    connectionId: string;
+    paymentMethodId: string;
+};
+type BeginCommerceExecutionInput = (BeginConnectedLinkExecutionInput & {
+    /** Primary path: the server resolves the immutable Stripe seller profile. */
+    executionMethod: 'STRIPE_PAYMENT_INTENT';
+    counterparty: {
+        canonicalId: string;
+        displayName: string;
+    };
+}) | (BeginConnectedLinkExecutionInput & {
+    /** Optional compatibility transport for a configured MPP merchant. */
+    executionMethod?: 'MPP';
+    counterparty: {
+        canonicalId: string;
+        displayName: string;
+        checkoutUrl: string;
+        mppNetworkId: string;
+    };
+}) | (BeginCommerceExecutionCommonInput & {
+    /** Public Stripe-hosted Checkout with Link offered when eligible. */
+    executionMethod: 'LINK_CHECKOUT';
+    counterparty: {
+        /** Identifier for the merchant profile configured by the Conto operator. */
+        canonicalId: string;
+    };
+}) | (BeginCommerceExecutionCommonInput & {
+    /** Merchant-independent guard for an exact privileged browser action. */
+    executionMethod: 'AGENT_CHECKOUT';
+    browserSessionId: string;
+    action: AgentCheckoutAction;
+    counterparty: {
+        canonicalId: string;
+        displayName: string;
+        checkoutUrl: string;
+    };
+}) | (BeginCommerceExecutionCommonInput & {
+    /** Provider-neutral guard for one exact privileged browser action. */
+    executionMethod: 'BROWSER_CHECKOUT';
+    browserSessionId: string;
+    action: BrowserCheckoutAction;
+    counterparty: {
+        canonicalId: string;
+        displayName: string;
+        checkoutUrl: string;
+    };
+});
+type CommerceExecutionStatus = 'DRAFT' | 'ACTION_REQUIRED' | 'AUTHORIZING' | 'AWAITING_APPROVAL' | 'READY' | 'PROCESSING' | 'SETTLED' | 'COMPLETED' | 'DENIED' | 'CANCELLED' | 'FAILED' | 'RETURNED' | 'EXPIRED' | 'NEEDS_RECONCILIATION';
+type CommerceExecutionProvider = 'STABLECOIN' | 'TOKENIZED_CARD' | 'STRIPE_LINK';
+type CommerceExecutionChannel = 'BROWSER' | 'MERCHANT_API' | 'CREDENTIAL_BROKER' | 'BANK_API' | 'WALLET_SIGNER';
+type CommerceCheckoutMethod = 'LINK' | 'CARD' | 'SHOP_PAY' | 'PAYPAL';
+type CommerceSettlementRail = 'CARD' | 'ACH' | 'WIRE' | 'STABLECOIN';
+type CommerceProposalState = 'DRAFT' | 'NEEDS_CONTEXT' | 'READY_FOR_POLICY' | 'CANCELLED';
+type CommerceProposalMissingFact = 'AGENT' | 'AMOUNT' | 'CURRENCY' | 'PURPOSE' | 'COUNTERPARTY_ID' | 'COUNTERPARTY_NAME' | 'CART_LINE_ITEMS' | 'CART_TOTAL' | 'PROVIDER_PRESENTATION';
+type CommerceFactSource = 'USER_ASSERTED' | 'AGENT_INFERRED' | 'BROWSER_OBSERVED' | 'MERCHANT_SIGNED' | 'PROVIDER_CONFIRMED' | 'ISSUER_CONFIRMED';
+type CommerceFactConfidence = 'LOW' | 'MEDIUM' | 'HIGH' | 'VERIFIED';
+type CommerceProposalFactKey = 'AMOUNT' | 'CURRENCY' | 'PURPOSE' | 'CATEGORY' | 'COUNTERPARTY' | 'CART' | 'EXECUTION';
+interface CommerceFactProvenanceInput {
+    source: CommerceFactSource;
+    confidence: CommerceFactConfidence;
+    observedAt?: string;
+    evidenceFingerprint?: string;
+}
+interface NormalizeCommerceProposalInput {
+    /** Stable caller-selected key for this evolving proposal. */
+    proposalKey: string;
+    proposalId?: string;
+    /** Zero for a caller-confirmed create, or the exact revision being replaced. */
+    expectedRevision?: number;
+    draft?: boolean;
+    amountMinor?: number;
+    maximumAmountMinor?: number;
+    currency?: string;
+    purpose?: string;
+    category?: string;
+    counterparty?: {
+        canonicalId?: string;
+        displayName?: string;
+        checkoutUrl?: string;
+    };
+    cart?: {
+        lineItems?: CommerceLineItemInput[];
+        totals?: CommerceTotalInput[];
+        fulfillment?: CommerceFulfillmentInput;
+    };
+    providerPresentation?: {
+        approvalSummary: string;
+        lineItemLabels: string[];
+    };
+    execution?: {
+        executionChannel?: CommerceExecutionChannel;
+        checkoutMethod?: CommerceCheckoutMethod;
+        settlementRail?: CommerceSettlementRail;
+    };
+    provenance?: Partial<Record<CommerceProposalFactKey, CommerceFactProvenanceInput>>;
+    /** Organization-registered semantic facts validated before policy evaluation. */
+    extensions?: Array<{
+        namespace: string;
+        value: unknown;
+    }>;
+}
+interface CommerceContextRequirement {
+    fact: CommerceProposalMissingFact;
+    reasonCode: `MISSING_${CommerceProposalMissingFact}`;
+    prompt: string;
+}
+interface CommerceProposalResolution {
+    proposal: {
+        id: string;
+        organizationId: string;
+        actorUserId: string;
+        agentId?: string;
+        state: CommerceProposalState;
+        amountMinor?: number;
+        maximumAmountMinor?: number;
+        currency?: string;
+        purpose?: string;
+        category?: string;
+        counterparty?: NormalizeCommerceProposalInput['counterparty'];
+        cart?: NormalizeCommerceProposalInput['cart'];
+        providerPresentation?: NormalizeCommerceProposalInput['providerPresentation'];
+        execution?: NormalizeCommerceProposalInput['execution'];
+        provenance: Partial<Record<CommerceProposalFactKey, CommerceFactProvenanceInput>>;
+        extensions: Array<{
+            namespace: string;
+            value: unknown;
+            schemaRevision?: number;
+            schemaFingerprint?: string;
+        }>;
+        missingFacts: CommerceProposalMissingFact[];
+    };
+    proposalFingerprint: string;
+    /** Durable, monotonically increasing proposal revision. */
+    revision: number;
+    /** True only when this request created the proposal head. */
+    created: boolean;
+    outcome: 'NEEDS_CONTEXT' | 'READY_FOR_POLICY';
+    requirements: CommerceContextRequirement[];
+    nextAction: 'COLLECT_CONTEXT' | 'BEGIN_POLICY_EVALUATION';
+}
+type CommerceExecutionAdapterKind = 'STABLECOIN' | 'TOKENIZED_CARD' | 'STRIPE_LINK' | 'LINK_CHECKOUT' | 'CHECKOUT_GUARD';
+type CommerceExecutionSourceKind = 'STABLECOIN_WALLET' | 'TOKENIZED_CARD' | 'STRIPE_LINK' | 'STRIPE_LINK_CHECKOUT' | 'AGENT_BROWSER_CHECKOUT';
+type CommerceExecutionArtifactKind = 'CARD' | 'LINK_PAY_TOKEN' | 'SHARED_PAYMENT_TOKEN';
+type CommerceExecutionDeliveryMode = 'SERVER_ONLY_ARTIFACT' | 'PROVIDER_DIRECT' | 'USER_INTERACTIVE';
+type CommerceExecutionConstraint = 'AMOUNT' | 'CURRENCY' | 'COUNTERPARTY' | 'CART' | 'PURPOSE' | 'EXPIRY' | 'SINGLE_USE';
+type CommerceExecutionConstraintCoverageLevel = 'UNSUPPORTED' | 'OBSERVE_ONLY' | 'CONTO_PRECHECK' | 'PROVIDER_ENFORCED';
+type CommerceExecutionConstraintCoverage = Readonly<Record<CommerceExecutionConstraint, CommerceExecutionConstraintCoverageLevel>>;
+/** Provider-independent, allowlisted evidence. It contains no Link credential material. */
+interface CommerceExecutionEvidence {
+    schemaVersion: 'conto.commerce-evidence.v1';
+    traceId: string;
+    executionId: string;
+    intentId: string;
+    organizationId: string;
+    actorUserId: string;
+    agentId?: string;
+    provider: CommerceExecutionProvider;
+    sourceKind: CommerceExecutionSourceKind;
+    amountMinor: number;
+    currency: string;
+    purpose: string;
+    counterpartyId: string;
+    counterpartyName: string;
+    intentFingerprint: string;
+    policyDecisionId: string;
+    policySnapshotHash: string;
+    grantId: string;
+    deliveryMode?: CommerceExecutionDeliveryMode;
+    artifactKind?: CommerceExecutionArtifactKind;
+    enforcementCoverage?: CommerceExecutionConstraintCoverage;
+    status: CommerceExecutionStatus;
+    providerStatus?: string;
+    providerReference?: string;
+    transactionReference?: string;
+    checkoutReference?: string;
+    /** Actual method observed after Stripe settlement; Link cannot be forced to display or win. */
+    actualPaymentMethod?: 'LINK' | 'CARD';
+    browserAction?: {
+        kind: AgentCheckoutActionKind;
+        provider: 'STRIPE_LINK';
+        checkoutMethod?: CommerceCheckoutMethod;
+        trustPolicyRevision?: number;
+        trustPolicyFingerprint?: string;
+        merchantOrigin: string;
+        actionFingerprint: string;
+    };
+    refund?: {
+        amountMinor: number;
+        currency: string;
+        state: string;
+    };
+}
+/** Safe execution projection. Raw provider responses and payment artifacts are excluded. */
+interface CommerceExecution {
+    id: string;
+    intentId: string;
+    organizationId: string;
+    agentId?: string;
+    provider: CommerceExecutionProvider;
+    /** Execution path selected before settlement; distinct from actualPaymentMethod. */
+    executionAdapter: CommerceExecutionAdapterKind;
+    /** Provider-neutral channel that must consume the Conto authorization. */
+    executionChannel: CommerceExecutionChannel;
+    /** Selected checkout method, or the method observed after a dynamic checkout settles. */
+    checkoutMethod?: CommerceCheckoutMethod;
+    /** Expected settlement rail when the current execution source establishes it. */
+    settlementRail?: CommerceSettlementRail;
+    status: CommerceExecutionStatus;
+    providerStatus?: string;
+    providerReference?: string;
+    /** Sanitized Link approval or Stripe-hosted Checkout URL. */
+    approvalUrl?: string;
+    artifactKind?: CommerceExecutionArtifactKind;
+    deliveryMode?: CommerceExecutionDeliveryMode;
+    amountMinor: number;
+    currency: string;
+    purpose: string;
+    category?: string;
+    counterparty: {
+        id: string;
+        name: string;
+    };
+    evidence: CommerceExecutionEvidence;
+    evidenceFingerprint: string;
+}
+interface CommerceExecutionResult {
+    execution: CommerceExecution;
+}
+interface ExecuteCommerceExecutionResult extends CommerceExecutionResult {
+    checkout: {
+        submitted: boolean;
+        deliveryMode: 'SERVER_ONLY_ARTIFACT';
+        accepted: boolean;
+    } | {
+        submitted: true;
+        deliveryMode: 'PROVIDER_DIRECT';
+    };
+}
+interface CheckoutActionAuthorization {
+    /** Durable single-use record consumed by the privileged browser runtime. */
+    authorizationId: string;
+    executionId: string;
+    browserSessionId: string;
+    grantId: string;
+    intentFingerprint: string;
+    actionFingerprint: string;
+    merchantOrigin: string;
+    actionKind: AgentCheckoutActionKind;
+    provider: 'STRIPE_LINK';
+    checkoutMethod?: CommerceCheckoutMethod;
+    expiresAt: string;
+    singleUse: true;
+}
+interface AuthorizeCheckoutActionResult extends CommerceExecutionResult {
+    authorization: CheckoutActionAuthorization;
+}
+interface BrowserActionClaimResult {
+    authorization: {
+        authorizationId: string;
+        state: 'DISPATCHING';
+        actionFingerprint: string;
+        expiresAt: string;
+    };
+}
+interface BrowserActionFinalizeResult {
+    authorization: {
+        authorizationId: string;
+        state: 'CONSUMED' | 'INDETERMINATE';
+    };
+}
+interface BrowserActionDispatchObservationInput {
+    reference: string;
+    observedAt: string;
+    pageUrl: string;
+}
+interface GuardCheckoutResult<T> extends AuthorizeCheckoutActionResult {
+    result: T;
+}
+interface GuardedBrowserDispatchResult<T> {
+    result: T;
+    observation: BrowserActionDispatchObservationInput;
+}
+type GuardedCheckoutInput = Extract<BeginCommerceExecutionInput, {
+    executionMethod: 'AGENT_CHECKOUT' | 'BROWSER_CHECKOUT';
+}>;
+/** Privileged runtime port; the agent model must not receive this driver directly. */
+interface PrivilegedBrowserCheckoutDriver<T> {
+    dispatch(input: {
+        authorization: CheckoutActionAuthorization;
+        browserSessionId: string;
+        action: AgentCheckoutAction | BrowserCheckoutAction;
+    }): Promise<GuardedBrowserDispatchResult<T>>;
+}
+interface RunGuardedCheckoutResult<T> extends GuardCheckoutResult<T> {
+    dispatchAttemptId: string;
+    observation: BrowserActionDispatchObservationInput;
+}
 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;
@@ -1076,8 +1889,15 @@ interface X402PreAuthorizeInput {
         department?: string;
         project?: string;
     };
+    facilitator?: string;
+    scheme?: string;
     /** Customer-supplied ID used to group authorization, recording, and spend reporting. */
     sessionId?: string;
+    paymentId?: string;
+    /** Exact wallet address that will sign. Provide together with network. */
+    payerAddress?: string;
+    /** CAIP-2 network from the x402 challenge, for example eip155:8453. */
+    network?: string;
 }
 interface X402PreAuthorizeResult extends ProtocolPreAuthorizeResult {
     x402: {
@@ -1086,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;
@@ -1096,6 +1964,10 @@ interface X402RecordInput {
     paymentId: string;
     /** Customer-supplied ID used to group related x402 payments. */
     sessionId?: string;
+    /** Exact wallet address that signed. Provide together with network. */
+    payerAddress?: string;
+    /** CAIP-2 network from the x402 challenge, for example eip155:8453. */
+    network?: string;
     context?: {
         department?: string;
         project?: string;
@@ -1106,7 +1978,7 @@ interface X402RecordInput {
         paymentId: string;
     }>;
 }
-interface X402RecordResult {
+interface X402RecordResult extends ProtocolRecordGrantResult {
     recorded: true;
     confirmed: true;
     txHash: string;
@@ -1125,6 +1997,10 @@ interface MppPreAuthorizeInput {
     depositAmount?: number;
     /** Customer-supplied ID used to group authorization, recording, and spend reporting. */
     sessionId?: string;
+    scheme?: string;
+    credentialId?: string;
+    challengeId?: string;
+    paymentMethod?: string;
 }
 interface MppPreAuthorizeResult extends ProtocolPreAuthorizeResult {
     mpp: {
@@ -1133,7 +2009,7 @@ interface MppPreAuthorizeResult extends ProtocolPreAuthorizeResult {
         sessionId?: string;
     };
 }
-interface MppRecordInput {
+interface MppRecordInput extends ProtocolRecordGrant {
     amount: number;
     currency?: string;
     recipientAddress: string;
@@ -1149,13 +2025,17 @@ interface MppRecordInput {
     };
     paymentReceipt?: string;
     intent?: 'charge' | 'session';
+    scheme?: string;
+    challengeId?: string;
+    paymentMethod?: string;
+    depositAmount?: number;
     batchItems?: Array<{
         amount: number;
         resourceUrl: string;
         credentialId: string;
     }>;
 }
-interface MppRecordResult {
+interface MppRecordResult extends ProtocolRecordGrantResult {
     recorded: true;
     txHash?: string;
     explorerUrl?: string;
@@ -1226,6 +2106,8 @@ declare class ContoError extends Error {
     readonly retryAfter?: number;
     readonly retryGuidance?: string;
     readonly actionUrl?: string;
+    readonly fieldErrors?: ApiErrorMetadata['fieldErrors'];
+    readonly reasons?: string[];
     constructor(message: string, metadata: ApiErrorMetadata);
 }
 /**
@@ -1238,6 +2120,23 @@ declare class ExternalCardConfirmationPendingError<TReceipt = unknown> extends C
     readonly receipt: TReceipt;
     constructor(requestId: string, confirmationInput: ExternalCardConfirmationInput, receipt: TReceipt);
 }
+/**
+ * The privileged browser action ran, but Conto did not acknowledge its final
+ * observation. Retry finalizeBrowserAction with these exact fields; never run
+ * the browser action again.
+ */
+declare class BrowserActionFinalizationPendingError<TResult = unknown> extends ContoError {
+    readonly authorizationId: string;
+    readonly dispatchAttemptId: string;
+    readonly result: TResult;
+    readonly observation: BrowserActionDispatchObservationInput;
+    constructor(input: {
+        authorizationId: string;
+        dispatchAttemptId: string;
+        result: TResult;
+        observation: BrowserActionDispatchObservationInput;
+    });
+}
 interface ContoRequestOptions {
     /** Set only when repeating this request cannot create an additional side effect. */
     idempotent?: boolean;
@@ -1250,10 +2149,85 @@ declare class Conto {
     private timeout;
     payments: PaymentsClient;
     cards: CardsClient;
+    connectedCards: ConnectedCardsClient;
     x402: X402Client;
     mpp: MppClient;
     constructor(config: ContoConfig);
-    /** Make an authenticated request to the Giro API */
+    /**
+     * List masked Link payment methods for a session-created connection that is
+     * explicitly bound to this agent. No Link token or payment artifact is
+     * returned through the agent SDK.
+     */
+    listStripeLinkPaymentMethods(connectionId: string): Promise<ListStripeLinkPaymentMethodsResult>;
+    /**
+     * Normalize and durably revise a partial agent purchase proposal without
+     * creating a payment side effect. Missing facts return as NEEDS_CONTEXT
+     * requirements; changed writes require the exact prior revision.
+     */
+    normalizeCommerceProposal(input: NormalizeCommerceProposalInput): Promise<CommerceProposalResolution>;
+    /** Reload one durable proposal head in this agent and tenant scope. */
+    getCommerceProposal(proposalId: string): Promise<CommerceProposalResolution>;
+    /**
+     * Evaluate policy and begin one exact Stripe Link commerce intent.
+     *
+     * The stable idempotency key makes transport retries safe. Reusing it with a
+     * different intent is rejected by the API.
+     */
+    beginCommerceExecution(input: BeginCommerceExecutionInput): Promise<CommerceExecutionResult>;
+    /** Atomically consume the Conto authorization for one exact browser action. */
+    authorizeCheckoutAction(executionId: string, browserSessionId: string, action: AgentCheckoutAction | BrowserCheckoutAction): Promise<AuthorizeCheckoutActionResult>;
+    /** Claim a durable browser action for one stable privileged-runtime attempt. */
+    claimBrowserAction(authorizationId: string, dispatchAttemptId: string, browserSessionId: string, action: AgentCheckoutAction | BrowserCheckoutAction): Promise<BrowserActionClaimResult>;
+    /** Finalize the exact dispatch attempt; this never performs the browser side effect. */
+    finalizeBrowserAction(authorizationId: string, input: {
+        dispatchAttemptId: string;
+        outcome: 'CONSUMED' | 'INDETERMINATE';
+        observation?: BrowserActionDispatchObservationInput;
+    }): Promise<BrowserActionFinalizeResult>;
+    /**
+     * Own the complete privileged-browser enforcement sequence. The stable
+     * dispatchAttemptId must be persisted by the runtime before this call.
+     */
+    runGuardedCheckout<T>(input: GuardedCheckoutInput, runtime: {
+        dispatchAttemptId: string;
+        execute: (authorization: CheckoutActionAuthorization) => Promise<GuardedBrowserDispatchResult<T>>;
+    }): Promise<RunGuardedCheckoutResult<T>>;
+    /**
+     * Reference privileged-driver integration. Only this wrapper should be
+     * exposed as the agent's payment-sensitive browser tool.
+     */
+    runGuardedCheckoutWithDriver<T>(input: GuardedCheckoutInput, runtime: {
+        dispatchAttemptId: string;
+        driver: PrivilegedBrowserCheckoutDriver<T>;
+    }): Promise<RunGuardedCheckoutResult<T>>;
+    /**
+     * Policy-check and authorize an exact action before invoking a legacy callback.
+     * @deprecated Use runGuardedCheckout so the durable claim and final
+     * observation cannot be omitted.
+     */
+    guardCheckout<T>(input: GuardedCheckoutInput, executor: (authorization: CheckoutActionAuthorization) => Promise<T>): Promise<GuardCheckoutResult<T>>;
+    /** Read one agent-scoped commerce execution and its normalized evidence. */
+    getCommerceExecution(executionId: string): Promise<CommerceExecutionResult>;
+    /**
+     * Observe Link state and reconcile terminal accounting. This operation is
+     * safe to retry because it does not request another checkout execution.
+     */
+    refreshCommerceExecution(executionId: string): Promise<CommerceExecutionResult>;
+    /**
+     * Execute the approved provider-direct or server-only checkout handoff. Transport retries are
+     * deliberately disabled. Read or refresh the execution after an ambiguous
+     * failure before taking another execution action.
+     */
+    executeCommerceExecution(executionId: string): Promise<ExecuteCommerceExecutionResult>;
+    /**
+     * Request cancellation and release reserved spend after Link confirms it.
+     * Transport retries are disabled because a lost provider response requires
+     * reconciliation.
+     */
+    cancelCommerceExecution(executionId: string): Promise<CommerceExecutionResult>;
+    /** Read credentials, linked wallets, effective policies, and scopes without creating a payment. */
+    setup(): Promise<AgentSetupResult>;
+    /** Make an authenticated request to the Conto API */
     request<T>(method: string, path: string, body?: Record<string, unknown>, options?: ContoRequestOptions): Promise<T>;
 }
 /** Agent client for the cooperative external-card policy overlay. */
@@ -1290,9 +2264,76 @@ declare class ControlledExternalCardPaymentTool<TReceipt = unknown> {
     constructor(cardsClient: CardsClient, executor: ExternalCardExecutor<TReceipt>);
     pay(input: ExternalCardApprovalInput): Promise<ControlledExternalCardPaymentResult<TReceipt>>;
 }
+/**
+ * Agent client for connected cards (gated pilot).
+ *
+ * A connected card is a customer card enrolled through the provider and
+ * delegated to this agent. `draw` mints one single-use credential against a
+ * verified mandate; `list` returns the masked cards and mandates the agent may
+ * 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.
+ */
+declare class ConnectedCardsClient {
+    private client;
+    constructor(client: Conto);
+    /**
+     * Draw one single-use card credential against a verified mandate.
+     *
+     * On an APPROVED, minted draw the result carries live card material in
+     * `credential`, returned exactly ONCE.
+     *
+     * CREDENTIAL SAFETY (load-bearing): the credential is the real, usable card.
+     * It is revealed a single time and cannot be re-fetched. Use it in-process at
+     * the intended merchant checkout only. Never log, print, serialize, persist,
+     * cache, or forward it, and never place it in an error, a monitoring event,
+     * or any other sink. See {@link ConnectedCardCredential}.
+     *
+     * Transport-level retry is deliberately OFF for this call. The server is
+     * idempotent on `idempotencyKey`, so an automatic retry after a successful
+     * mint would replay the draw and return the decision WITHOUT the credential,
+     * silently losing the one-shot card material. If a `draw` fails ambiguously,
+     * do not blindly retry: check the outcome, and reuse the same
+     * `idempotencyKey` only to reconcile the same draw.
+     *
+     * @example
+     * ```typescript
+     * const draw = await conto.connectedCards.draw({
+     *   cardId: 'cmm59z8fj000l49h7bjqza11p',
+     *   mandateId: 'cmm5a1b2c000m49h7defgh22q',
+     *   idempotencyKey: 'checkout_01J8...',
+     *   amountMinor: 4999,
+     *   merchant: { merchantName: 'Example Store', merchantCategory: '5311' },
+     * });
+     * if (draw.decision === 'APPROVED' && draw.credential) {
+     *   // Keep the credential in memory, acknowledge receipt, then use it at checkout.
+     *   await conto.connectedCards.acknowledgeDelivery(draw.requestId);
+     *   // Do not log or store draw.credential.
+     * }
+     * ```
+     */
+    draw(input: ConnectedCardDrawInput): Promise<ConnectedCardDrawResult>;
+    /**
+     * List the connected cards and active mandates this agent may draw against.
+     *
+     * The response is masked: no PAN and no provider tokens. This is a read-only
+     * GET, so transport retry on transient failures is safe.
+     */
+    /** Record receipt after a fresh draw. Does not confirm checkout or payment settlement. */
+    acknowledgeDelivery(requestId: string): Promise<{
+        acknowledged: boolean;
+        settlementVerified: false;
+    }>;
+    list(): Promise<ConnectedCardListResult>;
+}
 /** Client for payment operations */
 declare class PaymentsClient {
     private client;
+    /** Authorize an externally signed transfer. This write is not automatically retried. */
+    approve(input: ExternalWalletApprovalInput): Promise<ExternalWalletApprovalResult>;
+    /** Record an existing transfer. Never sends funds; reconcile conflicts using status(). */
+    confirm(requestId: string, input: ExternalWalletConfirmationInput): Promise<ExternalWalletConfirmationResult>;
     constructor(client: Conto);
     /**
      * Request authorization for a payment.
@@ -1388,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;
@@ -1411,4 +2462,4 @@ declare class MppClient {
     }): Promise<ProtocolServicesResult>;
 }
 
-export { type AdminExternalCardOverlayEnforcement, type Agent, type AgentExternalCard, type AgentStatus, type AgentType, type AgentWalletLink, type ApprovedExternalCardExecution, type AssignExternalCardInput, type AssignedPolicy, CardsClient, type ChainType, 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 DelegationType, type ExternalCard, type ExternalCardApprovalInput, type ExternalCardApprovalResult, type ExternalCardConfirmationInput, ExternalCardConfirmationPendingError, type ExternalCardConfirmationResult, type ExternalCardExecutionClaimResult, type ExternalCardExecutionResult, type ExternalCardExecutor, type ExternalCardOverlayEnforcement, type ExternalCardRequestStatusResult, type FreezeAgentInput, Conto as Giro, type ContoConfig as GiroConfig, ContoError as GiroError, type LinkWalletInput, type ListAgentsParams, type ListAgentsResponse, type ListPoliciesParams, type ListPoliciesResponse, type ListWalletsParams, type ListWalletsResponse, type MppBudgetResult, type MppPreAuthorizeInput, type MppPreAuthorizeResult, type MppRecordInput, type MppRecordResult, type OrganizationMember, type PaginatedResponse, type PaginationParams, type PauseExternalCardAssignmentResult, type PaymentExecuteResult, type PaymentRequestInput, type PaymentRequestResult, type PaymentStatusResult, type Policy, type PolicyRule, type PolicyType, type ProtocolBudgetResult, type ProtocolPreAuthorizeResult, type ProtocolServiceSummary, type ProtocolServicesResult, type ProvisionWalletResult, type RefreshBalanceResult, type RegisterExternalCardInput, type RuleAction, type RuleOperator, type RuleType, type SdkKey, type SdkKeyType, type UnfreezeAgentInput, type UpdateAgentInput, type UpdateExternalCardAssignmentInput, type UpdatePolicyInput, type UpdatePolicyRuleInput, type UpdateWalletInput, type Wallet, type WalletChainBalanceSnapshot, type WalletStatus, type WalletType, type X402BudgetResult, type X402PreAuthorizeInput, type X402PreAuthorizeResult, type X402RecordInput, type X402RecordResult, Conto as default };
+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 };