@openlup/platform 0.26.0 → 0.28.0

package/dist/commerce/orderEmailEligibility.js

@@ -0,0 +1,123 @@
+/**
+ * Skip reason meaning "the payer is inside a live payment session right now".
+ * Exported because it is the one skip reason a caller must treat as TRANSIENT;
+ * every other reason in this module is a settled fact about the order.
+ */
+export const PAYMENT_SESSION_ACTIVE = "payment_session_active";
+const SUCCESSFUL_PAYMENT_STATUSES = new Set(["succeeded", "paid", "captured"]);
+const ACTIVE_PAYMENT_STATUSES = new Set(["pending", "requires_action", "created", "processing"]);
+const FRESH_PAYMENT_ACTIVITY_MS = 15 * 60 * 1000;
+export function shouldSkipOrderDraftConfirmation(state) {
+    if (state === null)
+        return "order_unavailable";
+    if (state.orderStatus !== "draft")
+        return "order_no_longer_draft";
+    if (state.hasPayment)
+        return "order_no_longer_draft";
+    if (state.paymentStatus && state.paymentStatus !== "not_started")
+        return "order_no_longer_draft";
+    return null;
+}
+/**
+ * Eligibility for the checkout-recovery NUDGE only.
+ *
+ * `payment_session_active` below is a politeness rule: do not remind someone to
+ * pay while they are paying. It is correct here and wrong for a decline notice
+ * — see {@link shouldSkipPaymentFailedNotice}. A caller acting on this reason
+ * must defer rather than drop, because the nudge's emit key is once-per-order.
+ */
+export function shouldSkipCheckoutRecovery(state) {
+    if (state === null)
+        return "order_unavailable";
+    if (state.orderStatus !== "pending_payment")
+        return "order_not_pending_payment";
+    if (state.paymentStatus && SUCCESSFUL_PAYMENT_STATUSES.has(state.paymentStatus)) {
+        return "order_already_paid";
+    }
+    if (state.paymentStatus &&
+        ACTIVE_PAYMENT_STATUSES.has(state.paymentStatus) &&
+        isFreshPaymentActivity(state.paymentUpdatedAt)) {
+        return PAYMENT_SESSION_ACTIVE;
+    }
+    return null;
+}
+/**
+ * Eligibility for an OPERATOR-ISSUED recovery link.
+ *
+ * Deliberately not {@link shouldSkipCheckoutRecovery}. That gate is written for
+ * the cron nudge, and its first rule — leave `pending_payment` and we go quiet —
+ * is exactly wrong here. A human looked at the order and decided to send this
+ * link, and the orders they send it for are largely the ones that have ALREADY
+ * left `pending_payment`: `expired` is the ordinary case, and the redeem rail
+ * recreates such an order from its frozen quote when the customer opens the link.
+ * Reusing the cron gate would skip those as `order_not_pending_payment`, the
+ * operator would have promised an email that never arrives, and nothing anywhere
+ * would report a failure. The mint side has already run the full recovery
+ * eligibility for this order, so what is left here is only what can have changed
+ * between the mint and the send.
+ *
+ * What still suppresses: the order is gone, or the money is in. Both make the
+ * email actively wrong rather than merely late.
+ *
+ * `payment_session_active` behaves exactly as it does for the nudge, and for the
+ * same reason: do not tell someone to finish paying while they are paying. The
+ * caller must DEFER on it rather than drop, because a dropped operator link is
+ * the silent no-send this whole path is written to prevent.
+ */
+export function shouldSkipOperatorCheckoutRecovery(state) {
+    if (state === null)
+        return "order_unavailable";
+    if (state.orderStatus === "paid")
+        return "order_already_paid";
+    if (state.paymentStatus && SUCCESSFUL_PAYMENT_STATUSES.has(state.paymentStatus)) {
+        return "order_already_paid";
+    }
+    if (state.paymentStatus &&
+        ACTIVE_PAYMENT_STATUSES.has(state.paymentStatus) &&
+        isFreshPaymentActivity(state.paymentUpdatedAt)) {
+        return PAYMENT_SESSION_ACTIVE;
+    }
+    return null;
+}
+/**
+ * Eligibility for a recoverable payment-decline notice.
+ *
+ * Unlike a checkout reminder, a decline notice must not be suppressed by a live
+ * retry. Its producer key is once per order, so a later failed attempt cannot
+ * replace a notice that was consumed without sending.
+ *
+ * Suppress only when the order is unavailable, already paid, or no longer
+ * pending payment. The producer's claim delay lets successful retries settle
+ * before this lifecycle read; scheduling remains the producer/runtime's duty.
+ */
+export function shouldSkipPaymentFailedNotice(state) {
+    if (state === null)
+        return "order_unavailable";
+    if (state.orderStatus !== "pending_payment")
+        return "order_not_pending_payment";
+    if (state.paymentStatus && SUCCESSFUL_PAYMENT_STATUSES.has(state.paymentStatus)) {
+        return "order_already_paid";
+    }
+    return null;
+}
+export function shouldSkipCheckoutExpired(state) {
+    if (state === null)
+        return "order_unavailable";
+    if (state.orderStatus === "expired")
+        return null;
+    // ⛔ The activation sweep writes `cancelled`, never `expired`, so a first
+    // subscription abandoned at the 24h window would fail an `expired`-only gate
+    // and the buyer would hear nothing at all. Accepted ONLY with the sweep's own
+    // marker, so an ordinary cancellation still cannot reach this template.
+    if (state.orderStatus === "cancelled" && state.subscriptionActivationAbandoned === true)
+        return null;
+    return "order_not_expired";
+}
+function isFreshPaymentActivity(value) {
+    if (!value)
+        return false;
+    const timestamp = Date.parse(value);
+    if (!Number.isFinite(timestamp))
+        return false;
+    return Date.now() - timestamp < FRESH_PAYMENT_ACTIVITY_MS;
+}

package/dist/commerce/orderEmailLines.d.ts

@@ -0,0 +1,12 @@
+import type { OrderEmailLineItem } from "./outboxOrderDraftEmailPorts.js";
+export interface RawLine {
+    label: string | null;
+    quantity: number;
+    lineSubtotalMinor: number | null;
+    currency: string | null;
+}
+export interface OrderEmailLinePresentation<Locale extends string = string> {
+    formatMoney(amountMinor: number, currency: string): string;
+    genericItemLabel(locale: Locale): string;
+}
+export declare function buildItems<Locale extends string>(lines: RawLine[], locale: Locale, presentation: OrderEmailLinePresentation<Locale>): OrderEmailLineItem[];

package/dist/commerce/orderEmailLines.js

@@ -0,0 +1,8 @@
+export function buildItems(lines, locale, presentation) {
+    return lines.map((line) => {
+        const name = line.label ?? presentation.genericItemLabel(locale);
+        const lineTotalLabel = line.lineSubtotalMinor !== null && line.currency !== null
+            ? presentation.formatMoney(line.lineSubtotalMinor, line.currency) : "";
+        return { name, quantity: line.quantity, lineTotalLabel };
+    });
+}

package/dist/commerce/orderFeedbackContracts.d.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+export declare const ORDER_FEEDBACK_SUBMIT_RPC_NAME = "submit_order_feedback";
+export declare const ORDER_FEEDBACK_CHECK_RPC_NAME = "check_order_feedback_token";
+export declare const orderFeedbackTokenCheckRequestSchema: z.ZodObject<{
+    token: z.ZodString;
+}, z.core.$strict>;
+export type OrderFeedbackTokenCheckRequest = z.infer<typeof orderFeedbackTokenCheckRequestSchema>;
+export declare const orderFeedbackTokenCheckStatusSchema: z.ZodEnum<{
+    ready: "ready";
+    already_submitted: "already_submitted";
+    not_found: "not_found";
+}>;
+export type OrderFeedbackTokenCheckStatus = z.infer<typeof orderFeedbackTokenCheckStatusSchema>;
+export declare const orderFeedbackTokenCheckResponseSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        ready: "ready";
+        already_submitted: "already_submitted";
+        not_found: "not_found";
+    }>;
+}, z.core.$strict>;
+export type OrderFeedbackTokenCheckResponse = z.infer<typeof orderFeedbackTokenCheckResponseSchema>;
+export declare const orderFeedbackSubmitRequestSchema: z.ZodObject<{
+    token: z.ZodString;
+    rating: z.ZodNumber;
+    comment: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type OrderFeedbackSubmitRequest = z.infer<typeof orderFeedbackSubmitRequestSchema>;
+export declare const orderFeedbackSubmitStatusSchema: z.ZodEnum<{
+    already_submitted: "already_submitted";
+    not_found: "not_found";
+    submitted: "submitted";
+}>;
+export type OrderFeedbackSubmitStatus = z.infer<typeof orderFeedbackSubmitStatusSchema>;
+export declare const orderFeedbackSubmitResponseSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        already_submitted: "already_submitted";
+        not_found: "not_found";
+        submitted: "submitted";
+    }>;
+}, z.core.$strict>;
+export type OrderFeedbackSubmitResponse = z.infer<typeof orderFeedbackSubmitResponseSchema>;

package/dist/commerce/orderFeedbackContracts.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+// Contract for the public order-feedback (post-delivery review) submit BFF.
+// No login: the opaque token from the review-email link is the only credential.
+export const ORDER_FEEDBACK_SUBMIT_RPC_NAME = "submit_order_feedback";
+export const ORDER_FEEDBACK_CHECK_RPC_NAME = "check_order_feedback_token";
+export const orderFeedbackTokenCheckRequestSchema = z
+    .object({ token: z.string().min(1).max(128) })
+    .strict();
+export const orderFeedbackTokenCheckStatusSchema = z.enum([
+    "ready",
+    "already_submitted",
+    "not_found",
+]);
+export const orderFeedbackTokenCheckResponseSchema = z
+    .object({ status: orderFeedbackTokenCheckStatusSchema })
+    .strict();
+export const orderFeedbackSubmitRequestSchema = z
+    .object({
+    token: z.string().min(1).max(128),
+    rating: z.number().int().min(1).max(5),
+    comment: z.string().max(2000).optional(),
+})
+    .strict();
+// The RPC reports outcome without ever exposing the row, so the form can show
+// the right state (submitted / already submitted / unknown token).
+export const orderFeedbackSubmitStatusSchema = z.enum([
+    "submitted",
+    "already_submitted",
+    "not_found",
+]);
+export const orderFeedbackSubmitResponseSchema = z
+    .object({ status: orderFeedbackSubmitStatusSchema })
+    .strict();

package/dist/commerce/orderMoney.d.ts

@@ -0,0 +1,6 @@
+import type { OrderMoneyHeaderRow, OrderMoneyItemRow, CanonicalOrderMoney, OrderMoneyDiagnostic } from "./contracts/orderMoney.js";
+export type { OrderMoneyIssueCode, OrderMoneyHeaderRow, OrderMoneyItemRow, CanonicalOrderMoneyLine, CanonicalOrderMoney, OrderMoneyDiagnostic } from "./contracts/orderMoney.js";
+export declare const ORDER_HEADER_MONEY_COLUMNS: string;
+export declare const ORDER_ITEM_MONEY_COLUMNS: string;
+export declare function deriveOrderMoney(order: OrderMoneyHeaderRow, items?: readonly OrderMoneyItemRow[], onDiagnostic?: (diagnostic: OrderMoneyDiagnostic) => void): CanonicalOrderMoney;
+export declare function emitOrderMoneyDiagnostic(diagnostic: OrderMoneyDiagnostic): void;

package/dist/commerce/orderMoney.js

@@ -0,0 +1,168 @@
+export const ORDER_HEADER_MONEY_COLUMNS = [
+    "currency",
+    "subtotal_cents",
+    "discount_cents",
+    "shipping_cents",
+    "shipping_discount_cents",
+    "tax_cents",
+    "total_cents",
+].join(", ");
+export const ORDER_ITEM_MONEY_COLUMNS = [
+    "unit_price_cents",
+    "total_cents",
+    "discount_allocated_cents",
+    "effective_total_cents",
+    "effective_net_cents",
+    "vat_rate_bps",
+].join(", ");
+export function deriveOrderMoney(order, items, onDiagnostic = emitOrderMoneyDiagnostic) {
+    const issueCodes = new Set();
+    const shippingEffective = order.shipping_cents - order.shipping_discount_cents;
+    if (order.shipping_discount_cents < 0
+        || order.shipping_discount_cents > order.shipping_cents) {
+        issueCodes.add("shipping_discount_out_of_range");
+    }
+    if (order.discount_cents < 0 || order.discount_cents > order.subtotal_cents) {
+        issueCodes.add("product_discount_out_of_range");
+    }
+    if (order.subtotal_cents - order.discount_cents + shippingEffective
+        !== order.total_cents) {
+        issueCodes.add("header_equation_mismatch");
+    }
+    const lines = items?.map((item) => mapLine(item, issueCodes)) ?? [];
+    if (items)
+        validateLines(order, lines, issueCodes);
+    const result = {
+        orderId: order.id ?? null,
+        currency: order.currency,
+        subtotal: order.subtotal_cents,
+        productDiscount: order.discount_cents,
+        shippingGross: order.shipping_cents,
+        shippingDiscount: order.shipping_discount_cents,
+        shippingEffective,
+        tax: order.tax_cents,
+        total: order.total_cents,
+        lines,
+        validationScope: items ? "full" : "header",
+        reconciled: issueCodes.size === 0,
+        issueCodes: [...issueCodes],
+    };
+    if (!result.reconciled) {
+        try {
+            onDiagnostic({
+                event: "commerce_order_money_unreconciled",
+                orderId: result.orderId,
+                validationScope: result.validationScope,
+                issueCodes: result.issueCodes,
+            });
+        }
+        catch {
+            // Diagnostics must never turn the rollback-only read fallback into a
+            // customer-facing outage.
+        }
+    }
+    return result;
+}
+export function emitOrderMoneyDiagnostic(diagnostic) {
+    console.warn(diagnostic.event, JSON.stringify({
+        orderId: diagnostic.orderId,
+        validationScope: diagnostic.validationScope,
+        issueCodes: diagnostic.issueCodes,
+    }));
+}
+function mapLine(item, issueCodes) {
+    const trioComplete = item.discount_allocated_cents != null
+        && item.effective_total_cents != null
+        && item.effective_net_cents != null;
+    if (!trioComplete)
+        issueCodes.add("missing_item_canonical_money");
+    const discountAllocated = trioComplete ? item.discount_allocated_cents : 0;
+    const effectiveGross = trioComplete ? item.effective_total_cents : item.total_cents;
+    const effectiveNet = trioComplete
+        ? item.effective_net_cents
+        : netFromGross(item.total_cents, item.vat_rate_bps);
+    if (!isPositiveSafeInteger(item.quantity)) {
+        issueCodes.add("item_quantity_out_of_range");
+    }
+    if (!isNonNegativeSafeInteger(item.unit_price_cents)
+        || !isNonNegativeSafeInteger(item.total_cents)) {
+        issueCodes.add("item_catalog_money_out_of_range");
+    }
+    if (!isNonNegativeSafeInteger(item.vat_rate_bps)
+        || item.vat_rate_bps > 10_000) {
+        issueCodes.add("item_vat_rate_out_of_range");
+    }
+    if (trioComplete) {
+        if (!isNonNegativeSafeInteger(discountAllocated)
+            || discountAllocated > item.total_cents) {
+            issueCodes.add("item_discount_out_of_range");
+        }
+        if (!isNonNegativeSafeInteger(effectiveGross)
+            || !isNonNegativeSafeInteger(effectiveNet)
+            || effectiveGross > item.total_cents
+            || effectiveNet > effectiveGross) {
+            issueCodes.add("item_effective_money_out_of_range");
+        }
+    }
+    if (effectiveGross + discountAllocated !== item.total_cents) {
+        issueCodes.add("item_gross_equation_mismatch");
+    }
+    if (item.unit_price_cents * item.quantity !== item.total_cents) {
+        issueCodes.add("item_catalog_equation_mismatch");
+    }
+    if (effectiveNet !== netFromGross(effectiveGross, item.vat_rate_bps)) {
+        issueCodes.add("item_net_vat_mismatch");
+    }
+    return {
+        id: item.id ?? null,
+        quantity: item.quantity,
+        catalogUnit: item.unit_price_cents,
+        catalogTotal: item.total_cents,
+        discountAllocated,
+        effectiveGross,
+        effectiveNet,
+        vatRateBps: item.vat_rate_bps,
+    };
+}
+function validateLines(order, lines, issueCodes) {
+    const catalogTotal = sum(lines, (line) => line.catalogTotal);
+    const allocatedDiscount = sum(lines, (line) => line.discountAllocated);
+    const effectiveTotal = sum(lines, (line) => line.effectiveGross);
+    if (catalogTotal !== order.subtotal_cents)
+        issueCodes.add("catalog_subtotal_mismatch");
+    if (allocatedDiscount !== order.discount_cents)
+        issueCodes.add("allocated_discount_mismatch");
+    if (effectiveTotal !== order.subtotal_cents - order.discount_cents) {
+        issueCodes.add("effective_subtotal_mismatch");
+    }
+    if (effectiveTotal + order.shipping_cents - order.shipping_discount_cents
+        !== order.total_cents) {
+        issueCodes.add("total_positions_mismatch");
+    }
+    const rates = new Set(lines.map((line) => line.vatRateBps));
+    if (lines.length > 0 && rates.size !== 1)
+        issueCodes.add("mixed_vat_rates");
+    if (lines.length > 0 && rates.size === 1) {
+        const vatRateBps = lines[0]?.vatRateBps ?? 0;
+        const netTotal = sum(lines, (line) => line.effectiveNet)
+            + netFromGross(order.shipping_cents - order.shipping_discount_cents, vatRateBps);
+        if (order.total_cents - netTotal !== order.tax_cents) {
+            issueCodes.add("tax_total_mismatch");
+        }
+    }
+    else if (lines.length === 0 && order.total_cents !== order.tax_cents) {
+        issueCodes.add("tax_total_mismatch");
+    }
+}
+function netFromGross(gross, vatRateBps) {
+    return Math.round(gross * 10_000 / (10_000 + vatRateBps));
+}
+function isNonNegativeSafeInteger(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
+function isPositiveSafeInteger(value) {
+    return isNonNegativeSafeInteger(value) && value > 0;
+}
+function sum(items, value) {
+    return items.reduce((total, item) => total + value(item), 0);
+}