@conto_finance/sdk 0.5.4 → 0.6.0-beta.1

package/dist/index.d.ts

@@ -989,6 +989,8 @@ interface ContoConfig {
     baseUrl?: string;
     /** Request timeout in milliseconds. Defaults to 30000 */
     timeout?: number;
+    /** Defaults for the configured live Link checkout pilot. These are IDs, never Link credentials. */
+    link?: LinkPaymentDefaults;
 }
 interface PaymentRequestInput {
     /** Amount in the wallet chain stablecoin */
@@ -1028,6 +1030,92 @@ interface PaymentRequestInput {
     /** Client-supplied key for idempotent retries */
     idempotencyKey?: string;
 }
+/** Whether a path works: `unknown` means Conto has no evidence either way. */
+type SetupCapabilityState = 'yes' | 'no' | 'unknown';
+/**
+ * Stable setup issue codes. New codes can appear within a diagnostics version,
+ * so handle an unrecognized code by its `severity` and `actor`.
+ */
+type SetupDiagnosticIssueCode = 'AGENT_PAUSED' | 'AGENT_FROZEN' | 'AGENT_UNAVAILABLE' | 'SDK_KEY_EXPIRED' | 'SDK_KEY_REVOKED' | 'SCOPE_MISSING' | 'NO_WALLET' | 'WALLET_PAUSED' | 'WALLET_UNAVAILABLE' | 'WALLET_VIEW_ONLY' | 'WALLET_UNFUNDED' | 'MAINNET_REQUIRES_PROD_AGENT' | 'LIVE_PAYMENTS_PAUSED' | 'LIVE_PAYMENTS_UNAVAILABLE' | 'EXTERNAL_SIGNER_REQUIRED' | 'SANDBOX_UNCLAIMED' | 'SANDBOX_EXPIRED' | (string & {});
+/** A next step: a documented command, an API call, or a dashboard page for an owner. */
+type SetupDiagnosticAction = {
+    type: 'command';
+    command: string;
+    description: string;
+} | {
+    type: 'api';
+    method: 'GET' | 'POST' | 'PATCH';
+    /** Relative to the Conto base URL. Segments in braces are placeholders. */
+    href: string;
+    credential: 'sdk_key' | 'sandbox_api_key' | 'organization_api_key';
+    requiredScope: string | null;
+    description: string;
+} | {
+    type: 'owner_url';
+    /** A dashboard page, relative to the Conto base URL. */
+    url: string;
+    description: string;
+};
+interface SetupDiagnosticIssue {
+    code: SetupDiagnosticIssueCode;
+    /** `error` blocks a capability of the resource. `info` explains how a path works. */
+    severity: 'error' | 'warning' | 'info';
+    /** Who can resolve it: the agent with its own credentials, or an owner. */
+    actor: 'agent' | 'owner';
+    resource: {
+        type: 'agent' | 'wallet' | 'sdk_key' | 'organization';
+        id: string | null;
+    };
+    message: string;
+    /** The missing scope for SCOPE_MISSING, otherwise null. */
+    requiredScope: string | null;
+    actions: SetupDiagnosticAction[];
+}
+interface SetupWalletDiagnostics {
+    walletId: string;
+    /** `simulated` sandbox, `managed` by Conto, `external` signer, or `unknown`. */
+    executionMode: 'simulated' | 'managed' | 'external' | 'unknown';
+    network: 'testnet' | 'mainnet';
+    /** `not_checked`: Conto does not read this wallet's balance. */
+    funding: 'not_required' | 'funded' | 'unfunded' | 'not_checked';
+    walletLimits: boolean;
+    canRequest: SetupCapabilityState;
+    canExecute: SetupCapabilityState;
+    issueCodes: SetupDiagnosticIssueCode[];
+}
+interface SetupCardDiagnostics {
+    availability: 'available' | 'unavailable';
+    reason: 'sandbox_organization' | 'disabled' | 'plan' | null;
+    assignedCards: number;
+    activeAuthorizations: number;
+    canUse: 'yes' | 'no';
+}
+/** Versioned setup diagnostics from `GET /api/sdk/setup`. */
+interface SetupDiagnostics {
+    version: 'conto.setup-diagnostics.v1';
+    environment: {
+        kind: 'anonymous_sandbox' | 'claimed_sandbox' | 'account';
+        settlement: 'simulated' | 'per_wallet';
+        agentEnvironment: 'DEV' | 'STAGING' | 'PROD';
+        sandboxExpiresAt: string | null;
+    } | null;
+    status: {
+        authenticated: boolean;
+        canRequest: SetupCapabilityState;
+        canExecute: SetupCapabilityState;
+        ownerActionRequired: boolean;
+    };
+    wallets: SetupWalletDiagnostics[];
+    /** Test and live cards, reported apart from wallets. */
+    connectedCards: {
+        test: SetupCardDiagnostics;
+        live: SetupCardDiagnostics;
+    } | null;
+    controls: {
+        effectivePolicies: number;
+    } | null;
+    issues: SetupDiagnosticIssue[];
+}
 interface AgentSetupResult {
     agent: {
         id: string;
@@ -1078,6 +1166,11 @@ interface AgentSetupResult {
         totalVolume: number;
     }>;
     scopes: string[];
+    /**
+     * What this key can do and what needs an owner. Null when the server could
+     * not compute it for this request. Absent from servers that predate it.
+     */
+    diagnostics?: SetupDiagnostics | null;
 }
 interface ExternalWalletApprovalInput {
     amount: number;
@@ -1649,6 +1742,13 @@ type BeginConnectedLinkExecutionInput = BeginCommerceExecutionCommonInput & {
     paymentMethodId: string;
 };
 type BeginCommerceExecutionInput = (BeginConnectedLinkExecutionInput & {
+    executionMethod: 'LINK_PAY_TOKEN';
+    /** A server-configured digital-goods profile and its checkout URL. */
+    counterparty: {
+        canonicalId: string;
+        checkoutUrl: string;
+    };
+}) | (BeginConnectedLinkExecutionInput & {
     /** Primary path: the server resolves the immutable Stripe seller profile. */
     executionMethod: 'STRIPE_PAYMENT_INTENT';
     counterparty: {
@@ -1692,6 +1792,66 @@ type BeginCommerceExecutionInput = (BeginConnectedLinkExecutionInput & {
         checkoutUrl: string;
     };
 });
+/** Configuration inspection only: no policy evaluation, credential retrieval, or purchase. */
+interface LinkSetupInput {
+    connectionId?: string;
+    paymentMethodId?: string;
+    merchantId?: string;
+}
+interface LinkSetupCheck {
+    code: string;
+    status: 'PASS' | 'BLOCKED' | 'WARNING';
+    actor: 'developer' | 'owner' | 'operator';
+    message: string;
+}
+interface LinkSetupResult {
+    version: 'conto.link-setup.v1';
+    mode: 'LIVE' | 'SIMULATED';
+    configurationStatus: 'CONFIGURED' | 'INCOMPLETE';
+    checks: LinkSetupCheck[];
+    missingScopes: string[];
+    checkout?: {
+        merchantId: string;
+        origin: string;
+        currency: 'USD';
+        maxAmountMinor: number;
+    };
+    paymentAuthorization: 'NOT_EVALUATED';
+    providerVerified: false;
+    settlementVerified: false;
+}
+/** Reusable owner-provisioned identifiers. Per-purchase values can override these defaults. */
+interface LinkPaymentDefaults {
+    connectionId: string;
+    paymentMethodId: string;
+}
+/** Exact purchase facts for a configured USD digital-goods checkout. */
+interface LinkPaymentInput {
+    /** Persist this key before calling pay; reuse it for this exact purchase across restarts. */
+    idempotencyKey: string;
+    connectionId?: string;
+    paymentMethodId?: string;
+    /** Canonical ID of a checkout profile already configured by the deployment operator. */
+    merchantId: string;
+    checkoutUrl: string;
+    amountMinor: number;
+    currency?: 'USD';
+    purpose: string;
+    category?: string;
+    lineItems: CommerceLineItemInput[];
+    /** Required when the final amount differs from the line-item sum. Include the exact total breakdown. */
+    totals?: CommerceTotalInput[];
+}
+type LinkPaymentNextAction = 'APPROVE_IN_LINK' | 'WAIT' | 'RESUME' | 'RECONCILE' | 'NONE';
+/** Safe payment state; submission and completion are not proof of settlement. */
+interface LinkPaymentResult extends CommerceExecutionResult {
+    executionId: string;
+    status: CommerceExecutionStatus;
+    nextAction: LinkPaymentNextAction;
+    /** Present only while Link approval is needed. Show it to the account owner. */
+    approvalUrl?: string;
+    checkout?: ExecuteCommerceExecutionResult['checkout'];
+}
 type CommerceExecutionStatus = 'DRAFT' | 'ACTION_REQUIRED' | 'AUTHORIZING' | 'AWAITING_APPROVAL' | 'READY' | 'PROCESSING' | 'SETTLED' | 'COMPLETED' | 'DENIED' | 'CANCELLED' | 'FAILED' | 'RETURNED' | 'EXPIRED' | 'NEEDS_RECONCILIATION';
 type CommerceExecutionProvider = 'STABLECOIN' | 'TOKENIZED_CARD' | 'STRIPE_LINK';
 type CommerceExecutionChannel = 'BROWSER' | 'MERCHANT_API' | 'CREDENTIAL_BROKER' | 'BANK_API' | 'WALLET_SIGNER';
@@ -2220,7 +2380,14 @@ declare class ContoError extends Error {
     readonly actionUrl?: string;
     readonly fieldErrors?: ApiErrorMetadata['fieldErrors'];
     readonly reasons?: string[];
-    constructor(message: string, metadata: ApiErrorMetadata);
+    readonly diagnostics?: SetupDiagnostics;
+    constructor(message: string, metadata: ApiErrorMetadata, diagnostics?: unknown);
+}
+/** Execution was attempted. Inspect this existing execution before any further payment action. */
+declare class LinkPaymentExecutionError extends ContoError {
+    readonly executionId: string;
+    readonly nextAction: "RECONCILE";
+    constructor(executionId: string, error: unknown);
 }
 /**
  * The customer executor returned a receipt, but Conto did not acknowledge the
@@ -2259,6 +2426,7 @@ declare class Conto {
     #private;
     private baseUrl;
     private timeout;
+    link: LinkClient;
     payments: PaymentsClient;
     cards: CardsClient;
     connectedCards: ConnectedCardsClient;
@@ -2271,7 +2439,11 @@ declare class Conto {
      * explicitly bound to this agent. No Link token or payment artifact is
      * returned through the agent SDK.
      */
-    listStripeLinkPaymentMethods(connectionId: string): Promise<ListStripeLinkPaymentMethodsResult>;
+    listStripeLinkPaymentMethods(connectionId: string, options?: {
+        mode?: 'TEST' | 'LIVE';
+    }): Promise<ListStripeLinkPaymentMethodsResult>;
+    /** Read live Link configuration diagnostics without retrieving credentials or authorizing payment. */
+    getLinkSetup(input?: LinkSetupInput): Promise<LinkSetupResult>;
     /**
      * Normalize and durably revise a partial agent purchase proposal without
      * creating a payment side effect. Missing facts return as NEEDS_CONTEXT
@@ -2338,7 +2510,10 @@ declare class Conto {
      * reconciliation.
      */
     cancelCommerceExecution(executionId: string): Promise<CommerceExecutionResult>;
-    /** Read credentials, linked wallets, effective policies, and scopes without creating a payment. */
+    /**
+     * Read credentials, linked wallets, effective policies, scopes, and setup
+     * diagnostics without creating a payment.
+     */
     setup(): Promise<AgentSetupResult>;
     /** Make an authenticated request to the Conto API */
     request<T>(method: string, path: string, body?: Record<string, unknown>, options?: ContoRequestOptions): Promise<T>;
@@ -2608,4 +2783,34 @@ declare class MppClient {
     }): Promise<ProtocolServicesResult>;
 }
 
-export { type AdminExternalCardOverlayEnforcement, type Agent, type AgentCheckoutAction, type AgentCheckoutActionKind, type AgentExternalCard, type AgentSetupResult, type AgentStatus, type AgentType, type AgentWalletLink, type ApprovedExternalCardExecution, type AssignExternalCardInput, type AssignedPolicy, type AuthorizeCheckoutActionResult, type BeginCommerceExecutionInput, type BrowserActionClaimResult, type BrowserActionDispatchObservationInput, BrowserActionFinalizationPendingError, type BrowserActionFinalizeResult, type BrowserCheckoutAction, type BrowserCheckoutTargetResolver, type BrowserCheckoutTargetSnapshot, type BrowserCheckoutTargetVerificationCode, BrowserCheckoutTargetVerificationError, type CanonicalBrowserCheckoutTargetSnapshot, CardsClient, type ChainType, type CheckoutActionAuthorization, type CommerceCheckoutMethod, type CommerceContextRequirement, type CommerceExecution, type CommerceExecutionAdapterKind, type CommerceExecutionArtifactKind, type CommerceExecutionChannel, type CommerceExecutionConstraint, type CommerceExecutionConstraintCoverage, type CommerceExecutionConstraintCoverageLevel, type CommerceExecutionDeliveryMode, type CommerceExecutionEvidence, type CommerceExecutionProvider, type CommerceExecutionResult, type CommerceExecutionSourceKind, type CommerceExecutionStatus, type CommerceFactConfidence, type CommerceFactProvenanceInput, type CommerceFactSource, type CommerceFulfillmentInput, type CommerceLineItemInput, type CommerceProposalFactKey, type CommerceProposalMissingFact, type CommerceProposalResolution, type CommerceProposalState, type CommerceSettlementRail, type CommerceTotalInput, type CommerceTotalType, type ComparePolicyVersionsResponse, type ConnectedCardBrief, type ConnectedCardCredential, type ConnectedCardDrawInput, type ConnectedCardDrawMerchant, type ConnectedCardDrawResult, type ConnectedCardDrawable, type ConnectedCardListResult, type ConnectedCardMandate, type ConnectedCardMandateMerchant, type ConnectedCardReference, ConnectedCardsClient, Conto, ContoAdmin, type ContoAdminConfig, ContoAdminError, type ContoConfig, ContoError, type ContoRequestOptions, type ControlledExternalCardPaymentResult, ControlledExternalCardPaymentTool, type CreateAgentInput, type CreatePolicyInput, type CreatePolicyRuleInput, type CreateSdkKeyInput, type CreateSdkKeyResult, type CreateWalletInput, type CustodyType, type CustomerCustodyMode, type CustomerWalletControlModel, type CustomerWalletKeyAccess, type DelegationType, type ExecuteCommerceExecutionResult, type ExternalCard, type ExternalCardApprovalInput, type ExternalCardApprovalResult, type ExternalCardConfirmationInput, ExternalCardConfirmationPendingError, type ExternalCardConfirmationResult, type ExternalCardExecutionClaimResult, type ExternalCardExecutionResult, type ExternalCardExecutor, type ExternalCardOverlayEnforcement, type ExternalCardRequestStatusResult, type ExternalWalletApprovalInput, type ExternalWalletApprovalResult, type ExternalWalletConfirmationInput, type ExternalWalletConfirmationResult, type FreezeAgentInput, Conto as Giro, type ContoConfig as GiroConfig, ContoError as GiroError, type GuardCheckoutResult, type GuardedBrowserDispatchResult, type GuardedCheckoutInput, type LinkWalletInput, type ListAgentsParams, type ListAgentsResponse, type ListPoliciesParams, type ListPoliciesResponse, type ListPolicyVersionsResponse, type ListStripeLinkPaymentMethodsResult, type ListWalletsParams, type ListWalletsResponse, type MppBudgetResult, type MppPreAuthorizeInput, type MppPreAuthorizeResult, type MppRecordInput, type MppRecordResult, type NormalizeCommerceProposalInput, type OrganizationMember, type PaginatedResponse, type PaginationParams, type PauseExternalCardAssignmentResult, type PaymentExecuteResult, type PaymentRequestInput, type PaymentRequestResult, type PaymentStatusResult, type Policy, type PolicyRule, type PolicyType, type PolicyVersionChangeType, type PolicyVersionDetail, type PolicyVersionDiff, type PolicyVersionFieldChange, type PolicyVersionSnapshot, type PolicyVersionSnapshotRule, type PolicyVersionSummary, type PrivilegedBrowserCheckoutDriver, type ProtocolBudgetResult, type ProtocolPreAuthorizeResult, type ProtocolRecordGrant, type ProtocolRecordGrantResult, type ProtocolServiceSummary, type ProtocolServicesResult, type ProvisionWalletResult, type RefreshBalanceResult, type RegisterExternalCardInput, type RollbackPolicyVersionResponse, type RuleAction, type RuleOperator, type RuleType, type RunGuardedCheckoutResult, type SdkKey, type SdkKeyType, type StripeLinkCheckoutReadiness, type StripeLinkCheckoutReadinessResult, type StripeLinkCheckoutReadinessStatus, type StripeLinkCheckoutVerification, type StripeLinkPaymentMethod, type 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 };
+/** Narrow transport contract used by the isolated, credential-free test client. */
+type LinkCommerceClient = Pick<Conto, 'getLinkSetup' | 'listStripeLinkPaymentMethods' | 'beginCommerceExecution' | 'getCommerceExecution' | 'refreshCommerceExecution' | 'executeCommerceExecution' | 'cancelCommerceExecution'>;
+/** High-level client for the configured Link Pay Token checkout pilot. */
+declare class LinkClient {
+    #private;
+    constructor(client: LinkCommerceClient, defaults?: LinkPaymentDefaults);
+    /** Inspect the configured live path. This is not a payment authorization or provider connectivity test. */
+    setup(input?: LinkSetupInput): Promise<LinkSetupResult>;
+    /** Read masked LIVE funding sources; never selects a source or initiates payment. */
+    paymentMethods(connectionId?: string): Promise<ListStripeLinkPaymentMethodsResult>;
+    /**
+     * Begin one exact intent and execute only if already READY. Otherwise return
+     * the owner's approval action or existing state immediately, without polling.
+     */
+    pay(input: LinkPaymentInput): Promise<LinkPaymentResult>;
+    /**
+     * Continue the existing payment after approval. Reads before any mutation and
+     * never submits an execution already processing or requiring reconciliation.
+     */
+    resume(executionId: string): Promise<LinkPaymentResult>;
+    /** Observe and reconcile provider state. This method never submits a payment. */
+    status(executionId: string): Promise<LinkPaymentResult>;
+    /** Request cancellation of this existing Link payment; never retried automatically. */
+    cancel(executionId: string): Promise<LinkPaymentResult>;
+    private identifier;
+    private assertLinkExecution;
+    private executeIfReady;
+    private result;
+}
+
+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.js

@@ -46,7 +46,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@conto_finance/sdk",
-      version: "0.5.4",
+      version: "0.6.0-beta.1",
       description: "Conto SDK for AI agent payment authorization",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
@@ -71,10 +71,16 @@ var require_package = __commonJS({
           types: "./dist/checkout-verifier.d.ts",
           import: "./dist/checkout-verifier.mjs",
           require: "./dist/checkout-verifier.js"
+        },
+        "./link-testing": {
+          types: "./dist/link-testing.d.ts",
+          import: "./dist/link-testing.mjs",
+          require: "./dist/link-testing.js"
         }
       },
       publishConfig: {
-        access: "public"
+        access: "public",
+        tag: "beta"
       },
       engines: {
         node: ">=20.19.0"
@@ -83,11 +89,11 @@ var require_package = __commonJS({
         "dist"
       ],
       scripts: {
-        build: "tsup src/index.ts src/playwright.ts src/browserbase.ts src/checkout-verifier.ts --format cjs,esm --dts",
-        dev: "tsup src/index.ts src/playwright.ts src/browserbase.ts src/checkout-verifier.ts --format cjs,esm --dts --watch",
+        build: "tsup",
+        dev: "tsup --watch",
         lint: "tsc --noEmit",
         test: "npm run lint && npm run test:contract && npm run test:consumer",
-        "test:contract": "npm run build && node --test test/contract.test.mjs test/playwright.test.mjs test/browserbase.test.mjs test/checkout-verifier.test.mjs test/developer-experience.test.mjs",
+        "test:contract": "npm run build && node --test test/contract.test.mjs test/playwright.test.mjs test/browserbase.test.mjs test/checkout-verifier.test.mjs test/developer-experience.test.mjs test/link.test.mjs test/link-testing.test.mjs",
         "test:consumer": "npm run build && node --test test/consumer.test.mjs",
         "verify:release": "node scripts/verify-release.mjs",
         prepublishOnly: "npm run verify:release && npm run lint && npm run test:contract && npm run test:consumer"
@@ -161,6 +167,8 @@ __export(index_exports, {
   ControlledExternalCardPaymentTool: () => ControlledExternalCardPaymentTool,
   ExternalCardConfirmationPendingError: () => ExternalCardConfirmationPendingError,
   Giro: () => Conto,
+  LinkClient: () => LinkClient,
+  LinkPaymentExecutionError: () => LinkPaymentExecutionError,
   TestCardsClient: () => TestCardsClient,
   canonicalizeBrowserCheckoutTarget: () => canonicalizeBrowserCheckoutTarget,
   createVerifiedBrowserCheckoutDriver: () => createVerifiedBrowserCheckoutDriver,
@@ -1053,7 +1061,7 @@ function isValidBrowserActionObservation(value) {
   }
 }
 var ContoError = class extends Error {
-  constructor(message, metadata) {
+  constructor(message, metadata, diagnostics) {
     super(message);
     this.name = "ContoError";
     this.code = metadata.code;
@@ -1064,6 +1072,30 @@ var ContoError = class extends Error {
     this.actionUrl = metadata.actionUrl;
     this.fieldErrors = metadata.fieldErrors;
     this.reasons = metadata.reasons;
+    if (diagnostics !== null && typeof diagnostics === "object" && !Array.isArray(diagnostics) && "version" in diagnostics && diagnostics.version === "conto.setup-diagnostics.v1") {
+      this.diagnostics = diagnostics;
+    }
+  }
+};
+var LinkPaymentExecutionError = class extends ContoError {
+  constructor(executionId, error) {
+    const original = error instanceof ContoError ? error : void 0;
+    super(
+      original?.message ?? "Link execution could not be confirmed",
+      {
+        code: original?.code ?? "LINK_EXECUTION_UNCONFIRMED",
+        status: original?.status ?? 0,
+        requestId: original?.requestId,
+        retryAfter: original?.retryAfter,
+        fieldErrors: original?.fieldErrors,
+        reasons: original?.reasons,
+        retryGuidance: "Call link.status(executionId) to reconcile. Do not create another purchase or retry execution blindly."
+      },
+      original?.diagnostics
+    );
+    this.nextAction = "RECONCILE";
+    this.name = "LinkPaymentExecutionError";
+    this.executionId = executionId;
   }
 };
 var ExternalCardConfirmationPendingError = class extends ContoError {
@@ -1155,6 +1187,7 @@ var Conto = class {
     this.baseUrl = (config.baseUrl || "https://conto.finance").replace(/\/$/, "");
     assertSecureBaseUrl(this.baseUrl);
     this.timeout = config.timeout || 3e4;
+    this.link = new LinkClient(this, config.link);
     this.payments = new PaymentsClient(this);
     this.cards = new CardsClient(this);
     this.connectedCards = new ConnectedCardsClient(this);
@@ -1167,10 +1200,24 @@ var Conto = class {
    * explicitly bound to this agent. No Link token or payment artifact is
    * returned through the agent SDK.
    */
-  async listStripeLinkPaymentMethods(connectionId) {
+  async listStripeLinkPaymentMethods(connectionId, options) {
     return this.request(
       "GET",
-      withQuery("/api/sdk/stripe-link/payment-methods", { connectionId })
+      withQuery("/api/sdk/stripe-link/payment-methods", {
+        connectionId,
+        ...options?.mode ? { mode: options.mode } : {}
+      })
+    );
+  }
+  /** Read live Link configuration diagnostics without retrieving credentials or authorizing payment. */
+  async getLinkSetup(input = {}) {
+    return this.request(
+      "GET",
+      withQuery("/api/sdk/stripe-link/setup", {
+        connectionId: input.connectionId,
+        paymentMethodId: input.paymentMethodId,
+        merchantId: input.merchantId
+      })
     );
   }
   /**
@@ -1433,7 +1480,10 @@ var Conto = class {
       rethrowAmbiguousCommerceMutation(error, executionId, "cancel");
     }
   }
-  /** Read credentials, linked wallets, effective policies, and scopes without creating a payment. */
+  /**
+   * Read credentials, linked wallets, effective policies, scopes, and setup
+   * diagnostics without creating a payment.
+   */
   async setup() {
     return this.request("GET", "/api/sdk/setup");
   }
@@ -1463,7 +1513,8 @@ var Conto = class {
       if (!response.ok) {
         throw new ContoError(
           responseErrorMessage(data, response.status),
-          responseErrorMetadata(response, data)
+          responseErrorMetadata(response, data),
+          data !== null && typeof data === "object" && "diagnostics" in data ? data.diagnostics : void 0
         );
       }
       return data;
@@ -2096,6 +2147,176 @@ var MppClient = class {
   }
 };
 var index_default = Conto;
+var _client, _defaults;
+var LinkClient = class {
+  constructor(client, defaults) {
+    __privateAdd(this, _client);
+    __privateAdd(this, _defaults);
+    __privateSet(this, _client, client);
+    __privateSet(this, _defaults, defaults ? { ...defaults } : void 0);
+  }
+  /** Inspect the configured live path. This is not a payment authorization or provider connectivity test. */
+  async setup(input = {}) {
+    return __privateGet(this, _client).getLinkSetup({
+      connectionId: input.connectionId ?? __privateGet(this, _defaults)?.connectionId,
+      paymentMethodId: input.paymentMethodId ?? __privateGet(this, _defaults)?.paymentMethodId,
+      merchantId: input.merchantId
+    });
+  }
+  /** Read masked LIVE funding sources; never selects a source or initiates payment. */
+  async paymentMethods(connectionId) {
+    return __privateGet(this, _client).listStripeLinkPaymentMethods(
+      this.identifier(connectionId ?? __privateGet(this, _defaults)?.connectionId, "connectionId"),
+      { mode: "LIVE" }
+    );
+  }
+  /**
+   * Begin one exact intent and execute only if already READY. Otherwise return
+   * the owner's approval action or existing state immediately, without polling.
+   */
+  async pay(input) {
+    const connectionId = this.identifier(
+      input.connectionId ?? __privateGet(this, _defaults)?.connectionId,
+      "connectionId"
+    );
+    const paymentMethodId = this.identifier(
+      input.paymentMethodId ?? __privateGet(this, _defaults)?.paymentMethodId,
+      "paymentMethodId"
+    );
+    if (!Number.isSafeInteger(input.amountMinor) || input.amountMinor <= 0 || input.currency !== void 0 && input.currency !== "USD" || !Array.isArray(input.lineItems) || input.lineItems.length === 0 || typeof input.purpose !== "string" || !input.purpose.trim()) {
+      throw new ContoError("Supply a positive USD amount in cents, purpose, and line items", {
+        code: "INVALID_LINK_PURCHASE",
+        status: 0
+      });
+    }
+    const itemTotal = input.lineItems.reduce((sum, item) => {
+      if (!item || typeof item.name !== "string" || !item.name.trim() || !Number.isSafeInteger(item.quantity) || item.quantity <= 0 || !Number.isSafeInteger(item.unitAmountMinor) || item.unitAmountMinor < 0) {
+        throw new ContoError(
+          "Each line item needs a name, positive integer quantity, and price in cents",
+          {
+            code: "INVALID_LINK_PURCHASE",
+            status: 0
+          }
+        );
+      }
+      return sum + item.quantity * item.unitAmountMinor;
+    }, 0);
+    if (!input.totals && (!Number.isSafeInteger(itemTotal) || itemTotal !== input.amountMinor)) {
+      throw new ContoError(
+        "Supply the exact totals breakdown when the amount differs from the line items",
+        {
+          code: "LINK_TOTALS_REQUIRED",
+          status: 0
+        }
+      );
+    }
+    const result = await __privateGet(this, _client).beginCommerceExecution({
+      executionMethod: "LINK_PAY_TOKEN",
+      connectionId,
+      paymentMethodId,
+      idempotencyKey: input.idempotencyKey,
+      amountMinor: input.amountMinor,
+      currency: input.currency ?? "USD",
+      purpose: input.purpose,
+      category: input.category,
+      counterparty: { canonicalId: input.merchantId, checkoutUrl: input.checkoutUrl },
+      cart: {
+        lineItems: input.lineItems,
+        totals: input.totals ?? [{ type: "total", label: "Total", amountMinor: input.amountMinor }]
+      },
+      providerPresentation: {
+        approvalSummary: input.purpose.trim().slice(0, 500),
+        lineItemLabels: input.lineItems.map((item) => item.name.trim().slice(0, 120))
+      }
+    });
+    return this.executeIfReady(result);
+  }
+  /**
+   * Continue the existing payment after approval. Reads before any mutation and
+   * never submits an execution already processing or requiring reconciliation.
+   */
+  async resume(executionId) {
+    const id = this.identifier(executionId, "executionId");
+    const current = await __privateGet(this, _client).getCommerceExecution(id);
+    this.assertLinkExecution(current);
+    if (["AUTHORIZING", "AWAITING_APPROVAL", "ACTION_REQUIRED"].includes(current.execution.status)) {
+      return this.executeIfReady(await __privateGet(this, _client).refreshCommerceExecution(id));
+    }
+    return this.executeIfReady(current);
+  }
+  /** Observe and reconcile provider state. This method never submits a payment. */
+  async status(executionId) {
+    const id = this.identifier(executionId, "executionId");
+    this.assertLinkExecution(await __privateGet(this, _client).getCommerceExecution(id));
+    return this.result(await __privateGet(this, _client).refreshCommerceExecution(id));
+  }
+  /** Request cancellation of this existing Link payment; never retried automatically. */
+  async cancel(executionId) {
+    const id = this.identifier(executionId, "executionId");
+    this.assertLinkExecution(await __privateGet(this, _client).getCommerceExecution(id));
+    try {
+      return this.result(await __privateGet(this, _client).cancelCommerceExecution(id));
+    } catch (error) {
+      throw new LinkPaymentExecutionError(id, error);
+    }
+  }
+  identifier(value, field) {
+    if (typeof value !== "string" || !value.trim() || value.length > 255) {
+      throw new ContoError(
+        field === "executionId" ? "executionId is required; use the existing ID returned by link.pay()" : `${field} is required; configure the owner-provisioned Link IDs or supply them explicitly`,
+        {
+          code: "LINK_CONFIGURATION_REQUIRED",
+          status: 0
+        }
+      );
+    }
+    return value.trim();
+  }
+  assertLinkExecution(result) {
+    const execution = result.execution;
+    if (execution?.provider !== "STRIPE_LINK" || execution.executionAdapter !== "STRIPE_LINK" || execution.executionChannel !== "BROWSER" || execution.artifactKind !== void 0 && execution.artifactKind !== "LINK_PAY_TOKEN" || execution.deliveryMode !== void 0 && execution.deliveryMode !== "SERVER_ONLY_ARTIFACT") {
+      throw new ContoError("This execution is not a Link Pay Token checkout", {
+        code: "LINK_EXECUTION_MISMATCH",
+        status: 0
+      });
+    }
+  }
+  async executeIfReady(result) {
+    this.assertLinkExecution(result);
+    if (result.execution.status !== "READY") return this.result(result);
+    try {
+      return this.result(await __privateGet(this, _client).executeCommerceExecution(result.execution.id));
+    } catch (error) {
+      throw new LinkPaymentExecutionError(result.execution.id, error);
+    }
+  }
+  result(result) {
+    this.assertLinkExecution(result);
+    const { execution } = result;
+    const awaitingApproval = ["AUTHORIZING", "AWAITING_APPROVAL", "ACTION_REQUIRED"].includes(
+      execution.status
+    );
+    const nextAction = execution.status === "READY" ? "RESUME" : execution.status === "NEEDS_RECONCILIATION" ? "RECONCILE" : awaitingApproval && execution.approvalUrl ? "APPROVE_IN_LINK" : awaitingApproval || ["DRAFT", "PROCESSING"].includes(execution.status) ? "WAIT" : [
+      "SETTLED",
+      "COMPLETED",
+      "DENIED",
+      "CANCELLED",
+      "FAILED",
+      "RETURNED",
+      "EXPIRED"
+    ].includes(execution.status) ? "NONE" : "RECONCILE";
+    return {
+      executionId: execution.id,
+      status: execution.status,
+      nextAction,
+      ...nextAction === "APPROVE_IN_LINK" ? { approvalUrl: execution.approvalUrl } : {},
+      execution,
+      ..."checkout" in result ? { checkout: result.checkout } : {}
+    };
+  }
+};
+_client = new WeakMap();
+_defaults = new WeakMap();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BrowserActionFinalizationPendingError,
@@ -2109,6 +2330,8 @@ var index_default = Conto;
   ControlledExternalCardPaymentTool,
   ExternalCardConfirmationPendingError,
   Giro,
+  LinkClient,
+  LinkPaymentExecutionError,
   TestCardsClient,
   canonicalizeBrowserCheckoutTarget,
   createVerifiedBrowserCheckoutDriver,