@openlup/platform 0.25.0 → 0.27.0

package/dist/commerce/server/checkoutConflictClassifiers.js

@@ -0,0 +1,38 @@
+import { CheckoutOrchestrationError } from "./commerceCheckoutOrchestrationError.js";
+// Classifiers for the conflict outcomes the checkout orchestration can throw at the
+// `start_runtime` stage. Extracted from the handler so the money-path handler stays
+// within the source-size budget; behaviour is unchanged (pure predicates).
+export function isStockUnavailableCheckoutConflict(error) {
+    return (error instanceof CheckoutOrchestrationError &&
+        error.message === "start_runtime: Inventory reservation conflict");
+}
+export function isProviderAttemptInFlightCheckoutConflict(error) {
+    return (error instanceof CheckoutOrchestrationError &&
+        error.reason === "provider_attempt_in_flight");
+}
+export function isJourneyConsumedCheckoutConflict(error) {
+    return (error instanceof CheckoutOrchestrationError &&
+        error.reason === "journey_consumed");
+}
+/**
+ * `start_runtime` conflicts that map to an identical `CONFLICT + reason` response with
+ * no compensation side effect — the FE resumes/handles each by its `reason`. Order is
+ * significant and preserved from the original inline branches. Stock-unavailable is
+ * intentionally NOT here: it additionally cancels the abandoned order, so the handler
+ * keeps that branch inline.
+ */
+export const START_RUNTIME_SIMPLE_CONFLICTS = [
+    {
+        match: isProviderAttemptInFlightCheckoutConflict,
+        message: "Checkout payment already in flight",
+        reason: "provider_attempt_in_flight",
+    },
+];
+/** Scoped semantic details only; raw SQLSTATE does not authorize this classification. */
+export function isInventoryAdmissionBusy(error) {
+    if (!error || typeof error !== "object" || !("details" in error))
+        return false;
+    const details = error.details;
+    return !!details && typeof details === "object" && "code" in details && details.code === "55P03"
+        && "reason" in details && ["inventory_admission_busy", "inventory_lock_unavailable"].includes(String(details.reason));
+}

package/dist/commerce/server/checkoutExpiredRecoveryPolicy.d.ts

@@ -0,0 +1,38 @@
+import type { CreateQuoteResponse } from "../../pricing/index.js";
+import type { CheckoutRecoveryOrderSnapshot } from "./checkoutRecoveryOrderPort.js";
+import type { CheckoutRecoveryTokenInspection } from "./checkoutRecoveryToken.js";
+type RecoveryQuoteSnapshot = CreateQuoteResponse & {
+    quote: {
+        context?: {
+            sizeConstraint?: unknown;
+            shippingTerms?: {
+                version: unknown;
+                currency: string;
+                flatMinor: number;
+                freeThresholdMinor: number | null;
+            };
+        };
+    };
+};
+export declare const EXPIRED_CHECKOUT_RECOVERY_WINDOW_MS: number;
+export type ExpiredRecoveryEligibility = {
+    kind: "eligible";
+} | {
+    kind: "paid";
+} | {
+    kind: "cancelled";
+} | {
+    kind: "unavailable";
+};
+export declare function createExpiredCheckoutRecoveryPolicy<Order extends CheckoutRecoveryOrderSnapshot<unknown, unknown>>(bindings: {
+    admitsSubscriptionSubject(order: Order): boolean;
+}): {
+    classifyExpiredRecovery: (input: {
+        inspection: CheckoutRecoveryTokenInspection | null;
+        order: Order | null;
+        now: Date;
+    }) => ExpiredRecoveryEligibility;
+    classifyOrderRecoveryEligibility: (order: Order | null, now: Date) => ExpiredRecoveryEligibility;
+};
+export declare function quotesMatchForRecovery(frozen: RecoveryQuoteSnapshot, fresh: RecoveryQuoteSnapshot): boolean;
+export {};

package/dist/commerce/server/checkoutExpiredRecoveryPolicy.js

@@ -0,0 +1,85 @@
+export const EXPIRED_CHECKOUT_RECOVERY_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
+export function createExpiredCheckoutRecoveryPolicy(bindings) {
+    function classifyExpiredRecovery(input) {
+        const { inspection, order, now } = input;
+        if (!inspection || !order || inspection.clientId !== order.clientId)
+            return { kind: "unavailable" };
+        if (order.status === "paid")
+            return { kind: "paid" };
+        if (inspection.tokenState === "revoked" || inspection.tokenState === "used") {
+            return { kind: "unavailable" };
+        }
+        return classifyOrderRecoveryEligibility(order, now);
+    }
+    /**
+     * The ORDER half of the same decision, without a token in hand.
+     *
+     * `classifyExpiredRecovery` answers "may this bearer redeem?"; two of its checks
+     * (the token exists, belongs to this order's client, and is neither revoked nor
+     * used) are about the bearer and the rest are about the order. Only the second
+     * half can be asked BEFORE a token exists, which is exactly the question the
+     * operator's mint asks, so it lives here as one function both callers share.
+     *
+     * ⛔ Do not fork it. Mint-side eligibility drifting from redeem-side eligibility
+     * is how support hands a customer a link that the redeem rail then refuses — a
+     * dead link is worse than no button at all.
+     */
+    function classifyOrderRecoveryEligibility(order, now) {
+        if (!order)
+            return { kind: "unavailable" };
+        if (order.status === "paid")
+            return { kind: "paid" };
+        const createdAt = Date.parse(order.createdAt);
+        if (!Number.isFinite(createdAt) || now.getTime() - createdAt > EXPIRED_CHECKOUT_RECOVERY_WINDOW_MS) {
+            return { kind: "unavailable" };
+        }
+        if (order.status === "cancelled" && !order.technicallyExpired)
+            return { kind: "cancelled" };
+        // Recreation is only safe after a canonical expiry transition has also
+        // released the source reservation. `pending_payment` plus expired-looking
+        // metadata is an inconsistent/legacy state: keep the technical-expiry fence
+        // that prevents retrying its stale intent, but never create a second hold.
+        if (order.status !== "expired" && order.status !== "cancelled")
+            return { kind: "unavailable" };
+        if (!order.technicallyExpired)
+            return { kind: "unavailable" };
+        if (!order.quoteSnapshot || !order.shippingAddressId)
+            return { kind: "unavailable" };
+        if (order.mode === "subscription_cycle" && (!order.subscriptionId || !order.subscriptionCycleId || !bindings.admitsSubscriptionSubject(order))) {
+            return { kind: "unavailable" };
+        }
+        return { kind: "eligible" };
+    }
+    return { classifyExpiredRecovery, classifyOrderRecoveryEligibility };
+}
+export function quotesMatchForRecovery(frozen, fresh) {
+    return JSON.stringify(commercialFingerprint(frozen)) === JSON.stringify(commercialFingerprint(fresh));
+}
+function commercialFingerprint(snapshot) {
+    const quote = snapshot.quote;
+    const terms = quote.context?.shippingTerms;
+    return {
+        currency: quote.currency,
+        lines: quote.lines.map((line) => ({
+            sku: line.sku,
+            productSlug: line.productSlug,
+            quantity: line.quantity,
+            unitPriceGross: line.unitPriceGross,
+            lineSubtotalGross: line.lineSubtotalGross,
+            tax: line.tax,
+        })),
+        discounts: quote.discounts,
+        subtotalGross: quote.subtotalGross,
+        discountTotalGross: quote.discountTotalGross,
+        shippingGross: quote.shippingGross ?? null,
+        shippingDiscountGross: quote.shippingDiscountGross ?? null,
+        shippingTerms: terms ? { version: terms.version, currency: terms.currency,
+            flatMinor: terms.flatMinor, freeThresholdMinor: terms.freeThresholdMinor } : null,
+        totalGross: quote.totalGross,
+        netTotal: quote.netTotal,
+        taxTotal: quote.taxTotal,
+        mode: quote.context?.mode ?? null,
+        cadenceDays: quote.context?.cadenceDays ?? null,
+        sizeConstraint: quote.context?.sizeConstraint ?? null,
+    };
+}

package/dist/commerce/server/checkoutInvoiceBuyerSnapshot.d.ts

@@ -0,0 +1,22 @@
+import type { z } from "zod";
+export declare function buildCheckoutInvoiceBuyerSnapshot<Buyer>(intent: {
+    contact: {
+        firstName: string;
+        lastName: string;
+        email: string;
+    };
+    address: {
+        street: string;
+        city: string;
+        postalCode: string;
+        country: string;
+    };
+}, invoicePreference: {
+    kind: "b2c_named";
+} | {
+    kind: "b2b_vat";
+    companyName: string;
+    email?: string;
+    taxId?: string;
+    address: object;
+}, schema: z.ZodType<Buyer>): Buyer;

package/dist/commerce/server/checkoutInvoiceBuyerSnapshot.js

@@ -0,0 +1,30 @@
+export function buildCheckoutInvoiceBuyerSnapshot(intent, invoicePreference, schema) {
+    if (invoicePreference.kind === "b2b_vat") {
+        return schema.parse({
+            name: invoicePreference.companyName,
+            email: invoicePreference.email ?? intent.contact.email,
+            taxId: invoicePreference.taxId,
+            companyName: invoicePreference.companyName,
+            source: "checkout_invoice_preference",
+            address: {
+                ...invoicePreference.address,
+                source: "checkout_invoice_billing_address",
+            },
+        });
+    }
+    return schema.parse({
+        name: `${intent.contact.firstName} ${intent.contact.lastName}`.trim(),
+        email: intent.contact.email,
+        taxId: null,
+        companyName: null,
+        source: "checkout_invoice_preference",
+        address: {
+            line1: intent.address.street,
+            line2: null,
+            city: intent.address.city,
+            postalCode: intent.address.postalCode,
+            country: intent.address.country,
+            source: "checkout_shipping_address",
+        },
+    });
+}

package/dist/commerce/server/checkoutOfferPolicyPort.d.ts

@@ -0,0 +1,33 @@
+import type { CheckoutKind, CheckoutOfferPolicyPort } from "../contracts/index.js";
+export type { CheckoutOfferPolicyPort } from "../contracts/index.js";
+/** The refusal of an intent that carries an offer field when no adopter port is wired. */
+export declare const CHECKOUT_OFFER_VERSION_UNSUPPORTED = "offer_version_unsupported";
+export declare class CheckoutOfferRefusedError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+export type CheckoutOfferBinding<Intent, Quote> = {
+    port: CheckoutOfferPolicyPort<Intent, Quote>;
+    offerVersion: string;
+};
+/**
+ * Null, without a port call, for an intent that carries neither `offerVersion`
+ * nor `minimumUnits`. Otherwise the adopter's port must bind the offer: without
+ * a port the intent is refused with `offer_version_unsupported`, and a port
+ * refusal keeps its own reason. Both throw `CheckoutOfferRefusedError`.
+ */
+export declare function resolveCheckoutOffer<Intent extends {
+    offerVersion?: string;
+    minimumUnits?: number;
+}, Quote>(port: CheckoutOfferPolicyPort<Intent, Quote> | undefined, intent: Intent, checkoutKind: CheckoutKind): Promise<CheckoutOfferBinding<Intent, Quote> | null>;
+/**
+ * Writes a bound offer version and the adopter's evidence, checked against
+ * `commerceOfferEvidenceSchema`, into an accepted snapshot's context. Without a
+ * binding the same snapshot is returned; a bound snapshot without a context
+ * fails closed.
+ */
+export declare function withCheckoutOfferContext<Intent, Quote extends {
+    context?: object;
+}, Response extends {
+    quote: Quote;
+}>(binding: CheckoutOfferBinding<Intent, Quote> | null, intent: Intent, snapshot: Response): Promise<Response>;

package/dist/commerce/server/checkoutOfferPolicyPort.js

@@ -0,0 +1,49 @@
+import { commerceOfferEvidenceSchema } from "../offerEvidenceSchemas.js";
+/** The refusal of an intent that carries an offer field when no adopter port is wired. */
+export const CHECKOUT_OFFER_VERSION_UNSUPPORTED = "offer_version_unsupported";
+export class CheckoutOfferRefusedError extends Error {
+    reason;
+    constructor(reason) {
+        super(`checkout_offer_refused:${reason}`);
+        this.name = "CheckoutOfferRefusedError";
+        this.reason = reason;
+    }
+}
+/**
+ * Null, without a port call, for an intent that carries neither `offerVersion`
+ * nor `minimumUnits`. Otherwise the adopter's port must bind the offer: without
+ * a port the intent is refused with `offer_version_unsupported`, and a port
+ * refusal keeps its own reason. Both throw `CheckoutOfferRefusedError`.
+ */
+export async function resolveCheckoutOffer(port, intent, checkoutKind) {
+    if (intent.offerVersion === undefined && intent.minimumUnits === undefined)
+        return null;
+    if (!port)
+        throw new CheckoutOfferRefusedError(CHECKOUT_OFFER_VERSION_UNSUPPORTED);
+    const resolution = await port.resolve({ intent, checkoutKind });
+    if (resolution.kind === "refused")
+        throw new CheckoutOfferRefusedError(resolution.reason);
+    return { port, offerVersion: resolution.offerVersion };
+}
+/**
+ * Writes a bound offer version and the adopter's evidence, checked against
+ * `commerceOfferEvidenceSchema`, into an accepted snapshot's context. Without a
+ * binding the same snapshot is returned; a bound snapshot without a context
+ * fails closed.
+ */
+export async function withCheckoutOfferContext(binding, intent, snapshot) {
+    if (!binding)
+        return snapshot;
+    const context = snapshot.quote.context;
+    if (!context)
+        throw new Error("checkout_offer_context_missing");
+    const offerEvidence = commerceOfferEvidenceSchema.parse(await binding.port.evidence({
+        intent,
+        offerVersion: binding.offerVersion,
+        quote: snapshot.quote,
+    }));
+    return {
+        ...snapshot,
+        quote: { ...snapshot.quote, context: { ...context, offerVersion: binding.offerVersion, offerEvidence } },
+    };
+}

package/dist/commerce/server/checkoutPaymentContinuationCredential.d.ts

@@ -0,0 +1,58 @@
+export type CheckoutContinuationAction = {
+    kind: string;
+    provider?: string;
+    clientSecret?: string;
+    url?: string;
+};
+declare const PURPOSE: "commerce.checkout-payment-continuation.v1";
+export interface CheckoutPaymentContinuationInput<Rail extends string = string> {
+    journeyId: string;
+    orderId: string;
+    clientId: string;
+    paymentIntentId: string;
+    paymentAttemptId: string;
+    executionRail: Rail;
+}
+export interface CheckoutPaymentContinuationClaims<Rail extends string = string> extends CheckoutPaymentContinuationInput<Rail> {
+    version: 1;
+    purpose: typeof PURPOSE;
+    expiresAt: number;
+}
+export interface CheckoutPaymentContinuationCodec<Rail extends string = string> {
+    issue(input: CheckoutPaymentContinuationInput<Rail>): {
+        claims: CheckoutPaymentContinuationClaims<Rail>;
+        setCookie: string;
+    };
+    verifyCookieHeader(cookieHeader: unknown): CheckoutPaymentContinuationClaims<Rail> | null;
+}
+export type CheckoutPaymentContinuationMinter<Rail extends string = string> = (res: CheckoutCookieResponse, input: CheckoutPaymentContinuationInput<Rail>) => void;
+export interface CheckoutCookieResponse {
+    getHeader?(name: string): string | number | string[] | undefined;
+    setHeader(name: string, value: number | string | readonly string[]): unknown;
+}
+export declare function mintPaymentContinuationOnFreshAction<Rail extends string>(input: {
+    mint?: CheckoutPaymentContinuationMinter<Rail>;
+    res: CheckoutCookieResponse;
+    journeyId: string;
+    clientId: string;
+    requestRail: string;
+    response: {
+        status: string;
+        clientAction?: CheckoutContinuationAction;
+    };
+    result: {
+        continuationActionOrigin: "fresh_execution" | null;
+        executionRail: string;
+        paymentAttemptId: string | null;
+        paymentIntentId: string;
+        orderId: string;
+    };
+}, executionRails: readonly [Rail, Rail]): void;
+export declare function createCheckoutPaymentContinuationCodec<Rail extends string>(rootSecret: string | undefined, options: {
+    cookieName: string;
+    executionRails: readonly [Rail, Rail];
+    now?: () => Date;
+    ttlSeconds?: number;
+}): CheckoutPaymentContinuationCodec<Rail> | null;
+export declare function isCheckoutContinuationRail<Rail extends string>(value: unknown, executionRails: readonly Rail[]): value is Rail;
+export {};

package/dist/commerce/server/checkoutPaymentContinuationCredential.js

@@ -0,0 +1,154 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { CHECKOUT_PAYMENT_CONTINUATION_TTL_SECONDS } from "../paymentContinuation.js";
+const PURPOSE = "commerce.checkout-payment-continuation.v1";
+const DEFAULT_TTL_SECONDS = CHECKOUT_PAYMENT_CONTINUATION_TTL_SECONDS;
+const MIN_TTL_SECONDS = 60;
+const MAX_TTL_SECONDS = CHECKOUT_PAYMENT_CONTINUATION_TTL_SECONDS;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const JOURNEY_PATTERN = /^checkout:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export function mintPaymentContinuationOnFreshAction(input, executionRails) {
+    const { result, response } = input;
+    if (result.continuationActionOrigin !== "fresh_execution"
+        || !result.paymentAttemptId
+        || !isCheckoutContinuationRail(result.executionRail, executionRails)
+        || result.executionRail !== input.requestRail
+        || response.status === "price_changed"
+        || !responseWantsContinuation(response, result.executionRail, executionRails))
+        return;
+    // Split out from the guard above ON PURPOSE. Every condition there says "this
+    // attempt does not want a continuation"; this one says "it wants one and we
+    // cannot issue it", which is an operator problem and used to be
+    // indistinguishable from the first. That silence is how the capability stayed
+    // dormant in every environment without anyone noticing. Rail and reason only:
+    // no order, client, attempt or intent id is logged.
+    if (!input.mint) {
+        console.warn("checkout_payment_continuation_unavailable", JSON.stringify({ executionRail: result.executionRail, reason: "no_signing_secret" }));
+        return;
+    }
+    try {
+        input.mint(input.res, {
+            journeyId: input.journeyId,
+            orderId: result.orderId,
+            clientId: input.clientId,
+            paymentIntentId: result.paymentIntentId,
+            paymentAttemptId: result.paymentAttemptId,
+            executionRail: result.executionRail,
+        });
+    }
+    catch {
+        // Continuation is best-effort; checkout success must never depend on it.
+    }
+}
+export function createCheckoutPaymentContinuationCodec(rootSecret, options) {
+    if (!rootSecret || Buffer.byteLength(rootSecret, "utf8") < 32)
+        return null;
+    const now = options.now ?? (() => new Date());
+    const ttlSeconds = options.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+    if (!Number.isInteger(ttlSeconds) || ttlSeconds < MIN_TTL_SECONDS || ttlSeconds > MAX_TTL_SECONDS) {
+        throw new Error(`Checkout payment continuation TTL must be between ${MIN_TTL_SECONDS} and ${MAX_TTL_SECONDS} seconds`);
+    }
+    const signingKey = createHmac("sha256", rootSecret).update(PURPOSE).digest();
+    function sign(payload) {
+        return createHmac("sha256", signingKey).update(payload).digest("base64url");
+    }
+    return {
+        issue(input) {
+            if (!isValidInput(input, options.executionRails))
+                throw new Error("Invalid checkout payment continuation input");
+            const claims = {
+                version: 1,
+                purpose: PURPOSE,
+                expiresAt: Math.floor(now().getTime() / 1000) + ttlSeconds,
+                ...input,
+            };
+            const payload = Buffer.from(JSON.stringify(claims), "utf8").toString("base64url");
+            const token = `${payload}.${sign(payload)}`;
+            return {
+                claims,
+                setCookie: `${options.cookieName}=${token}; Path=/; Max-Age=${ttlSeconds}; Secure; HttpOnly; SameSite=Strict`,
+            };
+        },
+        verifyCookieHeader(cookieHeader) {
+            const token = readCookie(cookieHeader, options.cookieName);
+            if (!token)
+                return null;
+            const separator = token.indexOf(".");
+            if (separator <= 0 || separator === token.length - 1 || token.indexOf(".", separator + 1) !== -1)
+                return null;
+            const payload = token.slice(0, separator);
+            const suppliedSignature = token.slice(separator + 1);
+            const expectedSignature = sign(payload);
+            const supplied = Buffer.from(suppliedSignature, "utf8");
+            const expected = Buffer.from(expectedSignature, "utf8");
+            if (supplied.length !== expected.length || !timingSafeEqual(supplied, expected))
+                return null;
+            try {
+                const parsed = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+                if (!isValidClaims(parsed, options.executionRails))
+                    return null;
+                if (parsed.expiresAt <= Math.floor(now().getTime() / 1000))
+                    return null;
+                return parsed;
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+function isValidInput(value, executionRails) {
+    if (!isRecord(value))
+        return false;
+    return JOURNEY_PATTERN.test(readString(value, "journeyId"))
+        && UUID_PATTERN.test(readString(value, "orderId"))
+        && UUID_PATTERN.test(readString(value, "clientId"))
+        && UUID_PATTERN.test(readString(value, "paymentIntentId"))
+        && UUID_PATTERN.test(readString(value, "paymentAttemptId"))
+        && isCheckoutContinuationRail(value.executionRail, executionRails);
+}
+function isValidClaims(value, executionRails) {
+    if (!isRecord(value))
+        return false;
+    const keys = Object.keys(value).sort();
+    const expectedKeys = [
+        "clientId", "expiresAt", "journeyId", "orderId", "paymentAttemptId",
+        "executionRail", "paymentIntentId", "purpose", "version",
+    ].sort();
+    return keys.length === expectedKeys.length
+        && keys.every((key, index) => key === expectedKeys[index])
+        && value.version === 1
+        && value.purpose === PURPOSE
+        && Number.isInteger(value.expiresAt)
+        && isValidInput(value, executionRails);
+}
+function readCookie(header, name) {
+    const raw = Array.isArray(header) ? header[0] : header;
+    if (typeof raw !== "string")
+        return null;
+    for (const part of raw.split(";")) {
+        const trimmed = part.trim();
+        const separator = trimmed.indexOf("=");
+        if (separator > 0 && trimmed.slice(0, separator) === name) {
+            return trimmed.slice(separator + 1) || null;
+        }
+    }
+    return null;
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function readString(value, key) {
+    return typeof value[key] === "string" ? value[key] : "";
+}
+function responseWantsContinuation(response, rail, executionRails) {
+    return actionMatchesExecutionRail(response.clientAction, rail, executionRails)
+        || (response.clientAction?.kind === "none" && response.status === "processing");
+}
+function actionMatchesExecutionRail(action, rail, executionRails) {
+    return rail === executionRails[0]
+        ? action?.kind === "provider_embedded" && action.provider === executionRails[0]
+        : action?.kind === "redirect";
+}
+export function isCheckoutContinuationRail(value, executionRails) {
+    return typeof value === "string" && executionRails.includes(value);
+}

package/dist/commerce/server/checkoutQuoteTypes.d.ts

@@ -0,0 +1,19 @@
+import type { AcquisitionTermsExpectation, ResolvedAcquisitionTerms, CreateQuoteResponse, CommerceQuoteContext, PricingPolicySnapshot } from "../../pricing/index.js";
+export interface CheckoutQuoteSnapshot extends CreateQuoteResponse {
+    quote: CreateQuoteResponse["quote"] & {
+        context?: CommerceQuoteContext & {
+            pricingPolicy?: PricingPolicySnapshot;
+            acquisitionTerms?: ResolvedAcquisitionTerms;
+            shippingTerms?: unknown;
+            offerVersion?: string;
+        };
+    };
+}
+export interface ExpectedCheckoutQuote {
+    totalGross: {
+        amountMinor: number;
+        currency: string;
+    };
+    pricingPolicy?: PricingPolicySnapshot;
+    acquisitionTerms?: AcquisitionTermsExpectation;
+}

package/dist/commerce/server/checkoutQuoteTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/commerce/server/checkoutRecoveryOrderPort.d.ts

@@ -0,0 +1,42 @@
+export interface CheckoutRecoveryPriorPaymentEvidence {
+    paymentIntentId: string;
+    paymentAttemptId: string;
+    provider: string;
+    providerPaymentId: string | null;
+    idempotencyKey: string;
+    retryRequestId: string | null;
+}
+export type CheckoutRecoveryOrderSnapshot<Quote, PaymentStatus, Host extends object = object> = Host & {
+    orderId: string;
+    orderRef: string;
+    orderNumber: string;
+    clientId: string;
+    status: string;
+    mode: "subscription_cycle" | "one_time_order";
+    totalMinor: number;
+    currency: string;
+    cadenceDays: number | null;
+    createdAt: string;
+    customerEmail: string | null;
+    customerName: string | null;
+    paymentIntentId: string | null;
+    paymentIntentStatus: PaymentStatus | null;
+    subscriptionId: string | null;
+    subscriptionCycleId: string | null;
+    shippingAddressId?: string | null;
+    quoteSnapshot?: Quote | null;
+    runtimeMetadata?: Record<string, unknown>;
+    invoiceBuyerSnapshot?: Record<string, unknown>;
+    recoveryRootOrderId?: string;
+    recreatedFromOrderId?: string | null;
+    technicallyExpired?: boolean;
+    priorPaymentEvidence?: CheckoutRecoveryPriorPaymentEvidence | null;
+};
+export interface CheckoutRecoveryOrderReadPort<Order> {
+    getRecoveryOrder(input: {
+        orderId: string;
+    }): Promise<Order | null>;
+    getLatestRecoveryOrder?(input: {
+        orderId: string;
+    }): Promise<Order | null>;
+}

package/dist/commerce/server/checkoutRecoveryOrderPort.js

@@ -0,0 +1 @@
+export {};

package/dist/commerce/server/checkoutRecoveryToken.d.ts

@@ -0,0 +1,40 @@
+export interface CheckoutRecoveryTokenContext {
+    tokenId: string;
+    orderId: string;
+    clientId: string;
+    /** "subscription_cycle" | "one_time_order" — drives copy + post-pay activation. */
+    mode: string;
+    status: string;
+}
+export interface CheckoutRecoveryTokenInspection {
+    tokenId: string;
+    orderId: string;
+    clientId: string;
+    /** Null when the token exists but the order row is already gone. */
+    mode: string | null;
+    status: string | null;
+    subscriptionId: string | null;
+    tokenState: string;
+}
+/** Inspection RPC states; only the named continuation states may resume pending orders. */
+export declare function classifyCheckoutRecoveryTokenState(tokenState: string): "continuation" | "expired_policy" | "refused";
+export interface CheckoutRecoveryTokenPort {
+    /** Issue a token for an unpaid order. Returns the new token row id. */
+    issue(input: {
+        orderId: string;
+        rawToken: string;
+        expiresAt: string;
+    }): Promise<string>;
+    /** Validate a raw token; returns the order context, or null if invalid/expired/not recoverable. */
+    validate(rawToken: string, now?: Date): Promise<CheckoutRecoveryTokenContext | null>;
+    /**
+     * Inspect without granting continuation; callers must check state before reconstructing authority.
+     */
+    inspect(rawToken: string, now?: Date): Promise<CheckoutRecoveryTokenInspection | null>;
+}
+/** Canonical hash: SHA-256 hex of the raw token (matches the SQL `encode(sha256(...))`). */
+export declare function hashCheckoutRecoveryToken(token: string): string;
+/** A non-hex prefix keeps quoted-printable mail transports from consuming the URL separator. */
+export declare const CHECKOUT_RECOVERY_TOKEN_PREFIX = "rcv_";
+/** A 256-bit URL-safe random token for the deep-link, with the QP-safe prefix. */
+export declare function generateCheckoutRecoveryToken(): string;

package/dist/commerce/server/checkoutRecoveryToken.js

@@ -0,0 +1,26 @@
+import { createHash, randomBytes } from "node:crypto";
+/** Inspection RPC states; only the named continuation states may resume pending orders. */
+export function classifyCheckoutRecoveryTokenState(tokenState) {
+    switch (tokenState) {
+        case "active":
+        case "order_not_recoverable":
+            return "continuation";
+        case "expired":
+            return "expired_policy";
+        case "revoked":
+        case "used":
+        case "order_not_found":
+        default:
+            return "refused";
+    }
+}
+/** Canonical hash: SHA-256 hex of the raw token (matches the SQL `encode(sha256(...))`). */
+export function hashCheckoutRecoveryToken(token) {
+    return createHash("sha256").update(token).digest("hex");
+}
+/** A non-hex prefix keeps quoted-printable mail transports from consuming the URL separator. */
+export const CHECKOUT_RECOVERY_TOKEN_PREFIX = "rcv_";
+/** A 256-bit URL-safe random token for the deep-link, with the QP-safe prefix. */
+export function generateCheckoutRecoveryToken() {
+    return CHECKOUT_RECOVERY_TOKEN_PREFIX + randomBytes(32).toString("base64url");
+}