@conto_finance/sdk 0.6.2-beta.1 → 0.7.1

package/dist/index.d.ts

@@ -40,6 +40,48 @@ interface PurchaseGroceryItem {
 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;
@@ -66,6 +108,15 @@ interface PurchaseAction {
         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
@@ -119,7 +170,15 @@ interface Purchase {
     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;
@@ -190,8 +249,8 @@ interface CreatePurchaseInput {
         delegationId: string;
     };
     /**
-     * The buyer's saved delivery details answer the store's delivery form when
-     * the buyer has them. Leave out to use them when present, pass the buyer id
+     * 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;
@@ -1294,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;
@@ -1583,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;
@@ -2554,6 +2643,33 @@ interface WaitForCheckoutApprovalOptions {
     signal?: AbortSignal;
 }
 
+/**
+ * The Link card request is waiting for the person. Conto has already approved
+ * the purchase, and Link has created the request.
+ */
+interface LinkApprovalEvent {
+    /** The checkpoint Conto approved. */
+    checkpoint: CheckoutCheckpoint;
+    /** The Link spend request id, such as lsrq_... */
+    linkRequestId: string;
+    /**
+     * The Stripe Link page where the person can approve on the web while signed
+     * in to Link, so they do not need the Link app. Only an HTTPS link.com address
+     * is passed. Absent when Link gave none or it did not pass that check. The
+     * person can still approve in the Link app.
+     */
+    approvalUrl?: string;
+    /** When Link stops accepting approval, as an ISO 8601 time, when Link reports it. */
+    approvalExpiresAt?: string;
+}
+/**
+ * Called once when the Link card request is waiting for the person, after
+ * Conto approved the purchase and before the SDK starts waiting. Show
+ * approvalUrl to the person. The SDK does not wait for it to finish, and an
+ * error it throws or rejects with does not affect the purchase. A retry that
+ * resumes a waiting request calls it again with the same URL.
+ */
+type LinkApprovalCallback = (event: LinkApprovalEvent) => void | Promise<void>;
 /**
  * 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.
@@ -2565,6 +2681,8 @@ interface GetLinkCardInput extends Omit<BeginCheckoutCheckpointInput, 'checkoutM
     ownerApprovalTimeoutMs?: number;
     /** How long to wait for the person to approve in Link. Defaults to 10 minutes. */
     linkApprovalTimeoutMs?: number;
+    /** Called once with the Link approval page when the person needs to approve in Link. */
+    onLinkApproval?: LinkApprovalCallback;
     signal?: AbortSignal;
 }
 /** A new Link card for a changed final total. */
@@ -2578,6 +2696,8 @@ interface ReplaceLinkCardInput {
     totals?: CommerceTotalInput[];
     ownerApprovalTimeoutMs?: number;
     linkApprovalTimeoutMs?: number;
+    /** Called once with the Link approval page when the person needs to approve in Link. */
+    onLinkApproval?: LinkApprovalCallback;
     signal?: AbortSignal;
 }
 interface LinkCardResult {
@@ -3291,6 +3411,13 @@ declare class CheckoutApprovalTimeoutError extends ContoError {
 declare class LinkCardError extends ContoError {
     readonly checkpoint: CheckoutCheckpoint;
     readonly linkRequestId?: string;
+    /**
+     * The Stripe Link page where the person could approve the request, set when
+     * the SDK stopped while the request was waiting for them. It works only while
+     * the request is still open in Link. When holdReleased is true, Conto has
+     * already cancelled the request.
+     */
+    readonly approvalUrl?: string;
     /** True when Conto cancelled the checkpoint and released the held spend. */
     readonly holdReleased: boolean;
     constructor(input: {
@@ -3298,6 +3425,7 @@ declare class LinkCardError extends ContoError {
         code: string;
         checkpoint: CheckoutCheckpoint;
         linkRequestId?: string;
+        approvalUrl?: string;
         holdReleased: boolean;
         retryGuidance?: string;
     });
@@ -3765,7 +3893,9 @@ declare class CheckoutClient {
      * 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 their Link app.
+     *    amount at this merchant. The person approves it in Link. Pass
+     *    onLinkApproval to get Link's approval page, so they can approve on the
+     *    web without the Link app.
      * 3. The card is returned. It never reaches Conto.
      *
      * Then fill in the card, call confirm(result.checkpoint, { amountMinor,
@@ -3790,4 +3920,5 @@ declare class CheckoutClient {
     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 CheckoutPaymentReference, 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, type GetLinkCardInput, Conto as Giro, type ContoConfig as GiroConfig, ContoError as GiroError, type GuardCheckoutResult, type GuardedBrowserDispatchResult, type GuardedCheckoutInput, LinkCardCredential, LinkCardDeniedError, LinkCardError, LinkCardExpiredError, type LinkCardResult, LinkCardTimeoutError, LinkWallet, type LinkWalletInput, LinkWalletUnavailableError, 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 PurchaseAllowance, type PurchaseBuyer, type PurchaseBuyerCompanyCard, type PurchaseBuyerCompanyCardLimits, type PurchaseBuyerKitchenContext, type PurchaseCompanyCard, type PurchaseDelegation, type PurchaseEvent, type PurchaseEventPage, type PurchaseEvidence, type PurchaseGroceryItem, type PurchaseGroceryList, type PurchaseHostedLink, type PurchaseItem, type PurchaseKitchenContext, type PurchaseKitchenInventoryItem, type PurchaseKitchenListItem, type PurchaseKitchenPreferences, type PurchaseKitchenRecipe, type PurchaseKitchenUsual, type PurchaseList, type PurchaseMoney, type PurchasePaymentMethod, type PurchasePhase, type PurchaseRequest, type PurchaseResponseAck, type PurchaseStatus, PurchasesClient, type PurchasingCapabilities, type PurchasingSettings, type RecurringPurchase, type RecurringPurchaseCycleResult, type RecurringPurchaseCycleStatus, RecurringPurchasesClient, type RefreshBalanceResult, type RegisterExternalCardInput, type ReplaceLinkCardInput, 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, LinkApprovalCallback, LinkApprovalEvent, 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 };

package/dist/index.js

@@ -47,7 +47,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@conto_finance/sdk",
-      version: "0.6.2-beta.1",
+      version: "0.7.1",
       description: "Conto SDK for AI agent payment authorization",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
@@ -80,8 +80,7 @@ var require_package = __commonJS({
         }
       },
       publishConfig: {
-        access: "public",
-        tag: "beta"
+        access: "public"
       },
       engines: {
         node: ">=20.19.0"
@@ -119,7 +118,7 @@ var require_package = __commonJS({
         email: "support@conto.finance"
       },
       dependencies: {
-        "@sentry/node": "^10.73.0"
+        "@sentry/node": "^11.8.0"
       },
       peerDependencies: {
         "playwright-core": ">=1.50.0"
@@ -133,10 +132,10 @@ var require_package = __commonJS({
         esbuild: "0.28.1"
       },
       devDependencies: {
-        "@types/node": "22.19.18",
+        "@types/node": "26.6.5",
         "playwright-core": "1.61.0",
-        tsup: "^8.5.1",
-        typescript: "^5.9.3"
+        tsup: "^9.0.0",
+        typescript: "^6.0.3"
       }
     };
   }
@@ -198,6 +197,32 @@ var Sentry2 = __toESM(require("@sentry/node"));
 var import_node_crypto3 = require("crypto");
 var import_package_version2 = __toESM(require_package_version());
 
+// src/link-approval.ts
+function safeLinkApprovalUrl(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > 2048) return void 0;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return void 0;
+  }
+  if (url.protocol !== "https:" || url.username !== "" || url.password !== "" || url.port !== "" || !(url.hostname === "link.com" || url.hostname.endsWith(".link.com"))) {
+    return void 0;
+  }
+  url.hash = "";
+  return url.toString();
+}
+function linkTime(value) {
+  let ms = Number.NaN;
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    ms = value < 1e12 ? value * 1e3 : value;
+  } else if (typeof value === "string" && value.length > 0 && value.length <= 64) {
+    ms = Date.parse(value);
+  }
+  const date = new Date(ms);
+  return Number.isNaN(date.getTime()) ? void 0 : date.toISOString();
+}
+
 // src/purchases.ts
 var import_node_crypto = require("crypto");
 var TERMINAL = /* @__PURE__ */ new Set(["succeeded", "blocked", "failed", "cancelled"]);
@@ -1414,6 +1439,25 @@ var WalletsClient = class {
       {}
     );
   }
+  /**
+   * Get a one-time message for a self-custody wallet's address to sign. It
+   * expires after 10 minutes and replaces any earlier challenge.
+   */
+  async createOwnershipChallenge(walletId) {
+    return this.client.request(
+      "POST",
+      `/api/wallets/${encodeURIComponent(walletId)}/ownership-proof/challenge`,
+      {}
+    );
+  }
+  /** Prove your organization controls a self-custody wallet's address. */
+  async proveOwnership(walletId, input) {
+    return this.client.request(
+      "POST",
+      `/api/wallets/${encodeURIComponent(walletId)}/ownership-proof`,
+      input
+    );
+  }
 };
 var PoliciesClient = class {
   constructor(client) {
@@ -1666,6 +1710,8 @@ var LinkCardError = class extends ContoError {
     this.name = "LinkCardError";
     this.checkpoint = input.checkpoint;
     if (input.linkRequestId) this.linkRequestId = input.linkRequestId;
+    const approvalUrl = safeLinkApprovalUrl(input.approvalUrl);
+    if (approvalUrl) this.approvalUrl = approvalUrl;
     this.holdReleased = input.holdReleased;
   }
 };
@@ -2973,6 +3019,11 @@ async function closeLinkRequest(wallet, id) {
     return status !== void 0 && LINK_CLOSED_STATUSES.has(status);
   }
 }
+function assertLinkApprovalCallback(callback) {
+  if (callback !== void 0 && typeof callback !== "function") {
+    throw checkoutError("onLinkApproval must be a function");
+  }
+}
 function linkCreatedNothing(error) {
   return errorCode(error) === "LINK_WALLET_UNAVAILABLE" || errorReason(error) === "invalid_input";
 }
@@ -2982,6 +3033,23 @@ var LinkFailureSignal = class extends Error {
     this.failure = failure;
   }
 };
+function linkApprovalDetails(request) {
+  const approvalUrl = safeLinkApprovalUrl(request.approvalUrl);
+  const approvalExpiresAt = linkTime(request.approvalExpiresAt);
+  return {
+    ...approvalUrl ? { approvalUrl } : {},
+    ...approvalExpiresAt ? { approvalExpiresAt } : {}
+  };
+}
+function notifyLinkApproval(callback, event) {
+  try {
+    const result = callback(Object.freeze(event));
+    if (result !== null && typeof result === "object" && "then" in result) {
+      Promise.resolve(result).catch(() => void 0);
+    }
+  } catch {
+  }
+}
 var _client4, _CheckoutClient_instances, linkCardFor_fn;
 var CheckoutClient = class {
   constructor(client) {
@@ -3167,7 +3235,9 @@ var CheckoutClient = class {
    * 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 their Link app.
+   *    amount at this merchant. The person approves it in Link. Pass
+   *    onLinkApproval to get Link's approval page, so they can approve on the
+   *    web without the Link app.
    * 3. The card is returned. It never reaches Conto.
    *
    * Then fill in the card, call confirm(result.checkpoint, { amountMinor,
@@ -3183,10 +3253,18 @@ var CheckoutClient = class {
    * Link request.
    */
   async getLinkCard(input) {
-    const { wallet, ownerApprovalTimeoutMs, linkApprovalTimeoutMs, signal, ...beginInput } = input;
+    const {
+      wallet,
+      ownerApprovalTimeoutMs,
+      linkApprovalTimeoutMs,
+      onLinkApproval,
+      signal,
+      ...beginInput
+    } = input;
     if (!wallet || typeof wallet.createCardRequest !== "function") {
       throw checkoutError("wallet must be a LinkWallet, such as linkCliWallet()");
     }
+    assertLinkApprovalCallback(onLinkApproval);
     let checkpoint = await this.begin({ ...beginInput, checkoutMethod: "LINK" });
     if (checkpoint.stage === "AWAITING_APPROVAL") {
       checkpoint = await this.waitForApproval(checkpoint, {
@@ -3194,7 +3272,11 @@ var CheckoutClient = class {
         ...signal ? { signal } : {}
       });
     }
-    return __privateMethod(this, _CheckoutClient_instances, linkCardFor_fn).call(this, checkpoint, wallet, linkApprovalTimeoutMs, signal);
+    return __privateMethod(this, _CheckoutClient_instances, linkCardFor_fn).call(this, checkpoint, wallet, {
+      linkApprovalTimeoutMs,
+      signal,
+      onLinkApproval
+    });
   }
   /**
    * The final total differs from the one the Link card covers. This cancels
@@ -3203,10 +3285,18 @@ var CheckoutClient = class {
    * for it. Confirm the returned checkpoint with the same total.
    */
   async replaceLinkCard(previous, input) {
-    const { wallet, amountMinor, ownerApprovalTimeoutMs, linkApprovalTimeoutMs, signal } = input;
+    const {
+      wallet,
+      amountMinor,
+      ownerApprovalTimeoutMs,
+      linkApprovalTimeoutMs,
+      onLinkApproval,
+      signal
+    } = input;
     if (!Number.isSafeInteger(amountMinor) || amountMinor <= 0) {
       throw checkoutError("amountMinor must be a positive integer number of cents");
     }
+    assertLinkApprovalCallback(onLinkApproval);
     if (amountMinor === previous.checkpoint.amountMinor) return previous;
     const old = previous.checkpoint;
     if (!await closeLinkRequest(wallet, previous.linkRequestId)) {
@@ -3245,12 +3335,17 @@ var CheckoutClient = class {
         ...signal ? { signal } : {}
       });
     }
-    return __privateMethod(this, _CheckoutClient_instances, linkCardFor_fn).call(this, checkpoint, wallet, linkApprovalTimeoutMs, signal);
+    return __privateMethod(this, _CheckoutClient_instances, linkCardFor_fn).call(this, checkpoint, wallet, {
+      linkApprovalTimeoutMs,
+      signal,
+      onLinkApproval
+    });
   }
 };
 _client4 = new WeakMap();
 _CheckoutClient_instances = new WeakSet();
-linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 * 6e4, signal) {
+linkCardFor_fn = async function(checkpoint, wallet, options) {
+  const { linkApprovalTimeoutMs = 10 * 6e4, signal, onLinkApproval } = options;
   if (checkpoint.stage !== "APPROVED") {
     throw checkoutError(
       `Conto has not approved a card for this checkpoint (stage ${checkpoint.stage}). Do not pay.`,
@@ -3260,6 +3355,7 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
   const deadline = Date.now() + linkApprovalTimeoutMs;
   const call = signal ? { signal } : {};
   let linkRequestId;
+  let approvalUrl;
   let createStarted = false;
   try {
     const cardRequest = linkCardRequest(checkpoint);
@@ -3280,6 +3376,13 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
         message: "Link returned a request for a different amount."
       });
     }
+    if (LINK_WAITING_STATUSES.has(request.status)) {
+      const details = linkApprovalDetails(request);
+      approvalUrl = details.approvalUrl;
+      if (onLinkApproval) {
+        notifyLinkApproval(onLinkApproval, { checkpoint, linkRequestId: request.id, ...details });
+      }
+    }
     while (linkRequestWaiting(request)) {
       const remainingSeconds = Math.floor((deadline - Date.now()) / 1e3);
       if (remainingSeconds <= 0) {
@@ -3294,6 +3397,7 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
         ...call,
         timeoutSeconds: remainingSeconds
       });
+      approvalUrl = LINK_WAITING_STATUSES.has(request.status) ? linkApprovalDetails(request).approvalUrl ?? approvalUrl : void 0;
       if (linkRequestWaiting(request) && Date.now() - started < 1e3) {
         await sleep2(1e3, signal);
       }
@@ -3325,6 +3429,7 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
         code: "LINK_CARD_NOT_CANCELLED",
         checkpoint,
         linkRequestId,
+        ...approvalUrl ? { approvalUrl } : {},
         holdReleased: false,
         retryGuidance: "Retry with the same input to resume this Link request, or cancel it with wallet.cancel(error.linkRequestId) and then call checkout.cancel(error.checkpoint.id)."
       });
@@ -3338,6 +3443,7 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
       code: failure.code,
       checkpoint,
       ...linkRequestId ? { linkRequestId } : {},
+      ...linkRequestId && approvalUrl ? { approvalUrl } : {},
       holdReleased
     });
   }