@agent-cards/sdk 0.23.19 → 0.23.21

package/dist/amadeus.js

@@ -19,6 +19,11 @@
 // handed back in time. A token Wix mints after that point is one no charge ever names, so a paused
 // tokenize request gets the same 20 second window.
 //
+// HiPay's merchant page gives its hosted fields 20 seconds after Pay (getPaymentData answers TIMEOUT_ERROR), and
+// the merchant's server charges only a token the page read in time. A token HiPay mints after that point stays in
+// the frame unused (the frame's next Pay would send /update, which the SDK refuses), so a paused token create gets a
+// 12 second window: HiPay answers a create in about a second, so a card sent inside it reaches the page in time.
+//
 // So when the window closes and no answer is being handed to the page yet, the adapter asks for that
 // cancel. Confirmed: nothing was sent and nothing can be, so the attempt stops, the page's request
 // fails (a Secure Acceptance frame gets the stopped page), and the checkout reads failed. Not
@@ -30,16 +35,20 @@
 // the same cancel and the same rule, and when the API confirms neither, the attempt keeps waiting. The
 // Data Collection Page's store has no client timeout and gets no window. The window's events name the
 // processor: `amadeus_send_window_closed` and `amadeus_send_window_unconfirmed`,
-// `secure_acceptance_send_window_closed` and `secure_acceptance_send_window_unconfirmed`, or
-// `wix_payments_send_window_closed` and `wix_payments_send_window_unconfirmed`.
+// `secure_acceptance_send_window_closed` and `secure_acceptance_send_window_unconfirmed`,
+// `wix_payments_send_window_closed` and `wix_payments_send_window_unconfirmed`, or
+// `hipay_send_window_closed` and `hipay_send_window_unconfirmed`.
 import { amadeusCardUrl } from './amadeus-checkout.generated.js';
 import { isSecureAcceptanceTokenRequest } from './cybersource-secure-acceptance.generated.js';
 import { SECURE_ACCEPTANCE_PSP, SECURE_ACCEPTANCE_SEND_WINDOW_MS } from './cybersource-secure-acceptance.js';
 import { WIX_PAYMENTS_PSP, isWixPaymentsTokenizeUrl } from './wix-payments.generated.js';
+import { HIPAY_PSP, isHipayTokenUrl } from './hipay.generated.js';
 /** How long after the pause a paused Amadeus SDK add may still be sent. */
 export const AMADEUS_SEND_WINDOW_MS = 20_000;
 /** How long after the pause a paused Wix tokenize request may still be sent, of the 30 seconds Wix's widget waits. */
 export const WIX_PAYMENTS_SEND_WINDOW_MS = 20_000;
+/** How long after the pause a paused HiPay token create may still be sent, of the 20 seconds the merchant's page waits. */
+export const HIPAY_SEND_WINDOW_MS = 12_000;
 /**
  * True when a request the adapters refuse must fail as a network error (ERR_FAILED) rather than as
  * the cancellation (ERR_ABORTED) they use elsewhere. An XMLHttpRequest reports a cancellation only
@@ -53,7 +62,7 @@ export function failsAsNetworkError(url) {
 /**
  * The send window for a request paused under a preparation for `psp`, or null when it has none: a
  * prepared Amadeus SDK add, a prepared CyberSource Secure Acceptance token create and a prepared Wix
- * tokenize request, each 20 seconds.
+ * tokenize request, each 20 seconds, and a prepared HiPay token create, 12 seconds.
  */
 export function preparedSendWindowMs(psp, url) {
     if (psp === 'amadeus_checkout')
@@ -70,12 +79,16 @@ export function preparedSendWindowMs(psp, url) {
     }
     if (psp === WIX_PAYMENTS_PSP)
         return isWixPaymentsTokenizeUrl(url) ? WIX_PAYMENTS_SEND_WINDOW_MS : null;
+    if (psp === HIPAY_PSP)
+        return isHipayTokenUrl(url) ? HIPAY_SEND_WINDOW_MS : null;
     return null;
 }
 /** The processor a prepared request's send window names in its events, or null when it has none. */
 export function sendWindowProcessor(psp) {
     if (psp === WIX_PAYMENTS_PSP)
         return 'wix_payments';
+    if (psp === HIPAY_PSP)
+        return 'hipay';
     return psp === 'amadeus_checkout' ? 'amadeus' : psp === SECURE_ACCEPTANCE_PSP ? 'secure_acceptance' : null;
 }
 /** The send window for a prepared Amadeus SDK add, or null: preparedSendWindowMs for Amadeus alone. */

package/dist/buy.d.ts

@@ -16,8 +16,8 @@
  */
 import { ApiModule, type ApiTransport } from './api-module.js';
 import { AgentcardError } from './voice-types.js';
-/** Where a turn stands. `needs_input` is the common case: a question, or a cart waiting for its confirm; `needs_approval` is a confirm under `approval: 'voice'` waiting for the person's verdict on `authorization_id`. */
-export type BuyStatus = 'needs_input' | 'needs_approval' | 'order_placed' | 'partially_placed' | 'declined';
+/** Where a turn stands. `needs_input` is the common case: a question, or a cart waiting for its confirm; `needs_approval` is a confirm under `approval: 'voice'` waiting for the person's verdict on `authorization_id`; `approved_not_charged` is a sandbox browser checkout the person approved, where the card was never sent to the store. */
+export type BuyStatus = 'needs_input' | 'needs_approval' | 'order_placed' | 'partially_placed' | 'declined' | 'approved_not_charged';
 /** How a confirm that pays with the person's own card asks them: `page`, Agentcard's approval page on `approval_url` (the default); `voice`, the key word inside your app on the purchase's own `authorization_id`. */
 export type BuyApproval = 'voice' | 'page';
 /** The two ways a purchase approved by voice ends without an order: the person declined it, or the approval ran out before a confirm placed against it. */
@@ -129,6 +129,75 @@ export interface BuyUnmatched {
     detail: string | null;
     at: string;
 }
+/**
+ * The step your own agent takes next when the purchase agent hands it a matched offer's checkout
+ * (your client's browser mode is `agent`): open `buy_url` itself, in the browser that will check out,
+ * attach this SDK before the payment form, and create the checkout authorization the hint describes
+ * before `expires_at`. `reply` says the same in words.
+ */
+export interface BuyCheckoutHandoff {
+    type: 'open_offer';
+    buy_url: string;
+    store: {
+        domain: string;
+        name?: string;
+    };
+    product: {
+        id: string;
+        title: string;
+    };
+    quantity: number;
+    /** The catalog's price for the product and its `currency`, as the API sends it (see the Purchase API reference). */
+    listed_price: BuyApiAmount;
+    checkout: {
+        /** The `merchant`, `currency` and `checkout_origin` the checkout authorization names, and the most it may authorize, as the API sends them. */
+        authorization_hint: BuyApiAmount & {
+            merchant: string;
+            checkout_origin: string;
+        };
+        sdk: string;
+    };
+    rules: string[];
+    expires_at: string;
+}
+/**
+ * An amount object as the Purchase API sends it inside a browser checkout step: its `currency`, and its
+ * amount fields under the API's own names, passed through untyped. The SDK's one word for an amount is
+ * `amount`, and these objects reach a caller exactly as the API wrote them.
+ */
+export type BuyApiAmount = {
+    currency: string;
+} & Record<string, unknown>;
+/** An offer handed to your own agent, and how far it got (`link`, `product`, `cart`, `payment`, `approved`), read from the checkout authorization your SDK created. */
+export interface BuyOpenOffer {
+    type: 'open_offer';
+    buy_url: string;
+    store_domain: string;
+    product_id: string;
+    /** The catalog's price for the product, as the API sends it. */
+    listed_price: BuyApiAmount;
+    expires_at: string;
+    stage: string;
+    authorization_id: string | null;
+    authorization_status: string | null;
+    /** The store's charge on that authorization: `authorized` (a hold), `captured`, or null. */
+    charged_kind: string | null;
+}
+/** A checkout Agentcard ran in its own browser at a store, and where it stands (`at_payment`, `awaiting_approval`, `approved_not_charged`, `placed`, `declined`, `expired`, `failed`, `released`). */
+export interface BuyBrowserCheckout {
+    checkout_id: string;
+    status: string;
+    store: string;
+    store_url: string | null;
+    total_cents: number | null;
+    currency: string;
+    cart_hash: string;
+    approval_url: string | null;
+    authorization_id: string | null;
+    order_id: string | null;
+    failure_reason: string | null;
+    updated_at: string;
+}
 /**
  * One turn's answer. Branch on `status`; read `cart.hash` for the confirm
  * that follows; never parse `reply`. `error_code: 'turn_timeout'` means the
@@ -149,6 +218,8 @@ export interface BuyTurn extends BuyOutcome {
     catalog: BuyCatalog | null;
     error_code: string | null;
     unmatched: BuyUnmatched[];
+    /** The step your own agent takes next, when the purchase agent hands it the checkout; null otherwise. */
+    checkout_handoff: BuyCheckoutHandoff | null;
 }
 /** A turn the API declined: `status: 'declined'` with the code that says why. `isBuyDeclined` narrows to it. */
 export type BuyDeclined = BuyTurn & {
@@ -218,6 +289,10 @@ export interface BuyConversation {
     orders: BuyOrder[];
     carts: BuyCart[];
     unmatched: BuyUnmatched[];
+    /** The offers handed to your own agent on this conversation, and how far each got. */
+    open_offers: BuyOpenOffer[];
+    /** Every checkout Agentcard ran in its own browser on this conversation, and where each stands. */
+    browser_checkouts: BuyBrowserCheckout[];
     created_at: string;
     updated_at: string;
 }
@@ -263,6 +338,13 @@ export interface BuyConfirmInput {
      * `voice_declined` or `approval_expired`. Sent only when named.
      */
     approval?: BuyApproval;
+    /**
+     * On a repeat confirm of a browser cart waiting for the person's approval,
+     * hold up to 25 seconds and answer the moment they decide, instead of
+     * answering "still waiting" at once. The first confirm never holds: it
+     * answers with the `approval_url` straight away. Sent only when true.
+     */
+    wait?: boolean;
     /** How long this call waits for the turn. Default 130 seconds. */
     timeout_ms?: number;
 }

package/dist/buy.js

@@ -89,6 +89,17 @@ function cartsOf(v) {
 }
 const str = (v) => (typeof v === 'string' ? v : null);
 const num = (v) => (typeof v === 'number' ? v : null);
+const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/** The step this version knows, `open_offer`; an answer with none, or with a kind of step a later API adds, reads as null. */
+function checkoutHandoffOf(v) {
+    return isRecord(v) && v.type === 'open_offer' && typeof v.buy_url === 'string' ? v : null;
+}
+function openOffersOf(v) {
+    return Array.isArray(v) ? v.filter((o) => isRecord(o) && o.type === 'open_offer' && typeof o.buy_url === 'string') : [];
+}
+function browserCheckoutsOf(v) {
+    return Array.isArray(v) ? v.filter((b) => isRecord(b) && typeof b.checkout_id === 'string') : [];
+}
 function paymentSourceOf(v) {
     if (!v || typeof v !== 'object')
         return null;
@@ -102,7 +113,7 @@ function outcomeOf(a) {
         authorization_id: str(a.authorization_id),
     };
 }
-const STATUSES = new Set(['needs_input', 'needs_approval', 'order_placed', 'partially_placed', 'declined']);
+const STATUSES = new Set(['needs_input', 'needs_approval', 'order_placed', 'partially_placed', 'declined', 'approved_not_charged']);
 function statusOf(v) { return typeof v === 'string' && STATUSES.has(v) ? v : 'needs_input'; }
 function placementsOf(v) {
     if (!Array.isArray(v))
@@ -125,6 +136,7 @@ export function turnOf(body) {
         catalog: body.catalog && typeof body.catalog === 'object' ? body.catalog : null,
         error_code: str(body.error_code),
         unmatched: Array.isArray(body.unmatched) ? body.unmatched : [],
+        checkout_handoff: checkoutHandoffOf(body.checkout_handoff),
         ...outcomeOf(body),
     };
 }
@@ -138,6 +150,8 @@ function conversationOf(body) {
         orders: Array.isArray(body.orders) ? body.orders : [],
         carts: cartsOf(body.carts),
         unmatched: Array.isArray(body.unmatched) ? body.unmatched : [],
+        open_offers: openOffersOf(body.open_offers),
+        browser_checkouts: browserCheckoutsOf(body.browser_checkouts),
         created_at: str(body.created_at) ?? '',
         updated_at: str(body.updated_at) ?? '',
     };
@@ -231,6 +245,7 @@ export class BuyModule extends ApiModule {
             ...(input.delivery_address ? { delivery_address: input.delivery_address } : {}),
             ...(input.payment_source ? { payment_source: input.payment_source } : {}),
             ...(input.approval ? { approval: input.approval } : {}),
+            ...(input.wait === true ? { wait: true } : {}),
         };
         return this.turn(body, input.timeout_ms);
     }

package/dist/card-endpoint-facts.d.ts

@@ -41,7 +41,8 @@ export declare class CardEndpointFactsWatch {
     tracks(key: string): boolean;
     /**
      * A request left. Recorded only when it is a document, an XHR or a fetch (or of a type
-     * the adapter could not name) on the endpoint origin of a profile with facts.
+     * the adapter could not name) on the origin a profile's record comes from: its facts
+     * origin (D-EDGE's payment hub), else its endpoint origin (FastSpring's popup).
      */
     sent(key: string, request: {
         method: string;

package/dist/card-endpoint-facts.js

@@ -6,14 +6,22 @@
 // the popup document (script#viewdata) and replaces it with every JSON answer it reads
 // from the session URL, tax included. From attach on, the adapters tell this watch about
 // every request that leaves, every answer and every failure; it keeps, read-only, the
-// documents, XHRs and fetches on the endpoint origin of a profile with facts, and nothing
-// else, a bounded number of them, the busiest checkout session's oldest going first; what a
-// checkout lost to that bound can still refuse its capture. When that profile's card request
-// pauses, capture() waits briefly for any request on the same checkout session that left
-// before the pause, then takes the order record whose answer finished last, the one the page
-// shows, cut by payment-core to the values its reader reads (the total with tax, the
-// currency, test mode and the renewal marks). The create carries that cut record; the client
-// and the API read it with the same rules.
+// documents, XHRs and fetches on the origin a profile's record comes from (its endpoint's,
+// or the one its facts name), and nothing else, a bounded number of them, the busiest
+// checkout session's oldest going first; what a checkout lost to that bound can still refuse
+// its capture. When that profile's card request pauses, capture() waits briefly for any
+// request on the same checkout session that left before the pause, then takes the order
+// record whose answer finished last, the one the page shows, cut by payment-core to the
+// values its reader reads (the total with tax, the currency, test mode and the renewal
+// marks). The create carries that cut record; the client and the API read it with the same
+// rules.
+//
+// D-EDGE's card frame posts the card from card.secure-hotel-booking.com, and the payment hub
+// around it loads the booking from pay.secure-hotel-booking.com (POST /load/<session id>):
+// that answer is the record, and the frame's card post and the hub's own calls are one
+// checkout session by the session id they both carry (cardEndpointFactsSession). Its 3-D
+// Secure browser data (/setDevice) is an inert call; a voucher, points or a bank chosen in
+// the hub after /load leaves the booking unknown, and capture() refuses.
 //
 // A record holds the order only if the page changed nothing after it. payment-core's
 // merchantCardEndpointFactsRole names what each request is to the card request: a call
@@ -64,7 +72,8 @@ export class CardEndpointFactsWatch {
     tracks(key) { return this.exchanges.has(key); }
     /**
      * A request left. Recorded only when it is a document, an XHR or a fetch (or of a type
-     * the adapter could not name) on the endpoint origin of a profile with facts.
+     * the adapter could not name) on the origin a profile's record comes from: its facts
+     * origin (D-EDGE's payment hub), else its endpoint origin (FastSpring's popup).
      */
     sent(key, request) {
         if (this.origins.length === 0 || typeof request.url !== 'string' || typeof request.method !== 'string')

package/dist/card-endpoint.d.ts

@@ -49,6 +49,11 @@ export interface CardEndpointProfile {
      */
     readonly facts?: {
         readonly reader: string;
+        /**
+         * Null when the record's answers come from the endpoint origin; else the origin they come from, another host of
+         * the endpoint's site (D-EDGE's payment hub, beside the card frame that posts the card).
+         */
+        readonly origin: string | null;
         readonly responses: readonly {
             readonly method: string;
             readonly path: string;
@@ -101,9 +106,11 @@ export declare const CARD_ENDPOINT_MODE: "card_endpoint";
  *   (`detail` says what, naming fields, never values).
  * - `facts_unavailable`: the merchant keeps its own record of the order (profile.facts),
  *   and this runtime read none for this checkout, or one it cannot place.
- * - `facts_refused`: the merchant's own record says the order renews on a schedule, or
- *   that its checkout is in test mode. A total or currency that differs from the agent's
- *   is an AmountMismatchError instead.
+ * - `facts_refused`: the merchant's own record says the order renews on a schedule, that
+ *   the merchant charges the card later (a hotel rate that only guarantees the booking, a
+ *   charge on a later date, part of the room left for the stay), or that its checkout is
+ *   in test mode. A total or currency that differs from the agent's is an
+ *   AmountMismatchError instead.
  *
  * `not_enabled`, `amount_required`, `approval_required` and `preparation_unsupported`
  * answer the same way for every request on the attachment, so the adapters stop asking;
@@ -138,7 +145,10 @@ export declare function cardEndpointResendFor(url: string, method: string): Card
  * CORS preflight to the same URL defers), so routing a URL is never a decision to pause it.
  */
 export declare function cardEndpointRouted(url: string): boolean;
-/** The origins of the profiles whose merchant keeps its own record of the order: the only responses card-endpoint-facts.ts records. */
+/**
+ * The origins the record of each profile whose merchant keeps one comes from (its facts.origin, else its
+ * endpoint): the only responses card-endpoint-facts.ts records.
+ */
 export declare function cardEndpointFactsOrigins(): readonly string[];
 /**
  * The checkout session a request on the endpoint of a profile with facts belongs to: the
@@ -148,6 +158,12 @@ export declare function cardEndpointFactsOrigins(): readonly string[];
  * request. card-endpoint-facts.ts counts what it keeps, and what a checkout lost, by it.
  * When the paths of two profiles on one origin both fit, the shorter session is the one:
  * every request on a card request's session then gets the card request's own.
+ *
+ * For a profile whose record comes from its own origin (D-EDGE's payment hub beside the card
+ * frame), a request on that origin belongs to the session its last path segment names, the
+ * session id every hub URL ends in, and the profile's card request to the session its bind
+ * value names, both written on that origin ('https://pay.secure-hotel-booking.com/<id>'): the
+ * card post and the hub's own calls are one checkout, as payment-core's role rules read them.
  */
 export declare function cardEndpointFactsSession(url: string): string | null;
 /** Whether this build's copy of the profile takes payments (enabled, nothing pending, a reviewed HAR, not recurring). */

package/dist/card-endpoint.js

@@ -46,7 +46,9 @@
 // that sends the typed card again outside the card request is aborted in every status
 // (cardEndpointResendFor). And the merchant's own record of the order, which its page
 // reads from the endpoint origin, is recorded read-only (card-endpoint-facts.ts) and sent
-// with the create, so the agent's amount is held to the merchant's total.
+// with the create, so the agent's amount is held to the merchant's total. D-EDGE's card
+// frame is read the same way from the payment hub around it, whose booking record says
+// what the card pays now and whether the hotel charges it later.
 //
 // The endpoint URL (it carries cart, booking and instance ids), the paused body, the
 // session and the answer are cardholder data even with no real card in them: no
@@ -121,9 +123,23 @@ const ROUTED_METHODS = [...new Set(PROFILES.flatMap((profile) => [profile.method
 export function cardEndpointRouted(url) {
     return ROUTED_METHODS.some((method) => cardEndpointFor(url, method) !== null || cardEndpointResendFor(url, method) !== null);
 }
-/** The origins of the profiles whose merchant keeps its own record of the order: the only responses card-endpoint-facts.ts records. */
+/**
+ * The origins the record of each profile whose merchant keeps one comes from (its facts.origin, else its
+ * endpoint): the only responses card-endpoint-facts.ts records.
+ */
 export function cardEndpointFactsOrigins() {
-    return [...new Set(PROFILES.filter((profile) => profile.facts).map((profile) => profile.endpoint))];
+    return [...new Set(PROFILES.filter((profile) => profile.facts).map((profile) => profile.facts.origin ?? profile.endpoint))];
+}
+/**
+ * The `:name` segment of a card path template a URL path gives, when the path has the template's
+ * shape (as many segments, every literal one equal); else null.
+ */
+function boundSegment(template, segments, name) {
+    const want = template.split('/');
+    if (want.length !== segments.length || !want.every((part, i) => (part.startsWith(':') ? segments[i] !== '' : part === segments[i])))
+        return null;
+    const at = want.indexOf(`:${name}`);
+    return at < 1 ? null : segments[at];
 }
 /**
  * The checkout session a request on the endpoint of a profile with facts belongs to: the
@@ -133,6 +149,12 @@ export function cardEndpointFactsOrigins() {
  * request. card-endpoint-facts.ts counts what it keeps, and what a checkout lost, by it.
  * When the paths of two profiles on one origin both fit, the shorter session is the one:
  * every request on a card request's session then gets the card request's own.
+ *
+ * For a profile whose record comes from its own origin (D-EDGE's payment hub beside the card
+ * frame), a request on that origin belongs to the session its last path segment names, the
+ * session id every hub URL ends in, and the profile's card request to the session its bind
+ * value names, both written on that origin ('https://pay.secure-hotel-booking.com/<id>'): the
+ * card post and the hub's own calls are one checkout, as payment-core's role rules read them.
  */
 export function cardEndpointFactsSession(url) {
     let parsed;
@@ -143,9 +165,21 @@ export function cardEndpointFactsSession(url) {
         return null;
     }
     const segments = parsed.pathname.split('/');
+    for (const profile of PROFILES) {
+        const origin = profile.facts?.origin;
+        if (!origin)
+            continue;
+        if (parsed.origin === origin) {
+            const last = segments[segments.length - 1];
+            return last ? `${origin}/${last}` : null;
+        }
+        const bound = parsed.origin === profile.endpoint ? boundSegment(profile.path, segments, profile.facts.bind) : null;
+        if (bound)
+            return `${origin}/${bound}`;
+    }
     let shortest = null;
     for (const profile of PROFILES) {
-        if (!profile.facts || profile.endpoint !== parsed.origin)
+        if (!profile.facts || profile.facts.origin || profile.endpoint !== parsed.origin)
             continue;
         const template = profile.path.split('/');
         const at = template.indexOf(`:${profile.facts.bind}`);