@openlup/platform 0.26.0 → 0.27.0

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

@@ -0,0 +1,26 @@
+import type { CommerceEmailRuntime } from "./emailRuntime.js";
+import type { OutboxHandler } from "../outboxDispatchContracts.js";
+import { OUTBOX_RETURN_APPROVED_TEMPLATE_SLUG, OUTBOX_RETURN_REJECTED_TEMPLATE_SLUG, type OrderRecipientPort, type TransactionalEmailPort } from "../outboxOrderDraftEmailPorts.js";
+export { OUTBOX_RETURN_APPROVED_TEMPLATE_SLUG, OUTBOX_RETURN_REJECTED_TEMPLATE_SLUG };
+export declare function describeOutboxReturnEmail(eventType: string): {
+    eventType: string;
+    timeoutMs: number;
+};
+export declare const outboxReturnApprovedEmailDescriptor: Readonly<{
+    eventType: string;
+    timeoutMs: number;
+}>;
+export declare const outboxReturnRejectedEmailDescriptor: Readonly<{
+    eventType: string;
+    timeoutMs: number;
+}>;
+export declare function createOutboxReturnApprovedEmailHandler<Locale extends string>(deps: {
+    runtime: Pick<CommerceEmailRuntime<Locale>, "createTransactionalEmailHandler" | "resolveLocale">;
+    emailPort: TransactionalEmailPort<Locale>;
+    recipientPort: OrderRecipientPort;
+}): OutboxHandler;
+export declare function createOutboxReturnRejectedEmailHandler<Locale extends string>(deps: {
+    runtime: Pick<CommerceEmailRuntime<Locale>, "createTransactionalEmailHandler" | "resolveLocale">;
+    emailPort: TransactionalEmailPort<Locale>;
+    recipientPort: OrderRecipientPort;
+}): OutboxHandler;

package/dist/commerce/server/outboxReturnEmailHandlers.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { COMMERCE_RETURN_APPROVED_EVENT_TYPE, COMMERCE_RETURN_REJECTED_EVENT_TYPE, } from "../outboxEventSchemas.js";
+import { OUTBOX_RETURN_APPROVED_TEMPLATE_SLUG, OUTBOX_RETURN_REJECTED_TEMPLATE_SLUG, } from "../outboxOrderDraftEmailPorts.js";
+export { OUTBOX_RETURN_APPROVED_TEMPLATE_SLUG, OUTBOX_RETURN_REJECTED_TEMPLATE_SLUG };
+const HANDLER_TIMEOUT_MS = 10_000;
+export function describeOutboxReturnEmail(eventType) {
+    return { eventType, timeoutMs: HANDLER_TIMEOUT_MS };
+}
+export const outboxReturnApprovedEmailDescriptor = Object.freeze(describeOutboxReturnEmail(COMMERCE_RETURN_APPROVED_EVENT_TYPE));
+export const outboxReturnRejectedEmailDescriptor = Object.freeze(describeOutboxReturnEmail(COMMERCE_RETURN_REJECTED_EVENT_TYPE));
+const payloadSubsetSchema = z
+    .object({
+    orderUuid: z.guid(),
+    orderId: z.string().min(1),
+})
+    .passthrough();
+// Both return-decision emails (approved / rejected) share the same payload, dedupe,
+// recipient resolution, and snooze/retry/discard ladder as the order-refunded email;
+// they differ only in event type, template slug, and which port method sends them.
+function createReturnDecisionEmailHandler(deps) {
+    return deps.runtime.createTransactionalEmailHandler({
+        ...describeOutboxReturnEmail(deps.eventType),
+        templateSlug: deps.templateSlug,
+        schema: payloadSubsetSchema,
+        resolveKey: (payload) => payload.orderUuid,
+        recipientPort: deps.recipientPort,
+        findExistingSend: (slug, id) => deps.emailPort.findExistingSend(slug, id),
+        send: ({ payload, recipient, row, signal }) => deps.send(deps.emailPort, {
+            to: recipient.email,
+            firstName: recipient.firstName,
+            orderId: payload.orderId,
+            outboxEventId: row.id,
+            locale: deps.runtime.resolveLocale(recipient.country ?? null),
+            signal,
+        }),
+    });
+}
+export function createOutboxReturnApprovedEmailHandler(deps) {
+    return createReturnDecisionEmailHandler({
+        ...deps,
+        ...outboxReturnApprovedEmailDescriptor,
+        templateSlug: OUTBOX_RETURN_APPROVED_TEMPLATE_SLUG,
+        send: (port, input) => port.sendReturnApprovedNotice(input),
+    });
+}
+export function createOutboxReturnRejectedEmailHandler(deps) {
+    return createReturnDecisionEmailHandler({
+        ...deps,
+        ...outboxReturnRejectedEmailDescriptor,
+        templateSlug: OUTBOX_RETURN_REJECTED_TEMPLATE_SLUG,
+        send: (port, input) => port.sendReturnRejectedNotice(input),
+    });
+}

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

@@ -0,0 +1,17 @@
+import type { CommerceEmailRuntime } from "./emailRuntime.js";
+import type { OutboxHandler } from "../outboxDispatchContracts.js";
+import { OUTBOX_SHIPMENT_DELIVERED_TEMPLATE_SLUG, type OrderRecipientPort, type TransactionalEmailPort } from "../outboxOrderDraftEmailPorts.js";
+export { OUTBOX_SHIPMENT_DELIVERED_TEMPLATE_SLUG };
+export declare const outboxShipmentDeliveredEmailDescriptor: Readonly<{
+    eventType: "commerce.shipment.delivered";
+    timeoutMs: 10000;
+}>;
+export interface DeliveredEmailProviderKindReader {
+    readSelectedProviderKind(orderUuid: string): Promise<string | null>;
+}
+export declare function createOutboxShipmentDeliveredEmailHandler<Locale extends string>(deps: {
+    runtime: Pick<CommerceEmailRuntime<Locale>, "mapSendOutcome" | "parseOutboxPayload" | "providerOwnsDeliveredNotification" | "resolveLocale">;
+    emailPort: TransactionalEmailPort<Locale>;
+    recipientPort: OrderRecipientPort;
+    providerKindReader?: DeliveredEmailProviderKindReader;
+}): OutboxHandler;

package/dist/commerce/server/outboxShipmentDeliveredEmailHandler.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { COMMERCE_SHIPMENT_DELIVERED_EVENT_TYPE } from "../outboxEventSchemas.js";
+import { OUTBOX_SHIPMENT_DELIVERED_TEMPLATE_SLUG, } from "../outboxOrderDraftEmailPorts.js";
+export { OUTBOX_SHIPMENT_DELIVERED_TEMPLATE_SLUG };
+const HANDLER_TIMEOUT_MS = 10_000;
+export const outboxShipmentDeliveredEmailDescriptor = Object.freeze({
+    eventType: COMMERCE_SHIPMENT_DELIVERED_EVENT_TYPE, timeoutMs: HANDLER_TIMEOUT_MS,
+});
+const payloadSubsetSchema = z
+    .object({
+    orderUuid: z.guid(),
+    orderId: z.string().min(1),
+})
+    .passthrough();
+export function createOutboxShipmentDeliveredEmailHandler(deps) {
+    return {
+        ...outboxShipmentDeliveredEmailDescriptor,
+        async handle(row, signal) {
+            const parsed = deps.runtime.parseOutboxPayload(payloadSubsetSchema, row.payload);
+            if (parsed.ok === false) {
+                return parsed.outcome;
+            }
+            // Provider-aware suppression: the carrier (via the 3PL) owns the delivered notice
+            // for these providers, so sending ours would duplicate it. Recorded as processed
+            // (not discarded) so the event settles and never retries.
+            if (deps.providerKindReader) {
+                const providerKind = await deps.providerKindReader.readSelectedProviderKind(parsed.data.orderUuid);
+                if (providerKind && deps.runtime.providerOwnsDeliveredNotification(providerKind)) {
+                    return { kind: "processed", detail: { skipped: `carrier_owns_delivered:${providerKind}` } };
+                }
+            }
+            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_SHIPMENT_DELIVERED_TEMPLATE_SLUG, row.id);
+            if (alreadySent) {
+                return { kind: "processed", detail: { dedupe: "email_already_sent" } };
+            }
+            const outcome = await deps.emailPort.sendShipmentDeliveredNotice({
+                to: recipient.email,
+                firstName: recipient.firstName,
+                contextName: recipient.contextName ?? null,
+                orderId: parsed.data.orderId,
+                outboxEventId: row.id,
+                locale: deps.runtime.resolveLocale(recipient.country ?? null),
+                signal,
+            });
+            return deps.runtime.mapSendOutcome(outcome);
+        },
+    };
+}

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

@@ -0,0 +1,13 @@
+import type { CommerceEmailRuntime } from "./emailRuntime.js";
+import type { OutboxHandler } from "../outboxDispatchContracts.js";
+import { OUTBOX_SHIPMENT_DISPATCHED_TEMPLATE_SLUG, type OrderRecipientPort, type TransactionalEmailPort } from "../outboxOrderDraftEmailPorts.js";
+export { OUTBOX_SHIPMENT_DISPATCHED_TEMPLATE_SLUG };
+export declare const outboxShipmentDispatchedEmailDescriptor: Readonly<{
+    eventType: "commerce.shipment.dispatched";
+    timeoutMs: 10000;
+}>;
+export declare function createOutboxShipmentDispatchedEmailHandler<Locale extends string>(deps: {
+    runtime: Pick<CommerceEmailRuntime<Locale>, "carrierTrackingUrl" | "createTransactionalEmailHandler" | "legacyTrackingUrl" | "normalizeCarrierKind" | "resolveLocale">;
+    emailPort: TransactionalEmailPort<Locale>;
+    recipientPort: OrderRecipientPort;
+}): OutboxHandler;

package/dist/commerce/server/outboxShipmentDispatchedEmailHandler.js

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import { COMMERCE_SHIPMENT_DISPATCHED_EVENT_TYPE } from "../outboxEventSchemas.js";
+import { OUTBOX_SHIPMENT_DISPATCHED_TEMPLATE_SLUG, } from "../outboxOrderDraftEmailPorts.js";
+export { OUTBOX_SHIPMENT_DISPATCHED_TEMPLATE_SLUG };
+const HANDLER_TIMEOUT_MS = 10_000;
+export const outboxShipmentDispatchedEmailDescriptor = Object.freeze({
+    eventType: COMMERCE_SHIPMENT_DISPATCHED_EVENT_TYPE, timeoutMs: HANDLER_TIMEOUT_MS,
+});
+const trackingReferenceSchema = z
+    .object({
+    providerKind: z.string().trim().min(1).max(80).nullable().optional(),
+    carrierKind: z.string().trim().min(1).max(80).nullable().optional(),
+    service: z.string().trim().min(1).max(120).nullable().optional(),
+    trackingNumber: z.string().trim().min(1).max(160),
+    trackingUrl: z.string().url().max(500).nullable().optional(),
+})
+    .strict();
+const payloadSubsetSchema = z
+    .object({
+    orderUuid: z.guid(),
+    orderId: z.string().min(1),
+    providerKind: z.string().trim().min(1).max(80).nullable().optional(),
+    carrierKind: z.string().trim().min(1).max(80).nullable().optional(),
+    service: z.string().trim().min(1).max(120).nullable().optional(),
+    trackingNumber: z.string().trim().min(1).nullable().optional(),
+    trackingUrl: z.string().url().max(500).nullable().optional(),
+    trackingReferences: z.array(trackingReferenceSchema).max(20).optional(),
+})
+    .passthrough();
+export function createOutboxShipmentDispatchedEmailHandler(deps) {
+    return deps.runtime.createTransactionalEmailHandler({
+        ...outboxShipmentDispatchedEmailDescriptor,
+        templateSlug: OUTBOX_SHIPMENT_DISPATCHED_TEMPLATE_SLUG,
+        schema: payloadSubsetSchema,
+        resolveKey: (payload) => payload.orderUuid,
+        recipientPort: deps.recipientPort,
+        findExistingSend: (slug, id) => deps.emailPort.findExistingSend(slug, id),
+        send: ({ payload, recipient, row, signal }) => {
+            const tracking = resolveCustomerTracking(payload, deps.runtime);
+            return deps.emailPort.sendShipmentDispatchedNotice({
+                to: recipient.email,
+                firstName: recipient.firstName,
+                contextName: recipient.contextName ?? null,
+                orderId: payload.orderId,
+                trackingNumber: tracking.trackingNumber,
+                trackingUrl: tracking.trackingUrl,
+                outboxEventId: row.id,
+                locale: deps.runtime.resolveLocale(recipient.country ?? null),
+                signal,
+            });
+        },
+    });
+}
+function resolveCustomerTracking(payload, runtime) {
+    const refs = (payload.trackingReferences ?? []).map((ref) => ({
+        providerKind: normalizeKind(ref.providerKind),
+        carrierKind: normalizeKind(ref.carrierKind),
+        service: ref.service ?? null,
+        trackingNumber: ref.trackingNumber,
+        trackingUrl: ref.trackingUrl ?? null,
+    }));
+    const legacyRef = payload.trackingNumber
+        ? {
+            providerKind: normalizeKind(payload.providerKind),
+            carrierKind: normalizeKind(payload.carrierKind),
+            service: payload.service ?? null,
+            trackingNumber: payload.trackingNumber,
+            trackingUrl: payload.trackingUrl ?? null,
+        }
+        : null;
+    const candidates = refs.length > 0 ? refs : legacyRef ? [legacyRef] : [];
+    const primary = candidates.find((ref) => ref.trackingUrl) ?? candidates[0] ?? null;
+    if (!primary)
+        return { trackingNumber: null, trackingUrl: null };
+    // Persisted URL wins; otherwise the shared carrier registry builds one from
+    // the carrier kind (older shipment_external_refs rows predate URL persistence).
+    // The host retains its legacy fallback; unknown carriers remain number-only.
+    return {
+        trackingNumber: primary.trackingNumber,
+        trackingUrl: primary.trackingUrl ??
+            runtime.carrierTrackingUrl(runtime.normalizeCarrierKind({ carrierKind: primary.carrierKind, service: primary.service }), primary.trackingNumber) ??
+            runtime.legacyTrackingUrl(primary, refs.length > 0),
+    };
+}
+function normalizeKind(value) {
+    return value?.trim().toLowerCase() || null;
+}

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

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

package/dist/commerce/server/outboxShipmentExceptionEmailHandler.js

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { COMMERCE_SHIPMENT_EXCEPTION_EVENT_TYPE } from "../outboxEventSchemas.js";
+import { OUTBOX_SHIPMENT_EXCEPTION_TEMPLATE_SLUG, } from "../outboxOrderDraftEmailPorts.js";
+export { OUTBOX_SHIPMENT_EXCEPTION_TEMPLATE_SLUG };
+const HANDLER_TIMEOUT_MS = 10_000;
+export const outboxShipmentExceptionEmailDescriptor = Object.freeze({
+    eventType: COMMERCE_SHIPMENT_EXCEPTION_EVENT_TYPE, timeoutMs: HANDLER_TIMEOUT_MS,
+});
+const payloadSubsetSchema = z
+    .object({
+    orderUuid: z.guid(),
+    orderId: z.string().min(1),
+    customerNotification: z.literal("shipment_exception").optional(),
+})
+    .passthrough();
+export function createOutboxShipmentExceptionEmailHandler(deps) {
+    return {
+        ...outboxShipmentExceptionEmailDescriptor,
+        async handle(row, signal) {
+            const parsed = deps.runtime.parseOutboxPayload(payloadSubsetSchema, row.payload);
+            if (parsed.ok === false) {
+                return parsed.outcome;
+            }
+            if (parsed.data.customerNotification !== "shipment_exception") {
+                return { kind: "processed", detail: { skipped: "internal_fulfillment_hold" } };
+            }
+            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_SHIPMENT_EXCEPTION_TEMPLATE_SLUG, row.id);
+            if (alreadySent) {
+                return { kind: "processed", detail: { dedupe: "email_already_sent" } };
+            }
+            const outcome = await deps.emailPort.sendShipmentExceptionNotice({
+                to: recipient.email,
+                firstName: recipient.firstName,
+                orderId: parsed.data.orderId,
+                outboxEventId: row.id,
+                locale: deps.runtime.resolveLocale(recipient.country ?? null),
+                signal,
+            });
+            return deps.runtime.mapSendOutcome(outcome);
+        },
+    };
+}

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

@@ -0,0 +1,48 @@
+import type { z } from "zod";
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.js";
+interface ReferenceRuntime {
+    runtime: {
+        orderId: string;
+        clientId: string;
+        finalizedReplayed: boolean;
+        total: {
+            amountMinor: number;
+            currency: string;
+        };
+        payment: {
+            paymentIntentId: string;
+            paymentAttemptId: string | null;
+            status: string;
+            attemptStatus: string | null;
+        };
+    };
+}
+interface ReferenceSettlement {
+    paymentResult: {
+        status: string;
+        replayed: boolean;
+    };
+}
+export declare function createReferenceCheckoutHandler<Command, Runtime extends ReferenceRuntime, Settlement extends ReferenceSettlement, Response>({ startCheckout, checkRateLimit, checkRiskBlocklist, admitProfile, responder, requestSchema, responseSchema, }: {
+    startCheckout(command: Command): Promise<{
+        runtime: Runtime;
+        settlement: Settlement | null;
+        persistence: {
+            replayed: boolean;
+        };
+    }>;
+    checkRateLimit(req: HttpRequest, command: Command): Promise<{
+        allowed: boolean;
+    }>;
+    checkRiskBlocklist?(req: HttpRequest, command: Command): Promise<{
+        blocked: boolean;
+    }>;
+    admitProfile(command: Command): boolean;
+    responder: BffResponder;
+    requestSchema: z.ZodType<{
+        command: Command;
+    }>;
+    responseSchema: z.ZodType<Response>;
+}): (req: HttpRequest, res: HttpResponse) => Promise<void>;
+export {};

package/dist/commerce/server/referenceCheckoutHandler.js

@@ -0,0 +1,68 @@
+import { REFERENCE_CHECKOUT_V1 } from "../checkoutCommandSchemas.js";
+import { CommerceRuntimeConflictError, CommerceRuntimePersistenceError } from "../runtimeErrors.js";
+export function createReferenceCheckoutHandler({ startCheckout, checkRateLimit, checkRiskBlocklist, admitProfile, responder, requestSchema, responseSchema, }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+    return async function handler(req, res) {
+        if (req.method !== "POST") {
+            sendMethodNotAllowed(res, ["POST"]);
+            return;
+        }
+        const request = requestSchema.safeParse(req.body ?? {});
+        if (!request.success) {
+            sendBffError(res, "BAD_REQUEST", "Invalid reference checkout request", {
+                details: request.error.flatten(),
+            });
+            return;
+        }
+        try {
+            if (!admitProfile(request.data.command)) {
+                sendBffError(res, "BAD_REQUEST", "Checkout command does not match the active reference profile");
+                return;
+            }
+            if (!(await checkRateLimit(req, request.data.command)).allowed) {
+                sendBffError(res, "RATE_LIMITED", "Reference checkout rate limit exceeded");
+                return;
+            }
+            if (checkRiskBlocklist && (await checkRiskBlocklist(req, request.data.command)).blocked) {
+                sendBffError(res, "FORBIDDEN", "Reference checkout cannot be completed");
+                return;
+            }
+            // Settlement is owned by the shared paid-order service, not by this
+            // handler: it is present exactly when that service settled the attempt,
+            // and absent when the runtime is still awaiting or already refused it.
+            const result = await startCheckout(request.data.command);
+            const settled = result.settlement;
+            const response = responseSchema.safeParse({
+                version: REFERENCE_CHECKOUT_V1,
+                orderId: result.runtime.runtime.orderId,
+                clientId: result.runtime.runtime.clientId,
+                paymentIntentId: result.runtime.runtime.payment.paymentIntentId,
+                paymentAttemptId: result.runtime.runtime.payment.paymentAttemptId,
+                paymentStatus: settled?.paymentResult.status ?? result.runtime.runtime.payment.status,
+                paymentAttemptStatus: settled
+                    ? "succeeded"
+                    : result.runtime.runtime.payment.attemptStatus,
+                replayed: result.persistence.replayed ||
+                    result.runtime.runtime.finalizedReplayed ||
+                    (settled?.paymentResult.replayed ?? false),
+                total: result.runtime.runtime.total,
+            });
+            if (!response.success) {
+                sendBffError(res, "INVALID_RESPONSE", "Reference checkout returned invalid response");
+                return;
+            }
+            sendBffSuccess(res, response.data, { contractVersion: REFERENCE_CHECKOUT_V1 });
+        }
+        catch (error) {
+            if (error instanceof CommerceRuntimeConflictError) {
+                sendBffError(res, "CONFLICT", error.message, { details: error.details });
+                return;
+            }
+            if (error instanceof CommerceRuntimePersistenceError) {
+                sendBffError(res, "UPSTREAM_UNAVAILABLE", "Reference checkout persistence failed");
+                return;
+            }
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Reference checkout failed");
+        }
+    };
+}

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

@@ -0,0 +1,31 @@
+export interface ReservationSweepCounts {
+    ordersChecked: number;
+    ordersExpired: number;
+    reservationsReleased: number;
+    skippedPaid: number;
+    skippedTerminal: number;
+    skippedSubscription: number;
+}
+export type ReservationSweepRpcClient = {
+    rpc(name: string, args: Record<string, unknown>): PromiseLike<{
+        data: unknown;
+        error: {
+            message?: string;
+        } | null;
+    }>;
+};
+export interface RetryHoldSweepCounts {
+    holdsChecked: number;
+    holdsReleased: number;
+    skippedPaid: number;
+}
+export declare function createManagedReservationSweepPort(client: ReservationSweepRpcClient): {
+    sweep(input: {
+        now: string;
+        limit: number;
+    }): Promise<ReservationSweepCounts>;
+    sweepRetryHolds(input: {
+        now: string;
+        limit: number;
+    }): Promise<RetryHoldSweepCounts>;
+};

package/dist/commerce/server/reservationSweepPort.js

@@ -0,0 +1,45 @@
+export function createManagedReservationSweepPort(client) {
+    return {
+        async sweep(input) {
+            const { data, error } = await client.rpc("commerce_sweep_expired_reservation_holds", {
+                p_idempotency_prefix: "commerce-reservation-sweep-run",
+                p_now: input.now,
+                p_limit: input.limit,
+            });
+            if (error)
+                throw new Error(`rpc_sweep: ${error.message ?? "unknown"}`);
+            return readSweepCounts(data);
+        },
+        // Release-only: frees expired subscription_retry_window holds without
+        // touching the cycle order, subscription, or dunning case.
+        async sweepRetryHolds(input) {
+            const { data, error } = await client.rpc("commerce_sweep_expired_retry_holds", {
+                p_now: input.now,
+                p_limit: input.limit,
+            });
+            if (error)
+                throw new Error(`rpc_retry_hold_sweep: ${error.message ?? "unknown"}`);
+            const sweep = data?.retrySweep;
+            return {
+                holdsChecked: numberField(sweep, "holdsChecked"),
+                holdsReleased: numberField(sweep, "holdsReleased"),
+                skippedPaid: numberField(sweep, "skippedPaid"),
+            };
+        },
+    };
+}
+function readSweepCounts(data) {
+    const sweep = data?.sweep;
+    return {
+        ordersChecked: numberField(sweep, "ordersChecked"),
+        ordersExpired: numberField(sweep, "ordersExpired"),
+        reservationsReleased: numberField(sweep, "reservationsReleased"),
+        skippedPaid: numberField(sweep, "skippedPaid"),
+        skippedTerminal: numberField(sweep, "skippedTerminal"),
+        skippedSubscription: numberField(sweep, "skippedSubscription"),
+    };
+}
+function numberField(record, key) {
+    const value = record?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}

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

@@ -0,0 +1,22 @@
+export interface StarterTermsDecision {
+    intervalDays: number;
+    steadyCadenceDays: number;
+    steadyUnits: number;
+    graduationSizeConstraint?: Record<string, unknown>;
+}
+export type StarterTermsRefusal = "basket_too_small" | "basket_not_admitted" | "demand_unknown";
+export type StarterTermsResolution = {
+    kind: "terms";
+    terms: StarterTermsDecision;
+} | {
+    kind: "refused";
+    reason: StarterTermsRefusal;
+};
+export interface StarterTermsInput<Intent, Snapshot> {
+    intent: Intent;
+    authoritativeQuote: Snapshot;
+    offerVersion?: string;
+}
+export interface StarterTermsPort<Intent, Snapshot> {
+    resolve(input: StarterTermsInput<Intent, Snapshot>): Promise<StarterTermsResolution>;
+}

package/dist/commerce/server/starterTermsPort.js

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

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

@@ -0,0 +1,13 @@
+import type { CommerceReturnsPort, ReturnRequestCreateInput } from "../commerceReturnsPort.js";
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export interface CommerceReturnsRpcClient {
+    rpc(fn: string, params: Record<string, unknown>): PromiseLike<{
+        data: unknown;
+        error: {
+            code?: string;
+            message?: string;
+        } | null;
+    }>;
+}
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export declare function createSupabaseCommerceReturnsPort<Reason extends string = ReturnRequestCreateInput["reasonCode"]>(client: CommerceReturnsRpcClient): CommerceReturnsPort<Reason>;

package/dist/commerce/server/supabaseCommerceReturnsPort.js

@@ -0,0 +1,56 @@
+function parseResult(fn, data) {
+    const result = (data ?? {});
+    if (typeof result.returnRequestId !== "string" ||
+        typeof result.status !== "string") {
+        throw new Error(`${fn}_unexpected_result`);
+    }
+    return {
+        returnRequestId: result.returnRequestId,
+        status: result.status,
+        replayed: result.replayed === true,
+    };
+}
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export function createSupabaseCommerceReturnsPort(client) {
+    async function call(fn, params) {
+        const { data, error } = await client.rpc(fn, params);
+        if (error)
+            throw new Error(`${fn}_failed:${error.code ?? "unknown"}`);
+        return parseResult(fn, data);
+    }
+    return {
+        createRequest(input) {
+            return call("commerce_return_request_create", {
+                p_idempotency_key: input.idempotencyKey,
+                p_order_id: input.orderId,
+                p_lines: input.lines.map((line) => ({
+                    orderItemId: line.orderItemId,
+                    sku: line.sku ?? null,
+                    quantity: line.quantity,
+                    restockDisposition: line.restockDisposition ?? "restock",
+                })),
+                p_reason_code: input.reasonCode,
+                p_customer_note: input.customerNote ?? null,
+                p_requested_by: input.requestedBy ?? null,
+            });
+        },
+        approve(input) {
+            return call("commerce_return_approve", {
+                p_idempotency_key: input.idempotencyKey,
+                p_return_request_id: input.returnRequestId,
+                p_approved_by: input.actorUserId ?? null,
+                p_refund_mode: input.refundMode,
+                p_refund_amount_cents: input.refundAmountCents ?? null,
+                p_admin_note: input.adminNote ?? null,
+            });
+        },
+        reject(input) {
+            return call("commerce_return_reject", {
+                p_idempotency_key: input.idempotencyKey,
+                p_return_request_id: input.returnRequestId,
+                p_approved_by: input.actorUserId ?? null,
+                p_admin_note: input.adminNote ?? null,
+            });
+        },
+    };
+}

package/dist/communications/consentPurposeRegistry.d.ts

@@ -1,4 +1,4 @@
 import type { CommunicationPurpose } from "./contracts/types.js";
 import type { CommunicationPurposeDefinition, CommunicationPurposeRegistry } from "./contracts/consent.js";
 export declare function createCommunicationPurposeRegistry<const Purpose extends string = never>(additions?: readonly CommunicationPurposeDefinition<Purpose>[]): CommunicationPurposeRegistry<CommunicationPurpose | Purpose>;
-export declare const defaultCommunicationPurposeRegistry: CommunicationPurposeRegistry<"transactional" | "marketing_launch_offer" | "marketing_newsletter" | "tester_program" | "subscription_dunning" | "admin_notification">;
+export declare const defaultCommunicationPurposeRegistry: CommunicationPurposeRegistry<"transactional" | "subscription_dunning" | "marketing_launch_offer" | "marketing_newsletter" | "tester_program" | "admin_notification">;