@agent-cards/sdk 0.20.0 → 0.22.0

package/dist/primer.js

@@ -0,0 +1,82 @@
+// Primer Web SDK v2 (Headless Checkout and hosted fields), as the SDK sees it.
+//
+// Printful (printful.com) and GetYourGuide (getyourguide.com) take cards through Primer's hosted
+// fields. The merchant page never holds the card: Primer's hosted inputs hand it to a hidden
+// api-controller iframe on https://sdk.primer.io, which sends one fetch POST to
+// https://sdk.api.primer.io/payment-instruments (sdk.api.sandbox.primer.io in sandbox) as
+// application/json with the session's primer-client-token, and gets back a card token the SDK or
+// the merchant's server charges later. The request names no amount. The cardholder's device fills
+// the real card into the paused body and sends it to Primer itself; the page receives only Primer's
+// single-use token (token mode). The request comes from a cross-origin iframe, so the CDP adapter
+// pauses it in the iframe's own target, as it does for Spreedly's card frame.
+//
+// The registry entry ships dark (capability primer_payment_instruments). This build declares the
+// capability on syncRegistry, and the API serves the entry only to an org Agentcard enabled for
+// Primer, so for every other org nothing here fires: isCardRequest never recognizes a Primer URL and
+// Primer's requests go through untouched, exactly as before.
+//
+// For an org in the dark launch, a POST the registry recognizes on a Primer pci host is judged by
+// payment-core's own pause decision (primer.generated.ts classifyPrimerRequest), the rule the API
+// runs at create and the device runs before it fills anything:
+//   - a one-time new card from the legacy v2 controller pauses for approval;
+//   - a body with no card (PayPal, Apple Pay, Google Pay, Klarna) continues untouched;
+//   - a body that asks Primer to keep the card (tokenType MULTI_USE, paymentFlow VAULT) is aborted
+//     alone: a save-card choice on the page decides it, so the next request is judged again;
+//   - Primer Checkout (primer-js), whose controller gives up after 30 s, and any other shape the
+//     legacy controller would not send are aborted as an unsupported checkout before any create or
+//     prompt, and the attachment holds: the merchant's integration decides those.
+import { PRIMER_PCI_HOSTS, classifyPrimerRequest, primerResponseOutcome, sanitizePrimerResponse } from './primer.generated.js';
+export const PRIMER_PSP = 'primer';
+/** The dark-launch capability a build declares when it judges every Primer request with classifyPrimerRequest. */
+export const PRIMER_CAPABILITY = 'primer_payment_instruments';
+/** True for a URL on one of Primer's two pci hosts, whatever its path. */
+export function isPrimerPciHost(rawUrl) {
+    try {
+        return PRIMER_PCI_HOSTS.includes(new URL(rawUrl).hostname.toLowerCase());
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The gate's verdict for a POST the registry recognized on a Primer pci host: defer (a new card,
+ * which the arbiter pauses, or a body with no card, which the card-field rule continues), block it
+ * alone, or abort it as an unsupported checkout. A decision that throws refuses.
+ */
+export function primerRequestVerdict(request) {
+    if (request.body === null)
+        return { kind: 'block', reason: 'unreadable_primer_request' };
+    let decision;
+    try {
+        decision = classifyPrimerRequest(request.url, request.method.toUpperCase(), request.body, request.headers ?? {});
+    }
+    catch {
+        return { kind: 'unsupported', reason: 'unsupported_primer_request' };
+    }
+    if (decision === 'card' || decision === null)
+        return { kind: 'defer' };
+    if (decision === 'keep_on_file')
+        return { kind: 'block', reason: 'primer_keep_on_file' };
+    if (decision === 'unsupported_sdk')
+        return { kind: 'unsupported', reason: 'unsupported_primer_sdk' };
+    return { kind: 'unsupported', reason: 'unsupported_primer_request' };
+}
+/**
+ * The only answer the page may receive for an approved Primer request: status 200 or 201 and
+ * Primer's single-use card token rebuilt from payment-core's allow-list (sanitizePrimerResponse),
+ * under a JSON content type. Null for anything else: another status, a multi-use token or vaultData
+ * (the card was saved), a field out of bounds, a body that does not parse.
+ */
+export function primerTokenAnswer(status, body) {
+    if (status !== 200 && status !== 201)
+        return null;
+    try {
+        // No card here: the device already matched the token to the card it sent.
+        if (primerResponseOutcome(status, body, null).outcome !== 'approved')
+            return null;
+        return { status, headers: { 'content-type': 'application/json' }, body: sanitizePrimerResponse(body) };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/registry.d.ts

@@ -6,7 +6,12 @@
  * site shares another. The list is served from the Agentcard API at runtime so
  * integrators pick up new processors without shipping a release.
  */
-export type Encoding = 'json' | 'form';
+/**
+ * The shape of the card-bearing body. `jwe`: a compact JWE the processor's own card field
+ * sealed (CyberSource Flex), opaque to everyone but the processor; served only with the
+ * capability that reads its capture context.
+ */
+export type Encoding = 'json' | 'form' | 'jwe';
 /**
  * How a paused request gets its card. `token` (the default when absent): the
  * cardholder's device calls the processor and the runtime replays the
@@ -15,8 +20,13 @@ export type Encoding = 'json' | 'form';
  * the paused body and lets the request continue. `hosted_form`: the device
  * submits the processor's own form and the paused request resolves with no
  * processor answer (served only to SDKs that ask for it on sync).
+ * `device_encrypt`: the card is encrypted in-page under a per-session key the
+ * paused request does not carry (Payrails); the runtime supplies the key the
+ * page's init payload named, the device encrypts the real card and sends the
+ * request itself, and the runtime replays the processor's answer as in
+ * `token` (served only to SDKs that ask for it on sync).
  */
-export type CheckoutMode = 'token' | 'cse' | 'hosted_form';
+export type CheckoutMode = 'token' | 'cse' | 'hosted_form' | 'device_encrypt';
 export interface Recognizer {
     /** Stable id, e.g. "shopify" */
     psp: string;
@@ -31,7 +41,8 @@ export interface Recognizer {
      * here matches with them: they exist so a transport that can only pre-filter
      * by URL (CDP's `Fetch.enable`, which takes globs) can be armed from the
      * registry instead of a hardcoded list. Optional so a hand-built registry
-     * (tests, pinning) still type-checks.
+     * (tests, pinning) still type-checks. An empty list names no host, as on the
+     * server: the entry arms no pattern and claims no URL.
      */
     hosts?: string[];
     encoding: Encoding;
@@ -58,6 +69,24 @@ export interface Recognizer {
      * is not. Carried through syncRegistry() verbatim.
      */
     jsonCardFields?: (string | number)[][];
+    /**
+     * True when the processor reads form field names without regard to case
+     * (Authorize.Net: live forms post x_Background_URL and x_cust_ID), so
+     * cardFields match a key in any case and with surrounding spaces trimmed:
+     * a form that spells X_CARD_NUM is a card request like one that spells
+     * x_card_num. Carried verbatim by syncRegistry and read by card-fields.js.
+     */
+    caseInsensitiveFormKeys?: boolean;
+    /**
+     * True when the endpoint is the bare URL: a request whose URL carries a
+     * query string or a fragment, even an empty `?` or `#`, is not this
+     * processor's endpoint, so findRecognizer does not match it and the request
+     * continues untouched, exactly as the API refuses it
+     * (resolveRecognizerForUrl). Authorize.Net's transact.dll reads a query
+     * parameter as a form field, so a key the template policy never saw would
+     * ride with the card. Carried verbatim by syncRegistry.
+     */
+    bareEndpoint?: boolean;
     /**
      * With cardFields or jsonCardFields: the endpoints (regex source over
      * hostname + pathname, anchored) where a request without a card is routine
@@ -69,19 +98,39 @@ export interface Recognizer {
      * True when the card is encrypted inside the page before the request leaves.
      * A digit swap is useless here; the vault must re-run the PSP's client-side
      * crypto instead. Refused locally unless the entry also carries
-     * `mode: 'cse'`, which says the vault does exactly that.
+     * `mode: 'cse'` or `mode: 'device_encrypt'`, which say the vault does
+     * exactly that.
      */
     clientSideEncrypted?: boolean;
     /** How the card reaches the processor; absent means 'token'. Carried verbatim by syncRegistry. */
     mode?: CheckoutMode;
     /**
      * Dark launch: a capability name the API attaches to an entry it serves only
-     * to a client that declared it (?capabilities=). Absent on every entry in
-     * BUILTIN_REGISTRY, because a gated entry is left out of the built-in
-     * fallback. Carried verbatim by syncRegistry for a client that does declare
-     * it, so the SDK never has to act on it.
+     * to a client that declared it (?capabilities=), from an org Agentcard
+     * enabled for the processor. Absent on every entry in BUILTIN_REGISTRY,
+     * because a gated entry is left out of the built-in fallback. Carried
+     * verbatim by syncRegistry for a client that does declare it
+     * (SUPPORTED_CAPABILITIES). authorize() refuses an entry whose capability
+     * this build does not list in SUPPORTED_CAPABILITIES
+     * (UnsupportedCapabilityError), which only a hand-built registry can hold.
+     * GMO names `gmo_shared_pk`, CyberSource Flex names `capture_context`,
+     * Datatrans names `datatrans_secure_fields_tokenize`, Authorize.Net DPM
+     * names `authorize_net_dpm_form`, Pelecard names `pelecard_transaction`,
+     * Primer names `primer_payment_instruments`, Payrails names
+     * `payrails_device_encrypt`, Elavon Converge names `converge_hpp_process`,
+     * WSPay names `wspay_confirm` and Shiji STS names `shiji_sts_pinned_key`.
      */
     capability?: string;
+    /**
+     * The card-on-file policy the API applies to this processor's card post,
+     * served with the entry: `refuse`, `disclose` or `agentcard_single_use`
+     * (Datatrans: a post with usage=REGISTRATION). The SDK refuses such a post in
+     * the browser only while this is `refuse`, absent or a value it does not
+     * know; otherwise the post pauses and the API and the cardholder's device
+     * apply the policy. Read at each sync, so a policy change needs no SDK
+     * release.
+     */
+    cardOnFile?: string;
     /**
      * True when this processor cannot be taken over on an ordinary authorization:
      * the cardholder must have approved a prepare() first. authorize() refuses
@@ -102,11 +151,39 @@ export interface Recognizer {
     /**
      * True when a processor's host environment is enforced: the API refuses a
      * create whose host environment disagrees with the row's test/live nature, and
-     * the device sends only documented test cards to a sandbox host. Absent on
-     * every entry today; carried verbatim by syncRegistry, and the SDK never acts
+     * the device sends only documented test cards to a sandbox host. GMO sets it
+     * (stg.token.mul-pay.jp is its test host), and so does Datatrans
+     * (pay.sandbox.datatrans.com is its sandbox host), and so does Primer
+     * (sdk.api.sandbox.primer.io is its sandbox host), and so does Payrails (its
+     * two staging hosts are test hosts), and so does WSPay (proxy-test.wspay.biz
+     * is its test host), and so does Shiji STS (iframe.vault.eu.uat.shijipayment.com
+     * is its sandbox host); as dark entries none is ever in
+     * BUILTIN_REGISTRY. Carried verbatim by syncRegistry, and the SDK never acts
      * on it.
      */
     hostEnvironmentPinned?: boolean;
+    /**
+     * The card request's shape when it is not a POST body. Worldpay eProtect
+     * declares `{ method: 'GET', cardIn: 'query', response: 'jsonp' }`: its card
+     * rides in the query of one JSONP <script> GET. Absent means a POST. Carried
+     * verbatim by syncRegistry; isCardRequest reads `method` through
+     * recognizerRequestMethod, and pauses a GET only for a processor whose exact
+     * query this build can check.
+     */
+    request?: {
+        method: 'GET' | 'POST';
+        cardIn?: string;
+        response?: string;
+    };
+    /**
+     * Anchored regex SOURCES of hostnames the SDK pauses only to ABORT: Worldpay
+     * eProtect's failover host, where the vendor script re-sends the page's
+     * registration 5 seconds after an unanswered primary. Never a card
+     * destination: not in `hosts`, never recognized. cardUrlPatterns arms them so
+     * a raw CDP connection can refuse the re-send. Carried verbatim by
+     * syncRegistry.
+     */
+    abortHosts?: string[];
 }
 import { BUILTIN_REGISTRY } from './builtin-registry.generated.js';
 export { BUILTIN_REGISTRY };
@@ -124,7 +201,31 @@ export interface RecognizerOptions {
 export declare function isLoopbackUrl(parsed: URL): boolean;
 /** The glob patterns that pause every loopback request under a sandbox client; `isCardRequest` is the exact check. */
 export declare const LOOPBACK_URL_PATTERNS: readonly string[];
+/**
+ * The URLs a recognizer's own rules read for `url`. With sandbox credentials a loopback fixture's
+ * request is read on each of the processor's hosts whose endpoint its path matches (decision 178, the
+ * way findRecognizer recognises it), so a rule written against the processor's host, such as the
+ * card-free endpoints a catalog entry names, answers on the fixture as it would on the processor.
+ * Every other URL is read as it is.
+ */
+export declare function urlsOnProcessorHosts(url: string, rec: Recognizer, opts?: RecognizerOptions): string[];
 export declare function findRecognizer(url: string, registry?: Recognizer[], opts?: RecognizerOptions): Recognizer | null;
+/**
+ * The HTTP method of a recognizer's card request, the rule payment-core's
+ * recognizerRequestMethod applies: GET only when the entry declares
+ * `request.method: 'GET'` (Worldpay eProtect), POST for everything else, so a
+ * value that rode in over the wire as anything else never widens a POST
+ * recognizer.
+ */
+export declare function recognizerRequestMethod(rec: Pick<Recognizer, 'request'>): 'GET' | 'POST';
+/**
+ * Whether `method` is this recognizer's card request method for `url`. A GET
+ * carries the card in its URL, so a GET recognizer is a card request only for a
+ * processor whose exact query this build checks (Worldpay eProtect, through
+ * payment-core's grammar); any other GET recognizer is nothing this build can
+ * complete and is never paused.
+ */
+export declare function isRecognizerRequest(rec: Recognizer, url: string, method: string): boolean;
 /**
  * True when this processor cannot be taken over on an ordinary authorization:
  * the cardholder must have approved a prepare() first (the `preparationRequired`
@@ -133,8 +234,9 @@ export declare function findRecognizer(url: string, registry?: Recognizer[], opt
  * preparation_required for the same case. This is the SAME rule payment-core's
  * recognizerRequiresPreparation applies on the server, a strict `=== true`, so a
  * value that rode in over the wire (syncRegistry spreads the served JSON) cannot
- * turn a truthy string into a gate. Absent on every BUILTIN_REGISTRY entry, so
- * this is false for all 24 today.
+ * turn a truthy string into a gate. Absent on every BUILTIN_REGISTRY entry; only
+ * aci sets it, and aci reaches a client only through syncRegistry once the
+ * client declares its capability.
  */
 export declare function recognizerRequiresPreparation(rec: Pick<Recognizer, 'preparationRequired'>): boolean;
 /**

package/dist/registry.js

@@ -8,6 +8,8 @@
  */
 // Pinned fallback generated from the single shared processor catalog.
 import { BUILTIN_REGISTRY } from './builtin-registry.generated.js';
+import { isEprotectTokenRequest } from './eprotect.generated.js';
+import { EPROTECT_PSP } from './eprotect.js';
 export { BUILTIN_REGISTRY };
 /** True for a plain-http loopback address (`127.0.0.1` or `localhost`, any port); the only http a sandbox recogniser admits. */
 export function isLoopbackUrl(parsed) {
@@ -29,6 +31,27 @@ function literalHosts(sources) {
     }
     return out;
 }
+/**
+ * The URLs a recognizer's own rules read for `url`. With sandbox credentials a loopback fixture's
+ * request is read on each of the processor's hosts whose endpoint its path matches (decision 178, the
+ * way findRecognizer recognises it), so a rule written against the processor's host, such as the
+ * card-free endpoints a catalog entry names, answers on the fixture as it would on the processor.
+ * Every other URL is read as it is.
+ */
+export function urlsOnProcessorHosts(url, rec, opts = {}) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return [url];
+    }
+    if (!opts.sandbox || !isLoopbackUrl(parsed))
+        return [url];
+    const anchored = new RegExp(`^(?:${rec.match.source})$`, 'i');
+    const hosts = literalHosts(rec.hosts).filter((host) => anchored.test(`${host}${parsed.pathname}`));
+    return hosts.length > 0 ? hosts.map((host) => `https://${host}${parsed.pathname}${parsed.search}`) : [url];
+}
 export function findRecognizer(url, registry = BUILTIN_REGISTRY, opts = {}) {
     // Match the way the SERVER does, on the PARSED url — never as a substring of
     // the raw string. `match` is unanchored, so a raw-string test classifies any
@@ -52,8 +75,11 @@ export function findRecognizer(url, registry = BUILTIN_REGISTRY, opts = {}) {
     }
     // Decision 178: with sandbox credentials a loopback fixture store is judged by its path, as if it were
     // on each processor's own host; nothing else about the rule changes, and production never gets here.
+    // A bare endpoint keeps its rule below: no query string or fragment, as the API refuses one.
     if (opts.sandbox && isLoopbackUrl(parsed)) {
         return (registry.find((r) => {
+            if (r.bareEndpoint === true && /[?#]/.test(parsed.href))
+                return false;
             const anchored = new RegExp(`^(?:${r.match.source})$`, 'i');
             return literalHosts(r.hosts).some((host) => anchored.test(`${host}${parsed.pathname}`));
         }) ?? null);
@@ -62,18 +88,54 @@ export function findRecognizer(url, registry = BUILTIN_REGISTRY, opts = {}) {
         return null;
     const hostPath = `${parsed.hostname.toLowerCase()}${parsed.pathname}`;
     return (registry.find((r) => {
-        if (r.hosts && r.hosts.length > 0) {
-            const hostAllowed = r.hosts.some((h) => new RegExp(h, 'i').test(parsed.hostname));
-            if (!hostAllowed)
-                return false;
-        }
+        // hosts[], when the entry carries it, is the server's own allowlist, which admits no host it
+        // does not name: an entry served with none (verifone, found only through a reviewed merchant
+        // profile, verifone.ts) claims no URL here either.
+        if (Array.isArray(r.hosts) && !r.hosts.some((h) => new RegExp(h, 'i').test(parsed.hostname)))
+            return false;
+        // A bare endpoint (bareEndpoint, Authorize.Net's transact.dll) is not
+        // matched with any query string or fragment, even an empty `?` or `#`,
+        // exactly as the server refuses it: the parsed href keeps both, and a `?`
+        // or `#` inside the path is already percent-encoded there. A strict
+        // `=== true`, so a truthy value that rode in over the wire is not a rule.
+        if (r.bareEndpoint === true && /[?#]/.test(parsed.href))
+            return false;
         // FULLY ANCHORED, exactly as the server does it. Unanchored, any EXTENSION
         // of a valid path is admitted on a legitimate processor host
         // (api.stripe.com/v1/tokens/anything), which the service then refuses —
         // and a pause the SDK cannot complete becomes an abort.
-        return new RegExp(`^(?:${r.match.source})$`, 'i').test(hostPath);
+        if (!new RegExp(`^(?:${r.match.source})$`, 'i').test(hostPath))
+            return false;
+        // Worldpay eProtect's card rides in the query of a GET, so the query is
+        // the request: as on the server (payment-core resolveRecognizerForUrl),
+        // only the vendor's exact registration is recognized, never another
+        // /eProtect/paypage call.
+        return r.psp !== EPROTECT_PSP || isEprotectTokenRequest(url, 'GET');
     }) ?? null);
 }
+/**
+ * The HTTP method of a recognizer's card request, the rule payment-core's
+ * recognizerRequestMethod applies: GET only when the entry declares
+ * `request.method: 'GET'` (Worldpay eProtect), POST for everything else, so a
+ * value that rode in over the wire as anything else never widens a POST
+ * recognizer.
+ */
+export function recognizerRequestMethod(rec) {
+    return rec?.request?.method === 'GET' ? 'GET' : 'POST';
+}
+/**
+ * Whether `method` is this recognizer's card request method for `url`. A GET
+ * carries the card in its URL, so a GET recognizer is a card request only for a
+ * processor whose exact query this build checks (Worldpay eProtect, through
+ * payment-core's grammar); any other GET recognizer is nothing this build can
+ * complete and is never paused.
+ */
+export function isRecognizerRequest(rec, url, method) {
+    const expected = recognizerRequestMethod(rec);
+    if (typeof method !== 'string' || method.toUpperCase() !== expected)
+        return false;
+    return expected === 'POST' || (rec.psp === EPROTECT_PSP && isEprotectTokenRequest(url, 'GET'));
+}
 /**
  * True when this processor cannot be taken over on an ordinary authorization:
  * the cardholder must have approved a prepare() first (the `preparationRequired`
@@ -82,8 +144,9 @@ export function findRecognizer(url, registry = BUILTIN_REGISTRY, opts = {}) {
  * preparation_required for the same case. This is the SAME rule payment-core's
  * recognizerRequiresPreparation applies on the server, a strict `=== true`, so a
  * value that rode in over the wire (syncRegistry spreads the served JSON) cannot
- * turn a truthy string into a gate. Absent on every BUILTIN_REGISTRY entry, so
- * this is false for all 24 today.
+ * turn a truthy string into a gate. Absent on every BUILTIN_REGISTRY entry; only
+ * aci sets it, and aci reaches a client only through syncRegistry once the
+ * client declares its capability.
  */
 export function recognizerRequiresPreparation(rec) {
     return rec.preparationRequired === true;
@@ -118,8 +181,19 @@ export function cardUrlPatterns(registry) {
     return [...out];
 }
 function recognizerUrlPatterns(rec) {
-    const hosts = Array.isArray(rec?.hosts) ? rec.hosts.filter((h) => typeof h === 'string') : [];
-    if (hosts.length > 0) {
+    // Abort-only hosts are armed like card hosts: a request there has to be
+    // paused before the adapters can refuse it (Worldpay eProtect's failover).
+    const aborts = Array.isArray(rec?.abortHosts) ? rec.abortHosts.filter((h) => typeof h === 'string') : [];
+    return [...cardHostPatterns(rec), ...aborts.flatMap((h) => regexSourceToGlobs(h)).map((g) => wrap(g).toLowerCase())];
+}
+function cardHostPatterns(rec) {
+    if (Array.isArray(rec?.hosts)) {
+        // An entry that carries hosts[] carries the server's own allowlist, and the server admits no
+        // host it does not name (resolveRecognizerForUrl), so an entry served with none arms nothing.
+        // Verifone is one: its card request goes to the merchant's own server and is found only through
+        // a reviewed merchant profile (verifone.ts). Widening its never-matching `match` instead would
+        // arm `*` and pause every request on every page.
+        //
         // Host text ANYWHERE in the URL, not `*://host/*`. Two reasons: a URL with
         // userinfo (`https://u:p@host/…`) still has `host` as its hostname so the
         // registry matches it, and isCardRequest tests `match` unanchored against
@@ -133,7 +207,7 @@ function recognizerUrlPatterns(rec) {
         // normalization resolveRecognizerForUrl does with url.hostname. Do not
         // "fix" this by wildcarding the letters: `*???.??????.???*` matches most of
         // the web and would pause every request on the page.
-        return hosts.flatMap((h) => regexSourceToGlobs(h)).map((g) => wrap(g).toLowerCase());
+        return rec.hosts.filter((h) => typeof h === 'string').flatMap((h) => regexSourceToGlobs(h)).map((g) => wrap(g).toLowerCase());
     }
     // No hosts[] — a registry pinned before the field existed, or hand-built.
     // Fall back to widening `match`, which is the predicate isCardRequest

package/dist/shiji-sts.d.ts

@@ -0,0 +1,144 @@
+import { SHIJI_STS_COMPANION_WINDOW_MS, SHIJI_STS_PSP, ShijiStsError, isShijiStsHost } from './shiji-sts.generated.js';
+export { SHIJI_STS_COMPANION_WINDOW_MS, SHIJI_STS_PSP, ShijiStsError, isShijiStsHost };
+/** The dark-launch capability a build declares when it swaps Shiji's ciphertexts and binds its getCvvId companion. */
+export declare const SHIJI_STS_CAPABILITY = "shiji_sts_pinned_key";
+/**
+ * Why a Shiji STS request was refused, reported as the `reason` of the `unsupported_checkout` event
+ * and of the attachment's `unsupported` state:
+ *   shiji_sts_keep_on_file         a getTokenId in the proxy's shape while Agentcard cannot yet ask the
+ *                                  cardholder to let a hotel keep the card to guarantee the stay
+ *   unsupported_shiji_sts_request  any other request to getTokenId or getCvvId: not the proxy's shape,
+ *                                  a query, a port, or a body the classifier cannot read
+ *   shiji_sts_foreign_key          a card field encrypted under a key other than the pinned Shiji key
+ *   shiji_sts_companion_unbound    a getCvvId that follows no getTokenId this attachment continued,
+ *                                  or another page's or another accessToken's (a saved card's CVV)
+ *   shiji_sts_companion_expired    a getCvvId more than 120 s after the getTokenId it follows
+ *   shiji_sts_companion_used       a second getCvvId after the one the device's CVV went into
+ */
+export type ShijiStsUnsupportedReason = 'shiji_sts_keep_on_file' | 'unsupported_shiji_sts_request' | 'shiji_sts_foreign_key' | 'shiji_sts_companion_unbound' | 'shiji_sts_companion_expired' | 'shiji_sts_companion_used';
+/** What the adapters do with a POST the registry recognized on an STS host. */
+export type ShijiStsVerdict = {
+    kind: 'pause';
+} | {
+    kind: 'companion';
+} | {
+    kind: 'refuse';
+    reason: ShijiStsUnsupportedReason;
+};
+interface ShijiStsRequest {
+    url: string;
+    method: string;
+    body: string;
+}
+/**
+ * The verdict on a request to an STS host that the registry recognized: 'pause' for the one prompt
+ * (a getTokenId in the proxy's shape once the card-on-file decision allows it), 'companion' for a
+ * getCvvId in the proxy's shape, and 'refuse' with a reason for everything else. A classifier that
+ * throws refuses.
+ */
+export declare function shijiStsVerdict(request: ShijiStsRequest): ShijiStsVerdict;
+/** A cse substitution as the API serves it (substitute.ts Substitutions). */
+interface ServedSubstitutions {
+    encoding: string;
+    at: string;
+    fields: Record<string, string>;
+    remove?: string[];
+}
+/**
+ * Whether an approved Shiji STS authorization's served substitution is one this SDK can continue:
+ * JSON at the body root (`at` is ''), no sibling to remove, and exactly pan, expires and cvv, each a
+ * 128-byte ciphertext as JSEncrypt writes one. Anything else is not acted on.
+ */
+export declare function isShijiStsServedSubstitution(sub: unknown): sub is ServedSubstitutions;
+/**
+ * The page's reviewed getCvvId keys, as the API serves them beside an approved Shiji STS set
+ * (checkout.ts approvedShijiStsFields, `shiji_sts_companion`): the keySequence values Agentcard
+ * reviewed as the booking page's own getCvvId key (its SPS merchant's settings.client_key).
+ */
+export interface ShijiStsServedCompanion {
+    key_sequences: string[];
+}
+/**
+ * Whether the API's `shiji_sts_companion` beside an approved Shiji STS set is one this SDK can bind
+ * the companion getCvvId to: exactly `{ key_sequences }`, 1 to 16 non-empty keySequences of printable
+ * ASCII. Anything else, an API that serves none included, is not acted on: the approval reads as
+ * malformed and the getTokenId is not continued, so no card reaches Shiji while its CVV has no
+ * reviewed key to go to.
+ */
+export declare function isShijiStsServedCompanion(value: unknown): value is ShijiStsServedCompanion;
+/** The paused request an approval was created from: the URL and body the API reviewed at create. */
+export interface ShijiStsApprovedRequest {
+    url: string;
+    body: string;
+}
+/**
+ * The continuation of an approved getTokenId: the paused body with the device's pan and expires
+ * written over the page's own at the body root (payment-core substituteShijiSts, which refuses a
+ * value that is not a ciphertext under the pinned key), the device's cvv, which this body does not
+ * carry and the runtime keeps in memory for the one companion getCvvId, and the reviewed getCvvId
+ * keys that companion may carry it under (`companion`, the replay's shijiStsCompanion, which the
+ * client read from the API's shiji_sts_companion).
+ *
+ * Only into `approved`, the paused getTokenId the approval was created from: `url` and `body` must
+ * equal it byte for byte, so the accessToken and keySequence are the ones the API reviewed at create
+ * (its merchant binding). Every Shiji merchant's card is encrypted under the one pinned key, so the
+ * device's ciphertext would tokenize the card in any STS session a later request of the same shape
+ * names. The adapters never hand a Shiji approval to a retry either (cdp.ts survivesAbandonment).
+ *
+ * Null when neither URL is on an STS host, so every other processor keeps the generic swap. Throws
+ * for any other body or URL, an STS URL that is not getTokenId, a substitution
+ * isShijiStsServedSubstitution refuses (`sub` is whatever the approval served, of any processor's
+ * shape), no reviewed getCvvId key to bind the companion to, and while the card-on-file decision is
+ * open: in each case before anything continues.
+ */
+export declare function shijiStsTokenContinuation(url: string, body: string, sub: unknown, approved: ShijiStsApprovedRequest, companion?: {
+    keySequences: readonly string[];
+}): {
+    body: string;
+    cvv: string;
+    cvvKeySequences: string[];
+} | null;
+/**
+ * One attachment's getCvvId companion: at most one binding, to the getTokenId it last continued with
+ * the Vault's ciphertexts. `bind` runs right before that continue, `release` when the continue
+ * fails or the attachment is cancelled or its page goes away, `releasePage` when the frame or target
+ * the getTokenId came from goes away or commits a new document, and `claim` for every getCvvId in the
+ * proxy's shape. The binding is payment-core's (createShijiStsCompanion: same host, same page, same
+ * accessToken, a reviewed getCvvId key, within 120 s, once). The CVV ciphertext leaves memory with the
+ * one body it goes into or with the teardown that releases it, and the binding itself is dropped a
+ * little after its window, so a later getCvvId reads as unbound.
+ */
+export declare class ShijiStsCompanions {
+    private bound;
+    /**
+     * Bind the companion of `tokenRequest` (the paused getTokenId: its URL, method and body) for the
+     * page `page` (the adapter's opaque id for the frame that sent it) and keep `cvv`, the device's
+     * CVV ciphertext, for it, to go only into a getCvvId whose keySequence is one of `cvvKeySequences`
+     * (the reviewed getCvvId keys the approval served). Replaces any earlier binding. Throws
+     * ShijiStsError for a request that is not a getTokenId in the proxy's shape, a key list
+     * payment-core refuses (none, empty or malformed), and while the card-on-file decision is open.
+     */
+    bind(tokenRequest: ShijiStsRequest, page: string, cvv: string, cvvKeySequences: readonly string[], now?: number): void;
+    /** Drop the binding and the CVV ciphertext it holds. */
+    release(): void;
+    /**
+     * Drop the binding only when its page is one `gone` names: the adapter calls it with a test for the
+     * page ids of a frame or target that went away, so the CVV ciphertext never outlives the frame its
+     * getCvvId would have to come from, and a binding on another frame stays.
+     */
+    releasePage(gone: (page: string) => boolean): void;
+    /** Whether a binding is held (its window may have closed; claim decides). */
+    isBound(): boolean;
+    /** The page id the binding is held for, or null with none: an adapter compares its own ids to it. */
+    boundPage(): string | null;
+    /**
+     * The body to continue a getCvvId with, the device's CVV written over the page's own at the body
+     * root, or why the request is refused. Only the first getCvvId the binding answers 'swap' for gets
+     * a body; the CVV ciphertext is dropped as it is written, so a second one reads as used.
+     */
+    claim(request: ShijiStsRequest, page: string, now?: number): {
+        body: string;
+    } | {
+        reason: ShijiStsUnsupportedReason;
+    };
+}

package/dist/shiji-sts.generated.d.ts

@@ -0,0 +1,72 @@
+declare var SHIJI_STS_PSP: string;
+declare var SHIJI_STS_HOSTS: readonly string[];
+declare var SHIJI_STS_SANDBOX_HOST: string;
+declare var SHIJI_STS_TOKEN_PATH: string;
+declare var SHIJI_STS_CVV_PATH: string;
+declare var SHIJI_STS_KEY: Readonly<{
+    spki: "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDF68IfqgqwmtmAKHNDlEyO9dYQiJHLd9ZixQ32PmzQtBH/mK+KB0q9K2kT7IjL1KdfSPSh8zXlXJOzZ8HQPewmxZgDSnKBVoeVb8HENiaMcIioddz9GJSY1z5ZvEE2DZawiSRxOiOorXQ8HjyVF+1McoWbIShrbeLcT/lC/FS5UQIDAQAB";
+    sha256: "c7846a0f1736b11b7549a364122d43b6517b87989f873ad805748b1f5a469ff7";
+}>;
+declare var SHIJI_STS_CIPHERTEXT_BYTES: number;
+declare var SHIJI_STS_COMPANION_WINDOW_MS: number;
+declare var SHIJI_STS_FIELDS: Readonly<{
+    token: readonly string[];
+    cvv: readonly string[];
+}>;
+declare var SHIJI_STS_KEEP_ON_FILE: string;
+declare var SHIJI_STS_REFUSAL_REASONS: readonly string[];
+declare var ShijiStsError: {
+    new (reason: any): {
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+};
+declare function shijiStsRefusalMessage(reason: any): any;
+declare function shijiStsKeepOnFileRefusal(policy?: string): "keep_on_file" | null;
+declare function shijiStsEndpoint(url: any, method?: string): "token" | "cvv" | null;
+declare function shijiStsEnvironment(url: any, method?: string): "sandbox" | "live" | null;
+declare function isShijiStsHost(url: any): boolean;
+declare function isShijiStsCiphertext(value: any): boolean;
+declare function isShijiStsCiphertextUnderKey(value: any): boolean;
+declare function readShijiStsBody(kind: any, body: any): Readonly<{
+    ok: false;
+    reason: "unsupported";
+}> | Readonly<{
+    ok: false;
+    reason: "foreign_key";
+}> | Readonly<{
+    ok: boolean;
+    accessToken: any;
+    keySequence: any;
+    fields: Readonly<{}>;
+}>;
+declare function shijiStsBodyRefusal(url: any, body: any): any;
+declare function classifyShijiStsRequest(url: any, method: any, body: any): any;
+declare function isShijiStsCardRequest(request: any): boolean;
+declare function shijiStsPlaintexts(card: any): {
+    pan: string;
+    expires: string;
+    cvv: string;
+};
+declare function encryptShijiStsCard(card: any, facilities?: {}): {
+    pan: string;
+    expires: string;
+    cvv: string;
+};
+declare function shijiStsKeyUsable(authorization: any): boolean;
+declare function substituteShijiSts(url: any, body: any, fields: any): string;
+declare function shijiStsSubstitutionsRefusal(template: any, substitutions: any): {
+    code: string;
+    message: any;
+} | null;
+declare function createShijiStsCompanion(tokenRequest: any, { page, now, cvvKeySequences }?: {}): Readonly<{
+    claim: (request: any, context?: {}) => any;
+}>;
+declare function shijiStsResponseFacts(status: any, text: any): {
+    outcome: string;
+    code: any;
+};
+declare function sanitizeShijiStsResponse(text: any, status?: number): string;
+export { SHIJI_STS_CIPHERTEXT_BYTES, SHIJI_STS_COMPANION_WINDOW_MS, SHIJI_STS_CVV_PATH, SHIJI_STS_FIELDS, SHIJI_STS_HOSTS, SHIJI_STS_KEEP_ON_FILE, SHIJI_STS_KEY, SHIJI_STS_PSP, SHIJI_STS_REFUSAL_REASONS, SHIJI_STS_SANDBOX_HOST, SHIJI_STS_TOKEN_PATH, ShijiStsError, classifyShijiStsRequest, createShijiStsCompanion, encryptShijiStsCard, isShijiStsCardRequest, isShijiStsCiphertext, isShijiStsCiphertextUnderKey, isShijiStsHost, readShijiStsBody, sanitizeShijiStsResponse, shijiStsBodyRefusal, shijiStsEndpoint, shijiStsEnvironment, shijiStsKeepOnFileRefusal, shijiStsKeyUsable, shijiStsPlaintexts, shijiStsRefusalMessage, shijiStsResponseFacts, shijiStsSubstitutionsRefusal, substituteShijiSts };