@conto_finance/sdk 0.5.5 → 0.6.0-beta.1
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 +73 -1
- package/dist/index.d.mts +114 -3
- package/dist/index.d.ts +114 -3
- package/dist/index.js +229 -9
- package/dist/index.mjs +227 -9
- package/dist/link-testing.d.mts +37 -0
- package/dist/link-testing.d.ts +37 -0
- package/dist/link-testing.js +264 -0
- package/dist/link-testing.mjs +244 -0
- package/package.json +11 -5
package/README.md
CHANGED
|
@@ -27,7 +27,10 @@ drop-in replacement for `ContoAdmin`.
|
|
|
27
27
|
## Verify the connection
|
|
28
28
|
|
|
29
29
|
Requires Node.js 20.19+. Call `await conto.setup()` to inspect your agent, linked wallets,
|
|
30
|
-
effective policies, and scopes without creating a payment.
|
|
30
|
+
effective policies, and scopes without creating a payment. Its `diagnostics` field reports the
|
|
31
|
+
environment, whether the key can request and execute payments, and issues that say whether the
|
|
32
|
+
agent or an owner acts next. See
|
|
33
|
+
[setup diagnostics](https://conto.finance/docs/sdk/installation#setup-diagnostics).
|
|
31
34
|
|
|
32
35
|
## Agent SDK Quick Start
|
|
33
36
|
|
|
@@ -57,6 +60,75 @@ if (request.status === 'APPROVED') {
|
|
|
57
60
|
}
|
|
58
61
|
```
|
|
59
62
|
|
|
63
|
+
## Link Pay Token checkout pilot
|
|
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:
|
|
67
|
+
|
|
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.
|
|
89
|
+
|
|
90
|
+
```typescript
|
|
91
|
+
const conto = new Conto({
|
|
92
|
+
apiKey: process.env.CONTO_API_KEY!,
|
|
93
|
+
link: { connectionId: 'owner_connection_id', paymentMethodId: 'selected_payment_method_id' },
|
|
94
|
+
});
|
|
95
|
+
|
|
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);
|
|
106
|
+
```
|
|
107
|
+
|
|
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.
|
|
131
|
+
|
|
60
132
|
## External-card Policy Overlay
|
|
61
133
|
|
|
62
134
|
The admin client registers only a masked card alias and assigns cooperative
|
package/dist/index.d.mts
CHANGED
|
@@ -989,6 +989,8 @@ interface ContoConfig {
|
|
|
989
989
|
baseUrl?: string;
|
|
990
990
|
/** Request timeout in milliseconds. Defaults to 30000 */
|
|
991
991
|
timeout?: number;
|
|
992
|
+
/** Defaults for the configured live Link checkout pilot. These are IDs, never Link credentials. */
|
|
993
|
+
link?: LinkPaymentDefaults;
|
|
992
994
|
}
|
|
993
995
|
interface PaymentRequestInput {
|
|
994
996
|
/** Amount in the wallet chain stablecoin */
|
|
@@ -1740,6 +1742,13 @@ type BeginConnectedLinkExecutionInput = BeginCommerceExecutionCommonInput & {
|
|
|
1740
1742
|
paymentMethodId: string;
|
|
1741
1743
|
};
|
|
1742
1744
|
type BeginCommerceExecutionInput = (BeginConnectedLinkExecutionInput & {
|
|
1745
|
+
executionMethod: 'LINK_PAY_TOKEN';
|
|
1746
|
+
/** A server-configured digital-goods profile and its checkout URL. */
|
|
1747
|
+
counterparty: {
|
|
1748
|
+
canonicalId: string;
|
|
1749
|
+
checkoutUrl: string;
|
|
1750
|
+
};
|
|
1751
|
+
}) | (BeginConnectedLinkExecutionInput & {
|
|
1743
1752
|
/** Primary path: the server resolves the immutable Stripe seller profile. */
|
|
1744
1753
|
executionMethod: 'STRIPE_PAYMENT_INTENT';
|
|
1745
1754
|
counterparty: {
|
|
@@ -1783,6 +1792,66 @@ type BeginCommerceExecutionInput = (BeginConnectedLinkExecutionInput & {
|
|
|
1783
1792
|
checkoutUrl: string;
|
|
1784
1793
|
};
|
|
1785
1794
|
});
|
|
1795
|
+
/** Configuration inspection only: no policy evaluation, credential retrieval, or purchase. */
|
|
1796
|
+
interface LinkSetupInput {
|
|
1797
|
+
connectionId?: string;
|
|
1798
|
+
paymentMethodId?: string;
|
|
1799
|
+
merchantId?: string;
|
|
1800
|
+
}
|
|
1801
|
+
interface LinkSetupCheck {
|
|
1802
|
+
code: string;
|
|
1803
|
+
status: 'PASS' | 'BLOCKED' | 'WARNING';
|
|
1804
|
+
actor: 'developer' | 'owner' | 'operator';
|
|
1805
|
+
message: string;
|
|
1806
|
+
}
|
|
1807
|
+
interface LinkSetupResult {
|
|
1808
|
+
version: 'conto.link-setup.v1';
|
|
1809
|
+
mode: 'LIVE' | 'SIMULATED';
|
|
1810
|
+
configurationStatus: 'CONFIGURED' | 'INCOMPLETE';
|
|
1811
|
+
checks: LinkSetupCheck[];
|
|
1812
|
+
missingScopes: string[];
|
|
1813
|
+
checkout?: {
|
|
1814
|
+
merchantId: string;
|
|
1815
|
+
origin: string;
|
|
1816
|
+
currency: 'USD';
|
|
1817
|
+
maxAmountMinor: number;
|
|
1818
|
+
};
|
|
1819
|
+
paymentAuthorization: 'NOT_EVALUATED';
|
|
1820
|
+
providerVerified: false;
|
|
1821
|
+
settlementVerified: false;
|
|
1822
|
+
}
|
|
1823
|
+
/** Reusable owner-provisioned identifiers. Per-purchase values can override these defaults. */
|
|
1824
|
+
interface LinkPaymentDefaults {
|
|
1825
|
+
connectionId: string;
|
|
1826
|
+
paymentMethodId: string;
|
|
1827
|
+
}
|
|
1828
|
+
/** Exact purchase facts for a configured USD digital-goods checkout. */
|
|
1829
|
+
interface LinkPaymentInput {
|
|
1830
|
+
/** Persist this key before calling pay; reuse it for this exact purchase across restarts. */
|
|
1831
|
+
idempotencyKey: string;
|
|
1832
|
+
connectionId?: string;
|
|
1833
|
+
paymentMethodId?: string;
|
|
1834
|
+
/** Canonical ID of a checkout profile already configured by the deployment operator. */
|
|
1835
|
+
merchantId: string;
|
|
1836
|
+
checkoutUrl: string;
|
|
1837
|
+
amountMinor: number;
|
|
1838
|
+
currency?: 'USD';
|
|
1839
|
+
purpose: string;
|
|
1840
|
+
category?: string;
|
|
1841
|
+
lineItems: CommerceLineItemInput[];
|
|
1842
|
+
/** Required when the final amount differs from the line-item sum. Include the exact total breakdown. */
|
|
1843
|
+
totals?: CommerceTotalInput[];
|
|
1844
|
+
}
|
|
1845
|
+
type LinkPaymentNextAction = 'APPROVE_IN_LINK' | 'WAIT' | 'RESUME' | 'RECONCILE' | 'NONE';
|
|
1846
|
+
/** Safe payment state; submission and completion are not proof of settlement. */
|
|
1847
|
+
interface LinkPaymentResult extends CommerceExecutionResult {
|
|
1848
|
+
executionId: string;
|
|
1849
|
+
status: CommerceExecutionStatus;
|
|
1850
|
+
nextAction: LinkPaymentNextAction;
|
|
1851
|
+
/** Present only while Link approval is needed. Show it to the account owner. */
|
|
1852
|
+
approvalUrl?: string;
|
|
1853
|
+
checkout?: ExecuteCommerceExecutionResult['checkout'];
|
|
1854
|
+
}
|
|
1786
1855
|
type CommerceExecutionStatus = 'DRAFT' | 'ACTION_REQUIRED' | 'AUTHORIZING' | 'AWAITING_APPROVAL' | 'READY' | 'PROCESSING' | 'SETTLED' | 'COMPLETED' | 'DENIED' | 'CANCELLED' | 'FAILED' | 'RETURNED' | 'EXPIRED' | 'NEEDS_RECONCILIATION';
|
|
1787
1856
|
type CommerceExecutionProvider = 'STABLECOIN' | 'TOKENIZED_CARD' | 'STRIPE_LINK';
|
|
1788
1857
|
type CommerceExecutionChannel = 'BROWSER' | 'MERCHANT_API' | 'CREDENTIAL_BROKER' | 'BANK_API' | 'WALLET_SIGNER';
|
|
@@ -2311,7 +2380,14 @@ declare class ContoError extends Error {
|
|
|
2311
2380
|
readonly actionUrl?: string;
|
|
2312
2381
|
readonly fieldErrors?: ApiErrorMetadata['fieldErrors'];
|
|
2313
2382
|
readonly reasons?: string[];
|
|
2314
|
-
|
|
2383
|
+
readonly diagnostics?: SetupDiagnostics;
|
|
2384
|
+
constructor(message: string, metadata: ApiErrorMetadata, diagnostics?: unknown);
|
|
2385
|
+
}
|
|
2386
|
+
/** Execution was attempted. Inspect this existing execution before any further payment action. */
|
|
2387
|
+
declare class LinkPaymentExecutionError extends ContoError {
|
|
2388
|
+
readonly executionId: string;
|
|
2389
|
+
readonly nextAction: "RECONCILE";
|
|
2390
|
+
constructor(executionId: string, error: unknown);
|
|
2315
2391
|
}
|
|
2316
2392
|
/**
|
|
2317
2393
|
* The customer executor returned a receipt, but Conto did not acknowledge the
|
|
@@ -2350,6 +2426,7 @@ declare class Conto {
|
|
|
2350
2426
|
#private;
|
|
2351
2427
|
private baseUrl;
|
|
2352
2428
|
private timeout;
|
|
2429
|
+
link: LinkClient;
|
|
2353
2430
|
payments: PaymentsClient;
|
|
2354
2431
|
cards: CardsClient;
|
|
2355
2432
|
connectedCards: ConnectedCardsClient;
|
|
@@ -2362,7 +2439,11 @@ declare class Conto {
|
|
|
2362
2439
|
* explicitly bound to this agent. No Link token or payment artifact is
|
|
2363
2440
|
* returned through the agent SDK.
|
|
2364
2441
|
*/
|
|
2365
|
-
listStripeLinkPaymentMethods(connectionId: string
|
|
2442
|
+
listStripeLinkPaymentMethods(connectionId: string, options?: {
|
|
2443
|
+
mode?: 'TEST' | 'LIVE';
|
|
2444
|
+
}): Promise<ListStripeLinkPaymentMethodsResult>;
|
|
2445
|
+
/** Read live Link configuration diagnostics without retrieving credentials or authorizing payment. */
|
|
2446
|
+
getLinkSetup(input?: LinkSetupInput): Promise<LinkSetupResult>;
|
|
2366
2447
|
/**
|
|
2367
2448
|
* Normalize and durably revise a partial agent purchase proposal without
|
|
2368
2449
|
* creating a payment side effect. Missing facts return as NEEDS_CONTEXT
|
|
@@ -2702,4 +2783,34 @@ declare class MppClient {
|
|
|
2702
2783
|
}): Promise<ProtocolServicesResult>;
|
|
2703
2784
|
}
|
|
2704
2785
|
|
|
2705
|
-
|
|
2786
|
+
/** Narrow transport contract used by the isolated, credential-free test client. */
|
|
2787
|
+
type LinkCommerceClient = Pick<Conto, 'getLinkSetup' | 'listStripeLinkPaymentMethods' | 'beginCommerceExecution' | 'getCommerceExecution' | 'refreshCommerceExecution' | 'executeCommerceExecution' | 'cancelCommerceExecution'>;
|
|
2788
|
+
/** High-level client for the configured Link Pay Token checkout pilot. */
|
|
2789
|
+
declare class LinkClient {
|
|
2790
|
+
#private;
|
|
2791
|
+
constructor(client: LinkCommerceClient, defaults?: LinkPaymentDefaults);
|
|
2792
|
+
/** Inspect the configured live path. This is not a payment authorization or provider connectivity test. */
|
|
2793
|
+
setup(input?: LinkSetupInput): Promise<LinkSetupResult>;
|
|
2794
|
+
/** Read masked LIVE funding sources; never selects a source or initiates payment. */
|
|
2795
|
+
paymentMethods(connectionId?: string): Promise<ListStripeLinkPaymentMethodsResult>;
|
|
2796
|
+
/**
|
|
2797
|
+
* Begin one exact intent and execute only if already READY. Otherwise return
|
|
2798
|
+
* the owner's approval action or existing state immediately, without polling.
|
|
2799
|
+
*/
|
|
2800
|
+
pay(input: LinkPaymentInput): Promise<LinkPaymentResult>;
|
|
2801
|
+
/**
|
|
2802
|
+
* Continue the existing payment after approval. Reads before any mutation and
|
|
2803
|
+
* never submits an execution already processing or requiring reconciliation.
|
|
2804
|
+
*/
|
|
2805
|
+
resume(executionId: string): Promise<LinkPaymentResult>;
|
|
2806
|
+
/** Observe and reconcile provider state. This method never submits a payment. */
|
|
2807
|
+
status(executionId: string): Promise<LinkPaymentResult>;
|
|
2808
|
+
/** Request cancellation of this existing Link payment; never retried automatically. */
|
|
2809
|
+
cancel(executionId: string): Promise<LinkPaymentResult>;
|
|
2810
|
+
private identifier;
|
|
2811
|
+
private assertLinkExecution;
|
|
2812
|
+
private executeIfReady;
|
|
2813
|
+
private result;
|
|
2814
|
+
}
|
|
2815
|
+
|
|
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 };
|
package/dist/index.d.ts
CHANGED
|
@@ -989,6 +989,8 @@ interface ContoConfig {
|
|
|
989
989
|
baseUrl?: string;
|
|
990
990
|
/** Request timeout in milliseconds. Defaults to 30000 */
|
|
991
991
|
timeout?: number;
|
|
992
|
+
/** Defaults for the configured live Link checkout pilot. These are IDs, never Link credentials. */
|
|
993
|
+
link?: LinkPaymentDefaults;
|
|
992
994
|
}
|
|
993
995
|
interface PaymentRequestInput {
|
|
994
996
|
/** Amount in the wallet chain stablecoin */
|
|
@@ -1740,6 +1742,13 @@ type BeginConnectedLinkExecutionInput = BeginCommerceExecutionCommonInput & {
|
|
|
1740
1742
|
paymentMethodId: string;
|
|
1741
1743
|
};
|
|
1742
1744
|
type BeginCommerceExecutionInput = (BeginConnectedLinkExecutionInput & {
|
|
1745
|
+
executionMethod: 'LINK_PAY_TOKEN';
|
|
1746
|
+
/** A server-configured digital-goods profile and its checkout URL. */
|
|
1747
|
+
counterparty: {
|
|
1748
|
+
canonicalId: string;
|
|
1749
|
+
checkoutUrl: string;
|
|
1750
|
+
};
|
|
1751
|
+
}) | (BeginConnectedLinkExecutionInput & {
|
|
1743
1752
|
/** Primary path: the server resolves the immutable Stripe seller profile. */
|
|
1744
1753
|
executionMethod: 'STRIPE_PAYMENT_INTENT';
|
|
1745
1754
|
counterparty: {
|
|
@@ -1783,6 +1792,66 @@ type BeginCommerceExecutionInput = (BeginConnectedLinkExecutionInput & {
|
|
|
1783
1792
|
checkoutUrl: string;
|
|
1784
1793
|
};
|
|
1785
1794
|
});
|
|
1795
|
+
/** Configuration inspection only: no policy evaluation, credential retrieval, or purchase. */
|
|
1796
|
+
interface LinkSetupInput {
|
|
1797
|
+
connectionId?: string;
|
|
1798
|
+
paymentMethodId?: string;
|
|
1799
|
+
merchantId?: string;
|
|
1800
|
+
}
|
|
1801
|
+
interface LinkSetupCheck {
|
|
1802
|
+
code: string;
|
|
1803
|
+
status: 'PASS' | 'BLOCKED' | 'WARNING';
|
|
1804
|
+
actor: 'developer' | 'owner' | 'operator';
|
|
1805
|
+
message: string;
|
|
1806
|
+
}
|
|
1807
|
+
interface LinkSetupResult {
|
|
1808
|
+
version: 'conto.link-setup.v1';
|
|
1809
|
+
mode: 'LIVE' | 'SIMULATED';
|
|
1810
|
+
configurationStatus: 'CONFIGURED' | 'INCOMPLETE';
|
|
1811
|
+
checks: LinkSetupCheck[];
|
|
1812
|
+
missingScopes: string[];
|
|
1813
|
+
checkout?: {
|
|
1814
|
+
merchantId: string;
|
|
1815
|
+
origin: string;
|
|
1816
|
+
currency: 'USD';
|
|
1817
|
+
maxAmountMinor: number;
|
|
1818
|
+
};
|
|
1819
|
+
paymentAuthorization: 'NOT_EVALUATED';
|
|
1820
|
+
providerVerified: false;
|
|
1821
|
+
settlementVerified: false;
|
|
1822
|
+
}
|
|
1823
|
+
/** Reusable owner-provisioned identifiers. Per-purchase values can override these defaults. */
|
|
1824
|
+
interface LinkPaymentDefaults {
|
|
1825
|
+
connectionId: string;
|
|
1826
|
+
paymentMethodId: string;
|
|
1827
|
+
}
|
|
1828
|
+
/** Exact purchase facts for a configured USD digital-goods checkout. */
|
|
1829
|
+
interface LinkPaymentInput {
|
|
1830
|
+
/** Persist this key before calling pay; reuse it for this exact purchase across restarts. */
|
|
1831
|
+
idempotencyKey: string;
|
|
1832
|
+
connectionId?: string;
|
|
1833
|
+
paymentMethodId?: string;
|
|
1834
|
+
/** Canonical ID of a checkout profile already configured by the deployment operator. */
|
|
1835
|
+
merchantId: string;
|
|
1836
|
+
checkoutUrl: string;
|
|
1837
|
+
amountMinor: number;
|
|
1838
|
+
currency?: 'USD';
|
|
1839
|
+
purpose: string;
|
|
1840
|
+
category?: string;
|
|
1841
|
+
lineItems: CommerceLineItemInput[];
|
|
1842
|
+
/** Required when the final amount differs from the line-item sum. Include the exact total breakdown. */
|
|
1843
|
+
totals?: CommerceTotalInput[];
|
|
1844
|
+
}
|
|
1845
|
+
type LinkPaymentNextAction = 'APPROVE_IN_LINK' | 'WAIT' | 'RESUME' | 'RECONCILE' | 'NONE';
|
|
1846
|
+
/** Safe payment state; submission and completion are not proof of settlement. */
|
|
1847
|
+
interface LinkPaymentResult extends CommerceExecutionResult {
|
|
1848
|
+
executionId: string;
|
|
1849
|
+
status: CommerceExecutionStatus;
|
|
1850
|
+
nextAction: LinkPaymentNextAction;
|
|
1851
|
+
/** Present only while Link approval is needed. Show it to the account owner. */
|
|
1852
|
+
approvalUrl?: string;
|
|
1853
|
+
checkout?: ExecuteCommerceExecutionResult['checkout'];
|
|
1854
|
+
}
|
|
1786
1855
|
type CommerceExecutionStatus = 'DRAFT' | 'ACTION_REQUIRED' | 'AUTHORIZING' | 'AWAITING_APPROVAL' | 'READY' | 'PROCESSING' | 'SETTLED' | 'COMPLETED' | 'DENIED' | 'CANCELLED' | 'FAILED' | 'RETURNED' | 'EXPIRED' | 'NEEDS_RECONCILIATION';
|
|
1787
1856
|
type CommerceExecutionProvider = 'STABLECOIN' | 'TOKENIZED_CARD' | 'STRIPE_LINK';
|
|
1788
1857
|
type CommerceExecutionChannel = 'BROWSER' | 'MERCHANT_API' | 'CREDENTIAL_BROKER' | 'BANK_API' | 'WALLET_SIGNER';
|
|
@@ -2311,7 +2380,14 @@ declare class ContoError extends Error {
|
|
|
2311
2380
|
readonly actionUrl?: string;
|
|
2312
2381
|
readonly fieldErrors?: ApiErrorMetadata['fieldErrors'];
|
|
2313
2382
|
readonly reasons?: string[];
|
|
2314
|
-
|
|
2383
|
+
readonly diagnostics?: SetupDiagnostics;
|
|
2384
|
+
constructor(message: string, metadata: ApiErrorMetadata, diagnostics?: unknown);
|
|
2385
|
+
}
|
|
2386
|
+
/** Execution was attempted. Inspect this existing execution before any further payment action. */
|
|
2387
|
+
declare class LinkPaymentExecutionError extends ContoError {
|
|
2388
|
+
readonly executionId: string;
|
|
2389
|
+
readonly nextAction: "RECONCILE";
|
|
2390
|
+
constructor(executionId: string, error: unknown);
|
|
2315
2391
|
}
|
|
2316
2392
|
/**
|
|
2317
2393
|
* The customer executor returned a receipt, but Conto did not acknowledge the
|
|
@@ -2350,6 +2426,7 @@ declare class Conto {
|
|
|
2350
2426
|
#private;
|
|
2351
2427
|
private baseUrl;
|
|
2352
2428
|
private timeout;
|
|
2429
|
+
link: LinkClient;
|
|
2353
2430
|
payments: PaymentsClient;
|
|
2354
2431
|
cards: CardsClient;
|
|
2355
2432
|
connectedCards: ConnectedCardsClient;
|
|
@@ -2362,7 +2439,11 @@ declare class Conto {
|
|
|
2362
2439
|
* explicitly bound to this agent. No Link token or payment artifact is
|
|
2363
2440
|
* returned through the agent SDK.
|
|
2364
2441
|
*/
|
|
2365
|
-
listStripeLinkPaymentMethods(connectionId: string
|
|
2442
|
+
listStripeLinkPaymentMethods(connectionId: string, options?: {
|
|
2443
|
+
mode?: 'TEST' | 'LIVE';
|
|
2444
|
+
}): Promise<ListStripeLinkPaymentMethodsResult>;
|
|
2445
|
+
/** Read live Link configuration diagnostics without retrieving credentials or authorizing payment. */
|
|
2446
|
+
getLinkSetup(input?: LinkSetupInput): Promise<LinkSetupResult>;
|
|
2366
2447
|
/**
|
|
2367
2448
|
* Normalize and durably revise a partial agent purchase proposal without
|
|
2368
2449
|
* creating a payment side effect. Missing facts return as NEEDS_CONTEXT
|
|
@@ -2702,4 +2783,34 @@ declare class MppClient {
|
|
|
2702
2783
|
}): Promise<ProtocolServicesResult>;
|
|
2703
2784
|
}
|
|
2704
2785
|
|
|
2705
|
-
|
|
2786
|
+
/** Narrow transport contract used by the isolated, credential-free test client. */
|
|
2787
|
+
type LinkCommerceClient = Pick<Conto, 'getLinkSetup' | 'listStripeLinkPaymentMethods' | 'beginCommerceExecution' | 'getCommerceExecution' | 'refreshCommerceExecution' | 'executeCommerceExecution' | 'cancelCommerceExecution'>;
|
|
2788
|
+
/** High-level client for the configured Link Pay Token checkout pilot. */
|
|
2789
|
+
declare class LinkClient {
|
|
2790
|
+
#private;
|
|
2791
|
+
constructor(client: LinkCommerceClient, defaults?: LinkPaymentDefaults);
|
|
2792
|
+
/** Inspect the configured live path. This is not a payment authorization or provider connectivity test. */
|
|
2793
|
+
setup(input?: LinkSetupInput): Promise<LinkSetupResult>;
|
|
2794
|
+
/** Read masked LIVE funding sources; never selects a source or initiates payment. */
|
|
2795
|
+
paymentMethods(connectionId?: string): Promise<ListStripeLinkPaymentMethodsResult>;
|
|
2796
|
+
/**
|
|
2797
|
+
* Begin one exact intent and execute only if already READY. Otherwise return
|
|
2798
|
+
* the owner's approval action or existing state immediately, without polling.
|
|
2799
|
+
*/
|
|
2800
|
+
pay(input: LinkPaymentInput): Promise<LinkPaymentResult>;
|
|
2801
|
+
/**
|
|
2802
|
+
* Continue the existing payment after approval. Reads before any mutation and
|
|
2803
|
+
* never submits an execution already processing or requiring reconciliation.
|
|
2804
|
+
*/
|
|
2805
|
+
resume(executionId: string): Promise<LinkPaymentResult>;
|
|
2806
|
+
/** Observe and reconcile provider state. This method never submits a payment. */
|
|
2807
|
+
status(executionId: string): Promise<LinkPaymentResult>;
|
|
2808
|
+
/** Request cancellation of this existing Link payment; never retried automatically. */
|
|
2809
|
+
cancel(executionId: string): Promise<LinkPaymentResult>;
|
|
2810
|
+
private identifier;
|
|
2811
|
+
private assertLinkExecution;
|
|
2812
|
+
private executeIfReady;
|
|
2813
|
+
private result;
|
|
2814
|
+
}
|
|
2815
|
+
|
|
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 };
|