@agent-cards/sdk 0.23.19 → 0.23.21

package/dist/twoc2p.js

@@ -0,0 +1,85 @@
+// 2C2P's hosted payment page, the card payment as the SDK sees it (payment-core twoc2p.js has the request's shape,
+// the device's card field and the substitution). The page encrypts the card itself with 2C2P's library under one
+// static key and posts it in one request:
+//   POST https://pgwv4.2c2p.com/payment/<build>/Payment   (sandbox-pgwv4.2c2p.com for a sandbox token)
+//   {"paymentToken":..,"payment":{"code":{"channelCode":"CC"},"data":{..,"securePayToken":"<the card field>",..}}}
+// The agent's page encrypts a placeholder card, so the field carries the placeholder. This build holds that
+// Payment and writes over the field the approved card's own: the field the cardholder's device wrote under the key
+// payment-core pins (never a key from a row, a request or a page). Every other byte goes as the page wrote it (mode
+// cse), so the full card number never reaches the agent's runtime.
+//
+// The generic Adyen swap takes only JWEs, so this lane is dispatched by the Payment URL to substituteTwoC2p, as
+// Paddle TokenEx is to its own swap. 2C2P's field is the card under one static key, with no payment token inside:
+// it would pay any 2C2P merchant's Payment, so the continuation writes it only into the one request the approval
+// was created from, byte for byte.
+//
+// The registry entry ships dark (capability twoc2p_secure_pay). This build declares the capability on syncRegistry,
+// and the API serves the recognizer only to an org Agentcard enabled for twoc2p, so for every other org nothing here
+// fires. Autopilot never pays this processor: the API, the authority and the enclave refuse it.
+import { TWOC2P_FIELD, TWOC2P_FIELD_AT, twoC2pPaymentTarget, substituteTwoC2p } from './twoc2p.generated.js';
+/** The PSP id the API and the recognizer name this lane, re-exported so the client dispatches by it. */
+export { TWOC2P_PSP } from './twoc2p.generated.js';
+/** The dark-launch capability a build declares when it fills a 2C2P Payment with the device's card field. */
+export const TWOC2P_CAPABILITY = 'twoc2p_secure_pay';
+/**
+ * Whether an approved 2C2P authorization's served substitution is one this SDK can continue: JSON at payment.data,
+ * no sibling to remove, and exactly the one card field, a non-empty string. substituteTwoC2p checks the field
+ * against the pinned key for the Payment's environment; this is the shape gate the continuation runs first.
+ */
+export function isTwoC2pServedSubstitution(sub) {
+    if (!sub || typeof sub !== 'object' || Array.isArray(sub))
+        return false;
+    const { encoding, at, fields, remove } = sub;
+    if (encoding !== 'json' || at !== TWOC2P_FIELD_AT || !fields || typeof fields !== 'object' || Array.isArray(fields))
+        return false;
+    if (remove !== undefined && !(Array.isArray(remove) && remove.length === 0))
+        return false;
+    const named = fields;
+    return Object.keys(named).length === 1 && typeof named[TWOC2P_FIELD] === 'string' && named[TWOC2P_FIELD].length > 0;
+}
+/**
+ * The retirement a refused 2C2P continuation runs (twoC2pContinuation's `retire`), or undefined for a client that
+ * cannot cancel: the approval is cancelled as merchant_never_retried, since its field went to no request, and the
+ * API stops serving the field. The paused request fails at once, so the cancel is not awaited; when the API does not
+ * confirm it, `onEvent` hears approval_retire_unconfirmed with the authorization's id. The API's sweep drops the field
+ * once its readable window passes either way.
+ */
+export function twoC2pRetire(client, authorizationId, onEvent) {
+    const cancel = client?.cancelAuthorization;
+    if (typeof cancel !== 'function')
+        return undefined;
+    return () => {
+        void Promise.resolve()
+            .then(() => cancel.call(client, authorizationId, 'merchant_never_retried'))
+            .catch(() => onEvent?.({ type: 'approval_retire_unconfirmed', detail: { authorizationId, reason: 'authorization_cancel_unconfirmed' } }));
+    };
+}
+/**
+ * The continuation of an approved 2C2P Payment: the paused body with the device's card field written over the
+ * placeholder's (payment-core substituteTwoC2p, which refuses a field that is not one under the pinned key for the
+ * Payment's environment, or one already in the paused body).
+ *
+ * Only into `approved`, the paused Payment the approval was created from: `url` and `body` must equal it byte for
+ * byte. 2C2P's key is the same for every merchant, so the field would pay any later Payment of the same shape;
+ * binding it to the one request keeps this lane from ever writing one payment's field into another.
+ *
+ * Null when neither URL is a 2C2P Payment, so every other processor keeps its own swap. Throws for any other body or
+ * URL, and for a substitution the shape gate or the swap refuses, in each case before anything continues. A refusal
+ * means the device's field went to no request, so `retire` runs first: the caller retires the approval as
+ * merchant_never_retried, and the API stops serving the field (cdp.ts cseContinuation).
+ */
+export function twoC2pContinuation(url, body, sub, approved, retire) {
+    if (twoC2pPaymentTarget(url) === null && twoC2pPaymentTarget(approved.url) === null)
+        return null;
+    try {
+        if (url !== approved.url || body !== approved.body)
+            throw new Error('Refusing to substitute: the paused request is not the 2C2P payment the cardholder approved.');
+        if (!isTwoC2pServedSubstitution(sub))
+            throw new Error('Refusing to substitute: the 2C2P approval is not one card field.');
+        return { body: substituteTwoC2p(url, body, sub.fields[TWOC2P_FIELD]) };
+    }
+    catch (error) {
+        retire?.();
+        throw error;
+    }
+}

package/dist/voice.d.ts

@@ -18,18 +18,18 @@ import { type Action, type ActionState, type AppVoiceKeyDescription, type Approv
 export { stripePaymentIntentConfirm, type MintedIntent } from './requests.js';
 /**
  * The voice half of the client's options: named once, per business, when the
- * product approves purchases by voice. A client built without it is a
- * checkout client; every `voice.*` verb on it throws `missing_approval_posture`.
+ * product approves purchases by voice. A client built without it, or with no
+ * `approval`, approves on Agentcard's page (`'sheet'`).
  */
 export interface VoiceOptions {
     /**
-     * Required: how this product approves purchases. One choice per business,
-     * not per purchase. `'sheet'`: the person approves on Agentcard's page with
-     * a credential Agentcard verifies. `'in_app'`: hold-to-talk in your app,
+     * How this product approves purchases. One choice per business, not per
+     * purchase. `'sheet'` (the default): the person approves on Agentcard's page
+     * with a credential Agentcard verifies. `'in_app'`: hold-to-talk in your app,
      * judged on the phone and by Agentcard, signed by a key in your app.
-     * Sandbox and live behave the same. No default.
+     * Sandbox and live behave the same.
      */
-    approval: ApprovalPosture;
+    approval?: ApprovalPosture;
     /** Where the Vault sends the person back when a call names no `return_url` of its own. Exactly one of your registered links. */
     returnUrl?: string;
     /**
@@ -69,12 +69,15 @@ export declare const CANCEL_REASONS: readonly CancelReason[];
  * set that header, so a create that names no `checkout_origin` still carries the app's.
  */
 export declare function checkoutOriginOf(request: PausedRequest): string | null;
-export declare const MISSING_APPROVAL_POSTURE_MESSAGE = "Name how your product approves purchases: voice: { approval: 'sheet' } (the person approves on Agentcard's page with a credential Agentcard verifies) or voice: { approval: 'in_app' } (hold-to-talk in your app, judged on the phone and by Agentcard, signed by a key in your app). There is no default.";
+export declare const MISSING_APPROVAL_POSTURE_MESSAGE = "Name how your product approves purchases: voice: { approval: 'sheet' } (the person approves on Agentcard's page with a credential Agentcard verifies; the default when approval is left out) or voice: { approval: 'in_app' } (hold-to-talk in your app, judged on the phone and by Agentcard, signed by a key in your app).";
+/** The default posture: the person approves on Agentcard's page. */
+export declare const DEFAULT_APPROVAL_POSTURE: ApprovalPosture;
 /**
- * The posture as named. Throws `missing_approval_posture` when `voice` was
- * given without a valid posture, or, with `required`, when it was not given.
+ * The posture as named, or `'sheet'` when none was: a client built without
+ * `voice`, or with `voice` and no `approval`, approves on Agentcard's page.
+ * Throws `missing_approval_posture` only for a posture that is neither.
  */
-export declare function approvalPostureOf(options: VoiceOptions | undefined, required: boolean): ApprovalPosture | undefined;
+export declare function approvalPostureOf(options: VoiceOptions | undefined): ApprovalPosture;
 export { streamAddress } from './voice-stream.generated.js';
 /**
  * The sandbox request: a first run's purchase, naming no processor. Under a
@@ -89,8 +92,8 @@ export declare function bundleOf(ch: VoiceChallenge): HostApprovalBundle;
 export declare class VoiceModule extends ApiModule {
     private readonly options;
     private readonly clientIsSandbox;
-    /** The approval posture the client was constructed with, one per business; `undefined` when the client named none, and then every verb throws `missing_approval_posture`. */
-    readonly approval: ApprovalPosture | undefined;
+    /** The approval posture the client was constructed with, one per business; `'sheet'` when the client named none. */
+    readonly approval: ApprovalPosture;
     /** The grants this client minted, by session id: the verifier and the state, then the exchanged result. Memory only. */
     private readonly grants;
     /** Session id by minted `state`, so a return link finds its grant without naming the session. */

package/dist/voice.js

@@ -69,18 +69,21 @@ function approvalRequestFields(a) {
         out.external_user_id = a.external_user_id ?? null;
     return out;
 }
-export const MISSING_APPROVAL_POSTURE_MESSAGE = "Name how your product approves purchases: voice: { approval: 'sheet' } (the person approves on Agentcard's page with a credential Agentcard verifies) or voice: { approval: 'in_app' } (hold-to-talk in your app, judged on the phone and by Agentcard, signed by a key in your app). There is no default.";
+export const MISSING_APPROVAL_POSTURE_MESSAGE = "Name how your product approves purchases: voice: { approval: 'sheet' } (the person approves on Agentcard's page with a credential Agentcard verifies; the default when approval is left out) or voice: { approval: 'in_app' } (hold-to-talk in your app, judged on the phone and by Agentcard, signed by a key in your app).";
+/** The default posture: the person approves on Agentcard's page. */
+export const DEFAULT_APPROVAL_POSTURE = 'sheet';
 /**
- * The posture as named. Throws `missing_approval_posture` when `voice` was
- * given without a valid posture, or, with `required`, when it was not given.
+ * The posture as named, or `'sheet'` when none was: a client built without
+ * `voice`, or with `voice` and no `approval`, approves on Agentcard's page.
+ * Throws `missing_approval_posture` only for a posture that is neither.
  */
-export function approvalPostureOf(options, required) {
+export function approvalPostureOf(options) {
     const posture = options?.approval;
+    if (posture === undefined)
+        return DEFAULT_APPROVAL_POSTURE;
     if (posture === 'sheet' || posture === 'in_app')
         return posture;
-    if (options !== undefined || required)
-        throw new AgentcardError('missing_approval_posture', MISSING_APPROVAL_POSTURE_MESSAGE);
-    return undefined;
+    throw new AgentcardError('missing_approval_posture', MISSING_APPROVAL_POSTURE_MESSAGE);
 }
 export { streamAddress } from './voice-stream.generated.js';
 /**
@@ -212,7 +215,7 @@ function idempotencyKey() {
 export class VoiceModule extends ApiModule {
     options;
     clientIsSandbox;
-    /** The approval posture the client was constructed with, one per business; `undefined` when the client named none, and then every verb throws `missing_approval_posture`. */
+    /** The approval posture the client was constructed with, one per business; `'sheet'` when the client named none. */
     approval;
     /** The grants this client minted, by session id: the verifier and the state, then the exchanged result. Memory only. */
     grants = new Map();
@@ -222,10 +225,10 @@ export class VoiceModule extends ApiModule {
         super(t);
         this.options = options;
         this.clientIsSandbox = clientIsSandbox;
-        this.approval = approvalPostureOf(options, false);
+        this.approval = approvalPostureOf(options);
     }
     posture() {
-        return approvalPostureOf(this.options, true);
+        return this.approval;
     }
     /** Where the Vault sends the person back when a call names nothing, as the client was constructed. */
     get returnUrl() { return this.options?.returnUrl; }

package/examples/preflight/kernel-native/inventory.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "catalog_version": "2026-09-15.1",
-  "catalog_sha256": "47dd1bc5a749224f66980b42b758f9a19d9ac849e3a8d5230075226a4870fde5",
+  "catalog_sha256": "7f65e0f07138296b0cbff7dd1ed4331842b6dd45e2950f08273fcc772c7f63f6",
   "baseline_version": "kernel-native-docs-2026-09-11.1",
   "baseline_sha256": "d86722f49633d8223fccae54cd3d485df4375aee06aa156a273cc689b7c8507c",
   "native_build": null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/sdk",
-  "version": "0.23.19",
+  "version": "0.23.21",
   "description": "Agentcard's SDK: one client, Agentcard, with two modules. checkout pauses a browser purchase and pays it with the person's own card; voice connects a person to your product once and approves a purchase by voice inside it. Card data never enters your process.",
   "type": "module",
   "main": "dist/index.js",
@@ -30,8 +30,8 @@
     "_comment_test": "check:built runs first and names the command when a file the build generates (the copies in src/, the preflight contracts in dist/, the Kernel inventory) is missing or stale; verify:pack runs last, on the same dist.",
     "check:built": "node scripts/generate-payment-core.mjs --check && node scripts/generate-voice-stream.mjs --check && node scripts/generate-preflight-contract.mjs --check && node scripts/generate-kernel-native-inventory.mjs --check",
     "verify:pack": "node scripts/verify-pack.mjs",
-    "test": "npm run check:built && node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs preparation.test.mjs braintree.test.mjs pre-claim.test.mjs ekashu.test.mjs redsys.test.mjs paypal-hosted-fields.test.mjs paypal-card-forms.test.mjs cybersource-secure-acceptance.test.mjs ebanx.test.mjs autopilot.test.mjs stripe-checkout.test.mjs stripe-setup.test.mjs stripe-legacy-checkout.test.mjs payment-core.test.mjs prepared-processor.test.mjs merchant-hosted.test.mjs merchant-total.test.mjs sandbox-declaration.test.mjs minimum-delay.test.mjs paysafe.test.mjs wix-payments.test.mjs payu.test.mjs attachment.test.mjs worker-targets.test.mjs mercado-checkout.test.mjs mercado-polling.test.mjs amadeus.test.mjs pelecard.test.mjs aci.test.mjs primer.test.mjs payrails.test.mjs elavon-converge.test.mjs voice.test.mjs agentcard.test.mjs buy.test.mjs readme.test.mjs gmo.test.mjs cybersource-flex.test.mjs juspay-gate.test.mjs card-endpoint.test.mjs card-endpoint-fastspring.test.mjs card-endpoint-navigation.test.mjs merchant-session-probe.test.mjs datatrans.test.mjs authorize-net-dpm.test.mjs creditguard.test.mjs eprotect.test.mjs wspay.test.mjs shiji-sts.test.mjs worldline-mycheckout.test.mjs verifone.test.mjs gravy.test.mjs paddle-vgs.test.mjs paddle-tokenex.test.mjs lyra.test.mjs redact-url.test.mjs && node --test preflight-package.test.mjs preflight-collector.test.mjs && node --test kernel-native-qualification.test.mjs && node --test ../vault/scripts/recurly-validation/watch-duty-sdk-result.test.mjs && node scripts/verify-pack.mjs",
-    "test:browser": "node browser.test.mjs && node stripe-browser.test.mjs && node preparation-browser.test.mjs && node checkout-com-browser.test.mjs && node paysafe-preparation-browser.test.mjs && node owned-shop-browser.test.mjs && node spreedly-browser.test.mjs && node worker-browser.test.mjs && node amadeus-browser.test.mjs && node adyen-merchant-hosted-browser.test.mjs && node adyen-merchant-frames-browser.test.mjs && node fiserv-browser.test.mjs && node gmo-browser.test.mjs && node cybersource-flex-browser.test.mjs && node juspay-browser.test.mjs && node card-endpoint-browser.test.mjs && node datatrans-browser.test.mjs && node authorize-net-dpm-browser.test.mjs && node pelecard-browser.test.mjs && node aci-browser.test.mjs && node creditguard-browser.test.mjs && node primer-browser.test.mjs && node payrails-browser.test.mjs && node elavon-converge-browser.test.mjs && node eprotect-browser.test.mjs && node wspay-browser.test.mjs && node shiji-sts-browser.test.mjs && node worldline-mycheckout-browser.test.mjs && node paypal-hosted-fields-browser.test.mjs && node paypal-card-forms-browser.test.mjs && node cybersource-secure-acceptance-browser.test.mjs && node gravy-browser.test.mjs && node ebanx-browser.test.mjs",
+    "test": "npm run check:built && node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs preparation.test.mjs braintree.test.mjs pre-claim.test.mjs ekashu.test.mjs redsys.test.mjs quickpay.test.mjs paypal-hosted-fields.test.mjs paypal-card-forms.test.mjs cybersource-secure-acceptance.test.mjs ebanx.test.mjs autopilot.test.mjs stripe-checkout.test.mjs stripe-setup.test.mjs stripe-legacy-checkout.test.mjs payment-core.test.mjs prepared-processor.test.mjs merchant-hosted.test.mjs merchant-total.test.mjs sandbox-declaration.test.mjs minimum-delay.test.mjs paysafe.test.mjs wix-payments.test.mjs hipay.test.mjs payu.test.mjs attachment.test.mjs worker-targets.test.mjs mercado-checkout.test.mjs mercado-polling.test.mjs amadeus.test.mjs pelecard.test.mjs aci.test.mjs primer.test.mjs payrails.test.mjs elavon-converge.test.mjs voice.test.mjs agentcard.test.mjs buy.test.mjs readme.test.mjs gmo.test.mjs cybersource-flex.test.mjs juspay-gate.test.mjs card-endpoint.test.mjs card-endpoint-fastspring.test.mjs card-endpoint-navigation.test.mjs merchant-session-probe.test.mjs datatrans.test.mjs authorize-net-dpm.test.mjs creditguard.test.mjs eprotect.test.mjs wspay.test.mjs shiji-sts.test.mjs worldline-mycheckout.test.mjs verifone.test.mjs gravy.test.mjs paddle-vgs.test.mjs hold.test.mjs paddle-tokenex.test.mjs lyra.test.mjs gopay.test.mjs twoc2p.test.mjs pay-nl.test.mjs redact-url.test.mjs hosted-entry.test.mjs comgate.test.mjs przelewy24.test.mjs tokenex-iframe.test.mjs transbank.test.mjs sumup.test.mjs && node --test preflight-package.test.mjs preflight-collector.test.mjs browser-tests.test.mjs && node --test kernel-native-qualification.test.mjs && node --test ../vault/scripts/recurly-validation/watch-duty-sdk-result.test.mjs && node scripts/verify-pack.mjs",
+    "test:browser": "node browser-tests.mjs",
     "check:payment-core": "node scripts/generate-payment-core.mjs --check",
     "check:voice-stream": "node scripts/generate-voice-stream.mjs --check",
     "test:preflight": "node --test preflight-package.test.mjs preflight-collector.test.mjs kernel-native-qualification.test.mjs",