@agent-cards/sdk 0.20.0 → 0.22.0

package/dist/merchant-hosted.d.ts

@@ -100,7 +100,10 @@ export declare function armServedProfiles(entries?: readonly unknown[]): Merchan
  * under a test_ key.
  */
 export declare function declareSandboxMerchant(input: SandboxMerchantDeclaration): MerchantProfile;
-/** The armed profile whose endpoint, or a sibling of it (same origin and path shape), a URL is; null for any other URL. */
+/**
+ * The armed profile whose endpoint, a sibling of it (same origin and path shape), its then
+ * request or one of its other card requests a URL is; null for any other URL.
+ */
 export declare function merchantProfileFor(profiles: readonly MerchantProfile[], url: string): MerchantProfile | null;
 /** The Fetch.enable globs that pause every armed profile's endpoint and its siblings, a declared endpoint included. */
 export declare function merchantProfileUrlPatterns(profiles: readonly MerchantProfile[]): string[];

package/dist/merchant-hosted.js

@@ -110,11 +110,14 @@ export function declareSandboxMerchant(input) {
     return Object.freeze({ id: built.id, merchant: url.hostname, status: 'enabled',
         sandboxDeclaration: Object.freeze({ endpoint: input.endpoint, clientKey: input.clientKey }) });
 }
-/** How a URL relates to an armed profile: its declared endpoint when it has one, else the reviewed endpoint. */
+/** How a URL relates to an armed profile: its declared endpoint when it has one, else the reviewed requests. */
 function relationTo(profile, url) {
     return profile.sandboxDeclaration ? declaredRelation(profile.sandboxDeclaration.endpoint, url) : urlRelation(profile.id, url);
 }
-/** The armed profile whose endpoint, or a sibling of it (same origin and path shape), a URL is; null for any other URL. */
+/**
+ * The armed profile whose endpoint, a sibling of it (same origin and path shape), its then
+ * request or one of its other card requests a URL is; null for any other URL.
+ */
 export function merchantProfileFor(profiles, url) {
     if (typeof url !== 'string')
         return null;

package/dist/merchant-session-probe.d.ts

@@ -0,0 +1,48 @@
+/** One cookie of the merchant's jar, name and value only. */
+export interface MerchantSessionCookie {
+    name: string;
+    value: string;
+}
+/** What a probe create carries: the reviewed profile and the kept cookies, and the names it dropped (never their values). */
+export interface MerchantSessionCapture {
+    profile: string;
+    cookies: MerchantSessionCookie[];
+    dropped: string[];
+}
+/**
+ * Why a capture was refused before anything left this process. `signed_in`: the jar holds
+ * a sign-in token (phase 1 reads guest checkouts only); `no_session`: nothing but
+ * bot-manager cookies, or nothing at all; `invalid_session`: a cookie that is not an RFC
+ * 6265 pair, one name twice, or past the limits; `unknown_profile`: no reviewed read.
+ */
+export type MerchantSessionRefusal = 'unknown_profile' | 'signed_in' | 'no_session' | 'invalid_session';
+export declare class MerchantSessionRefusedError extends Error {
+    readonly profile: string;
+    readonly reason: MerchantSessionRefusal;
+    constructor(profile: string, reason: MerchantSessionRefusal);
+}
+/** The URL whose cookie jar a capture reads: the block's endpoint and read path. Null for a profile with no reviewed read. */
+export declare function merchantSessionReadUrl(profile: string): string | null;
+/** The capture rules alone, for a jar already read: kept cookies, dropped names, or a MerchantSessionRefusedError. */
+export declare function merchantSessionCapture(profile: string, jar: readonly {
+    name: string;
+    value: string;
+}[]): MerchantSessionCapture;
+/** The CDP command a capture needs: Network.getCookies on the page session. */
+export interface MerchantSessionCdp {
+    send(method: 'Network.getCookies', params: {
+        urls: string[];
+    }, sessionId?: string): Promise<{
+        cookies?: {
+            name: string;
+            value: string;
+        }[];
+    } | undefined>;
+}
+/**
+ * Read the merchant's cookie jar for a profile's read URL on a CDP page session (the
+ * agent's own browser, after the person built the cart by hand) and apply the capture
+ * rules. The jar is read the 14b way: Network.getCookies for the exact read URL, so only
+ * the cookies the merchant's own page would send there, HttpOnly included.
+ */
+export declare function captureMerchantSession(cdp: MerchantSessionCdp, sessionId: string | undefined, profile: string): Promise<MerchantSessionCapture>;

package/dist/merchant-session-probe.js

@@ -0,0 +1,53 @@
+// The merchant-session probe's capture (the deterministic merchant total, phase 0): the
+// SDK reads the merchant's cookie jar for a reviewed read URL, the way the card endpoint
+// capture reads it for a paused card request (Network.getCookies, HttpOnly included), and
+// hands the kept cookies to the API's probe create. No card request is paused, no JWE is
+// made and no card is involved: the cardholder's Vault page reads the merchant's own total
+// through the merchant-session relay, once, and records what it saw.
+//
+// The same rules as the API and the Vault run (payment-core merchant-session.js, the SDK's
+// generated copy): every bot-manager cookie is dropped (D19), and a jar that carries a
+// sign-in token is refused before anything leaves this process (D22). The cookies are a
+// merchant session: no event, error or log line from this module names a value.
+import { MERCHANT_SESSION_PROFILES as SHARED_PROFILES, merchantSessionCookies as sharedCookies, } from './merchant-session.generated.js';
+export class MerchantSessionRefusedError extends Error {
+    profile;
+    reason;
+    constructor(profile, reason) {
+        super(`refused a merchant read for ${profile} (${reason}). Nothing was sent.`);
+        this.profile = profile;
+        this.reason = reason;
+        this.name = 'MerchantSessionRefusedError';
+    }
+}
+const BLOCKS = SHARED_PROFILES;
+const keptCookies = (profile, jar) => sharedCookies(profile, jar);
+/** The URL whose cookie jar a capture reads: the block's endpoint and read path. Null for a profile with no reviewed read. */
+export function merchantSessionReadUrl(profile) {
+    const block = BLOCKS.find((entry) => entry.profile === profile);
+    return block ? `${block.endpoint}${block.read.path}` : null;
+}
+/** The capture rules alone, for a jar already read: kept cookies, dropped names, or a MerchantSessionRefusedError. */
+export function merchantSessionCapture(profile, jar) {
+    if (!merchantSessionReadUrl(profile))
+        throw new MerchantSessionRefusedError(profile, 'unknown_profile');
+    const kept = keptCookies(profile, (Array.isArray(jar) ? jar : []).map(({ name, value }) => ({ name, value })));
+    if (!kept.ok) {
+        const reason = kept.code === 'signed_in' || kept.code === 'no_session' || kept.code === 'unknown_profile' ? kept.code : 'invalid_session';
+        throw new MerchantSessionRefusedError(profile, reason);
+    }
+    return { profile, cookies: kept.cookies, dropped: kept.dropped };
+}
+/**
+ * Read the merchant's cookie jar for a profile's read URL on a CDP page session (the
+ * agent's own browser, after the person built the cart by hand) and apply the capture
+ * rules. The jar is read the 14b way: Network.getCookies for the exact read URL, so only
+ * the cookies the merchant's own page would send there, HttpOnly included.
+ */
+export async function captureMerchantSession(cdp, sessionId, profile) {
+    const url = merchantSessionReadUrl(profile);
+    if (!url)
+        throw new MerchantSessionRefusedError(profile, 'unknown_profile');
+    const jar = (await cdp.send('Network.getCookies', { urls: [url] }, sessionId))?.cookies ?? [];
+    return merchantSessionCapture(profile, jar);
+}

package/dist/merchant-session.generated.d.ts

@@ -0,0 +1,69 @@
+declare var MERCHANT_SESSION_MODE: string;
+declare var MERCHANT_SESSION_USER_AGENT: string;
+declare var MERCHANT_SESSION_BOT_COOKIES: any;
+declare var MERCHANT_SESSION_SIGN_IN_COOKIES: any;
+declare var MERCHANT_SESSION_READ_LIMITS: any;
+declare var MERCHANT_SESSION_RELAY_URL: string;
+declare var MERCHANT_SESSION_COOKIE_LIMITS: any;
+declare var MERCHANT_SESSION_PROFILES: any;
+declare function merchantSessionProfile(id: any): any;
+declare function merchantSessionHosts(): unknown[];
+declare function merchantSessionProfileRefusal(block: any): string | null;
+declare function merchantSessionCookies(id: any, cookies: any): {
+    ok: boolean;
+    code: any;
+    reason: any;
+} | {
+    ok: boolean;
+    cookies: {
+        name: any;
+        value: any;
+    }[];
+    dropped: any[];
+    header: string;
+};
+declare function merchantSessionRead(id: any, session: any): any;
+declare var MERCHANT_SESSION_CACHE_FACT_CHARS: number;
+declare function merchantSessionAnswerFacts(response: any): {
+    status: any;
+    challenge: string | null;
+    headerNames: string[];
+    cache: {};
+};
+declare function merchantSessionReading(id: any, response: any, { now }?: {}): {
+    ok: boolean;
+    code: any;
+    reason: any;
+} | {
+    ok: boolean;
+    profile: any;
+    totalMinor: number;
+    currency: any;
+    cartId: string;
+    cartIdSha256: string;
+    expiresAt: number | null;
+    snapshotSha256: string;
+    digests: {
+        goods: string;
+        destination: string;
+        recipient: string;
+    };
+    kountSessionSha256: null;
+} | {
+    ok: boolean;
+    profile: any;
+    totalMinor: number;
+    currency: any;
+    cartId: null;
+    cartIdSha256: null;
+    expiresAt: null;
+    snapshotSha256: string;
+    digests: {
+        goods: string;
+        destination: string;
+        recipient: string;
+    };
+    kountSessionSha256: string | null;
+};
+declare function sameMerchantSnapshot(a: any, b: any): boolean;
+export { MERCHANT_SESSION_BOT_COOKIES, MERCHANT_SESSION_CACHE_FACT_CHARS, MERCHANT_SESSION_COOKIE_LIMITS, MERCHANT_SESSION_MODE, MERCHANT_SESSION_PROFILES, MERCHANT_SESSION_READ_LIMITS, MERCHANT_SESSION_RELAY_URL, MERCHANT_SESSION_SIGN_IN_COOKIES, MERCHANT_SESSION_USER_AGENT, merchantSessionAnswerFacts, merchantSessionCookies, merchantSessionHosts, merchantSessionProfile, merchantSessionProfileRefusal, merchantSessionRead, merchantSessionReading, sameMerchantSnapshot };