@openlup/platform 0.26.0 → 0.27.0

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

@@ -0,0 +1,40 @@
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+export type OrderReviewMediaMime = "image/jpeg" | "image/png" | "image/webp";
+export interface OrderReviewRawUploadSession {
+    upload(input: {
+        body: AsyncIterable<Uint8Array>;
+        signal: AbortSignal;
+    }): Promise<OrderReviewRawUploadResult>;
+}
+export interface OrderReviewRawUploadBinding {
+    admit(input: {
+        capabilityDigest: string;
+        declaredMime: OrderReviewMediaMime;
+        declaredBytes: number;
+    }): Promise<OrderReviewRawUploadSession | OrderReviewRawUploadResult>;
+}
+export type OrderReviewRawUploadResult = {
+    kind: "complete";
+    status: 200 | 201;
+    mediaRef: string;
+} | {
+    kind: "refused";
+    status: 404 | 409 | 413 | 415 | 503;
+    code: string;
+};
+export type OrderReviewRawUploadBindingState = {
+    kind: "direct";
+    binding: OrderReviewRawUploadBinding;
+} | {
+    kind: "hosted";
+} | {
+    kind: "unbound";
+};
+export declare function createOrderReviewRawUploadHandler(options: {
+    resolveBinding: () => OrderReviewRawUploadBindingState | Promise<OrderReviewRawUploadBindingState>;
+    timeoutMs?: number;
+}): (req: HttpRequest, res: HttpResponse) => Promise<void>;
+export declare function inspectImageHeader(mime: OrderReviewMediaMime, bytes: Uint8Array, declaredBytes: number): {
+    width: number;
+    height: number;
+} | null;

package/dist/commerce/server/orderReviewRawUploadHandler.js

@@ -0,0 +1,316 @@
+import { createHash } from "node:crypto";
+import { crc32 } from "node:zlib";
+const MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
+const MAX_IMAGE_HEADER_BYTES = 64 * 1024;
+const MAX_DIMENSION = 8192;
+const MAX_PIXELS = 40_000_000;
+const CAPABILITY_HEADER = "authorization";
+const ALLOWED_MIME = new Set(["image/jpeg", "image/png", "image/webp"]);
+export function createOrderReviewRawUploadHandler(options) {
+    return async function orderReviewRawUpload(req, res) {
+        if (req.method !== "PUT")
+            return sendError(res, 405, "METHOD_NOT_ALLOWED");
+        let state;
+        try {
+            state = await options.resolveBinding();
+        }
+        catch {
+            return sendError(res, 503, "ORDER_REVIEW_MEDIA_UNAVAILABLE");
+        }
+        if (state.kind === "hosted")
+            return sendError(res, 405, "METHOD_NOT_ALLOWED");
+        if (state.kind === "unbound")
+            return sendError(res, 503, "ORDER_REVIEW_MEDIA_UNAVAILABLE");
+        let headers;
+        try {
+            headers = validateHeaders(req);
+        }
+        catch (error) {
+            const input = asInputError(error);
+            return sendError(res, input.status, input.code);
+        }
+        let admission;
+        try {
+            admission = await state.binding.admit({
+                capabilityDigest: headers.capabilityDigest,
+                declaredMime: headers.mime,
+                declaredBytes: headers.bytes,
+            });
+        }
+        catch {
+            return sendError(res, 503, "ORDER_REVIEW_MEDIA_UNAVAILABLE");
+        }
+        if (isResult(admission)) {
+            if (admission.kind === "refused")
+                req.resume();
+            return sendResult(res, admission);
+        }
+        const abort = new AbortController();
+        const timeout = setTimeout(() => {
+            abort.abort(new Error("raw upload deadline exceeded"));
+            req.destroy();
+        }, options.timeoutMs ?? 30_000);
+        timeout.unref?.();
+        const onAborted = () => abort.abort(new Error("raw upload aborted"));
+        req.once("aborted", onAborted);
+        try {
+            const result = await admission.upload({
+                body: validatedImageBody(req, headers.mime, headers.bytes, abort.signal),
+                signal: abort.signal,
+            });
+            return sendResult(res, result);
+        }
+        catch (error) {
+            if (error instanceof InputError)
+                return sendError(res, error.status, error.code);
+            if (abort.signal.aborted)
+                return sendError(res, 400, "UPLOAD_ABORTED");
+            return sendError(res, 503, "ORDER_REVIEW_MEDIA_UNAVAILABLE");
+        }
+        finally {
+            clearTimeout(timeout);
+            req.off("aborted", onAborted);
+        }
+    };
+}
+function validateHeaders(req) {
+    if (headerValues(req, "transfer-encoding").length > 0)
+        fail(400, "TRANSFER_ENCODING_REFUSED");
+    if (headerValues(req, "content-encoding").length > 0)
+        fail(400, "CONTENT_ENCODING_REFUSED");
+    if (headerValues(req, "range").length > 0)
+        fail(400, "RANGE_REFUSED");
+    const lengths = headerValues(req, "content-length");
+    if (lengths.length !== 1 || !/^[1-9][0-9]*$/.test(lengths[0]) || lengths[0].includes(",")) {
+        fail(400, "INVALID_CONTENT_LENGTH");
+    }
+    const bytes = Number(lengths[0]);
+    if (!Number.isSafeInteger(bytes))
+        fail(400, "INVALID_CONTENT_LENGTH");
+    if (bytes > MAX_UPLOAD_BYTES)
+        fail(413, "UPLOAD_TOO_LARGE");
+    const contentTypes = headerValues(req, "content-type");
+    if (contentTypes.length !== 1 || contentTypes[0].includes(";") || contentTypes[0].includes(",")) {
+        fail(415, "UNSUPPORTED_MEDIA_TYPE");
+    }
+    const mime = contentTypes[0].trim().toLowerCase();
+    if (!ALLOWED_MIME.has(mime))
+        fail(415, "UNSUPPORTED_MEDIA_TYPE");
+    const authorizations = headerValues(req, CAPABILITY_HEADER);
+    if (authorizations.length !== 1)
+        fail(404, "ORDER_REVIEW_MEDIA_NOT_FOUND");
+    const match = /^Bearer (order-review-upload:[a-f0-9-]{36})$/.exec(authorizations[0]);
+    if (!match)
+        fail(404, "ORDER_REVIEW_MEDIA_NOT_FOUND");
+    const capabilityDigest = createHash("sha256").update(match[1], "utf8").digest("hex");
+    return { capabilityDigest, mime: mime, bytes };
+}
+function headerValues(req, name) {
+    const values = [];
+    const raw = req.rawHeaders ?? [];
+    for (let index = 0; index < raw.length; index += 2) {
+        if (raw[index]?.toLowerCase() === name)
+            values.push(raw[index + 1] ?? "");
+    }
+    if (values.length > 0)
+        return values;
+    const fallback = req.headers[name];
+    if (fallback === undefined)
+        return [];
+    return Array.isArray(fallback) ? fallback : [String(fallback)];
+}
+async function* validatedImageBody(source, mime, declaredBytes, signal) {
+    const header = Buffer.alloc(MAX_IMAGE_HEADER_BYTES);
+    const pending = [];
+    let headerBytes = 0;
+    let seen = 0;
+    let accepted = false;
+    for await (const value of source) {
+        if (signal.aborted)
+            fail(400, "UPLOAD_ABORTED");
+        const chunk = toBytes(value);
+        seen += chunk.byteLength;
+        if (seen > declaredBytes || seen > MAX_UPLOAD_BYTES)
+            fail(413, "UPLOAD_TOO_LARGE");
+        if (!accepted) {
+            pending.push(chunk);
+            const copyBytes = Math.min(chunk.byteLength, header.byteLength - headerBytes);
+            if (copyBytes > 0) {
+                header.set(chunk.subarray(0, copyBytes), headerBytes);
+                headerBytes += copyBytes;
+            }
+            const dimensions = inspectImageHeader(mime, header.subarray(0, headerBytes), declaredBytes);
+            if (dimensions) {
+                assertDimensions(dimensions.width, dimensions.height);
+                accepted = true;
+                for (const buffered of pending)
+                    yield buffered;
+                pending.length = 0;
+            }
+            else if (headerBytes === MAX_IMAGE_HEADER_BYTES) {
+                fail(415, "INVALID_IMAGE");
+            }
+        }
+        else {
+            yield chunk;
+        }
+    }
+    if (signal.aborted)
+        fail(400, "UPLOAD_ABORTED");
+    if (seen !== declaredBytes)
+        fail(400, "CONTENT_LENGTH_MISMATCH");
+    if (!accepted)
+        fail(415, "INVALID_IMAGE");
+}
+export function inspectImageHeader(mime, bytes, declaredBytes) {
+    if (mime === "image/png") {
+        if (bytes.length < 33) {
+            if (bytes.length === declaredBytes)
+                fail(415, "INVALID_IMAGE");
+            return null;
+        }
+        if (!matches(bytes, 0, [137, 80, 78, 71, 13, 10, 26, 10]) || readU32BE(bytes, 8) !== 13
+            || ascii(bytes, 12, 4) !== "IHDR" || declaredBytes < 57 || crc32(bytes.subarray(12, 29)) !== readU32BE(bytes, 29)) {
+            fail(415, "INVALID_IMAGE");
+        }
+        const depths = { 0: [1, 2, 4, 8, 16], 2: [8, 16], 3: [1, 2, 4, 8], 4: [8, 16], 6: [8, 16] };
+        if (!depths[bytes[25]]?.includes(bytes[24]) || bytes[26] !== 0 || bytes[27] !== 0 || bytes[28] > 1)
+            fail(415, "INVALID_IMAGE");
+        return { width: readU32BE(bytes, 16), height: readU32BE(bytes, 20) };
+    }
+    if (mime === "image/webp")
+        return inspectWebp(bytes, declaredBytes);
+    return inspectJpeg(bytes);
+}
+function inspectWebp(bytes, declaredBytes) {
+    if (bytes.length < 16)
+        return null;
+    if (ascii(bytes, 0, 4) !== "RIFF" || ascii(bytes, 8, 4) !== "WEBP")
+        fail(415, "INVALID_IMAGE");
+    if (readU32LE(bytes, 4) + 8 !== declaredBytes)
+        fail(415, "INVALID_IMAGE");
+    const kind = ascii(bytes, 12, 4);
+    const chunkBytes = readU32LE(bytes, 16);
+    if (kind === "VP8X") {
+        if (bytes.length < 38) {
+            if (bytes.length === declaredBytes)
+                fail(415, "INVALID_IMAGE");
+            return null;
+        }
+        if (chunkBytes !== 10 || !["VP8 ", "VP8L", "ALPH"].includes(ascii(bytes, 30, 4)))
+            fail(415, "INVALID_IMAGE");
+        return { width: 1 + readU24LE(bytes, 24), height: 1 + readU24LE(bytes, 27) };
+    }
+    if (kind === "VP8L") {
+        if (bytes.length < 25)
+            return null;
+        if (bytes[20] !== 0x2f || chunkBytes < 6 || 20 + chunkBytes + (chunkBytes & 1) !== declaredBytes)
+            fail(415, "INVALID_IMAGE");
+        return {
+            width: 1 + (((bytes[22] & 0x3f) << 8) | bytes[21]),
+            height: 1 + (((bytes[24] & 0x0f) << 10) | (bytes[23] << 2) | ((bytes[22] & 0xc0) >> 6)),
+        };
+    }
+    if (kind === "VP8 ") {
+        if (bytes.length < 30)
+            return null;
+        if (!matches(bytes, 23, [0x9d, 0x01, 0x2a]) || chunkBytes < 10
+            || 20 + chunkBytes + (chunkBytes & 1) !== declaredBytes)
+            fail(415, "INVALID_IMAGE");
+        return { width: readU16LE(bytes, 26) & 0x3fff, height: readU16LE(bytes, 28) & 0x3fff };
+    }
+    fail(415, "INVALID_IMAGE");
+}
+function inspectJpeg(bytes) {
+    if (bytes.length < 4)
+        return null;
+    if (bytes[0] !== 0xff || bytes[1] !== 0xd8)
+        fail(415, "INVALID_IMAGE");
+    let offset = 2;
+    while (offset + 3 < bytes.length) {
+        if (bytes[offset] !== 0xff)
+            fail(415, "INVALID_IMAGE");
+        while (bytes[offset] === 0xff)
+            offset += 1;
+        if (offset >= bytes.length)
+            return null;
+        const marker = bytes[offset++];
+        if (marker === 0xd9 || marker === 0xda)
+            fail(415, "INVALID_IMAGE");
+        if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7))
+            continue;
+        if (offset + 1 >= bytes.length)
+            return null;
+        const length = (bytes[offset] << 8) | bytes[offset + 1];
+        if (length < 2)
+            fail(415, "INVALID_IMAGE");
+        if (isStartOfFrame(marker)) {
+            if (length < 11)
+                fail(415, "INVALID_IMAGE");
+            if (offset + length > bytes.length)
+                return null;
+            const components = bytes[offset + 7];
+            if (bytes[offset + 2] !== 8 || components < 1 || components > 4 || length !== 8 + 3 * components)
+                fail(415, "INVALID_IMAGE");
+            return {
+                height: (bytes[offset + 3] << 8) | bytes[offset + 4],
+                width: (bytes[offset + 5] << 8) | bytes[offset + 6],
+            };
+        }
+        if (offset + length > bytes.length)
+            return null;
+        offset += length;
+    }
+    return null;
+}
+function isStartOfFrame(marker) {
+    return marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker);
+}
+function assertDimensions(width, height) {
+    if (width < 1 || height < 1 || width > MAX_DIMENSION || height > MAX_DIMENSION || width * height > MAX_PIXELS) {
+        fail(415, "INVALID_IMAGE_DIMENSIONS");
+    }
+}
+function toBytes(value) {
+    if (typeof value === "string")
+        return Buffer.from(value);
+    if (value instanceof Uint8Array)
+        return value;
+    fail(400, "INVALID_BODY_CHUNK");
+}
+class InputError extends Error {
+    status;
+    code;
+    constructor(status, code) {
+        super(code);
+        this.status = status;
+        this.code = code;
+    }
+}
+function fail(status, code) { throw new InputError(status, code); }
+function asInputError(error) {
+    return error instanceof InputError ? error : new InputError(400, "INVALID_UPLOAD_BODY");
+}
+function isResult(value) {
+    return "kind" in value;
+}
+function sendResult(res, result) {
+    if (result.kind === "complete") {
+        res.status(result.status).json({ data: { mediaRef: result.mediaRef } });
+    }
+    else
+        sendError(res, result.status, result.code);
+}
+function sendError(res, status, code) {
+    res.status(status).json({ error: { code, message: "Order review media request refused" } });
+}
+function matches(bytes, offset, expected) {
+    return expected.every((value, index) => bytes[offset + index] === value);
+}
+function ascii(bytes, offset, length) {
+    return String.fromCharCode(...bytes.subarray(offset, offset + length));
+}
+function readU16LE(bytes, offset) { return bytes[offset] | (bytes[offset + 1] << 8); }
+function readU24LE(bytes, offset) { return readU16LE(bytes, offset) | (bytes[offset + 2] << 16); }
+function readU32LE(bytes, offset) { return (readU16LE(bytes, offset) | (readU16LE(bytes, offset + 2) << 16)) >>> 0; }
+function readU32BE(bytes, offset) { return ((bytes[offset] << 24) | (bytes[offset + 1] << 16) | (bytes[offset + 2] << 8) | bytes[offset + 3]) >>> 0; }

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

@@ -0,0 +1,14 @@
+import type { CommerceEmailRuntime } from "./emailRuntime.js";
+import type { OutboxHandler } from "../outboxDispatchContracts.js";
+import { OUTBOX_CHECKOUT_EXPIRED_TEMPLATE_SLUG, type OrderPaymentLifecyclePort, type OrderRecipientPort, type TransactionalEmailPort } from "../outboxOrderDraftEmailPorts.js";
+export { OUTBOX_CHECKOUT_EXPIRED_TEMPLATE_SLUG };
+export declare const outboxCheckoutExpiredEmailDescriptor: Readonly<{
+    eventType: "commerce.checkout.expired";
+    timeoutMs: 10000;
+}>;
+export declare function createOutboxCheckoutExpiredEmailHandler<Locale extends string>(deps: {
+    runtime: Pick<CommerceEmailRuntime<Locale>, "formatMoney" | "mapSendOutcome" | "parseOutboxPayload" | "resolveLocale">;
+    emailPort: TransactionalEmailPort<Locale>;
+    recipientPort: OrderRecipientPort;
+    lifecyclePort: OrderPaymentLifecyclePort;
+}): OutboxHandler;

package/dist/commerce/server/outboxCheckoutExpiredEmailHandler.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { COMMERCE_CHECKOUT_EXPIRED_EVENT_TYPE } from "../outboxEventSchemas.js";
+import { OUTBOX_CHECKOUT_EXPIRED_TEMPLATE_SLUG, } from "../outboxOrderDraftEmailPorts.js";
+import { shouldSkipCheckoutExpired } from "../orderEmailEligibility.js";
+export { OUTBOX_CHECKOUT_EXPIRED_TEMPLATE_SLUG };
+const HANDLER_TIMEOUT_MS = 10_000;
+export const outboxCheckoutExpiredEmailDescriptor = Object.freeze({
+    eventType: COMMERCE_CHECKOUT_EXPIRED_EVENT_TYPE, timeoutMs: HANDLER_TIMEOUT_MS,
+});
+const payloadSubsetSchema = z
+    .object({
+    orderUuid: z.guid(),
+    orderId: z.string().min(1),
+    totalCents: z.number().int().nonnegative().optional(),
+    currency: z.string().trim().min(1).optional(),
+    recoveryToken: z.string().trim().min(1).optional(),
+})
+    .passthrough();
+export function createOutboxCheckoutExpiredEmailHandler(deps) {
+    return {
+        ...outboxCheckoutExpiredEmailDescriptor,
+        async handle(row, signal) {
+            const parsed = deps.runtime.parseOutboxPayload(payloadSubsetSchema, row.payload);
+            if (parsed.ok === false) {
+                return parsed.outcome;
+            }
+            const lifecycle = await deps.lifecyclePort.read(parsed.data.orderUuid, signal);
+            const skipReason = shouldSkipCheckoutExpired(lifecycle);
+            if (skipReason) {
+                return { kind: "processed", detail: { skipped: skipReason } };
+            }
+            const recipient = await deps.recipientPort.resolve(parsed.data.orderUuid, signal);
+            if (recipient === null) {
+                return { kind: "processed", detail: { skipped: "recipient_unresolved" } };
+            }
+            const alreadySent = await deps.emailPort.findExistingSend(OUTBOX_CHECKOUT_EXPIRED_TEMPLATE_SLUG, row.id);
+            if (alreadySent) {
+                return { kind: "processed", detail: { dedupe: "email_already_sent" } };
+            }
+            const payload = parsed.data;
+            const amountLabel = payload.totalCents !== undefined && payload.currency !== undefined
+                ? deps.runtime.formatMoney(payload.totalCents, payload.currency)
+                : null;
+            const outcome = await deps.emailPort.sendCheckoutExpiredNotice({
+                to: recipient.email,
+                firstName: recipient.firstName,
+                orderId: payload.orderId,
+                amountLabel,
+                recoveryToken: payload.recoveryToken ?? null,
+                outboxEventId: row.id,
+                locale: deps.runtime.resolveLocale(recipient.country ?? null),
+                signal,
+            });
+            return deps.runtime.mapSendOutcome(outcome);
+        },
+    };
+}

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

@@ -0,0 +1,13 @@
+import type { CommerceEmailRuntime } from "./emailRuntime.js";
+import { type OrderPaymentLifecyclePort, type TransactionalEmailPort, type OrderRecipientPort } from "../outboxOrderDraftEmailPorts.js";
+import type { OutboxHandler } from "../outboxDispatchContracts.js";
+export declare const outboxCheckoutRecoveryEmailDescriptor: Readonly<{
+    eventType: "commerce.checkout_recovery";
+    timeoutMs: 10000;
+}>;
+export declare function createOutboxCheckoutRecoveryEmailHandler<Locale extends string>(deps: {
+    runtime: Pick<CommerceEmailRuntime<Locale>, "mapSendOutcome" | "parseOutboxPayload" | "resolveLocale">;
+    emailPort: TransactionalEmailPort<Locale>;
+    recipientPort: OrderRecipientPort;
+    lifecyclePort: OrderPaymentLifecyclePort;
+}): OutboxHandler;

package/dist/commerce/server/outboxCheckoutRecoveryEmailHandler.js

@@ -0,0 +1,150 @@
+// Checkout-recovery email handler (W3, transactional). Consumes the
+// commerce.checkout_recovery outbox events produced by the W2 enqueue cron and
+// sends a "finish your payment" email with a signed deep-link to complete payment
+// for the SAME unpaid order. Transactional: NO marketing-consent gate. Promotes
+// the W2 producer from dormant to runtime-gated.
+//
+// Three producers feed this one handler: the W2 cron, the operator payment-link
+// command (`operatorIssued: true`), and the buyer's own escape hatch off a payment
+// step that will not finish (`buyerRequested: true`). They differ in one place
+// only — which eligibility question is asked below — and share the template, the
+// dedupe ledger and the deep-link build.
+//
+// handle() flow: parse the minimal payload -> resolve recipient by order ->
+// dedupe on the email_sends ledger -> build the localized deep-link from the raw
+// recovery token -> send -> map the provider outcome to a worker outcome.
+import { z } from "zod";
+import { COMMERCE_CHECKOUT_RECOVERY_EVENT_TYPE } from "../outboxEventSchemas.js";
+import { OUTBOX_CHECKOUT_RECOVERY_TEMPLATE_SLUG, } from "../outboxOrderDraftEmailPorts.js";
+import { PAYMENT_SESSION_ACTIVE, shouldSkipCheckoutRecovery, shouldSkipOperatorCheckoutRecovery, } from "../orderEmailEligibility.js";
+const HANDLER_TIMEOUT_MS = 10_000;
+export const outboxCheckoutRecoveryEmailDescriptor = Object.freeze({
+    eventType: COMMERCE_CHECKOUT_RECOVERY_EVENT_TYPE, timeoutMs: HANDLER_TIMEOUT_MS,
+});
+// Deferrals allowed before a nudge blocked by a live payment session retires.
+// The dispatcher's default backoff is 60 s doubling to a 3600 s cap, so five
+// attempts span ~31 min — past the 15 min activity window that produced the
+// skip, and well inside the 120 min subscription sweep that would cancel the
+// order anyway. It also sits under the default `maxAttempts` of 8: exhausting
+// retries routes a row to the terminal DLQ as `discarded`, which records a
+// dispatch failure for a reminder that was merely untimely. Retiring as
+// `processed` keeps it an honest deliberate skip. A deployment that configures
+// `maxAttempts` below this ceiling has chosen fewer retries globally, and gets
+// that choice here too.
+const PAYMENT_SESSION_RETRY_CEILING = 5;
+// Frozen minimal parse: orderId (recipient + linkage) and recoveryToken (the
+// deep-link) are load-bearing; mode/reminderHours degrade to safe defaults so a
+// producer tweak never retro-DLQs an in-flight reminder.
+//
+// `operatorIssued` says a human minted this link on the operator surface rather
+// than the cron finding an abandoned order. `buyerRequested` says the BUYER asked
+// for it, from inside the payment step they are stuck on. Both optional, and
+// absent means the cron: every row already in flight when either shipped keeps
+// its exact behaviour.
+const payloadSubsetSchema = z
+    .object({
+    orderId: z.guid(),
+    recoveryToken: z.string().min(1),
+    mode: z.string().optional(),
+    reminderHours: z.number().int().positive().optional(),
+    operatorIssued: z.boolean().optional(),
+    buyerRequested: z.boolean().optional(),
+})
+    .passthrough();
+export function createOutboxCheckoutRecoveryEmailHandler(deps) {
+    return {
+        ...outboxCheckoutRecoveryEmailDescriptor,
+        async handle(row, signal) {
+            const parsed = deps.runtime.parseOutboxPayload(payloadSubsetSchema, row.payload);
+            if (parsed.ok === false) {
+                return parsed.outcome;
+            }
+            const lifecycle = await deps.lifecyclePort.read(parsed.data.orderId, signal);
+            // Three producers, three questions. The cron asks "is this order still
+            // sitting unpaid", and going quiet once it is not is right. An
+            // operator-issued link is a decision a human already made about an order
+            // that has usually left `pending_payment` — expired is the ordinary case —
+            // and the redeem rail recreates it when the customer opens the link.
+            // Judging that by the cron's rule would skip it as
+            // `order_not_pending_payment` and no-send in silence.
+            const skipReason = parsed.data.buyerRequested
+                ? skipReasonForBuyerRequestedRecovery(lifecycle)
+                : parsed.data.operatorIssued
+                    ? shouldSkipOperatorCheckoutRecovery(lifecycle)
+                    : shouldSkipCheckoutRecovery(lifecycle);
+            if (skipReason === PAYMENT_SESSION_ACTIVE) {
+                // A live payment session is temporary. The producer key is unique per
+                // event, so settling it as processed would consume the only reminder
+                // without sending. Defer until the session settles, subject to the
+                // retry ceiling below.
+                //
+                // Read `attempts` defensively: `undefined < n` is false, which would
+                // retire the nudge on its FIRST deferral — the precise opposite of the
+                // intent here, and silent.
+                const attempts = Number.isFinite(row.attempts) ? row.attempts : 0;
+                if (attempts < PAYMENT_SESSION_RETRY_CEILING) {
+                    return { kind: "retry", reason: PAYMENT_SESSION_ACTIVE };
+                }
+                // Past the ceiling, retire deliberately. Letting retries run out routes
+                // the row to the terminal DLQ as `discarded`, which reads as a dispatch
+                // failure for a reminder that was only untimely.
+                return { kind: "processed", detail: { skipped: "payment_session_exhausted" } };
+            }
+            if (skipReason) {
+                return { kind: "processed", detail: { skipped: skipReason } };
+            }
+            const recipient = await deps.recipientPort.resolve(parsed.data.orderId, signal);
+            if (recipient === null) {
+                // No client on the order (or unreadable) — nothing to send, never retry.
+                return { kind: "processed", detail: { skipped: "recipient_unresolved" } };
+            }
+            const alreadySent = await deps.emailPort.findExistingSend(OUTBOX_CHECKOUT_RECOVERY_TEMPLATE_SLUG, row.id);
+            if (alreadySent) {
+                return { kind: "processed", detail: { dedupe: "email_already_sent" } };
+            }
+            const locale = deps.runtime.resolveLocale(recipient.country ?? null);
+            const outcome = await deps.emailPort.sendCheckoutRecovery({
+                to: recipient.email,
+                firstName: recipient.firstName,
+                contextName: recipient.contextName ?? null,
+                orderId: parsed.data.orderId,
+                recoveryToken: parsed.data.recoveryToken,
+                mode: parsed.data.mode ?? "one_time",
+                reminderHours: parsed.data.reminderHours ?? 1,
+                outboxEventId: row.id,
+                // Marks the deep-link as the one the buyer mailed themselves off a stuck
+                // payment step, so the landing page can tell that arrival apart from a
+                // cron nudge. Absent for every other producer, which keeps their URLs
+                // byte-identical to what they were.
+                linkSource: parsed.data.buyerRequested ? "buyer_hatch" : undefined,
+                locale,
+                signal,
+            });
+            return deps.runtime.mapSendOutcome(outcome);
+        },
+    };
+}
+/**
+ * Eligibility for a link the BUYER asked for, from inside the payment step.
+ *
+ * Everything the operator rule suppresses is suppressed here too — the order is
+ * gone, or the money is already in — because those make the email actively wrong
+ * rather than merely late. Exactly ONE rule is lifted:
+ * `payment_session_active`.
+ *
+ * That rule is a politeness rule: do not remind someone to pay while they are
+ * paying. For this producer it is not merely unhelpful, it is inverted. A buyer
+ * who taps this control is BY CONSTRUCTION inside a live payment session — that
+ * session is the thing that will not finish, and asking for a way out of it is
+ * the whole request. Deferring on it would defer every buyer row through the
+ * retry ceiling and then retire it as `payment_session_exhausted`, so the hatch
+ * would send nothing, ever, and nothing would report a failure.
+ *
+ * Written here rather than as a fourth predicate in `orderEmailEligibility`: it
+ * is not a different question from the operator's, it is the operator's question
+ * with its one transient answer already decided by who is asking.
+ */
+function skipReasonForBuyerRequestedRecovery(lifecycle) {
+    const reason = shouldSkipOperatorCheckoutRecovery(lifecycle);
+    return reason === PAYMENT_SESSION_ACTIVE ? null : reason;
+}

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

@@ -0,0 +1,46 @@
+import type { CommerceEmailRuntime } from "./emailRuntime.js";
+import type { OutboxHandlerDescriptor } from "@openlup/core/outbox";
+import type { OutboxHandler, OutboxHandlerRegistry } from "../outboxDispatchContracts.js";
+import type { OrderPaymentLifecyclePort, OrderPaidLinesPort, OrderRecipientPort, TransactionalEmailPort } from "../outboxOrderDraftEmailPorts.js";
+import { type OrderPaidParcelNoteReader } from "./outboxOrderPaidEmailHandler.js";
+import { type DeliveredEmailProviderKindReader } from "./outboxShipmentDeliveredEmailHandler.js";
+import type { OrderPaidFulfillmentPort } from "./outboxOrderPaidFulfillmentPorts.js";
+import { type OrderPaidRiskAssessmentPort } from "./outboxOrderPaidFulfillmentHandler.js";
+import { type OrderBuyerCommsPolicy } from "../salesChannelEnvelope.js";
+/**
+ * Reads the sales-source buyer-comms policy for one order. `null` is
+ * the answer for an order that names no channel — a storefront order, or one
+ * that predates the source axis.
+ *
+ * Read on every event so changes to `sales_channels.buyer_comms_owner` take
+ * effect on the next dispatch. A cached policy could keep sending after
+ * ownership has changed.
+ */
+export interface OrderBuyerCommsPolicyReader {
+    readOrderBuyerCommsPolicy(orderUuid: string): Promise<OrderBuyerCommsPolicy | null>;
+}
+export type TransactionalEmailRegistryDeps<Locale extends string = string> = {
+    runtime: CommerceEmailRuntime<Locale>;
+    emailPort: TransactionalEmailPort<Locale>;
+    recipientPort: OrderRecipientPort;
+    lifecyclePort: OrderPaymentLifecyclePort;
+    orderPaidLinesPort: OrderPaidLinesPort;
+    orderPaidParcelNote?: OrderPaidParcelNoteReader<Locale>;
+    deliveredProviderKindReader?: DeliveredEmailProviderKindReader;
+    buyerCommsPolicyReader?: OrderBuyerCommsPolicyReader;
+};
+export declare function describeCoreOutboxHandlers(selection: {
+    transactionalEmail: boolean;
+    fulfillmentEnabled: boolean;
+}): OutboxHandlerDescriptor[];
+export declare function createOutboxDispatchRegistry<Locale extends string>(deps: {
+    /** Bind the existing outbox rail's composition; commerce owns no second rail. */
+    uniqueRegistry(handlers: readonly OutboxHandler[]): OutboxHandlerRegistry;
+    transactionalEmail?: TransactionalEmailRegistryDeps<Locale>;
+    fulfillmentPort?: OrderPaidFulfillmentPort;
+    riskPort?: OrderPaidRiskAssessmentPort;
+    riskEnabled?: boolean;
+    fulfillmentEnabled: boolean;
+    extraHandlers?: readonly OutboxHandler[];
+    expectedDescriptors?: () => readonly OutboxHandlerDescriptor[];
+}): OutboxHandlerRegistry;