@conto_finance/sdk 0.6.1 → 0.7.0

package/dist/index.d.ts

@@ -1,6 +1,9 @@
+import { LinkWallet, LinkCardCredential } from './link-wallet.js';
+export { LinkCallOptions, LinkCardRequestInput, LinkSpendRequest, LinkSpendRequestStatus, LinkWaitOptions } from './link-wallet.js';
+
 type PurchaseStatus = 'queued' | 'running' | 'awaiting_action' | 'submitting' | 'reconciling' | 'succeeded' | 'blocked' | 'failed' | 'cancelled';
 type PurchasePhase = 'queued' | 'shopping' | 'checkout' | 'review' | 'scheduled' | 'authorization' | 'payment' | 'reconciliation' | 'closed_unconfirmed' | 'complete';
-type PurchaseActionKind = 'buyer_details' | 'purchase_review' | 'organization_approval' | 'card_verification' | 'merchant_signin' | 'merchant_challenge';
+type PurchaseActionKind = 'buyer_details' | 'purchase_review' | 'organization_approval' | 'card_verification' | 'merchant_signin' | 'merchant_challenge' | 'budget_increase';
 type PurchaseActionAuthority = 'agent_or_buyer' | 'buyer' | 'cardholder' | 'organization';
 interface PurchaseMoney {
     /** Positive integer in minor units. */
@@ -14,6 +17,77 @@ interface PurchaseItem {
     quantity?: number;
     options?: string[];
 }
+/** One grocery to find, in the shopper's words. Conto never substitutes a different product. */
+interface PurchaseGroceryItem {
+    /** A short name, such as `Bananas`. */
+    label: string;
+    /** Plain search words, such as `bananas`. No prices, quantities or package sizes. */
+    query: string;
+    /** 1 to 20. */
+    quantity: number;
+    /** A package size, such as `1 pint`. */
+    size?: string;
+    /** How the item is sold, such as `bunch`, `bag` or `lb`. */
+    unit?: string;
+    brand?: string;
+    /** Words the item must not match, such as `organic`. */
+    exclude?: string[];
+}
+/**
+ * Groceries for one grocery store: an Instacart store link, or Conto Test
+ * Grocery in test mode. Up to 20 items. Use instead of `items`.
+ */
+interface PurchaseGroceryList {
+    items: PurchaseGroceryItem[];
+}
+/** A grocery list purchase's items, delivery and fees at the store. */
+interface PurchaseGrocery {
+    /** Each list item that has settled so far, by its position in the list. */
+    items: ({
+        index: number;
+        label: string;
+        status: 'added';
+        /** The store's product name. */
+        name: string;
+        quantity: number;
+        /** The line's price for that quantity. */
+        price: PurchaseMoney;
+    } | {
+        index: number;
+        label: string;
+        status: 'skipped';
+        reason: 'no_match' | 'size_unavailable' | 'brand_unavailable' | 'excluded';
+    })[];
+    /** The delivery time chosen at checkout. */
+    delivery: {
+        title: string;
+        window: string;
+        kind: 'priority' | 'standard' | 'scheduled' | 'other';
+        windowStart: string | null;
+        windowEnd: string | null;
+        price: PurchaseMoney | null;
+    } | null;
+    /** The store checkout's totals and fees, as it showed them. */
+    summary: {
+        itemsSubtotal: PurchaseMoney | null;
+        deliveryFee: PurchaseMoney | null;
+        serviceFee: PurchaseMoney | null;
+        bagFee: PurchaseMoney | null;
+        tax: PurchaseMoney | null;
+        tip: PurchaseMoney | null;
+        otherFees: {
+            label: string;
+            amount: PurchaseMoney;
+        }[];
+        total: PurchaseMoney | null;
+    } | null;
+}
+interface PurchaseRequest {
+    url: string;
+    task?: string;
+    items?: PurchaseItem[];
+    groceryList?: PurchaseGroceryList;
+}
 interface PurchaseAction {
     id: string;
     kind: PurchaseActionKind;
@@ -24,6 +98,25 @@ interface PurchaseAction {
     /** For buyer_details: the form and the field names it accepts. */
     form?: 'delivery' | 'billing' | 'store_order_contact';
     fields?: string[];
+    /**
+     * For budget_increase: the maximum is above maxCost. Answer
+     * `{ decision: 'raise', maxCostMinor }` with at least the maximum, or
+     * `{ decision: 'decline' }`.
+     */
+    budget?: {
+        estimate: PurchaseMoney;
+        maximum: PurchaseMoney;
+        maxCost: PurchaseMoney;
+    };
+    /**
+     * For a merchant_signin you answer: the store sign-in step. Answer `email`
+     * with `{ email }` (or `{ email, createAccount: true, agreedToStoreTerms: true }`)
+     * and `code` with `{ code }`, the 6-digit code the store sent the buyer.
+     */
+    signin?: {
+        store: 'instacart';
+        step: 'email' | 'code';
+    };
     /**
      * For buyer, cardholder and reviewer actions: the Conto page that completes
      * it. It works only inside a hosted buyer session or the dashboard, so it is
@@ -60,29 +153,40 @@ interface Purchase {
     phase: PurchasePhase;
     /** Increases by one with every visible change. */
     version: number;
-    request: {
-        url: string;
-        task?: string;
-        items?: PurchaseItem[];
-    };
+    request: PurchaseRequest;
     maxCost: PurchaseMoney;
     quote: {
         merchant: string;
         description: string | null;
+        /** What limits and the card are held to: the maximum, until a receipt records the final total. */
         total: PurchaseMoney;
+        /** The store's own total. */
+        estimate: PurchaseMoney;
+        /** The most the order can come to. The same as the estimate for an exact total. */
+        maximum: PurchaseMoney;
         estimatedTax: boolean;
     } | null;
     requiredAction: PurchaseAction | null;
     result: {
         outcome: 'merchant_confirmed' | 'checkout_reported' | 'credential_unused' | 'not_completed' | 'denied' | 'cancelled';
         merchantReference: string | null;
+        /** merchant_confirmed: the store's order number, when shown. */
+        orderNumber?: string | null;
+        /** merchant_confirmed: the store's receipt or order page, when shown. */
+        receiptUrl?: string | null;
+        /** merchant_confirmed: the amount the store charged, when shown. */
+        charged?: PurchaseMoney | null;
     } | null;
+    /** Present for a grocery list purchase. */
+    grocery?: PurchaseGrocery;
     paymentEvidence: PurchaseEvidence;
     progress: {
         steps: number;
         message: string | null;
     };
     reasonCode: string | null;
+    /** With POLICY_DENIED on a company card: which limit refused the purchase. */
+    limitReached?: 'buyer_daily' | 'buyer_monthly' | 'buyer_daily_count' | 'store' | 'card_or_policy';
     cancellation: {
         requestedAt: string;
     } | null;
@@ -131,11 +235,7 @@ interface PurchaseList {
 }
 interface CreatePurchaseInput {
     buyerId: string;
-    request: {
-        url: string;
-        task?: string;
-        items?: PurchaseItem[];
-    };
+    request: PurchaseRequest;
     /** The most this purchase may cost, delivered. It narrows the delegation, never widens it. */
     maxCost: PurchaseMoney;
     /**
@@ -148,8 +248,12 @@ interface CreatePurchaseInput {
         methodId: string;
         delegationId: string;
     };
-    /** The buyer id, to use the buyer's saved delivery details. */
-    buyerProfileId?: string;
+    /**
+     * New purchases snapshot saved delivery details at creation for the store's
+     * delivery form. Leave out to use them when present, pass the buyer id
+     * to require them, or null to never use them.
+     */
+    buyerProfileId?: string | null;
 }
 interface PurchaseResponseAck {
     id: string;
@@ -172,7 +276,7 @@ interface WatchPurchaseOptions {
     mode?: 'auto' | 'stream' | 'poll';
     /** Polling interval. Defaults to 2000 ms. */
     pollIntervalMs?: number;
-    /** Stop waiting after this long. Defaults to no limit. */
+    /** Stop observing after this many milliseconds (0 stops immediately). Does not cancel the purchase. */
     maxWaitMs?: number;
 }
 declare const isFinalPurchaseStatus: (status: PurchaseStatus) => boolean;
@@ -192,7 +296,7 @@ type SseFrame = {
     data: string;
 };
 /** Parses server-sent events from a byte stream. */
-declare function parseServerSentEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<SseFrame>;
+declare function parseServerSentEvents(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<SseFrame>;
 type RecurringPurchaseCycleStatus = 'checking' | 'scheduled' | 'needs_review' | 'paying' | 'paid' | 'skipped' | 'missed' | 'failed' | 'cancelled';
 /** A repeat order the buyer set up while approving a purchase on Conto's hosted page. */
 interface RecurringPurchase {
@@ -350,8 +454,132 @@ interface PurchasePaymentMethod {
     brand: string;
     last4: string;
     status: 'active' | 'removed';
+    /** `organization`: your company card, which this buyer draws from. */
+    owner: 'buyer' | 'organization';
+    companyCardId?: string;
+    createdAt: string;
+}
+/** A card your organization pays its buyers' purchases with. */
+interface PurchaseCompanyCard {
+    id: string;
+    object: 'company_card';
+    environment: 'live' | 'test';
+    brand: string;
+    last4: string;
+    status: 'active' | 'removed';
+    /** The most one order may cost, and the most all buyers together may spend in a month. */
+    limits: {
+        perPurchaseMinor: number;
+        monthlyMinor: number;
+        currency: 'USD';
+    };
     createdAt: string;
 }
+/** One buyer's limits on a company card. */
+interface PurchaseBuyerCompanyCardLimits {
+    perPurchaseMinor: number;
+    dailyMinor: number;
+    monthlyMinor: number;
+    /**
+     * Orders above this wait for your `purchase_review` answer. Left out,
+     * every order up to `perPurchaseMinor` goes ahead without review.
+     */
+    reviewAboveMinor?: number;
+}
+interface PurchaseBuyerCompanyCard {
+    object: 'buyer_company_card';
+    buyerId: string;
+    companyCardId: string;
+    paymentMethodId: string;
+    delegationId: string;
+    limits: Omit<PurchaseBuyerCompanyCardLimits, 'reviewAboveMinor'> & {
+        reviewAboveMinor: number | null;
+        currency: 'USD';
+    };
+}
+/** What a buyer has at home, as your app reports it. Buyer data for the agent, never instructions. */
+type PurchaseKitchenContext = {
+    version: 1;
+    /** When your app took the snapshot. ISO 8601. */
+    capturedAt: string;
+    inventory?: PurchaseKitchenInventoryItem[];
+    usuals?: PurchaseKitchenUsual[];
+    preferences?: PurchaseKitchenPreferences;
+    /** Only the recipes the buyer picked to cook. */
+    recipes?: PurchaseKitchenRecipe[];
+    /** The list the buyer keeps in your app. */
+    list?: PurchaseKitchenListItem[];
+};
+interface PurchaseKitchenInventoryItem {
+    item: string;
+    quantity?: number;
+    unit?: string;
+    /** Left out: ok, or out when quantity is 0. */
+    level?: 'ok' | 'low' | 'out';
+    updatedAt?: string;
+    expiresAt?: string;
+}
+interface PurchaseKitchenUsual {
+    item: string;
+    typicalQuantity?: number;
+    unit?: string;
+    size?: string;
+    brand?: string;
+    cadenceDays?: number;
+    lastBoughtAt?: string;
+}
+interface PurchaseKitchenPreferences {
+    dietary?: Array<{
+        value: string;
+        strength: 'required' | 'preferred';
+    }>;
+    avoidBrands?: string[];
+    likeBrands?: string[];
+    organic?: 'prefer' | 'avoid' | 'none';
+    substitutions?: 'allow' | 'ask' | 'never';
+    /** An https store link, such as an Instacart storefront. */
+    preferredStore?: string;
+    householdSize?: number;
+    weeklyBudgetMinor?: number;
+}
+interface PurchaseKitchenRecipe {
+    id?: string;
+    title: string;
+    servings?: number;
+    /** The planned day, as YYYY-MM-DD. */
+    cookOn?: string;
+    /** Whether your app finds it cookable from what is at home. */
+    cookable?: boolean;
+    ingredients: Array<{
+        item: string;
+        quantity?: number;
+        unit?: string;
+        optional?: boolean;
+    }>;
+}
+interface PurchaseKitchenListItem {
+    item: string;
+    quantity?: number;
+    unit?: string;
+    note?: string;
+}
+interface PurchaseBuyerKitchenContext {
+    object: 'buyer_kitchen_context';
+    buyerId: string;
+    /** Null when nothing was pushed. */
+    context: PurchaseKitchenContext | null;
+    summary: {
+        capturedAt: string;
+        inventory: number;
+        low: number;
+        out: number;
+        usuals: number;
+        recipes: number;
+        list: number;
+    } | null;
+    /** When Conto received the snapshot. */
+    receivedAt: string | null;
+}
 interface PurchaseDelegation {
     id: string;
     object: 'delegation';
@@ -363,9 +591,14 @@ interface PurchaseDelegation {
     limits: {
         perPurchaseMinor: number;
         dailyMinor: number;
+        /** Company card only. */
+        monthlyMinor?: number;
+        /** Company card only: orders above this wait for your review. */
+        reviewAboveMinor?: number;
         currency: 'USD';
     };
-    requiresPurchaseReview: true;
+    /** false for a company card delegation, which you review above `reviewAboveMinor` only. */
+    requiresPurchaseReview: boolean;
     requiresCardVerification: boolean;
     createdAt: string;
     revokedAt: string | null;
@@ -380,6 +613,39 @@ interface PurchaseHostedLink {
     url: string;
     expiresAt: string;
 }
+/** Buyer-approved spending at one store; not a merchant-independent allowance. */
+interface PurchaseAllowance {
+    id: string;
+    object: 'allowance';
+    buyerId: string;
+    agentId: string;
+    delegationId: string;
+    paymentMethodId: string;
+    environment: 'live' | 'test';
+    status: 'pending_verification' | 'active' | 'revoked' | 'expired';
+    kind: 'store' | 'recurrence';
+    merchant: {
+        name: string;
+        origin: string;
+    };
+    limits: {
+        perPurchaseMinor: number;
+        periodMinor: number;
+        period: 'day' | 'week' | 'month';
+        totalMinor: number;
+        currency: 'USD';
+    };
+    expiresAt: string;
+    createdAt: string;
+    activatedAt: string | null;
+    revokedAt: string | null;
+}
+interface PurchasingSettings {
+    /** Origins a hosted page may return the buyer to. */
+    allowedReturnOrigins: string[];
+    /** Whether Conto emails buyers about their purchases. On by default. */
+    buyerEmails: boolean;
+}
 interface PurchasingCapabilities {
     object: 'purchasing_capabilities';
     /** Test mode is open to every organization. Live needs Conto to enable it. */
@@ -389,6 +655,7 @@ interface PurchasingCapabilities {
     }>;
     currencies: string[];
     cardNetworks: string[];
+    /** Checkout paths: `browser_checkout`, `store_order` and `test_store`. */
     executors: Array<{
         executor: string;
         available: boolean;
@@ -398,6 +665,10 @@ interface PurchasingCapabilities {
     allowances?: Record<'test' | 'live', {
         available: boolean;
     }>;
+    /** Whether your app can push what its buyers have at home. */
+    kitchenContext?: {
+        available: boolean;
+    };
     unsupported: Array<{
         capability: string;
         reason: string;
@@ -429,6 +700,18 @@ declare class AdminPurchasingClient {
     constructor(client: AdminTransport);
     /** Buyers' repeat orders: list, read, start or skip an order, and cancel. */
     readonly recurringPurchases: OrganizationRecurringPurchasesClient;
+    /** Inspect or revoke buyer-approved allowances. Grants remain on the buyer's hosted page. */
+    readonly allowances: {
+        /** Returns up to 50 allowances for this buyer, newest first. */
+        list: (params: {
+            buyerId: string;
+        }) => Promise<{
+            items: PurchaseAllowance[];
+        }>;
+        get: (id: string) => Promise<PurchaseAllowance>;
+        /** Stops future credential release; does not undo payments already submitted. */
+        revoke: (id: string) => Promise<PurchaseAllowance>;
+    };
     readonly buyers: {
         /** Maps one of your users to a buyer with its own agent, or returns the existing one. */
         create: (input: {
@@ -447,6 +730,56 @@ declare class AdminPurchasingClient {
         }>;
         /** Stops the buyer's agent. Purchases that may already be paid stay visible. */
         stop: (id: string) => Promise<PurchaseBuyer>;
+        /**
+         * Lets the buyer pay with your company card within limits you set for
+         * them, or replaces those limits. The buyer must not have their own card.
+         */
+        setCompanyCard: (id: string, input: {
+            companyCardId: string;
+            limits: PurchaseBuyerCompanyCardLimits;
+        }) => Promise<PurchaseBuyerCompanyCard>;
+        /** The buyer stops paying with your company card. */
+        removeCompanyCard: (id: string) => Promise<{
+            buyerId: string;
+            object: "buyer_company_card";
+            removed: true;
+        }>;
+        /**
+         * Replaces what the buyer has at home: inventory, usuals, preferences,
+         * chosen recipes and their list. The whole snapshot, every time. Needs
+         * Conto to enable kitchen context for your organization.
+         */
+        setKitchenContext: (id: string, context: PurchaseKitchenContext) => Promise<PurchaseBuyerKitchenContext>;
+        /** The snapshot Conto holds, with context null when nothing was pushed. */
+        getKitchenContext: (id: string) => Promise<PurchaseBuyerKitchenContext>;
+        clearKitchenContext: (id: string) => Promise<{
+            buyerId: string;
+            object: "buyer_kitchen_context";
+            removed: true;
+        }>;
+    };
+    /** Cards your organization pays its buyers' purchases with. Test cards only for now. */
+    readonly companyCards: {
+        create: (input: {
+            environment: "live" | "test";
+            limits: {
+                perPurchaseMinor: number;
+                monthlyMinor: number;
+            };
+        }) => Promise<PurchaseCompanyCard>;
+        list: () => Promise<{
+            items: PurchaseCompanyCard[];
+        }>;
+        get: (id: string) => Promise<PurchaseCompanyCard>;
+        /** Changes the card's own caps. Each buyer's limits stay as they are. */
+        update: (id: string, input: {
+            limits: {
+                perPurchaseMinor: number;
+                monthlyMinor: number;
+            };
+        }) => Promise<PurchaseCompanyCard>;
+        /** No buyer can start or pay a purchase with the card after this. */
+        remove: (id: string) => Promise<PurchaseCompanyCard>;
     };
     readonly paymentMethods: {
         /** A single-use link to the hosted setup page: limits, card and delegation. */
@@ -477,14 +810,12 @@ declare class AdminPurchasingClient {
      */
     readonly purchases: OrganizationPurchasesClient;
     readonly settings: {
-        get: () => Promise<{
-            allowedReturnOrigins: string[];
-        }>;
+        get: () => Promise<PurchasingSettings>;
+        /** Changes only the fields you pass. */
         update: (input: {
-            allowedReturnOrigins: string[];
-        }) => Promise<{
-            allowedReturnOrigins: string[];
-        }>;
+            allowedReturnOrigins?: string[];
+            buyerEmails?: boolean;
+        }) => Promise<PurchasingSettings>;
     };
     /** What this organization can run now: test mode always, live once Conto enables it. */
     capabilities(): Promise<PurchasingCapabilities>;
@@ -1022,6 +1353,29 @@ interface RefreshBalanceResult {
     balances: WalletChainBalanceSnapshot[];
     lastRefreshed: string;
 }
+/** A one-time message for a self-custody wallet's address to sign. */
+interface WalletOwnershipChallenge {
+    walletId: string;
+    address: string;
+    chainType: ChainType;
+    chainId: string;
+    /** Sign exactly this text: EIP-191 personal_sign on EVM, Ed25519 on Solana. */
+    message: string;
+    expiresAt: string;
+    /** When the wallet was last proven, or null if never. */
+    provenAt: string | null;
+}
+interface ProveWalletOwnershipInput {
+    /** The challenge message, unchanged. */
+    message: string;
+    /** EVM: 0x-prefixed hex signature. Solana: base58 or base64 signature. */
+    signature: string;
+}
+interface WalletOwnershipProof {
+    walletId: string;
+    proven: true;
+    provenAt: string;
+}
 interface PolicyRule {
     id: string;
     policyId: string;
@@ -1311,6 +1665,13 @@ declare class WalletsClient {
     provision(walletId: string): Promise<ProvisionWalletResult>;
     /** Refresh a wallet's balance from the chain */
     refreshBalance(walletId: string): Promise<RefreshBalanceResult>;
+    /**
+     * Get a one-time message for a self-custody wallet's address to sign. It
+     * expires after 10 minutes and replaces any earlier challenge.
+     */
+    createOwnershipChallenge(walletId: string): Promise<WalletOwnershipChallenge>;
+    /** Prove your organization controls a self-custody wallet's address. */
+    proveOwnership(walletId: string, input: ProveWalletOwnershipInput): Promise<WalletOwnershipProof>;
 }
 declare class PoliciesClient {
     private client;
@@ -2209,21 +2570,34 @@ interface BeginCheckoutCheckpointInput {
     /** Defaults to one Total entry equal to amountMinor. */
     totals?: CommerceTotalInput[];
 }
+/**
+ * The payment behind a checkout, such as the Link spend request that issued a
+ * Link card. An id only, never card data.
+ */
+interface CheckoutPaymentReference {
+    provider: 'LINK';
+    /** The Link spend request id, such as lsrq_... */
+    id: string;
+}
 /** Second checkpoint: the final total shown right before the payment is submitted. */
 interface ConfirmCheckoutCheckpointInput {
     amountMinor: number;
     currency?: 'USD';
-    /** Final line items, needed only when the total changed. Defaults to the approved items. */
+    /** Observed final items. Supplied items are checked even when the total is unchanged. */
     lineItems?: CommerceLineItemInput[];
-    /** Final totals, such as tax and shipping. Defaults to one Total entry. */
+    /** Observed final charges. Supplied charges are checked even when the total is unchanged. */
     totals?: CommerceTotalInput[];
     /** Page where the payment is submitted: the merchant's site or the payment method's. */
     pageUrl?: string;
+    /** The Link card's spend request, from getLinkCard(). */
+    paymentReference?: CheckoutPaymentReference;
 }
 interface ReportCheckoutOutcomeInput {
     outcome: CheckoutOutcome;
     /** Merchant order or receipt number. Never a payment credential. */
     reference?: string;
+    /** The Link card's spend request, from getLinkCard(). */
+    paymentReference?: CheckoutPaymentReference;
 }
 interface CheckoutCheckpoint {
     id: string;
@@ -2250,6 +2624,8 @@ interface CheckoutCheckpoint {
     /** Present when the agent's rules sent this purchase to the owner for approval. */
     approval?: CheckoutCheckpointApproval;
     outcomeReference?: string;
+    /** The payment your checkout reported at confirm or outcome, such as a Link spend request. */
+    paymentReference?: CheckoutPaymentReference;
     /** Outcomes are reported by your checkout. Conto does not verify settlement here. */
     settlementVerified: false;
 }
@@ -2266,6 +2642,45 @@ interface WaitForCheckoutApprovalOptions {
     pollIntervalMs?: number;
     signal?: AbortSignal;
 }
+
+/**
+ * A Link card for one purchase: the checkpoint begin input plus the Link
+ * wallet that runs in your environment. The checkout method is always LINK.
+ */
+interface GetLinkCardInput extends Omit<BeginCheckoutCheckpointInput, 'checkoutMethod'> {
+    /** For example linkCliWallet() from @conto_finance/sdk/link-wallet. */
+    wallet: LinkWallet;
+    /** How long to wait for the owner when a rule requires approval. Defaults to 10 minutes. */
+    ownerApprovalTimeoutMs?: number;
+    /** How long to wait for the person to approve in Link. Defaults to 10 minutes. */
+    linkApprovalTimeoutMs?: number;
+    signal?: AbortSignal;
+}
+/** A new Link card for a changed final total. */
+interface ReplaceLinkCardInput {
+    wallet: LinkWallet;
+    /** The final total in cents, including shipping and tax. */
+    amountMinor: number;
+    /** Final line items. Defaults to the approved items. */
+    lineItems?: CommerceLineItemInput[];
+    /** Final totals, such as tax and shipping. Defaults to one Total entry. */
+    totals?: CommerceTotalInput[];
+    ownerApprovalTimeoutMs?: number;
+    linkApprovalTimeoutMs?: number;
+    signal?: AbortSignal;
+}
+interface LinkCardResult {
+    /** The approved checkpoint. Pass it to confirm() right before paying. */
+    checkpoint: CheckoutCheckpoint;
+    /**
+     * Live card data for this purchase only. It stays in this process: printing
+     * or serializing the result shows only the last four digits.
+     */
+    card: LinkCardCredential;
+    linkRequestId: string;
+    /** Pass to confirm() and reportOutcome() so the owner sees which Link request paid. */
+    paymentReference: CheckoutPaymentReference;
+}
 /** 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. */
@@ -2957,6 +3372,41 @@ declare class CheckoutApprovalTimeoutError extends ContoError {
     readonly checkpoint: CheckoutCheckpoint;
     constructor(checkpoint: CheckoutCheckpoint);
 }
+/**
+ * getLinkCard() or replaceLinkCard() stopped after Conto approved the purchase.
+ * No card was returned. Conto cancelled the checkpoint to release the held
+ * spend unless holdReleased is false. Do not pay.
+ */
+declare class LinkCardError extends ContoError {
+    readonly checkpoint: CheckoutCheckpoint;
+    readonly linkRequestId?: string;
+    /** True when Conto cancelled the checkpoint and released the held spend. */
+    readonly holdReleased: boolean;
+    constructor(input: {
+        message: string;
+        code: string;
+        checkpoint: CheckoutCheckpoint;
+        linkRequestId?: string;
+        holdReleased: boolean;
+        retryGuidance?: string;
+    });
+}
+/** The person declined the Link card request, or it was cancelled in Link. */
+declare class LinkCardDeniedError extends LinkCardError {
+    constructor(input: ConstructorParameters<typeof LinkCardError>[0]);
+}
+/** The Link card request expired before the person approved it. */
+declare class LinkCardExpiredError extends LinkCardError {
+    constructor(input: ConstructorParameters<typeof LinkCardError>[0]);
+}
+/** The person did not approve in Link before linkApprovalTimeoutMs. Conto cancelled the request. */
+declare class LinkCardTimeoutError extends LinkCardError {
+    constructor(input: ConstructorParameters<typeof LinkCardError>[0]);
+}
+/** The Link wallet cannot run here: link-cli is not installed or not logged in. */
+declare class LinkWalletUnavailableError extends LinkCardError {
+    constructor(input: ConstructorParameters<typeof LinkCardError>[0]);
+}
 interface ContoRequestOptions {
     /** Set only when repeating this request cannot create an additional side effect. */
     idempotent?: boolean;
@@ -3396,6 +3846,38 @@ declare class CheckoutClient {
      */
     cancel(checkpointId: string): Promise<CheckoutCheckpoint>;
     get(checkpointId: string): Promise<CheckoutCheckpoint>;
+    /**
+     * Get a Stripe Link card for one purchase, issued only after Conto approves
+     * it. Call this at the payment step, once the final total with shipping and
+     * tax is known.
+     *
+     * 1. Conto runs checkpoint 1 and holds the spend. When a rule requires the
+     *    owner's approval, this waits for it.
+     * 2. Only then does the wallet ask Link for a card for exactly the approved
+     *    amount at this merchant. The person approves it in Link.
+     * 3. The card is returned. It never reaches Conto.
+     *
+     * Then fill in the card, call confirm(result.checkpoint, { amountMinor,
+     * paymentReference: result.paymentReference }) right before paying, pay only
+     * if it resolves, and report the outcome. If the final total differs, call
+     * replaceLinkCard() instead of confirming.
+     *
+     * A Conto denial throws before Link is called. When Link declines, expires,
+     * times out, or is unavailable, this cancels the checkpoint to release the
+     * held spend and throws a LinkCardError. When Conto cannot cancel an open Link
+     * request, it keeps the hold and throws LINK_CARD_NOT_CANCELLED with the
+     * request id. Retrying with the same input resumes the same checkpoint and
+     * Link request.
+     */
+    getLinkCard(input: GetLinkCardInput): Promise<LinkCardResult>;
+    /**
+     * The final total differs from the one the Link card covers. This cancels
+     * the old Link request and checkpoint, begins a checkpoint at the final
+     * total (waiting for the owner when a rule requires it), and gets a new card
+     * for it. Confirm the returned checkpoint with the same total.
+     */
+    replaceLinkCard(previous: LinkCardResult, input: ReplaceLinkCardInput): Promise<LinkCardResult>;
 }
 
-export { type AdminExternalCardOverlayEnforcement, AdminPurchasingClient, 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 BeginCheckoutCheckpointInput, type BeginCommerceExecutionInput, type BrowserActionClaimResult, type BrowserActionDispatchObservationInput, BrowserActionFinalizationPendingError, type BrowserActionFinalizeResult, type BrowserCheckoutAction, type BrowserCheckoutTargetResolver, type BrowserCheckoutTargetSnapshot, type BrowserCheckoutTargetVerificationCode, BrowserCheckoutTargetVerificationError, type CancellationOutcome, type CanonicalBrowserCheckoutTargetSnapshot, CardsClient, type ChainType, type CheckoutActionAuthorization, CheckoutApprovalDeniedError, CheckoutApprovalExpiredError, CheckoutApprovalPendingError, CheckoutApprovalTimeoutError, type CheckoutCheckpoint, type CheckoutCheckpointApproval, CheckoutCheckpointClosedError, type CheckoutCheckpointMethod, type CheckoutCheckpointNextAction, type CheckoutCheckpointStage, CheckoutClient, type CheckoutOutcome, 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 ConfirmCheckoutCheckpointInput, type ConnectedCardBrief, type ConnectedCardCredential, type ConnectedCardDrawInput, type ConnectedCardDrawMerchant, type ConnectedCardDrawResult, type ConnectedCardDrawable, type ConnectedCardListResult, type ConnectedCardMandate, type ConnectedCardMandateMerchant, type ConnectedCardOutcomeReport, type ConnectedCardOutcomeReportResult, type ConnectedCardReference, ConnectedCardsClient, Conto, ContoAdmin, type ContoAdminConfig, ContoAdminError, type ContoConfig, ContoError, type ContoRequestOptions, type ControlledExternalCardPaymentResult, ControlledExternalCardPaymentTool, type CreateAgentInput, type CreatePolicyInput, type CreatePolicyRuleInput, type CreatePurchaseInput, 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 ListWalletsParams, type ListWalletsResponse, type MppBudgetResult, type MppPreAuthorizeInput, type MppPreAuthorizeResult, type MppRecordInput, type MppRecordResult, type NormalizeCommerceProposalInput, type OrganizationMember, OrganizationPurchasesClient, OrganizationRecurringPurchasesClient, 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 Purchase, type PurchaseAction, type PurchaseActionAuthority, type PurchaseActionKind, type PurchaseBuyer, type PurchaseDelegation, type PurchaseEvent, type PurchaseEventPage, type PurchaseEvidence, type PurchaseHostedLink, type PurchaseItem, type PurchaseList, type PurchaseMoney, type PurchasePaymentMethod, type PurchasePhase, type PurchaseResponseAck, type PurchaseStatus, PurchasesClient, type PurchasingCapabilities, type RecurringPurchase, type RecurringPurchaseCycleResult, type RecurringPurchaseCycleStatus, RecurringPurchasesClient, type RefreshBalanceResult, type RegisterExternalCardInput, type ReportCheckoutOutcomeInput, type RollbackPolicyVersionResponse, type RuleAction, type RuleOperator, type RuleType, type RunGuardedCheckoutResult, type SdkKey, type SdkKeyType, type SetupCapabilityState, type SetupCardDiagnostics, type SetupDiagnosticAction, type SetupDiagnosticIssue, type SetupDiagnosticIssueCode, type SetupDiagnostics, type SetupWalletDiagnostics, type TestCardCredential, type TestCardDrawResult, type TestCardDrawable, type TestCardListResult, type TestCardReceipt, TestCardsClient, type TestCheckoutInput, type TestCheckoutResult, type TestMerchant, type TestMerchantProduct, type UnfreezeAgentInput, type UpdateAgentInput, type UpdateExternalCardAssignmentInput, type UpdatePolicyInput, type UpdatePolicyRuleInput, type UpdateWalletInput, type VerifiedBrowserCheckoutTarget, type WaitForCheckoutApprovalOptions, type Wallet, type WalletChainBalanceSnapshot, type WalletStatus, type WalletType, type WatchPurchaseOptions, type X402Authorization, type X402BudgetResult, type X402PayInput, type X402PayResult, type X402PaymentRequirements, type X402PreAuthorizeInput, type X402PreAuthorizeResult, type X402RecordInput, type X402RecordResult, canonicalizeBrowserCheckoutTarget, createVerifiedBrowserCheckoutDriver, Conto as default, fingerprintBrowserCheckoutTarget, isFinalPurchaseStatus, parseServerSentEvents, verifyPurchaseWebhook };
+export { AdminPurchasingClient, BrowserActionFinalizationPendingError, BrowserCheckoutTargetVerificationError, CardsClient, CheckoutApprovalDeniedError, CheckoutApprovalExpiredError, CheckoutApprovalPendingError, CheckoutApprovalTimeoutError, CheckoutCheckpointClosedError, CheckoutClient, ConnectedCardsClient, Conto, ContoAdmin, ContoAdminError, ContoError, ControlledExternalCardPaymentTool, ExternalCardConfirmationPendingError, Conto as Giro, ContoError as GiroError, LinkCardCredential, LinkCardDeniedError, LinkCardError, LinkCardExpiredError, LinkCardTimeoutError, LinkWallet, LinkWalletUnavailableError, OrganizationPurchasesClient, OrganizationRecurringPurchasesClient, PurchasesClient, RecurringPurchasesClient, TestCardsClient, canonicalizeBrowserCheckoutTarget, createVerifiedBrowserCheckoutDriver, Conto as default, fingerprintBrowserCheckoutTarget, isFinalPurchaseStatus, parseServerSentEvents, verifyPurchaseWebhook };
+export type { AdminExternalCardOverlayEnforcement, Agent, AgentCheckoutAction, AgentCheckoutActionKind, AgentExternalCard, AgentSetupResult, AgentStatus, AgentType, AgentWalletLink, ApprovedExternalCardExecution, AssignExternalCardInput, AssignedPolicy, AuthorizeCheckoutActionResult, BeginCheckoutCheckpointInput, BeginCommerceExecutionInput, BrowserActionClaimResult, BrowserActionDispatchObservationInput, BrowserActionFinalizeResult, BrowserCheckoutAction, BrowserCheckoutTargetResolver, BrowserCheckoutTargetSnapshot, BrowserCheckoutTargetVerificationCode, CancellationOutcome, CanonicalBrowserCheckoutTargetSnapshot, ChainType, CheckoutActionAuthorization, CheckoutCheckpoint, CheckoutCheckpointApproval, CheckoutCheckpointMethod, CheckoutCheckpointNextAction, CheckoutCheckpointStage, CheckoutOutcome, CheckoutPaymentReference, CommerceCheckoutMethod, CommerceContextRequirement, CommerceExecution, CommerceExecutionAdapterKind, CommerceExecutionArtifactKind, CommerceExecutionChannel, CommerceExecutionConstraint, CommerceExecutionConstraintCoverage, CommerceExecutionConstraintCoverageLevel, CommerceExecutionDeliveryMode, CommerceExecutionEvidence, CommerceExecutionProvider, CommerceExecutionResult, CommerceExecutionSourceKind, CommerceExecutionStatus, CommerceFactConfidence, CommerceFactProvenanceInput, CommerceFactSource, CommerceFulfillmentInput, CommerceLineItemInput, CommerceProposalFactKey, CommerceProposalMissingFact, CommerceProposalResolution, CommerceProposalState, CommerceSettlementRail, CommerceTotalInput, CommerceTotalType, ComparePolicyVersionsResponse, ConfirmCheckoutCheckpointInput, ConnectedCardBrief, ConnectedCardCredential, ConnectedCardDrawInput, ConnectedCardDrawMerchant, ConnectedCardDrawResult, ConnectedCardDrawable, ConnectedCardListResult, ConnectedCardMandate, ConnectedCardMandateMerchant, ConnectedCardOutcomeReport, ConnectedCardOutcomeReportResult, ConnectedCardReference, ContoAdminConfig, ContoConfig, ContoRequestOptions, ControlledExternalCardPaymentResult, CreateAgentInput, CreatePolicyInput, CreatePolicyRuleInput, CreatePurchaseInput, CreateSdkKeyInput, CreateSdkKeyResult, CreateWalletInput, CustodyType, CustomerCustodyMode, CustomerWalletControlModel, CustomerWalletKeyAccess, DelegationType, ExecuteCommerceExecutionResult, ExternalCard, ExternalCardApprovalInput, ExternalCardApprovalResult, ExternalCardConfirmationInput, ExternalCardConfirmationResult, ExternalCardExecutionClaimResult, ExternalCardExecutionResult, ExternalCardExecutor, ExternalCardOverlayEnforcement, ExternalCardRequestStatusResult, ExternalWalletApprovalInput, ExternalWalletApprovalResult, ExternalWalletConfirmationInput, ExternalWalletConfirmationResult, FreezeAgentInput, GetLinkCardInput, ContoConfig as GiroConfig, GuardCheckoutResult, GuardedBrowserDispatchResult, GuardedCheckoutInput, LinkCardResult, LinkWalletInput, ListAgentsParams, ListAgentsResponse, ListPoliciesParams, ListPoliciesResponse, ListPolicyVersionsResponse, ListWalletsParams, ListWalletsResponse, MppBudgetResult, MppPreAuthorizeInput, MppPreAuthorizeResult, MppRecordInput, MppRecordResult, NormalizeCommerceProposalInput, OrganizationMember, PaginatedResponse, PaginationParams, PauseExternalCardAssignmentResult, PaymentExecuteResult, PaymentRequestInput, PaymentRequestResult, PaymentStatusResult, Policy, PolicyRule, PolicyType, PolicyVersionChangeType, PolicyVersionDetail, PolicyVersionDiff, PolicyVersionFieldChange, PolicyVersionSnapshot, PolicyVersionSnapshotRule, PolicyVersionSummary, PrivilegedBrowserCheckoutDriver, ProtocolBudgetResult, ProtocolPreAuthorizeResult, ProtocolRecordGrant, ProtocolRecordGrantResult, ProtocolServiceSummary, ProtocolServicesResult, ProveWalletOwnershipInput, ProvisionWalletResult, Purchase, PurchaseAction, PurchaseActionAuthority, PurchaseActionKind, PurchaseAllowance, PurchaseBuyer, PurchaseBuyerCompanyCard, PurchaseBuyerCompanyCardLimits, PurchaseBuyerKitchenContext, PurchaseCompanyCard, PurchaseDelegation, PurchaseEvent, PurchaseEventPage, PurchaseEvidence, PurchaseGrocery, PurchaseGroceryItem, PurchaseGroceryList, PurchaseHostedLink, PurchaseItem, PurchaseKitchenContext, PurchaseKitchenInventoryItem, PurchaseKitchenListItem, PurchaseKitchenPreferences, PurchaseKitchenRecipe, PurchaseKitchenUsual, PurchaseList, PurchaseMoney, PurchasePaymentMethod, PurchasePhase, PurchaseRequest, PurchaseResponseAck, PurchaseStatus, PurchasingCapabilities, PurchasingSettings, RecurringPurchase, RecurringPurchaseCycleResult, RecurringPurchaseCycleStatus, RefreshBalanceResult, RegisterExternalCardInput, ReplaceLinkCardInput, ReportCheckoutOutcomeInput, RollbackPolicyVersionResponse, RuleAction, RuleOperator, RuleType, RunGuardedCheckoutResult, SdkKey, SdkKeyType, SetupCapabilityState, SetupCardDiagnostics, SetupDiagnosticAction, SetupDiagnosticIssue, SetupDiagnosticIssueCode, SetupDiagnostics, SetupWalletDiagnostics, TestCardCredential, TestCardDrawResult, TestCardDrawable, TestCardListResult, TestCardReceipt, TestCheckoutInput, TestCheckoutResult, TestMerchant, TestMerchantProduct, UnfreezeAgentInput, UpdateAgentInput, UpdateExternalCardAssignmentInput, UpdatePolicyInput, UpdatePolicyRuleInput, UpdateWalletInput, VerifiedBrowserCheckoutTarget, WaitForCheckoutApprovalOptions, Wallet, WalletChainBalanceSnapshot, WalletOwnershipChallenge, WalletOwnershipProof, WalletStatus, WalletType, WatchPurchaseOptions, X402Authorization, X402BudgetResult, X402PayInput, X402PayResult, X402PaymentRequirements, X402PreAuthorizeInput, X402PreAuthorizeResult, X402RecordInput, X402RecordResult };