@openlup/platform 0.26.0 → 0.28.0

package/dist/commerce/server/commerceCheckoutResume.js

@@ -0,0 +1,81 @@
+import { CHECKOUT_RESUME_CONTRACT_VERSION } from "../checkoutResumeSchemas.js";
+import { CommerceCheckoutResumePersistenceError } from "../errors.js";
+const SELECT_COLUMNS = "id, last_section_id, draft_state, expires_at, created_at, updated_at";
+export function createCommerceCheckoutResumeQueryPort(client, draftSchema) {
+    return {
+        async upsertDraft(input) {
+            const payload = {
+                token_hash: input.tokenHash,
+                idempotency_key_hash: input.idempotencyKeyHash,
+                last_section_id: input.lastSectionId,
+                draft_state: input.draftState,
+                redacted_fields: input.draftState.redactedFields,
+                expires_at: input.expiresAt,
+                revoked_at: null,
+                updated_at: input.now,
+            };
+            const { data: existing, error: existingError } = await client
+                .from("commerce_checkout_resume_drafts")
+                .select("id, expires_at, revoked_at")
+                .eq("token_hash", input.tokenHash)
+                .maybeSingle();
+            if (existingError)
+                throw mapError(existingError);
+            if (existing && !isActiveResumeRow(existing, input.now)) {
+                throw new CommerceCheckoutResumePersistenceError("Checkout resume draft token is expired or revoked", { boundary: "commerce_checkout_resume_drafts", reason: "expired_or_revoked" });
+            }
+            const query = existing
+                ? client
+                    .from("commerce_checkout_resume_drafts")
+                    .update(payload)
+                    .eq("token_hash", input.tokenHash)
+                    .is("revoked_at", null)
+                    .gt("expires_at", input.now)
+                : client.from("commerce_checkout_resume_drafts").insert(payload);
+            const { data, error } = await query.select(SELECT_COLUMNS).single();
+            if (error)
+                throw mapError(error);
+            return parseRow(data, false);
+        },
+        async readDraftByTokenHash(input) {
+            const { data, error } = await client
+                .from("commerce_checkout_resume_drafts")
+                .select(SELECT_COLUMNS)
+                .eq("token_hash", input.tokenHash)
+                .is("revoked_at", null)
+                .gt("expires_at", input.now)
+                .maybeSingle();
+            if (error)
+                throw mapError(error);
+            if (!data)
+                return null;
+            return parseRow(data, true);
+        },
+    };
+    function isActiveResumeRow(row, now) {
+        return !row.revoked_at && !!row.expires_at && row.expires_at > now;
+    }
+    function parseRow(row, replayed) {
+        const data = row;
+        const parsed = draftSchema.safeParse({
+            id: data.id,
+            contractVersion: CHECKOUT_RESUME_CONTRACT_VERSION,
+            lastSectionId: data.last_section_id,
+            draftState: data.draft_state,
+            expiresAt: data.expires_at,
+            createdAt: data.created_at,
+            updatedAt: data.updated_at,
+            replayed,
+        });
+        if (!parsed.success) {
+            throw new CommerceCheckoutResumePersistenceError("Checkout resume draft response invalid", { boundary: "commerce_checkout_resume_drafts" });
+        }
+        return parsed.data;
+    }
+}
+function mapError(error) {
+    return new CommerceCheckoutResumePersistenceError("Checkout resume draft persistence failed", {
+        code: error.code,
+        boundary: "commerce_checkout_resume_drafts",
+    });
+}

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

@@ -0,0 +1,54 @@
+import type { z } from "zod";
+import type { CheckoutKind, CommerceResumableOrderReadPort, ResumableOrderSnapshot } from "../contracts/index.js";
+export declare function subscriptionResponse(intent: {
+    cadenceDays: number | null;
+}, checkoutKind: CheckoutKind): {
+    requested: boolean;
+    cadenceDays: null;
+    activationStatus: "not_applicable";
+} | {
+    requested: boolean;
+    cadenceDays: number | null;
+    activationStatus: "pending_payment_success";
+};
+export interface CheckoutResumeGuardDeps {
+    resumableOrderPort?: CommerceResumableOrderReadPort;
+    resumeWindowMinutes?: number;
+}
+export declare function selectedDeliveryMatches(orderMetadata: Record<string, unknown> | null | undefined, intent: {
+    selectedDelivery?: unknown;
+}): boolean;
+export interface QuoteLikeSnapshot {
+    currency: string;
+    totalGross: {
+        amountMinor: number;
+        currency: string;
+    };
+    lines: ReadonlyArray<{
+        sku: string;
+        quantity: number;
+    }>;
+}
+export declare function createCheckoutResumeGuard<Intent extends {
+    idempotencyKey: string;
+    cadenceDays: number | null;
+    selectedDelivery?: unknown;
+}, Response>(bindings: {
+    responseSchema: z.ZodType<Response>;
+    statusUrl(orderId: string, paymentIntentId: string, clientId: string): string;
+}): {
+    resolveResumeOpenOrderResponse: (input: {
+        deps: CheckoutResumeGuardDeps;
+        clientId: string;
+        checkoutKind: CheckoutKind;
+        intent: Intent;
+        acceptedQuote?: QuoteLikeSnapshot;
+        now: () => Date;
+    }) => Promise<Response | null>;
+    buildSavedOrderResumeResponse: (input: {
+        resumable: ResumableOrderSnapshot;
+        clientId: string;
+        checkoutKind: CheckoutKind;
+        intent: Intent;
+    }) => Response;
+};

package/dist/commerce/server/commerceCheckoutResumeGuard.js

@@ -0,0 +1,138 @@
+import { resolveDeliverySelectionEvidence } from "../../shipping/index.js";
+import { CHECKOUT_CONTRACT_VERSION } from "../checkoutSchemas.js";
+import { safeCommerceDiagnosticValue } from "./commerceDiagnostics.js";
+export function subscriptionResponse(intent, checkoutKind) {
+    return checkoutKind === "one_time" ? { requested: false, cadenceDays: null, activationStatus: "not_applicable" }
+        : { requested: true, cadenceDays: intent.cadenceDays, activationStatus: "pending_payment_success" };
+}
+const DEFAULT_RESUME_WINDOW_MINUTES = 60;
+export function selectedDeliveryMatches(orderMetadata, intent) {
+    const existing = resolveDeliverySelectionEvidence({ orderMetadata }).selection;
+    const fresh = resolveDeliverySelectionEvidence({
+        orderMetadata: { selectedDelivery: intent.selectedDelivery },
+    }).selection;
+    if (!existing || !fresh)
+        return false;
+    return deliveryKey(existing) === deliveryKey(fresh);
+}
+function deliveryKey(selection) {
+    const pickupPoint = selection.pickupPoint && typeof selection.pickupPoint === "object"
+        ? selection.pickupPoint
+        : {};
+    return [
+        text(selection.providerKind),
+        text(selection.carrierKind),
+        text(selection.carrierCode),
+        text(selection.serviceCode ?? selection.service),
+        text(selection.deliveryKind ?? selection.kind),
+        text(pickupPoint.id ?? pickupPoint.pointId),
+    ].join("|");
+}
+function text(value) {
+    return typeof value === "string" ? value.trim().toLowerCase() : "";
+}
+function quoteMatches(orderMetadata, accepted) {
+    const stored = readStoredQuote(orderMetadata);
+    if (!stored)
+        return false;
+    return stored.currency === accepted.currency
+        && stored.totalGross.currency === accepted.totalGross.currency
+        && stored.totalGross.amountMinor === accepted.totalGross.amountMinor
+        && lineKey(stored.lines) === lineKey(accepted.lines);
+}
+function readStoredQuote(orderMetadata) {
+    // The producer stores the whole envelope, so the quote sits one level down.
+    const snapshot = orderMetadata?.quoteSnapshot;
+    const quote = isRecord(snapshot) ? snapshot.quote : undefined;
+    if (!isRecord(quote))
+        return null;
+    const total = quote.totalGross;
+    const lines = quote.lines;
+    if (typeof quote.currency !== "string" || !isRecord(total) || !Array.isArray(lines))
+        return null;
+    if (typeof total.amountMinor !== "number" || typeof total.currency !== "string")
+        return null;
+    const parsed = [];
+    for (const line of lines) {
+        if (!isRecord(line) || typeof line.sku !== "string" || typeof line.quantity !== "number") {
+            return null;
+        }
+        parsed.push({ sku: line.sku, quantity: line.quantity });
+    }
+    return {
+        currency: quote.currency,
+        totalGross: { amountMinor: total.amountMinor, currency: total.currency },
+        lines: parsed,
+    };
+}
+function lineKey(lines) {
+    return lines.map((line) => `${line.sku}x${line.quantity}`).sort().join("|");
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+export function createCheckoutResumeGuard(bindings) {
+    function buildSavedOrderResumeResponse(input) {
+        const { resumable, clientId, checkoutKind, intent } = input;
+        return bindings.responseSchema.parse({
+            contractVersion: CHECKOUT_CONTRACT_VERSION,
+            checkoutKind,
+            orderRef: `order_${resumable.orderId}`,
+            orderId: resumable.orderId,
+            status: resumable.status,
+            paymentIntentId: resumable.paymentIntentId,
+            clientId,
+            clientAction: { kind: "none" },
+            statusUrl: bindings.statusUrl(resumable.orderId, resumable.paymentIntentId, clientId),
+            subscription: subscriptionResponse(intent, checkoutKind),
+            payment: { requiresReusablePaymentMethod: checkoutKind === "subscription_initial" },
+        });
+    }
+    async function resolveResumeOpenOrderResponse(input) {
+        const { deps, clientId, checkoutKind, intent, acceptedQuote, now } = input;
+        if (!deps.resumableOrderPort)
+            return null;
+        try {
+            const resumable = await deps.resumableOrderPort.findResumableOrderForClient({
+                clientId,
+                withinMinutes: deps.resumeWindowMinutes ?? DEFAULT_RESUME_WINDOW_MINUTES,
+                now: now(),
+                journeyKey: intent.idempotencyKey,
+            });
+            if (!resumable)
+                return null;
+            if (acceptedQuote && resumable.sameJourney) {
+                // The buyer edited their cart; they did not come back on another device.
+                // Answering with this order would re-offer the OLD total. Falling through
+                // hands the case to `commerce_supersede_pre_payment_order_draft`, which
+                // cancels the unpaid order plus its intent, attempt and PROVISIONAL
+                // subscription and re-drafts at the new price — and which refuses outright
+                // once money has moved, at which point this guard legitimately owns it.
+                console.info("checkout_resume_skipped_same_journey", JSON.stringify({ orderId: resumable.orderId, status: resumable.status }));
+                return null;
+            }
+            if (!selectedDeliveryMatches(resumable.metadata, intent)) {
+                console.info("checkout_resume_skipped_delivery_mismatch", JSON.stringify({ orderId: resumable.orderId, status: resumable.status }));
+                return null;
+            }
+            if (acceptedQuote && !quoteMatches(resumable.metadata, acceptedQuote)) {
+                // Second, independent barrier. A different journey can still hold a
+                // different basket — same buyer, two tabs, two configurations — and money
+                // is what the buyer is about to authorize, so it must be the money they
+                // were just shown.
+                console.info("checkout_resume_skipped_quote_mismatch", JSON.stringify({ orderId: resumable.orderId, status: resumable.status }));
+                return null;
+            }
+            const response = buildSavedOrderResumeResponse({ resumable, clientId, checkoutKind, intent });
+            console.info("checkout_resumed_open_order", JSON.stringify({ orderId: resumable.orderId, status: resumable.status }));
+            return response;
+        }
+        catch (error) {
+            console.warn("checkout_resume_lookup_failed", JSON.stringify({
+                message: safeCommerceDiagnosticValue(error instanceof Error ? error.message : String(error)),
+            }));
+            return null;
+        }
+    }
+    return { resolveResumeOpenOrderResponse, buildSavedOrderResumeResponse };
+}

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

@@ -0,0 +1,39 @@
+import type { HttpRequest } from "../../http/index.js";
+interface CheckoutSavedPaymentMethodResolverPort<Flow extends string, MethodKind extends string = string, RecurringModel extends string = string> {
+    resolveSavedPaymentMethod(input: {
+        accessToken: string;
+        clientId: string;
+        savedMethodId: string;
+        requestedFlow: Flow;
+        now: Date;
+    }): Promise<{
+        providerMethodRef: string;
+        providerAliasType: MethodKind;
+        recurringModel?: RecurringModel;
+    } | null>;
+}
+export type ResolveSavedMethodResult<MethodKind extends string = string, RecurringModel extends string = string> = {
+    kind: "none";
+} | {
+    kind: "resolved";
+    paymentMethodRef: string;
+    paymentMethodAliasType: MethodKind;
+    paymentMethodRecurringModel?: RecurringModel;
+} | {
+    kind: "rejected";
+    reason: "saved_payment_method_resolver_unavailable" | "saved_payment_method_session_required" | "saved_payment_method_unavailable" | "saved_payment_method_read_failed";
+};
+export declare function createCheckoutSavedPaymentMethodResolver<Execution, Flow extends string, MethodKind extends string = string, RecurringModel extends string = string>(requestForExecution: (execution: Execution | undefined) => {
+    flow: Flow;
+    savedMethodId: string;
+} | null): {
+    resolveSavedPaymentMethodForCheckout: ({ req, paymentExecution, clientId, savedPaymentMethodResolverPort, now, recordStage, }: {
+        req: HttpRequest;
+        paymentExecution: Execution | undefined;
+        clientId: string;
+        savedPaymentMethodResolverPort?: CheckoutSavedPaymentMethodResolverPort<Flow, MethodKind, RecurringModel>;
+        now: () => Date;
+        recordStage: <T>(stage: "payment_method_ref", operation: () => Promise<T>) => Promise<T>;
+    }) => Promise<ResolveSavedMethodResult<MethodKind, RecurringModel>>;
+};
+export {};

package/dist/commerce/server/commerceCheckoutSavedPaymentMethod.js

@@ -0,0 +1,44 @@
+export function createCheckoutSavedPaymentMethodResolver(requestForExecution) {
+    async function resolveSavedPaymentMethodForCheckout({ req, paymentExecution, clientId, savedPaymentMethodResolverPort, now, recordStage, }) {
+        const savedPaymentMethodRequest = requestForExecution(paymentExecution);
+        if (!savedPaymentMethodRequest)
+            return { kind: "none" };
+        if (!savedPaymentMethodResolverPort) {
+            return { kind: "rejected", reason: "saved_payment_method_resolver_unavailable" };
+        }
+        const accessToken = readBearerToken(req);
+        if (!accessToken) {
+            return { kind: "rejected", reason: "saved_payment_method_session_required" };
+        }
+        try {
+            const resolved = await recordStage("payment_method_ref", () => savedPaymentMethodResolverPort.resolveSavedPaymentMethod({
+                accessToken,
+                clientId,
+                savedMethodId: savedPaymentMethodRequest.savedMethodId,
+                requestedFlow: savedPaymentMethodRequest.flow,
+                now: now(),
+            }));
+            if (!resolved) {
+                return { kind: "rejected", reason: "saved_payment_method_unavailable" };
+            }
+            return {
+                kind: "resolved",
+                paymentMethodRef: resolved.providerMethodRef,
+                paymentMethodAliasType: resolved.providerAliasType,
+                ...(resolved.recurringModel
+                    ? { paymentMethodRecurringModel: resolved.recurringModel }
+                    : {}),
+            };
+        }
+        catch {
+            return { kind: "rejected", reason: "saved_payment_method_read_failed" };
+        }
+    }
+    function readBearerToken(req) {
+        const raw = req.headers.authorization;
+        const value = Array.isArray(raw) ? raw[0] : raw;
+        const match = value?.match(/^Bearer\s+(.+)$/i);
+        return match?.[1]?.trim() || null;
+    }
+    return { resolveSavedPaymentMethodForCheckout };
+}

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

@@ -0,0 +1,7 @@
+import { CheckoutOrchestrationError } from "./commerceCheckoutOrchestrationError.js";
+export declare function createCheckoutStartRuntimeFailure(bindings: {
+    checkoutProviderAttemptFailure(error: unknown): CheckoutOrchestrationError | null;
+    prepareConflictReason: string;
+}): {
+    mapStartRuntimeFailure: (error: unknown, draftOrderId: string) => CheckoutOrchestrationError;
+};

package/dist/commerce/server/commerceCheckoutStartRuntimeFailure.js

@@ -0,0 +1,39 @@
+import { CommerceRuntimeConflictError } from "../runtimeErrors.js";
+import { isInventoryAdmissionBusy } from "./checkoutConflictClassifiers.js";
+import { messageOf } from "../checkoutHelpers.js";
+import { CheckoutOrchestrationError } from "./commerceCheckoutOrchestrationError.js";
+export function createCheckoutStartRuntimeFailure(bindings) {
+    function mapStartRuntimeFailure(error, draftOrderId) {
+        const providerAttemptFailure = bindings.checkoutProviderAttemptFailure(error);
+        if (providerAttemptFailure) {
+            // `executePreparedProviderAttempt` writes the payment-control attempt
+            // before it calls the PSP. Once that dispatch throws, the PSP may still
+            // have accepted the charge. Keep the finalized order, reservation and
+            // provisional subscription intact until reconciliation establishes the
+            // terminal result; a compensating release here could both oversell stock
+            // and permit a second charge for the same journey.
+            return providerAttemptFailure;
+        }
+        if (error instanceof CommerceRuntimeConflictError &&
+            error.details.reason === bindings.prepareConflictReason) {
+            // D8 refused a changed request before a second PSP call. Keep the existing
+            // prepared attempt and aggregate fenced until reconciliation resolves it.
+            return new CheckoutOrchestrationError("start_runtime: provider attempt remains in flight", null, "provider_attempt_in_flight");
+        }
+        if (error instanceof CommerceRuntimeConflictError && error.details.reason === "acquisition_terms_changed") {
+            return new CheckoutOrchestrationError("Acquisition terms changed", draftOrderId, "acquisition_terms_changed");
+        }
+        if (isInventoryAdmissionBusy(error)) {
+            return new CheckoutOrchestrationError("Inventory admission temporarily unavailable", null, "inventory_admission_busy");
+        }
+        if (error instanceof CommerceRuntimeConflictError &&
+            error.details.reason === "journey_consumed") {
+            // The journey key already finalized an order; the fresh draft minted for
+            // this submit is abandoned and needs compensation, and the client must
+            // rotate its key before retrying.
+            return new CheckoutOrchestrationError(messageOf(error, "start_runtime"), draftOrderId, "journey_consumed");
+        }
+        return new CheckoutOrchestrationError(messageOf(error, "start_runtime"), draftOrderId);
+    }
+    return { mapStartRuntimeFailure };
+}

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

@@ -0,0 +1,8 @@
+export type CheckoutStage = "quote" | "order_draft" | "start_runtime" | "account_link" | "apply_payment_result";
+export type CheckoutStageRecorder = <T>(stage: CheckoutStage, operation: () => Promise<T>) => Promise<T>;
+export type CheckoutTimingStage = CheckoutStage | "rate_limit" | "risk_blocklist" | "persist_intent" | "payment_method_ref" | "customer_defaults" | "total";
+export type CheckoutTimingOutcome = "success" | "error" | "rejected";
+export declare function createCheckoutTimingLogger(requestId: string, route: string): {
+    record: CheckoutStageRecorder & (<T>(stage: CheckoutTimingStage, operation: () => Promise<T>) => Promise<T>);
+    log: (stage: CheckoutTimingStage, outcome: CheckoutTimingOutcome) => void;
+};

package/dist/commerce/server/commerceCheckoutTiming.js

@@ -0,0 +1,31 @@
+export function createCheckoutTimingLogger(requestId, route) {
+    const totalStartedAt = Date.now();
+    const write = (stage, startedAt, outcome) => {
+        console.log(JSON.stringify({
+            level: "info",
+            event: "checkout_stage",
+            request_id: requestId,
+            route,
+            stage,
+            duration_ms: Math.max(0, Date.now() - startedAt),
+            outcome,
+        }));
+    };
+    return {
+        async record(stage, operation) {
+            const startedAt = Date.now();
+            try {
+                const result = await operation();
+                write(stage, startedAt, "success");
+                return result;
+            }
+            catch (error) {
+                write(stage, startedAt, "error");
+                throw error;
+            }
+        },
+        log(stage, outcome) {
+            write(stage, totalStartedAt, outcome);
+        },
+    };
+}

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

@@ -0,0 +1,6 @@
+export declare function safeCommerceDiagnosticValue(value: unknown): string | null;
+export declare function checkoutOrchestrationFailureDetails(reason: string | null, previewDiagnosticsEnabled?: boolean): {
+    feature: "checkout";
+    stage: "orchestrate_order";
+    diagnosticReason?: string;
+};

package/dist/commerce/server/commerceDiagnostics.js

@@ -0,0 +1,31 @@
+const MAX_DIAGNOSTIC_LENGTH = 240;
+const REDACTION_PATTERNS = [
+    [/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g, "[redacted-email]"],
+    [/\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9_]+\b/g, "[redacted-key]"],
+    [
+        /\b(client_secret|payment_secret|secret|token|authorization|password|pass|apikey|api_key)\s*[:=]\s*["']?[^"',\s}]+/gi,
+        "$1=[redacted]",
+    ],
+    [/\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi, "Bearer [redacted]"],
+    [/\b[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\b/gi, "[redacted-uuid]"],
+    [/\b(?:intent|checkout|order|payment|subscription|idempotency)[-_a-z0-9]*[:=][A-Za-z0-9._:-]{12,}/gi, "[redacted-id]"],
+    [/\+?\d[\d\s().-]{7,}\d/g, "[redacted-number]"],
+];
+export function safeCommerceDiagnosticValue(value) {
+    if (value === null || value === undefined)
+        return null;
+    let text = String(value);
+    for (const [pattern, replacement] of REDACTION_PATTERNS) {
+        text = text.replace(pattern, replacement);
+    }
+    return text.length > MAX_DIAGNOSTIC_LENGTH
+        ? `${text.slice(0, MAX_DIAGNOSTIC_LENGTH - 3)}...`
+        : text;
+}
+export function checkoutOrchestrationFailureDetails(reason, previewDiagnosticsEnabled = false) {
+    return {
+        feature: "checkout",
+        stage: "orchestrate_order",
+        ...(previewDiagnosticsEnabled && reason ? { diagnosticReason: reason } : {}),
+    };
+}

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

@@ -0,0 +1,7 @@
+import type { CommerceOmsHoldPort } from "../oms/omsPorts.js";
+import { type BaseDeps } from "./commerceOmsHandlers.js";
+import type { OmsHandlerRequest } from "./handlerSupport.js";
+export declare function createAdminCommerceOrderCancelHandler<Response>({ authorizeAdmin, omsPort, mutationsEnabled, respond, }: BaseDeps<Response> & {
+    omsPort: Pick<CommerceOmsHoldPort, "cancelOrder">;
+    mutationsEnabled: () => boolean;
+}): (req: OmsHandlerRequest, res: Response) => Promise<void>;

package/dist/commerce/server/commerceOmsCancelOrderHandler.js

@@ -0,0 +1,22 @@
+import { adminCommerceOrderCancelRequestSchema, adminCommerceOrderMarkRefundedResponseSchema, } from "../oms/omsContracts.js";
+import { authorize, parseOmsRequest, sendOmsMutationResponse } from "./commerceOmsHandlers.js";
+// This is deliberately not the fulfillment cancellation boundary. It only
+// terminalizes an unpaid commerce order; the SQL RPC owns the state-machine and
+// reservation-release side effect.
+export function createAdminCommerceOrderCancelHandler({ authorizeAdmin, omsPort, mutationsEnabled, respond, }) {
+    return async function handler(req, res) {
+        if (req.method !== "POST")
+            return respond.sendMethodNotAllowed(res, ["POST"]);
+        const auth = await authorize(req, res, authorizeAdmin, respond);
+        if (!auth)
+            return;
+        if (!mutationsEnabled()) {
+            respond.sendBffError(res, "FORBIDDEN", "Commerce OMS order cancellation is not enabled");
+            return;
+        }
+        const request = parseOmsRequest(res, respond, adminCommerceOrderCancelRequestSchema, req.body ?? {}, "Invalid admin commerce order cancellation request");
+        if (request === undefined)
+            return;
+        await sendOmsMutationResponse(res, respond, () => omsPort.cancelOrder({ ...request, actorUserId: auth.userId }), adminCommerceOrderMarkRefundedResponseSchema, "Admin commerce order cancellation returned invalid response", "Admin commerce order cancellation failed", (data) => data.status === "cancelled");
+    };
+}

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

@@ -0,0 +1,18 @@
+import type { OmsHandlerDeps, OmsHandlerRequest } from "./handlerSupport.js";
+/**
+ * The `?view=control_plane_v1` read handlers. Unlike the V0 handlers in
+ * `commerceOmsHandlers.ts`, these deliberately take NO `governance` dependency and
+ * do not run `applyOmsAgentCustomerReadGate`: `commerce.oms_control_plane.v1`
+ * carries no customer identity, so the gate would audit a `customer_read` of zero
+ * customers and mask a field the strict contract forbids — and the portable
+ * `node-postgres` branch of this same contract has neither an actor kind nor an
+ * audit client to run it with. The exemption holds only while the projection stays
+ * customer-free, a precondition pinned in `omsControlPlaneReadGovernance.test.ts`.
+ */
+import { type CommerceOmsControlPlanePort } from "../oms/omsControlPlane.js";
+type Deps<Response> = OmsHandlerDeps<Response> & {
+    port: CommerceOmsControlPlanePort;
+};
+export declare function createCommerceOmsControlPlaneListHandler<Response>({ authorizeAdmin, port, respond }: Deps<Response>): (req: OmsHandlerRequest, res: Response) => Promise<void>;
+export declare function createCommerceOmsControlPlaneDetailHandler<Response>({ authorizeAdmin, port, respond }: Deps<Response>): (req: OmsHandlerRequest, res: Response) => Promise<void>;
+export {};

package/dist/commerce/server/commerceOmsControlPlaneHandlers.js

@@ -0,0 +1,60 @@
+/**
+ * The `?view=control_plane_v1` read handlers. Unlike the V0 handlers in
+ * `commerceOmsHandlers.ts`, these deliberately take NO `governance` dependency and
+ * do not run `applyOmsAgentCustomerReadGate`: `commerce.oms_control_plane.v1`
+ * carries no customer identity, so the gate would audit a `customer_read` of zero
+ * customers and mask a field the strict contract forbids — and the portable
+ * `node-postgres` branch of this same contract has neither an actor kind nor an
+ * audit client to run it with. The exemption holds only while the projection stays
+ * customer-free, a precondition pinned in `omsControlPlaneReadGovernance.test.ts`.
+ */
+import { omsControlPlaneDetailRequestSchema, omsControlPlaneDetailResponseSchema, omsControlPlaneListRequestSchema, omsControlPlaneListResponseSchema, } from "../oms/omsControlPlane.js";
+export function createCommerceOmsControlPlaneListHandler({ authorizeAdmin, port, respond }) {
+    return async (req, res) => {
+        if (req.method !== "GET")
+            return respond.sendMethodNotAllowed(res, ["GET"]);
+        if (!await authorize(req, res, authorizeAdmin, respond))
+            return;
+        const request = omsControlPlaneListRequestSchema.safeParse(req.query ?? {});
+        if (!request.success) {
+            respond.sendBffError(res, "BAD_REQUEST", "Invalid OMS control-plane list request", { details: request.error.flatten() });
+            return;
+        }
+        try {
+            const result = omsControlPlaneListResponseSchema.parse(await port.listOrders(request.data));
+            respond.sendBffSuccess(res, result);
+        }
+        catch {
+            respond.sendBffError(res, "UPSTREAM_UNAVAILABLE", "OMS control-plane list is unavailable");
+        }
+    };
+}
+export function createCommerceOmsControlPlaneDetailHandler({ authorizeAdmin, port, respond }) {
+    return async (req, res) => {
+        if (req.method !== "GET")
+            return respond.sendMethodNotAllowed(res, ["GET"]);
+        if (!await authorize(req, res, authorizeAdmin, respond))
+            return;
+        const request = omsControlPlaneDetailRequestSchema.safeParse(req.query ?? {});
+        if (!request.success) {
+            respond.sendBffError(res, "BAD_REQUEST", "Invalid OMS control-plane detail request", { details: request.error.flatten() });
+            return;
+        }
+        try {
+            const result = await port.getOrderDetail(request.data);
+            if (!result)
+                return respond.sendBffError(res, "NOT_FOUND", "Commerce order not found");
+            respond.sendBffSuccess(res, omsControlPlaneDetailResponseSchema.parse(result));
+        }
+        catch {
+            respond.sendBffError(res, "UPSTREAM_UNAVAILABLE", "OMS control-plane detail is unavailable");
+        }
+    };
+}
+async function authorize(req, res, authorizeAdmin, respond) {
+    const result = await authorizeAdmin(req);
+    if (result.ok === true)
+        return true;
+    respond.sendBffError(res, result.code, result.message);
+    return false;
+}

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

@@ -0,0 +1,47 @@
+import { type CommerceOmsHoldPort, type CommerceOmsReadPort } from "../oms/omsPorts.js";
+import type { OmsHandlerDeps, OmsHandlerRequest, OmsHandlerResponder } from "./handlerSupport.js";
+import { type OmsAdminAuthResult as AdminAuthResult } from "./handlerSupport.js";
+export type { OmsAdminAuthResult as AdminAuthResult } from "./handlerSupport.js";
+export type BaseDeps<Response> = OmsHandlerDeps<Response>;
+export declare function createAdminCommerceOrdersListHandler<Response>({ authorizeAdmin, omsPort, readGate, listRequestSchema, listResponseSchema, detailResponseSchema, respond, }: BaseDeps<Response> & {
+    omsPort: Pick<CommerceOmsReadPort, "listOrders">;
+}): (req: OmsHandlerRequest, res: Response) => Promise<void>;
+export declare function createAdminCommerceOrderDetailHandler<Response>({ authorizeAdmin, omsPort, readGate, listRequestSchema, listResponseSchema, detailResponseSchema, respond, }: BaseDeps<Response> & {
+    omsPort: Pick<CommerceOmsReadPort, "getOrderDetail">;
+}): (req: OmsHandlerRequest, res: Response) => Promise<void>;
+export declare function createAdminCommerceOrderHoldHandler<Response>({ authorizeAdmin, omsPort, respond, }: BaseDeps<Response> & {
+    omsPort: Pick<CommerceOmsHoldPort, "createHold">;
+}): (req: OmsHandlerRequest, res: Response) => Promise<void>;
+export declare function createAdminCommerceOrderReleaseHoldHandler<Response>({ authorizeAdmin, omsPort, respond, }: BaseDeps<Response> & {
+    omsPort: Pick<CommerceOmsHoldPort, "releaseHold">;
+}): (req: OmsHandlerRequest, res: Response) => Promise<void>;
+export declare function createAdminCommerceOrderNoteHandler<Response>({ authorizeAdmin, omsPort, respond, }: BaseDeps<Response> & {
+    omsPort: Pick<CommerceOmsHoldPort, "addNote">;
+}): (req: OmsHandlerRequest, res: Response) => Promise<void>;
+export declare function createAdminCommerceOrderUpdateShippingAddressHandler<Response>({ authorizeAdmin, omsPort, respond, }: BaseDeps<Response> & {
+    omsPort: Pick<CommerceOmsHoldPort, "updateShippingAddress">;
+}): (req: OmsHandlerRequest, res: Response) => Promise<void>;
+export declare function authorize<Response>(req: OmsHandlerRequest, res: Response, authorizeAdmin: (req: OmsHandlerRequest) => Promise<AdminAuthResult>, respond: OmsHandlerResponder<Response>): Promise<{
+    ok: true;
+    userId: string;
+    isMachineActor?: boolean;
+} | null>;
+export declare function parseOmsRequest<Response, T>(res: Response, respond: OmsHandlerResponder<Response>, schema: {
+    safeParse: (input: unknown) => {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            flatten: () => unknown;
+        };
+    };
+}, input: unknown, message: string): T | undefined;
+export declare function sendOmsMutationResponse<Response, T>(res: Response, respond: OmsHandlerResponder<Response>, action: () => Promise<unknown>, schema: {
+    safeParse: (input: unknown) => {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+    };
+}, invalidMessage: string, failedMessage: string, accept?: (data: T) => boolean): Promise<void>;