@conto_finance/sdk 0.6.0-beta.1 → 0.6.0-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -60,74 +60,39 @@ if (request.status === 'APPROVED') {
60
60
  }
61
61
  ```
62
62
 
63
- ## Link Pay Token checkout pilot
63
+ ## Checkout checkpoints
64
64
 
65
- Install the Link pilot with `npm install @conto_finance/sdk@0.6.0-beta.1` (the `beta` channel).
66
- For a credential-free local workflow test:
65
+ Use `conto.checkout` when your agent runs its own checkout. Call Conto right before the payment
66
+ method opens and again right before the payment is submitted. Conto checks the agent's rules at
67
+ both points and holds the spend in between. Your checkout must stop whenever a call fails.
67
68
 
68
- ```typescript
69
- import { createLinkTestClient } from '@conto_finance/sdk/link-testing';
70
- const test = createLinkTestClient({ scenario: 'approved' });
71
- // Use the purchase shape below, then simulate the owner's approval explicitly.
72
- const payment = await test.link.pay(purchase);
73
- await test.link.approve(payment.executionId);
74
- const result = await test.link.resume(payment.executionId);
75
- // result.mode === 'SIMULATED'; result.settlementVerified === false
76
- ```
77
-
78
- Scenarios include `approved`, `denied`, `expired`, and `interrupted`. This in-memory simulator
79
- makes no network calls and does not validate real policy, credentials, checkout, or settlement.
80
- It uses the same SDK workflow helper; the live client has no `approve()` method.
81
-
82
-
83
- SDK 0.6.0-beta.1 adds a one-call payment helper for configured live Link checkouts. The stable
84
- 0.5.5 package does not include this helper.
85
- This remains an assisted pilot: an operator configures the checkout profile and a signed-in owner
86
- connects Link and binds it to your agent. Only self-contained USD digital-goods checkouts are
87
- supported. See the [runnable example](../../examples/link-checkout-sdk/README.md) for package
88
- installation and the [operator setup](../../docs/STRIPE_LINK_PAY_TOKEN_RUNTIME.md) for prerequisites.
69
+ Checkout checkpoints need SDK 0.6.0-beta.2 or later: `npm install @conto_finance/sdk@beta`.
89
70
 
90
71
  ```typescript
91
- const conto = new Conto({
92
- apiKey: process.env.CONTO_API_KEY!,
93
- link: { connectionId: 'owner_connection_id', paymentMethodId: 'selected_payment_method_id' },
72
+ const checkpoint = await conto.checkout.begin({
73
+ idempotencyKey: order.id,
74
+ merchant: { id: 'acme-retail', name: 'ACME Retail', checkoutUrl: page.url() },
75
+ amountMinor: 7900,
76
+ purpose: 'Drip coffee maker the shopper chose',
77
+ lineItems: [{ name: 'Drip coffee maker', quantity: 1, unitAmountMinor: 7900 }],
78
+ });
79
+ // Open Link. The buyer signs in and the final total appears.
80
+
81
+ const confirmed = await conto.checkout.confirm(checkpoint, {
82
+ amountMinor: finalTotal,
83
+ totals: finalTotals, // tax and shipping, if the total changed
94
84
  });
85
+ // Submit the payment, then report what happened.
95
86
 
96
- // Save one idempotency key per purchase before sending. These are illustrative cart values.
97
- const purchase = {
98
- idempotencyKey: 'persisted_order_123',
99
- merchantId: 'configured_checkout_profile',
100
- checkoutUrl: 'https://shop.example/checkout/order_123',
101
- amountMinor: 1200,
102
- purpose: 'Purchase a digital report',
103
- lineItems: [{ name: 'Digital report', quantity: 1, unitAmountMinor: 1200 }],
104
- };
105
- const payment = await conto.link.pay(purchase);
87
+ await conto.checkout.reportOutcome(confirmed.id, { outcome: 'PAID', reference: orderNumber });
106
88
  ```
107
89
 
108
- Before paying, call `await conto.link.setup({ merchantId: purchase.merchantId })` with an
109
- `agents:read` key. It returns versioned checks with the responsible actor and missing payment
110
- scopes, including owner binding/expiry, deployment profiles, runtime configuration, and the
111
- active wallet assignment currently required for budget reservations. It runs while the execution
112
- gate is off, reads metadata only, and never authorizes a purchase. `configurationStatus:
113
- 'CONFIGURED'` is not proof of provider connectivity, policy approval, available funds, or settlement.
114
-
115
- Persist `payment.executionId`. When `nextAction` is `APPROVE_IN_LINK`, show `payment.approvalUrl`
116
- to the owner. After approval, call `await conto.link.resume(payment.executionId)` to continue that
117
- same purchase. `await conto.link.status(payment.executionId)` refreshes evidence without paying;
118
- `cancel(id)` requests cancellation. `paymentMethods()` lists masked LIVE funding sources using
119
- the configured connection. No method returns a Link credential.
120
-
121
- `pay()` executes immediately only when the server returns READY. It never polls indefinitely or
122
- retries an execution write. Policy denial and pending Conto approval throw `ContoError` before
123
- Link is called. An execution/cancellation error is a `LinkPaymentExecutionError` with the original
124
- `executionId` and `nextAction: 'RECONCILE'`; inspect `link.status(error.executionId)` before any
125
- further payment action. Do not create another purchase to recover from an uncertain result.
126
-
127
- Supply `totals` when tax, fees, or discounts change the amount from the line-item sum. Server
128
- checkout verification remains authoritative. `PROCESSING` or `COMPLETED` does not prove
129
- settlement. The helper simplifies SDK calls; owner login, profile setup, and live validation are
130
- still required, and separate unrestricted payment tools remain outside this flow.
90
+ - If the final total differs from the approved one, `confirm()` starts a new checkpoint at the
91
+ final total, so the rules check the amount actually paid.
92
+ - `reportOutcome()` accepts `PAID`, `NOT_PAID`, or `UNKNOWN`. Until an outcome arrives, the spend
93
+ stays counted. Cancel an unconfirmed checkpoint with `conto.checkout.cancel(id)`.
94
+ - Conto records what your checkout reports and does not see the charge. For control at the
95
+ moment of payment, pay with a Conto-managed wallet or a card Conto authorizes.
131
96
 
132
97
  ## External-card Policy Overlay
133
98
 
package/dist/index.d.mts CHANGED
@@ -739,8 +739,11 @@ declare class AdminCardsClient {
739
739
  /** List overlay requests, including executions that need receipt reconciliation. */
740
740
  listRequests(input?: ListExternalCardRequestsInput): Promise<ListExternalCardRequestsResponse>;
741
741
  /**
742
- * Resolve a claimed execution after checking the customer's processor or
743
- * receipt. Resolving NOT_EXECUTED releases the reserved policy amount.
742
+ * @deprecated Resolution requires a signed-in user. SDK admin keys and
743
+ * organization API keys receive HTTP 403 INSUFFICIENT_PERMISSIONS from this
744
+ * endpoint. Have a signed-in organization owner or admin review the processor
745
+ * evidence and resolve the request through Conto's authenticated interface.
746
+ * Retained for source compatibility; this method does not bypass that restriction.
744
747
  */
745
748
  resolveRequest(requestId: string, input: ResolveExternalCardRequestInput): Promise<ResolveExternalCardRequestResult>;
746
749
  /** Pause the Conto-controlled path and revoke live overlay grants. */
@@ -1701,6 +1704,72 @@ interface CommerceFulfillmentInput {
1701
1704
  postalCode?: string;
1702
1705
  countryCode?: string;
1703
1706
  }
1707
+ type CheckoutCheckpointMethod = 'LINK' | 'CARD' | 'SHOP_PAY' | 'PAYPAL';
1708
+ type CheckoutCheckpointStage = 'APPROVED' | 'CONFIRMING' | 'CONFIRMED' | 'PAID' | 'NOT_PAID' | 'OUTCOME_UNKNOWN' | 'DENIED' | 'CANCELLED' | 'EXPIRED';
1709
+ type CheckoutCheckpointNextAction = 'CONFIRM_BEFORE_PAYING' | 'PAY_THEN_REPORT_OUTCOME' | 'REPORT_OUTCOME' | 'WAIT' | 'NONE';
1710
+ type CheckoutOutcome = 'PAID' | 'NOT_PAID' | 'UNKNOWN';
1711
+ /** First checkpoint: the purchase as the checkout shows it before the payment method opens. */
1712
+ interface BeginCheckoutCheckpointInput {
1713
+ /** Stable key for this purchase. Reuse it to retry begin safely. */
1714
+ idempotencyKey: string;
1715
+ merchant: {
1716
+ id: string;
1717
+ name: string;
1718
+ checkoutUrl: string;
1719
+ };
1720
+ /** Integer amount in minor units (cents). */
1721
+ amountMinor: number;
1722
+ currency?: 'USD';
1723
+ purpose: string;
1724
+ /** Optional semantic policy category, such as OFFICE_SUPPLIES. */
1725
+ category?: string;
1726
+ /** Defaults to LINK. */
1727
+ checkoutMethod?: CheckoutCheckpointMethod;
1728
+ lineItems: CommerceLineItemInput[];
1729
+ /** Defaults to one Total entry equal to amountMinor. */
1730
+ totals?: CommerceTotalInput[];
1731
+ }
1732
+ /** Second checkpoint: the final total shown right before the payment is submitted. */
1733
+ interface ConfirmCheckoutCheckpointInput {
1734
+ amountMinor: number;
1735
+ currency?: 'USD';
1736
+ /** Final line items, needed only when the total changed. Defaults to the approved items. */
1737
+ lineItems?: CommerceLineItemInput[];
1738
+ /** Final totals, such as tax and shipping. Defaults to one Total entry. */
1739
+ totals?: CommerceTotalInput[];
1740
+ /** Page where the payment is submitted: the merchant's site or the payment method's. */
1741
+ pageUrl?: string;
1742
+ }
1743
+ interface ReportCheckoutOutcomeInput {
1744
+ outcome: CheckoutOutcome;
1745
+ /** Merchant order or receipt number. Never a payment credential. */
1746
+ reference?: string;
1747
+ }
1748
+ interface CheckoutCheckpoint {
1749
+ id: string;
1750
+ idempotencyKey: string;
1751
+ agentId?: string;
1752
+ checkoutMethod: CheckoutCheckpointMethod;
1753
+ stage: CheckoutCheckpointStage;
1754
+ nextAction: CheckoutCheckpointNextAction;
1755
+ amountMinor: number;
1756
+ currency: string;
1757
+ purpose: string;
1758
+ category?: string;
1759
+ merchant: {
1760
+ id: string;
1761
+ name: string;
1762
+ checkoutUrl?: string;
1763
+ };
1764
+ cart: {
1765
+ lineItems: CommerceLineItemInput[];
1766
+ totals: CommerceTotalInput[];
1767
+ };
1768
+ expiresAt: string;
1769
+ outcomeReference?: string;
1770
+ /** Outcomes are reported by your checkout. Conto does not verify settlement here. */
1771
+ settlementVerified: false;
1772
+ }
1704
1773
  /** Exact Stripe Link purchase intent evaluated and bound by Conto policy. */
1705
1774
  interface BeginCommerceExecutionCommonInput {
1706
1775
  /** Stable key for this exact intent. Reuse it when reconciling or retrying begin. */
@@ -2427,6 +2496,8 @@ declare class Conto {
2427
2496
  private baseUrl;
2428
2497
  private timeout;
2429
2498
  link: LinkClient;
2499
+ /** Lightweight checkpoints before the payment method opens and before payment. */
2500
+ checkout: CheckoutClient;
2430
2501
  payments: PaymentsClient;
2431
2502
  cards: CardsClient;
2432
2503
  connectedCards: ConnectedCardsClient;
@@ -2785,7 +2856,30 @@ declare class MppClient {
2785
2856
 
2786
2857
  /** Narrow transport contract used by the isolated, credential-free test client. */
2787
2858
  type LinkCommerceClient = Pick<Conto, 'getLinkSetup' | 'listStripeLinkPaymentMethods' | 'beginCommerceExecution' | 'getCommerceExecution' | 'refreshCommerceExecution' | 'executeCommerceExecution' | 'cancelCommerceExecution'>;
2788
- /** High-level client for the configured Link Pay Token checkout pilot. */
2859
+ /**
2860
+ * Lightweight checkout checkpoints for any agent runtime. Call begin() before the
2861
+ * payment method opens and confirm() right before the payment is submitted. Pay
2862
+ * only after confirm() succeeds, then report the outcome. Conto decides and
2863
+ * records each step; your checkout enforces the answer.
2864
+ */
2865
+ declare class CheckoutClient {
2866
+ #private;
2867
+ constructor(client: Pick<Conto, 'request'>);
2868
+ /** First checkpoint. A ContoError means Conto did not approve: stop the checkout. */
2869
+ begin(input: BeginCheckoutCheckpointInput): Promise<CheckoutCheckpoint>;
2870
+ /**
2871
+ * Second checkpoint, right before the payment is submitted. If the total
2872
+ * changed since begin() (tax or shipping, for example), this cancels the
2873
+ * approved checkpoint and starts a new one at the final total, so the agent's
2874
+ * rules see the amount actually being paid. Pay only if this resolves.
2875
+ */
2876
+ confirm(checkpoint: CheckoutCheckpoint, input: ConfirmCheckoutCheckpointInput): Promise<CheckoutCheckpoint>;
2877
+ /** Report what happened after a confirmed checkpoint. Safe to repeat with the same outcome. */
2878
+ reportOutcome(checkpointId: string, input: ReportCheckoutOutcomeInput): Promise<CheckoutCheckpoint>;
2879
+ /** Cancel a checkpoint that was not confirmed and release its spend. */
2880
+ cancel(checkpointId: string): Promise<CheckoutCheckpoint>;
2881
+ get(checkpointId: string): Promise<CheckoutCheckpoint>;
2882
+ }
2789
2883
  declare class LinkClient {
2790
2884
  #private;
2791
2885
  constructor(client: LinkCommerceClient, defaults?: LinkPaymentDefaults);
@@ -2813,4 +2907,4 @@ declare class LinkClient {
2813
2907
  private result;
2814
2908
  }
2815
2909
 
2816
- 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, LinkClient, type LinkCommerceClient, type LinkPaymentDefaults, LinkPaymentExecutionError, type LinkPaymentInput, type LinkPaymentNextAction, type LinkPaymentResult, type LinkSetupCheck, type LinkSetupInput, type LinkSetupResult, 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 SetupCapabilityState, type SetupCardDiagnostics, type SetupDiagnosticAction, type SetupDiagnosticIssue, type SetupDiagnosticIssueCode, type SetupDiagnostics, type SetupWalletDiagnostics, type StripeLinkCheckoutReadiness, type StripeLinkCheckoutReadinessResult, type StripeLinkCheckoutReadinessStatus, type StripeLinkCheckoutVerification, type StripeLinkPaymentMethod, 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 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 };
2910
+ 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 BeginCheckoutCheckpointInput, 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 CheckoutCheckpoint, 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 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, LinkClient, type LinkCommerceClient, type LinkPaymentDefaults, LinkPaymentExecutionError, type LinkPaymentInput, type LinkPaymentNextAction, type LinkPaymentResult, type LinkSetupCheck, type LinkSetupInput, type LinkSetupResult, 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 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 StripeLinkCheckoutReadiness, type StripeLinkCheckoutReadinessResult, type StripeLinkCheckoutReadinessStatus, type StripeLinkCheckoutVerification, type StripeLinkPaymentMethod, 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 Wallet, type WalletChainBalanceSnapshot, type WalletStatus, type WalletType, type X402Authorization, type X402BudgetResult, type X402PayInput, type X402PayResult, type X402PaymentRequirements, type X402PreAuthorizeInput, type X402PreAuthorizeResult, type X402RecordInput, type X402RecordResult, canonicalizeBrowserCheckoutTarget, createVerifiedBrowserCheckoutDriver, Conto as default, fingerprintBrowserCheckoutTarget };
package/dist/index.d.ts CHANGED
@@ -739,8 +739,11 @@ declare class AdminCardsClient {
739
739
  /** List overlay requests, including executions that need receipt reconciliation. */
740
740
  listRequests(input?: ListExternalCardRequestsInput): Promise<ListExternalCardRequestsResponse>;
741
741
  /**
742
- * Resolve a claimed execution after checking the customer's processor or
743
- * receipt. Resolving NOT_EXECUTED releases the reserved policy amount.
742
+ * @deprecated Resolution requires a signed-in user. SDK admin keys and
743
+ * organization API keys receive HTTP 403 INSUFFICIENT_PERMISSIONS from this
744
+ * endpoint. Have a signed-in organization owner or admin review the processor
745
+ * evidence and resolve the request through Conto's authenticated interface.
746
+ * Retained for source compatibility; this method does not bypass that restriction.
744
747
  */
745
748
  resolveRequest(requestId: string, input: ResolveExternalCardRequestInput): Promise<ResolveExternalCardRequestResult>;
746
749
  /** Pause the Conto-controlled path and revoke live overlay grants. */
@@ -1701,6 +1704,72 @@ interface CommerceFulfillmentInput {
1701
1704
  postalCode?: string;
1702
1705
  countryCode?: string;
1703
1706
  }
1707
+ type CheckoutCheckpointMethod = 'LINK' | 'CARD' | 'SHOP_PAY' | 'PAYPAL';
1708
+ type CheckoutCheckpointStage = 'APPROVED' | 'CONFIRMING' | 'CONFIRMED' | 'PAID' | 'NOT_PAID' | 'OUTCOME_UNKNOWN' | 'DENIED' | 'CANCELLED' | 'EXPIRED';
1709
+ type CheckoutCheckpointNextAction = 'CONFIRM_BEFORE_PAYING' | 'PAY_THEN_REPORT_OUTCOME' | 'REPORT_OUTCOME' | 'WAIT' | 'NONE';
1710
+ type CheckoutOutcome = 'PAID' | 'NOT_PAID' | 'UNKNOWN';
1711
+ /** First checkpoint: the purchase as the checkout shows it before the payment method opens. */
1712
+ interface BeginCheckoutCheckpointInput {
1713
+ /** Stable key for this purchase. Reuse it to retry begin safely. */
1714
+ idempotencyKey: string;
1715
+ merchant: {
1716
+ id: string;
1717
+ name: string;
1718
+ checkoutUrl: string;
1719
+ };
1720
+ /** Integer amount in minor units (cents). */
1721
+ amountMinor: number;
1722
+ currency?: 'USD';
1723
+ purpose: string;
1724
+ /** Optional semantic policy category, such as OFFICE_SUPPLIES. */
1725
+ category?: string;
1726
+ /** Defaults to LINK. */
1727
+ checkoutMethod?: CheckoutCheckpointMethod;
1728
+ lineItems: CommerceLineItemInput[];
1729
+ /** Defaults to one Total entry equal to amountMinor. */
1730
+ totals?: CommerceTotalInput[];
1731
+ }
1732
+ /** Second checkpoint: the final total shown right before the payment is submitted. */
1733
+ interface ConfirmCheckoutCheckpointInput {
1734
+ amountMinor: number;
1735
+ currency?: 'USD';
1736
+ /** Final line items, needed only when the total changed. Defaults to the approved items. */
1737
+ lineItems?: CommerceLineItemInput[];
1738
+ /** Final totals, such as tax and shipping. Defaults to one Total entry. */
1739
+ totals?: CommerceTotalInput[];
1740
+ /** Page where the payment is submitted: the merchant's site or the payment method's. */
1741
+ pageUrl?: string;
1742
+ }
1743
+ interface ReportCheckoutOutcomeInput {
1744
+ outcome: CheckoutOutcome;
1745
+ /** Merchant order or receipt number. Never a payment credential. */
1746
+ reference?: string;
1747
+ }
1748
+ interface CheckoutCheckpoint {
1749
+ id: string;
1750
+ idempotencyKey: string;
1751
+ agentId?: string;
1752
+ checkoutMethod: CheckoutCheckpointMethod;
1753
+ stage: CheckoutCheckpointStage;
1754
+ nextAction: CheckoutCheckpointNextAction;
1755
+ amountMinor: number;
1756
+ currency: string;
1757
+ purpose: string;
1758
+ category?: string;
1759
+ merchant: {
1760
+ id: string;
1761
+ name: string;
1762
+ checkoutUrl?: string;
1763
+ };
1764
+ cart: {
1765
+ lineItems: CommerceLineItemInput[];
1766
+ totals: CommerceTotalInput[];
1767
+ };
1768
+ expiresAt: string;
1769
+ outcomeReference?: string;
1770
+ /** Outcomes are reported by your checkout. Conto does not verify settlement here. */
1771
+ settlementVerified: false;
1772
+ }
1704
1773
  /** Exact Stripe Link purchase intent evaluated and bound by Conto policy. */
1705
1774
  interface BeginCommerceExecutionCommonInput {
1706
1775
  /** Stable key for this exact intent. Reuse it when reconciling or retrying begin. */
@@ -2427,6 +2496,8 @@ declare class Conto {
2427
2496
  private baseUrl;
2428
2497
  private timeout;
2429
2498
  link: LinkClient;
2499
+ /** Lightweight checkpoints before the payment method opens and before payment. */
2500
+ checkout: CheckoutClient;
2430
2501
  payments: PaymentsClient;
2431
2502
  cards: CardsClient;
2432
2503
  connectedCards: ConnectedCardsClient;
@@ -2785,7 +2856,30 @@ declare class MppClient {
2785
2856
 
2786
2857
  /** Narrow transport contract used by the isolated, credential-free test client. */
2787
2858
  type LinkCommerceClient = Pick<Conto, 'getLinkSetup' | 'listStripeLinkPaymentMethods' | 'beginCommerceExecution' | 'getCommerceExecution' | 'refreshCommerceExecution' | 'executeCommerceExecution' | 'cancelCommerceExecution'>;
2788
- /** High-level client for the configured Link Pay Token checkout pilot. */
2859
+ /**
2860
+ * Lightweight checkout checkpoints for any agent runtime. Call begin() before the
2861
+ * payment method opens and confirm() right before the payment is submitted. Pay
2862
+ * only after confirm() succeeds, then report the outcome. Conto decides and
2863
+ * records each step; your checkout enforces the answer.
2864
+ */
2865
+ declare class CheckoutClient {
2866
+ #private;
2867
+ constructor(client: Pick<Conto, 'request'>);
2868
+ /** First checkpoint. A ContoError means Conto did not approve: stop the checkout. */
2869
+ begin(input: BeginCheckoutCheckpointInput): Promise<CheckoutCheckpoint>;
2870
+ /**
2871
+ * Second checkpoint, right before the payment is submitted. If the total
2872
+ * changed since begin() (tax or shipping, for example), this cancels the
2873
+ * approved checkpoint and starts a new one at the final total, so the agent's
2874
+ * rules see the amount actually being paid. Pay only if this resolves.
2875
+ */
2876
+ confirm(checkpoint: CheckoutCheckpoint, input: ConfirmCheckoutCheckpointInput): Promise<CheckoutCheckpoint>;
2877
+ /** Report what happened after a confirmed checkpoint. Safe to repeat with the same outcome. */
2878
+ reportOutcome(checkpointId: string, input: ReportCheckoutOutcomeInput): Promise<CheckoutCheckpoint>;
2879
+ /** Cancel a checkpoint that was not confirmed and release its spend. */
2880
+ cancel(checkpointId: string): Promise<CheckoutCheckpoint>;
2881
+ get(checkpointId: string): Promise<CheckoutCheckpoint>;
2882
+ }
2789
2883
  declare class LinkClient {
2790
2884
  #private;
2791
2885
  constructor(client: LinkCommerceClient, defaults?: LinkPaymentDefaults);
@@ -2813,4 +2907,4 @@ declare class LinkClient {
2813
2907
  private result;
2814
2908
  }
2815
2909
 
2816
- 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, LinkClient, type LinkCommerceClient, type LinkPaymentDefaults, LinkPaymentExecutionError, type LinkPaymentInput, type LinkPaymentNextAction, type LinkPaymentResult, type LinkSetupCheck, type LinkSetupInput, type LinkSetupResult, 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 SetupCapabilityState, type SetupCardDiagnostics, type SetupDiagnosticAction, type SetupDiagnosticIssue, type SetupDiagnosticIssueCode, type SetupDiagnostics, type SetupWalletDiagnostics, type StripeLinkCheckoutReadiness, type StripeLinkCheckoutReadinessResult, type StripeLinkCheckoutReadinessStatus, type StripeLinkCheckoutVerification, type StripeLinkPaymentMethod, 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 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 };
2910
+ 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 BeginCheckoutCheckpointInput, 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 CheckoutCheckpoint, 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 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, LinkClient, type LinkCommerceClient, type LinkPaymentDefaults, LinkPaymentExecutionError, type LinkPaymentInput, type LinkPaymentNextAction, type LinkPaymentResult, type LinkSetupCheck, type LinkSetupInput, type LinkSetupResult, 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 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 StripeLinkCheckoutReadiness, type StripeLinkCheckoutReadinessResult, type StripeLinkCheckoutReadinessStatus, type StripeLinkCheckoutVerification, type StripeLinkPaymentMethod, 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 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 };