@conto_finance/sdk 0.5.2 → 0.5.4

package/README.md

@@ -2,7 +2,7 @@
 
 Conto is a buyer-side control layer. Integrate it in the agent owner's runtime or payment tools;
 the owner or budget holder sets policy before the agent pays.
-See [buyer-side control](https://conto.finance/docs/guides/buyer-side-control) for the authorization
+See [buyer-side control](https://conto.finance/docs/introduction/concepts) for the authorization
 and execution boundary.
 
 TypeScript SDK for Conto. Use it when you control the agent runtime and want typed access to

package/dist/browserbase.d.mts

@@ -69,6 +69,7 @@ interface BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig {
     maxSessions?: number;
     targetStore: EncryptedPlaywrightCheckoutTargetStoreConfig;
     dispatchAttemptFor: GuardedPlaywrightCheckoutRuntimeConfig['dispatchAttemptFor'];
+    claimDispatchAttempt?: GuardedPlaywrightCheckoutRuntimeConfig['claimDispatchAttempt'];
     /** Dedicated service credential. Conto and Browserbase API keys are rejected. */
     token: string;
     maxBodyBytes?: number;

package/dist/browserbase.d.ts

@@ -69,6 +69,7 @@ interface BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig {
     maxSessions?: number;
     targetStore: EncryptedPlaywrightCheckoutTargetStoreConfig;
     dispatchAttemptFor: GuardedPlaywrightCheckoutRuntimeConfig['dispatchAttemptFor'];
+    claimDispatchAttempt?: GuardedPlaywrightCheckoutRuntimeConfig['claimDispatchAttempt'];
     /** Dedicated service credential. Conto and Browserbase API keys are rejected. */
     token: string;
     maxBodyBytes?: number;

package/dist/browserbase.js

@@ -585,6 +585,12 @@ function createGuardedPlaywrightCheckoutRuntime(config) {
         "dispatchAttemptId",
         255
       );
+      if (config.claimDispatchAttempt && !await config.claimDispatchAttempt(dispatchAttemptId)) {
+        throw Object.assign(
+          new Error("This dispatch attempt has already started. Reconcile before another action."),
+          { code: "CONFLICT", status: 409 }
+        );
+      }
       return config.conto.runGuardedCheckoutWithDriver(input, {
         dispatchAttemptId,
         driver: adapter.driver
@@ -919,6 +925,7 @@ function createGuardedPlaywrightCheckoutRuntimeHost(config) {
     pageForSession: browserSessions.pageForSession,
     targetStore,
     dispatchAttemptFor: config.dispatchAttemptFor,
+    claimDispatchAttempt: config.claimDispatchAttempt,
     clickTimeoutMs: config.clickTimeoutMs,
     popupTimeoutMs: config.popupTimeoutMs,
     targetTtlMs: config.targetTtlMs,
@@ -1242,7 +1249,7 @@ function safeRuntimeError(error) {
     return httpJson(error.status, { code: error.code });
   }
   const record = error && typeof error === "object" ? error : void 0;
-  const candidateCode = record?.code;
+  const candidateCode = record?.code === "POLICY_VIOLATION" ? "POLICY_DENIED" : record?.code === "APPROVAL_REQUIRED" ? "REQUIRES_APPROVAL" : record?.code;
   const code = typeof candidateCode === "string" && SAFE_RUNTIME_ERROR_CODES.has(candidateCode) ? candidateCode : "SERVER_ERROR";
   let status = typeof record?.status === "number" ? record.status : code.startsWith("BROWSER_") ? 409 : 500;
   if (!Number.isInteger(status) || status < 400 || status > 599) status = 409;
@@ -1928,6 +1935,7 @@ function createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost(config) {
     },
     targetStore: config.targetStore,
     dispatchAttemptFor: config.dispatchAttemptFor,
+    claimDispatchAttempt: config.claimDispatchAttempt,
     token: config.token,
     maxBodyBytes: config.maxBodyBytes,
     clickTimeoutMs: config.clickTimeoutMs,

package/dist/browserbase.mjs

@@ -1,8 +1,8 @@
 import {
   createGuardedPlaywrightCheckoutRuntimeHost
-} from "./chunk-HM4EG5MH.mjs";
+} from "./chunk-VSIO6PYA.mjs";
 import "./chunk-O5RAAB2U.mjs";
-import "./chunk-B7F5QLE5.mjs";
+import "./chunk-WSIKPUZJ.mjs";
 
 // src/browserbase.ts
 import { createHmac, timingSafeEqual } from "crypto";
@@ -551,6 +551,7 @@ function createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost(config) {
     },
     targetStore: config.targetStore,
     dispatchAttemptFor: config.dispatchAttemptFor,
+    claimDispatchAttempt: config.claimDispatchAttempt,
     token: config.token,
     maxBodyBytes: config.maxBodyBytes,
     clickTimeoutMs: config.clickTimeoutMs,

package/dist/checkout-verifier.mjs

@@ -1,4 +1,4 @@
-import "./chunk-B7F5QLE5.mjs";
+import "./chunk-WSIKPUZJ.mjs";
 
 // src/checkout-verifier.ts
 import { createHash, randomUUID } from "crypto";

package/dist/{chunk-HM4EG5MH.mjs → chunk-VSIO6PYA.mjs}

@@ -447,6 +447,12 @@ function createGuardedPlaywrightCheckoutRuntime(config) {
         "dispatchAttemptId",
         255
       );
+      if (config.claimDispatchAttempt && !await config.claimDispatchAttempt(dispatchAttemptId)) {
+        throw Object.assign(
+          new Error("This dispatch attempt has already started. Reconcile before another action."),
+          { code: "CONFLICT", status: 409 }
+        );
+      }
       return config.conto.runGuardedCheckoutWithDriver(input, {
         dispatchAttemptId,
         driver: adapter.driver
@@ -781,6 +787,7 @@ function createGuardedPlaywrightCheckoutRuntimeHost(config) {
     pageForSession: browserSessions.pageForSession,
     targetStore,
     dispatchAttemptFor: config.dispatchAttemptFor,
+    claimDispatchAttempt: config.claimDispatchAttempt,
     clickTimeoutMs: config.clickTimeoutMs,
     popupTimeoutMs: config.popupTimeoutMs,
     targetTtlMs: config.targetTtlMs,
@@ -1104,7 +1111,7 @@ function safeRuntimeError(error) {
     return httpJson(error.status, { code: error.code });
   }
   const record = error && typeof error === "object" ? error : void 0;
-  const candidateCode = record?.code;
+  const candidateCode = record?.code === "POLICY_VIOLATION" ? "POLICY_DENIED" : record?.code === "APPROVAL_REQUIRED" ? "REQUIRES_APPROVAL" : record?.code;
   const code = typeof candidateCode === "string" && SAFE_RUNTIME_ERROR_CODES.has(candidateCode) ? candidateCode : "SERVER_ERROR";
   let status = typeof record?.status === "number" ? record.status : code.startsWith("BROWSER_") ? 409 : 500;
   if (!Number.isInteger(status) || status < 400 || status > 599) status = 409;

package/dist/{chunk-B7F5QLE5.mjs → chunk-WSIKPUZJ.mjs}

@@ -4,6 +4,9 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
 var __commonJS = (cb, mod) => function __require() {
   try {
     return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
@@ -27,8 +30,15 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
   mod
 ));
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
 
 export {
   __commonJS,
-  __toESM
+  __toESM,
+  __privateGet,
+  __privateAdd,
+  __privateSet
 };

package/dist/index.d.mts

@@ -673,7 +673,7 @@ interface StripeLinkCheckoutReadinessResult {
     readonly readiness: StripeLinkCheckoutReadiness;
 }
 declare class ContoAdmin {
-    private orgApiKey;
+    #private;
     private baseUrl;
     private timeout;
     agents: AgentsClient;
@@ -1486,6 +1486,90 @@ interface ConnectedCardListResult {
     /** Masked drawable cards and their active mandates. No PAN or provider token. */
     cards: ConnectedCardDrawable[];
 }
+/**
+ * The opaque single-use token a test-card draw returns once. Not card data, and
+ * accepted only by {@link TestCardsClient.checkout}. Handle it the way you would
+ * a live credential: keep it out of logs, errors, and model context.
+ */
+interface TestCardCredential {
+    token: string;
+    format: 'test_token';
+}
+interface TestCardDrawResult {
+    environment: 'test';
+    requestId: string;
+    minted: boolean;
+    replayed: boolean;
+    decision: 'APPROVED' | 'DENIED' | 'REQUIRES_APPROVAL';
+    reasons: string[];
+    reconciliationRequired?: boolean;
+    /** Present only on the response that issues it. A replay never returns it again. */
+    testCredential?: TestCardCredential;
+    credentialExpiresAt?: string;
+    notice?: string;
+}
+interface TestMerchantProduct {
+    sku: string;
+    name: string;
+    unitAmountMinor: number;
+}
+interface TestMerchant {
+    key: string;
+    name: string;
+    categoryCode: string;
+    countryCode: string;
+    products: TestMerchantProduct[];
+}
+interface TestCardDrawable extends ConnectedCardDrawable {
+    environment: 'test';
+    label: string;
+}
+interface TestCardListResult {
+    environment: 'test';
+    cards: TestCardDrawable[];
+    merchants: TestMerchant[];
+}
+interface TestCheckoutInput {
+    requestId: string;
+    /** The `testCredential.token` from the draw. */
+    credential: string;
+    /** Items from the test merchant's catalog. Omit to buy one line for the authorized amount. */
+    items?: Array<{
+        sku: string;
+        quantity: number;
+    }>;
+}
+interface TestCardReceipt {
+    environment: 'test';
+    simulated: true;
+    settlementMode: 'test';
+    notice: string;
+    orderId: string;
+    orderNumber: string;
+    requestId: string;
+    transactionId: string;
+    agentId: string;
+    cardId: string;
+    merchant: {
+        key: string;
+        name: string;
+    };
+    items: Array<{
+        sku: string;
+        name: string;
+        quantity: number;
+        unitAmountMinor: number;
+        amountMinor: number;
+    }>;
+    amountMinor: number;
+    currency: string;
+    createdAt: string;
+}
+interface TestCheckoutResult extends TestCardReceipt {
+    /** True when this credential already completed this checkout. Nothing new was recorded. */
+    replayed: boolean;
+    status: 'COMPLETED';
+}
 interface StripeLinkPaymentMethod {
     id: string;
     type: string;
@@ -2023,6 +2107,12 @@ interface MppPreAuthorizeResult extends ProtocolPreAuthorizeResult {
     };
 }
 interface MppRecordInput extends ProtocolRecordGrant {
+    /**
+     * Amount the service charged. Must be positive, except `0` on a session's
+     * closing record (`closeSession: true`) when the session charged nothing
+     * more. That close needs `grantId` and `grantSignature` and takes no
+     * `txHash`, `paymentReceipt`, or `batchItems`.
+     */
     amount: number;
     currency?: string;
     recipientAddress: string;
@@ -2047,12 +2137,21 @@ interface MppRecordInput extends ProtocolRecordGrant {
         resourceUrl: string;
         credentialId: string;
     }>;
+    /**
+     * Send true on the final record of a session (`intent: 'session'`). Conto
+     * closes the session and releases the unused part of its grant. Send it
+     * with `amount: 0` when the session has nothing more to charge. Repeating
+     * that close returns the same result.
+     */
+    closeSession?: boolean;
 }
 interface MppRecordResult extends ProtocolRecordGrantResult {
     recorded: true;
     txHash?: string;
     explorerUrl?: string;
     sessionId?: string;
+    /** True when a record with `amount: 0` closed the session. No transaction was recorded. */
+    sessionClosed?: true;
 }
 interface ProtocolBudgetResult {
     spend: {
@@ -2157,12 +2256,13 @@ interface ContoRequestOptions {
     maxRetries?: number;
 }
 declare class Conto {
-    private apiKey;
+    #private;
     private baseUrl;
     private timeout;
     payments: PaymentsClient;
     cards: CardsClient;
     connectedCards: ConnectedCardsClient;
+    testCards: TestCardsClient;
     x402: X402Client;
     mpp: MppClient;
     constructor(config: ContoConfig);
@@ -2340,6 +2440,37 @@ declare class ConnectedCardsClient {
     }>;
     list(): Promise<ConnectedCardListResult>;
 }
+/**
+ * Test cards: try card controls with simulated purchases. See the section
+ * comment above {@link TestCardCredential}.
+ */
+declare class TestCardsClient {
+    private client;
+    constructor(client: Conto);
+    /** The agent's test cards and active test authorizations, plus the test merchants. */
+    list(): Promise<TestCardListResult>;
+    /**
+     * Request a single-use test credential. Same rules as
+     * {@link ConnectedCardsClient.draw}: one stable idempotency key per purchase,
+     * no automatic transport retry, and after a human approves a review, resend
+     * the identical request with the same key.
+     */
+    draw(input: ConnectedCardDrawInput): Promise<TestCardDrawResult>;
+    /** Record receipt of a test credential. Not a checkout and not a payment. */
+    acknowledgeDelivery(requestId: string): Promise<{
+        environment: 'test';
+        acknowledged: boolean;
+        settlementVerified: false;
+    }>;
+    /**
+     * Complete a simulated purchase at the Conto test merchant with the test
+     * credential. Retrying with the same draw and credential returns the same
+     * receipt with `replayed: true`, so this call is safe to retry.
+     */
+    checkout(input: TestCheckoutInput): Promise<TestCheckoutResult>;
+    /** Read back one of this agent's simulated receipts. */
+    receipt(orderId: string): Promise<TestCardReceipt>;
+}
 /** Client for payment operations */
 declare class PaymentsClient {
     private client;
@@ -2477,4 +2608,4 @@ 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 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 };
+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 };

package/dist/index.d.ts

@@ -673,7 +673,7 @@ interface StripeLinkCheckoutReadinessResult {
     readonly readiness: StripeLinkCheckoutReadiness;
 }
 declare class ContoAdmin {
-    private orgApiKey;
+    #private;
     private baseUrl;
     private timeout;
     agents: AgentsClient;
@@ -1486,6 +1486,90 @@ interface ConnectedCardListResult {
     /** Masked drawable cards and their active mandates. No PAN or provider token. */
     cards: ConnectedCardDrawable[];
 }
+/**
+ * The opaque single-use token a test-card draw returns once. Not card data, and
+ * accepted only by {@link TestCardsClient.checkout}. Handle it the way you would
+ * a live credential: keep it out of logs, errors, and model context.
+ */
+interface TestCardCredential {
+    token: string;
+    format: 'test_token';
+}
+interface TestCardDrawResult {
+    environment: 'test';
+    requestId: string;
+    minted: boolean;
+    replayed: boolean;
+    decision: 'APPROVED' | 'DENIED' | 'REQUIRES_APPROVAL';
+    reasons: string[];
+    reconciliationRequired?: boolean;
+    /** Present only on the response that issues it. A replay never returns it again. */
+    testCredential?: TestCardCredential;
+    credentialExpiresAt?: string;
+    notice?: string;
+}
+interface TestMerchantProduct {
+    sku: string;
+    name: string;
+    unitAmountMinor: number;
+}
+interface TestMerchant {
+    key: string;
+    name: string;
+    categoryCode: string;
+    countryCode: string;
+    products: TestMerchantProduct[];
+}
+interface TestCardDrawable extends ConnectedCardDrawable {
+    environment: 'test';
+    label: string;
+}
+interface TestCardListResult {
+    environment: 'test';
+    cards: TestCardDrawable[];
+    merchants: TestMerchant[];
+}
+interface TestCheckoutInput {
+    requestId: string;
+    /** The `testCredential.token` from the draw. */
+    credential: string;
+    /** Items from the test merchant's catalog. Omit to buy one line for the authorized amount. */
+    items?: Array<{
+        sku: string;
+        quantity: number;
+    }>;
+}
+interface TestCardReceipt {
+    environment: 'test';
+    simulated: true;
+    settlementMode: 'test';
+    notice: string;
+    orderId: string;
+    orderNumber: string;
+    requestId: string;
+    transactionId: string;
+    agentId: string;
+    cardId: string;
+    merchant: {
+        key: string;
+        name: string;
+    };
+    items: Array<{
+        sku: string;
+        name: string;
+        quantity: number;
+        unitAmountMinor: number;
+        amountMinor: number;
+    }>;
+    amountMinor: number;
+    currency: string;
+    createdAt: string;
+}
+interface TestCheckoutResult extends TestCardReceipt {
+    /** True when this credential already completed this checkout. Nothing new was recorded. */
+    replayed: boolean;
+    status: 'COMPLETED';
+}
 interface StripeLinkPaymentMethod {
     id: string;
     type: string;
@@ -2023,6 +2107,12 @@ interface MppPreAuthorizeResult extends ProtocolPreAuthorizeResult {
     };
 }
 interface MppRecordInput extends ProtocolRecordGrant {
+    /**
+     * Amount the service charged. Must be positive, except `0` on a session's
+     * closing record (`closeSession: true`) when the session charged nothing
+     * more. That close needs `grantId` and `grantSignature` and takes no
+     * `txHash`, `paymentReceipt`, or `batchItems`.
+     */
     amount: number;
     currency?: string;
     recipientAddress: string;
@@ -2047,12 +2137,21 @@ interface MppRecordInput extends ProtocolRecordGrant {
         resourceUrl: string;
         credentialId: string;
     }>;
+    /**
+     * Send true on the final record of a session (`intent: 'session'`). Conto
+     * closes the session and releases the unused part of its grant. Send it
+     * with `amount: 0` when the session has nothing more to charge. Repeating
+     * that close returns the same result.
+     */
+    closeSession?: boolean;
 }
 interface MppRecordResult extends ProtocolRecordGrantResult {
     recorded: true;
     txHash?: string;
     explorerUrl?: string;
     sessionId?: string;
+    /** True when a record with `amount: 0` closed the session. No transaction was recorded. */
+    sessionClosed?: true;
 }
 interface ProtocolBudgetResult {
     spend: {
@@ -2157,12 +2256,13 @@ interface ContoRequestOptions {
     maxRetries?: number;
 }
 declare class Conto {
-    private apiKey;
+    #private;
     private baseUrl;
     private timeout;
     payments: PaymentsClient;
     cards: CardsClient;
     connectedCards: ConnectedCardsClient;
+    testCards: TestCardsClient;
     x402: X402Client;
     mpp: MppClient;
     constructor(config: ContoConfig);
@@ -2340,6 +2440,37 @@ declare class ConnectedCardsClient {
     }>;
     list(): Promise<ConnectedCardListResult>;
 }
+/**
+ * Test cards: try card controls with simulated purchases. See the section
+ * comment above {@link TestCardCredential}.
+ */
+declare class TestCardsClient {
+    private client;
+    constructor(client: Conto);
+    /** The agent's test cards and active test authorizations, plus the test merchants. */
+    list(): Promise<TestCardListResult>;
+    /**
+     * Request a single-use test credential. Same rules as
+     * {@link ConnectedCardsClient.draw}: one stable idempotency key per purchase,
+     * no automatic transport retry, and after a human approves a review, resend
+     * the identical request with the same key.
+     */
+    draw(input: ConnectedCardDrawInput): Promise<TestCardDrawResult>;
+    /** Record receipt of a test credential. Not a checkout and not a payment. */
+    acknowledgeDelivery(requestId: string): Promise<{
+        environment: 'test';
+        acknowledged: boolean;
+        settlementVerified: false;
+    }>;
+    /**
+     * Complete a simulated purchase at the Conto test merchant with the test
+     * credential. Retrying with the same draw and credential returns the same
+     * receipt with `replayed: true`, so this call is safe to retry.
+     */
+    checkout(input: TestCheckoutInput): Promise<TestCheckoutResult>;
+    /** Read back one of this agent's simulated receipts. */
+    receipt(orderId: string): Promise<TestCardReceipt>;
+}
 /** Client for payment operations */
 declare class PaymentsClient {
     private client;
@@ -2477,4 +2608,4 @@ 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 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 };
+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 };

package/dist/index.js

@@ -5,6 +5,9 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
 var __commonJS = (cb, mod) => function __require() {
   try {
     return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
@@ -33,13 +36,17 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
 
 // package.json
 var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@conto_finance/sdk",
-      version: "0.5.2",
+      version: "0.5.4",
       description: "Conto SDK for AI agent payment authorization",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
@@ -154,6 +161,7 @@ __export(index_exports, {
   ControlledExternalCardPaymentTool: () => ControlledExternalCardPaymentTool,
   ExternalCardConfirmationPendingError: () => ExternalCardConfirmationPendingError,
   Giro: () => Conto,
+  TestCardsClient: () => TestCardsClient,
   canonicalizeBrowserCheckoutTarget: () => canonicalizeBrowserCheckoutTarget,
   createVerifiedBrowserCheckoutDriver: () => createVerifiedBrowserCheckoutDriver,
   default: () => index_default,
@@ -175,7 +183,15 @@ var PUBLIC_PAYMENT_REASONS = /* @__PURE__ */ new Set([
   "This payment requires approval before it can proceed.",
   "No usable wallet is linked to this agent.",
   "This payee needs review before payments to it can proceed automatically.",
-  "A reviewer declined this payment."
+  "A reviewer declined this payment.",
+  "This payment is missing a category, which a payment control requires.",
+  "This payment is missing the recipient country, which a payment control requires.",
+  "This payment is missing the target contract address, which a payment control requires.",
+  "This payment is missing the service URL, which a payment control requires.",
+  "This payment is missing a session ID, which a payment control requires.",
+  "This payment is missing the x402 facilitator, which a payment control requires.",
+  "This payment is missing the MPP intent, which a payment control requires.",
+  "This payment is missing the MPP payment method, which a payment control requires."
 ]);
 function customerPaymentReasons(value) {
   return Array.isArray(value) ? [
@@ -503,8 +519,11 @@ var ContoAdminError = class extends Error {
     this.retryGuidance = metadata.retryGuidance;
   }
 };
+var _orgApiKey;
 var ContoAdmin = class {
   constructor(config) {
+    // An ECMAScript private field, so logging or serializing a client never prints the key.
+    __privateAdd(this, _orgApiKey);
     if (!config.orgApiKey) {
       throw new Error("Organization API key is required");
     }
@@ -518,7 +537,7 @@ var ContoAdmin = class {
         "Invalid API key format. Expected organization API key starting with conto_xxx..."
       );
     }
-    this.orgApiKey = config.orgApiKey;
+    __privateSet(this, _orgApiKey, config.orgApiKey);
     this.baseUrl = (config.baseUrl || "https://conto.finance").replace(/\/$/, "");
     assertSecureBaseUrl(this.baseUrl);
     this.timeout = config.timeout || 3e4;
@@ -542,7 +561,7 @@ var ContoAdmin = class {
         {
           method: normalizedMethod,
           headers: {
-            Authorization: `Bearer ${this.orgApiKey}`,
+            Authorization: `Bearer ${__privateGet(this, _orgApiKey)}`,
             "Content-Type": "application/json",
             "User-Agent": `@conto_finance/sdk-admin/${import_package_version.SDK_PACKAGE_VERSION}`
           },
@@ -582,6 +601,7 @@ var ContoAdmin = class {
     }
   }
 };
+_orgApiKey = new WeakMap();
 var PaymentRailsClient = class {
   constructor(client) {
     this.client = client;
@@ -1019,14 +1039,6 @@ var TeamClient = class {
 };
 
 // src/index.ts
-if (process.env.SENTRY_DSN) {
-  Sentry2.init({
-    dsn: process.env.SENTRY_DSN,
-    environment: process.env.NODE_ENV || "production",
-    tracesSampleRate: 0.05,
-    enableLogs: true
-  });
-}
 function isValidBrowserActionObservation(value) {
   if (!value || typeof value !== "object") return false;
   const observation = value;
@@ -1128,21 +1140,25 @@ function rethrowAmbiguousCommerceMutation(error, executionId, action) {
   }
   throw error;
 }
+var _apiKey;
 var Conto = class {
   constructor(config) {
+    // An ECMAScript private field, so logging or serializing a client never prints the key.
+    __privateAdd(this, _apiKey);
     if (!config.apiKey) {
       throw new Error("API key is required");
     }
     if (!config.apiKey.startsWith("conto_agent_")) {
       throw new Error("Invalid API key format. Expected conto_agent_xxx...");
     }
-    this.apiKey = config.apiKey;
+    __privateSet(this, _apiKey, config.apiKey);
     this.baseUrl = (config.baseUrl || "https://conto.finance").replace(/\/$/, "");
     assertSecureBaseUrl(this.baseUrl);
     this.timeout = config.timeout || 3e4;
     this.payments = new PaymentsClient(this);
     this.cards = new CardsClient(this);
     this.connectedCards = new ConnectedCardsClient(this);
+    this.testCards = new TestCardsClient(this);
     this.x402 = new X402Client(this);
     this.mpp = new MppClient(this);
   }
@@ -1434,7 +1450,7 @@ var Conto = class {
         {
           method: normalizedMethod,
           headers: {
-            Authorization: `Bearer ${this.apiKey}`,
+            Authorization: `Bearer ${__privateGet(this, _apiKey)}`,
             "Content-Type": "application/json",
             "User-Agent": `@conto_finance/sdk/${import_package_version2.SDK_PACKAGE_VERSION}`
           },
@@ -1474,6 +1490,7 @@ var Conto = class {
     }
   }
 };
+_apiKey = new WeakMap();
 var CardsClient = class {
   constructor(client) {
     this.client = client;
@@ -1710,6 +1727,65 @@ var ConnectedCardsClient = class {
     return this.client.request("GET", "/api/sdk/connected-cards");
   }
 };
+var TestCardsClient = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** The agent's test cards and active test authorizations, plus the test merchants. */
+  async list() {
+    return this.client.request("GET", "/api/sdk/connected-cards/test");
+  }
+  /**
+   * Request a single-use test credential. Same rules as
+   * {@link ConnectedCardsClient.draw}: one stable idempotency key per purchase,
+   * no automatic transport retry, and after a human approves a review, resend
+   * the identical request with the same key.
+   */
+  async draw(input) {
+    const idempotencyKey = input.idempotencyKey?.trim();
+    if (!idempotencyKey || idempotencyKey.length < 8 || idempotencyKey.length > 128) {
+      throw new ContoError("idempotencyKey must contain 8 to 128 characters", {
+        code: "INVALID_IDEMPOTENCY_KEY",
+        status: 0,
+        retryGuidance: "Generate one stable identifier per purchase and reuse it only to resume the same purchase."
+      });
+    }
+    return this.client.request("POST", "/api/sdk/connected-cards/test/draws", {
+      ...input,
+      idempotencyKey,
+      currency: input.currency ?? "USD"
+    });
+  }
+  /** Record receipt of a test credential. Not a checkout and not a payment. */
+  async acknowledgeDelivery(requestId) {
+    return this.client.request(
+      "POST",
+      `/api/sdk/connected-cards/test/draws/${encodeURIComponent(requestId)}/acknowledge`,
+      {},
+      { idempotent: true }
+    );
+  }
+  /**
+   * Complete a simulated purchase at the Conto test merchant with the test
+   * credential. Retrying with the same draw and credential returns the same
+   * receipt with `replayed: true`, so this call is safe to retry.
+   */
+  async checkout(input) {
+    return this.client.request(
+      "POST",
+      "/api/sdk/connected-cards/test/checkout",
+      { ...input },
+      { idempotent: true }
+    );
+  }
+  /** Read back one of this agent's simulated receipts. */
+  async receipt(orderId) {
+    return this.client.request(
+      "GET",
+      `/api/sdk/connected-cards/test/orders/${encodeURIComponent(orderId)}`
+    );
+  }
+};
 function approvalRetryGuidance(requestId) {
   const id = JSON.stringify(requestId);
   return `An approver in Conto executes the payment when they approve it. After approval, call payments.execute(${id}) or payments.status(${id}) to get the receipt. Do not request the payment again.`;
@@ -2033,6 +2109,7 @@ var index_default = Conto;
   ControlledExternalCardPaymentTool,
   ExternalCardConfirmationPendingError,
   Giro,
+  TestCardsClient,
   canonicalizeBrowserCheckoutTarget,
   createVerifiedBrowserCheckoutDriver,
   fingerprintBrowserCheckoutTarget

package/dist/index.mjs

@@ -6,15 +6,18 @@ import {
 } from "./chunk-O5RAAB2U.mjs";
 import {
   __commonJS,
+  __privateAdd,
+  __privateGet,
+  __privateSet,
   __toESM
-} from "./chunk-B7F5QLE5.mjs";
+} from "./chunk-WSIKPUZJ.mjs";
 
 // package.json
 var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@conto_finance/sdk",
-      version: "0.5.2",
+      version: "0.5.4",
       description: "Conto SDK for AI agent payment authorization",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
@@ -131,7 +134,15 @@ var PUBLIC_PAYMENT_REASONS = /* @__PURE__ */ new Set([
   "This payment requires approval before it can proceed.",
   "No usable wallet is linked to this agent.",
   "This payee needs review before payments to it can proceed automatically.",
-  "A reviewer declined this payment."
+  "A reviewer declined this payment.",
+  "This payment is missing a category, which a payment control requires.",
+  "This payment is missing the recipient country, which a payment control requires.",
+  "This payment is missing the target contract address, which a payment control requires.",
+  "This payment is missing the service URL, which a payment control requires.",
+  "This payment is missing a session ID, which a payment control requires.",
+  "This payment is missing the x402 facilitator, which a payment control requires.",
+  "This payment is missing the MPP intent, which a payment control requires.",
+  "This payment is missing the MPP payment method, which a payment control requires."
 ]);
 function customerPaymentReasons(value) {
   return Array.isArray(value) ? [
@@ -342,8 +353,11 @@ var ContoAdminError = class extends Error {
     this.retryGuidance = metadata.retryGuidance;
   }
 };
+var _orgApiKey;
 var ContoAdmin = class {
   constructor(config) {
+    // An ECMAScript private field, so logging or serializing a client never prints the key.
+    __privateAdd(this, _orgApiKey);
     if (!config.orgApiKey) {
       throw new Error("Organization API key is required");
     }
@@ -357,7 +371,7 @@ var ContoAdmin = class {
         "Invalid API key format. Expected organization API key starting with conto_xxx..."
       );
     }
-    this.orgApiKey = config.orgApiKey;
+    __privateSet(this, _orgApiKey, config.orgApiKey);
     this.baseUrl = (config.baseUrl || "https://conto.finance").replace(/\/$/, "");
     assertSecureBaseUrl(this.baseUrl);
     this.timeout = config.timeout || 3e4;
@@ -381,7 +395,7 @@ var ContoAdmin = class {
         {
           method: normalizedMethod,
           headers: {
-            Authorization: `Bearer ${this.orgApiKey}`,
+            Authorization: `Bearer ${__privateGet(this, _orgApiKey)}`,
             "Content-Type": "application/json",
             "User-Agent": `@conto_finance/sdk-admin/${import_package_version.SDK_PACKAGE_VERSION}`
           },
@@ -421,6 +435,7 @@ var ContoAdmin = class {
     }
   }
 };
+_orgApiKey = new WeakMap();
 var PaymentRailsClient = class {
   constructor(client) {
     this.client = client;
@@ -858,14 +873,6 @@ var TeamClient = class {
 };
 
 // src/index.ts
-if (process.env.SENTRY_DSN) {
-  Sentry2.init({
-    dsn: process.env.SENTRY_DSN,
-    environment: process.env.NODE_ENV || "production",
-    tracesSampleRate: 0.05,
-    enableLogs: true
-  });
-}
 function isValidBrowserActionObservation(value) {
   if (!value || typeof value !== "object") return false;
   const observation = value;
@@ -967,21 +974,25 @@ function rethrowAmbiguousCommerceMutation(error, executionId, action) {
   }
   throw error;
 }
+var _apiKey;
 var Conto = class {
   constructor(config) {
+    // An ECMAScript private field, so logging or serializing a client never prints the key.
+    __privateAdd(this, _apiKey);
     if (!config.apiKey) {
       throw new Error("API key is required");
     }
     if (!config.apiKey.startsWith("conto_agent_")) {
       throw new Error("Invalid API key format. Expected conto_agent_xxx...");
     }
-    this.apiKey = config.apiKey;
+    __privateSet(this, _apiKey, config.apiKey);
     this.baseUrl = (config.baseUrl || "https://conto.finance").replace(/\/$/, "");
     assertSecureBaseUrl(this.baseUrl);
     this.timeout = config.timeout || 3e4;
     this.payments = new PaymentsClient(this);
     this.cards = new CardsClient(this);
     this.connectedCards = new ConnectedCardsClient(this);
+    this.testCards = new TestCardsClient(this);
     this.x402 = new X402Client(this);
     this.mpp = new MppClient(this);
   }
@@ -1273,7 +1284,7 @@ var Conto = class {
         {
           method: normalizedMethod,
           headers: {
-            Authorization: `Bearer ${this.apiKey}`,
+            Authorization: `Bearer ${__privateGet(this, _apiKey)}`,
             "Content-Type": "application/json",
             "User-Agent": `@conto_finance/sdk/${import_package_version2.SDK_PACKAGE_VERSION}`
           },
@@ -1313,6 +1324,7 @@ var Conto = class {
     }
   }
 };
+_apiKey = new WeakMap();
 var CardsClient = class {
   constructor(client) {
     this.client = client;
@@ -1549,6 +1561,65 @@ var ConnectedCardsClient = class {
     return this.client.request("GET", "/api/sdk/connected-cards");
   }
 };
+var TestCardsClient = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** The agent's test cards and active test authorizations, plus the test merchants. */
+  async list() {
+    return this.client.request("GET", "/api/sdk/connected-cards/test");
+  }
+  /**
+   * Request a single-use test credential. Same rules as
+   * {@link ConnectedCardsClient.draw}: one stable idempotency key per purchase,
+   * no automatic transport retry, and after a human approves a review, resend
+   * the identical request with the same key.
+   */
+  async draw(input) {
+    const idempotencyKey = input.idempotencyKey?.trim();
+    if (!idempotencyKey || idempotencyKey.length < 8 || idempotencyKey.length > 128) {
+      throw new ContoError("idempotencyKey must contain 8 to 128 characters", {
+        code: "INVALID_IDEMPOTENCY_KEY",
+        status: 0,
+        retryGuidance: "Generate one stable identifier per purchase and reuse it only to resume the same purchase."
+      });
+    }
+    return this.client.request("POST", "/api/sdk/connected-cards/test/draws", {
+      ...input,
+      idempotencyKey,
+      currency: input.currency ?? "USD"
+    });
+  }
+  /** Record receipt of a test credential. Not a checkout and not a payment. */
+  async acknowledgeDelivery(requestId) {
+    return this.client.request(
+      "POST",
+      `/api/sdk/connected-cards/test/draws/${encodeURIComponent(requestId)}/acknowledge`,
+      {},
+      { idempotent: true }
+    );
+  }
+  /**
+   * Complete a simulated purchase at the Conto test merchant with the test
+   * credential. Retrying with the same draw and credential returns the same
+   * receipt with `replayed: true`, so this call is safe to retry.
+   */
+  async checkout(input) {
+    return this.client.request(
+      "POST",
+      "/api/sdk/connected-cards/test/checkout",
+      { ...input },
+      { idempotent: true }
+    );
+  }
+  /** Read back one of this agent's simulated receipts. */
+  async receipt(orderId) {
+    return this.client.request(
+      "GET",
+      `/api/sdk/connected-cards/test/orders/${encodeURIComponent(orderId)}`
+    );
+  }
+};
 function approvalRetryGuidance(requestId) {
   const id = JSON.stringify(requestId);
   return `An approver in Conto executes the payment when they approve it. After approval, call payments.execute(${id}) or payments.status(${id}) to get the receipt. Do not request the payment again.`;
@@ -1871,6 +1942,7 @@ export {
   ControlledExternalCardPaymentTool,
   ExternalCardConfirmationPendingError,
   Conto as Giro,
+  TestCardsClient,
   canonicalizeBrowserCheckoutTarget,
   createVerifiedBrowserCheckoutDriver,
   index_default as default,

package/dist/playwright.d.mts

@@ -91,6 +91,8 @@ interface GuardedPlaywrightCheckoutRuntimeConfig extends PlaywrightCheckoutAdapt
         browserSessionId: string;
         targetFingerprint: string;
     }): Promise<string>;
+    /** Atomically starts an attempt once across runtime instances. Never release after a failure. */
+    claimDispatchAttempt?(dispatchAttemptId: string): Promise<boolean>;
 }
 /**
  * Safe façade to expose as the agent's checkout capability. It intentionally
@@ -191,6 +193,7 @@ interface GuardedPlaywrightCheckoutRuntimeHostConfig {
     targetStore: EncryptedPlaywrightCheckoutTargetStoreConfig;
     /** Atomically loads or creates one stable attempt for the checkout intent. */
     dispatchAttemptFor: GuardedPlaywrightCheckoutRuntimeConfig['dispatchAttemptFor'];
+    claimDispatchAttempt?: GuardedPlaywrightCheckoutRuntimeConfig['claimDispatchAttempt'];
     /** Dedicated service credential. Conto API keys are rejected. */
     token: string;
     maxBodyBytes?: number;

package/dist/playwright.d.ts

@@ -91,6 +91,8 @@ interface GuardedPlaywrightCheckoutRuntimeConfig extends PlaywrightCheckoutAdapt
         browserSessionId: string;
         targetFingerprint: string;
     }): Promise<string>;
+    /** Atomically starts an attempt once across runtime instances. Never release after a failure. */
+    claimDispatchAttempt?(dispatchAttemptId: string): Promise<boolean>;
 }
 /**
  * Safe façade to expose as the agent's checkout capability. It intentionally
@@ -191,6 +193,7 @@ interface GuardedPlaywrightCheckoutRuntimeHostConfig {
     targetStore: EncryptedPlaywrightCheckoutTargetStoreConfig;
     /** Atomically loads or creates one stable attempt for the checkout intent. */
     dispatchAttemptFor: GuardedPlaywrightCheckoutRuntimeConfig['dispatchAttemptFor'];
+    claimDispatchAttempt?: GuardedPlaywrightCheckoutRuntimeConfig['claimDispatchAttempt'];
     /** Dedicated service credential. Conto API keys are rejected. */
     token: string;
     maxBodyBytes?: number;

package/dist/playwright.js

@@ -585,6 +585,12 @@ function createGuardedPlaywrightCheckoutRuntime(config) {
         "dispatchAttemptId",
         255
       );
+      if (config.claimDispatchAttempt && !await config.claimDispatchAttempt(dispatchAttemptId)) {
+        throw Object.assign(
+          new Error("This dispatch attempt has already started. Reconcile before another action."),
+          { code: "CONFLICT", status: 409 }
+        );
+      }
       return config.conto.runGuardedCheckoutWithDriver(input, {
         dispatchAttemptId,
         driver: adapter.driver
@@ -919,6 +925,7 @@ function createGuardedPlaywrightCheckoutRuntimeHost(config) {
     pageForSession: browserSessions.pageForSession,
     targetStore,
     dispatchAttemptFor: config.dispatchAttemptFor,
+    claimDispatchAttempt: config.claimDispatchAttempt,
     clickTimeoutMs: config.clickTimeoutMs,
     popupTimeoutMs: config.popupTimeoutMs,
     targetTtlMs: config.targetTtlMs,
@@ -1242,7 +1249,7 @@ function safeRuntimeError(error) {
     return httpJson(error.status, { code: error.code });
   }
   const record = error && typeof error === "object" ? error : void 0;
-  const candidateCode = record?.code;
+  const candidateCode = record?.code === "POLICY_VIOLATION" ? "POLICY_DENIED" : record?.code === "APPROVAL_REQUIRED" ? "REQUIRES_APPROVAL" : record?.code;
   const code = typeof candidateCode === "string" && SAFE_RUNTIME_ERROR_CODES.has(candidateCode) ? candidateCode : "SERVER_ERROR";
   let status = typeof record?.status === "number" ? record.status : code.startsWith("BROWSER_") ? 409 : 500;
   if (!Number.isInteger(status) || status < 400 || status > 599) status = 409;

package/dist/playwright.mjs

@@ -7,9 +7,9 @@ import {
   createPlaywrightCdpSessionRegistry,
   createPlaywrightCheckoutAdapter,
   createPlaywrightSessionObserver
-} from "./chunk-HM4EG5MH.mjs";
+} from "./chunk-VSIO6PYA.mjs";
 import "./chunk-O5RAAB2U.mjs";
-import "./chunk-B7F5QLE5.mjs";
+import "./chunk-WSIKPUZJ.mjs";
 export {
   createEncryptedPlaywrightCheckoutTargetStore,
   createGuardedPlaywrightCheckoutHttpHandler,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conto_finance/sdk",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Conto SDK for AI agent payment authorization",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",