@mohasinac/appkit 4.58.0 → 4.60.0

package/dist/features/obligations/repository/obligations.repository.d.ts

@@ -0,0 +1,68 @@
+import type { DocumentReference } from "firebase-admin/firestore";
+import { BaseRepository } from "../../../providers/db-firebase";
+import { type ObligationDocument, type ObligationKind, type ObligationState } from "../schemas/firestore";
+export interface OpenObligationInput {
+    kind: ObligationKind;
+    subjectCollection: string;
+    subjectId: string;
+    dueAt: Date;
+    isTestData?: boolean;
+    note?: string;
+    now?: Date;
+}
+export interface CloseObligationInput {
+    state: Exclude<ObligationState, "open">;
+    closeReason: string;
+    now?: Date;
+}
+export declare class ObligationsRepository extends BaseRepository<ObligationDocument> {
+    constructor();
+    /**
+     * Open an obligation, or leave an existing open one exactly as it is.
+     *
+     * 🛑 `.create()`, fails-if-exists — which gives the invariant **at most one
+     * open obligation per (subject, kind)**. That is what makes it safe to
+     * reconcile obligations on EVERY order write, including the great majority
+     * that change nothing relevant: a double create is a no-op, not a second
+     * timer.
+     *
+     * 🛑 It deliberately does NOT update the `dueAt` of an existing row. The
+     * clock starts once, at the anchoring event, and a later write re-deriving a
+     * slightly different deadline must not quietly extend it — that would let a
+     * seller refresh their own dispatch deadline by touching the order.
+     */
+    open(input: OpenObligationInput): Promise<{
+        id: string;
+        created: boolean;
+    }>;
+    /** Close one, with a reason. Never throws — see `open`. */
+    close(subjectId: string, kind: ObligationKind, input: CloseObligationInput): Promise<void>;
+    /**
+     * The sweep's ONE query: open obligations past due.
+     *
+     * 🛑 One equality (`state`) and one inequality (`dueAt`), ordered by `dueAt`
+     * — the only shape Firestore serves without demanding the inequality field
+     * lead the sort (Root Cause #59). **ONE composite index for every kind**,
+     * which is the whole reason `kind` is a field rather than named deadline
+     * columns on the order: fifteen named deadline fields would mean fifteen
+     * queries per tick and fifteen new composite indexes on a collection that
+     * already carries 55. The two orphan `prizeRevealDeadline` indexes — on a
+     * field that exists in no TypeScript file — are a preview of that failure.
+     */
+    listDue(now: Date, limit?: number): Promise<ObligationDocument[]>;
+    /** Open obligations approaching their deadline, for the warning pass. */
+    listUpcoming(horizon: Date, now: Date, limit?: number): Promise<ObligationDocument[]>;
+    /**
+     * Every open obligation for one subject — the quiet-period check.
+     *
+     * 🛑 This is the QUIET PERIOD invariant's query, and the payout path must
+     * call it at BOTH batch-creation and settlement time. A refund posted between
+     * the two would otherwise silently shrink a payout an admin had already sent.
+     */
+    listOpenForSubject(subjectId: string): Promise<ObligationDocument[]>;
+    /** Record that a warning was sent, so a re-run does not re-warn. */
+    recordWarning(id: string, at: Date): Promise<void>;
+    /** Refs for a subject's obligations — used when an order is hard-deleted. */
+    refsForSubject(subjectId: string): Promise<DocumentReference[]>;
+}
+export declare function obligationsRepository(): ObligationsRepository;

package/dist/features/obligations/repository/obligations.repository.js

@@ -0,0 +1,158 @@
+import { BaseRepository, prepareForFirestore } from "../../../providers/db-firebase/index.js";
+import { normalizeError } from "../../../errors/normalize.js";
+import { OBLIGATIONS_COLLECTION, OBLIGATION_ACTIVE_STATES, OBLIGATION_FIELDS, createObligationId, } from "../schemas/firestore.js";
+export class ObligationsRepository extends BaseRepository {
+    /*
+     * 🛑 NO `SIEVE_FIELDS`, deliberately.
+     *
+     * `audit-sieve-field-coverage` targets every `*.repository.ts` defining one,
+     * and this collection has no filterable admin list to justify it: the sweep
+     * uses exactly one query shape, and an operator looking at a deadline looks
+     * at the ORDER, not at the index row. Declaring a Sieve surface nothing calls
+     * is the speculative-infra pattern — the `route-schema-registry` lesson, 576
+     * keys into a layer with no readers.
+     */
+    constructor() {
+        super(OBLIGATIONS_COLLECTION);
+    }
+    /**
+     * Open an obligation, or leave an existing open one exactly as it is.
+     *
+     * 🛑 `.create()`, fails-if-exists — which gives the invariant **at most one
+     * open obligation per (subject, kind)**. That is what makes it safe to
+     * reconcile obligations on EVERY order write, including the great majority
+     * that change nothing relevant: a double create is a no-op, not a second
+     * timer.
+     *
+     * 🛑 It deliberately does NOT update the `dueAt` of an existing row. The
+     * clock starts once, at the anchoring event, and a later write re-deriving a
+     * slightly different deadline must not quietly extend it — that would let a
+     * seller refresh their own dispatch deadline by touching the order.
+     */
+    async open(input) {
+        const now = input.now ?? new Date();
+        const id = createObligationId(input.subjectId, input.kind);
+        const doc = {
+            id,
+            kind: input.kind,
+            subjectCollection: input.subjectCollection,
+            subjectId: input.subjectId,
+            dueAt: input.dueAt,
+            state: "open",
+            ...(input.isTestData ? { isTestData: true } : {}),
+            ...(input.note ? { note: input.note } : {}),
+            createdAt: now,
+            updatedAt: now,
+        };
+        try {
+            await this.getCollection().doc(id).create(prepareForFirestore(doc));
+            return { id, created: true };
+        }
+        catch (err) {
+            /*
+             * Any failure is treated as "already there". Unlike the gateway-event
+             * inbox — which must fail OPEN because a lost event is unrecoverable —
+             * an obligation is a derived hint: the next order write reconciles again,
+             * and the subject itself still carries the facts. Rethrowing here would
+             * let a transient Firestore blip fail the ORDER WRITE that triggered the
+             * reconcile, which is the one thing that must not happen.
+             */
+            void normalizeError(err);
+            return { id, created: false };
+        }
+    }
+    /** Close one, with a reason. Never throws — see `open`. */
+    async close(subjectId, kind, input) {
+        const now = input.now ?? new Date();
+        try {
+            await this.getCollection()
+                .doc(createObligationId(subjectId, kind))
+                .update({
+                state: input.state,
+                closeReason: input.closeReason,
+                closedAt: now,
+                updatedAt: now,
+            });
+        }
+        catch (err) {
+            // Closing one that does not exist is the normal case, not a fault.
+            void normalizeError(err);
+        }
+    }
+    /**
+     * The sweep's ONE query: open obligations past due.
+     *
+     * 🛑 One equality (`state`) and one inequality (`dueAt`), ordered by `dueAt`
+     * — the only shape Firestore serves without demanding the inequality field
+     * lead the sort (Root Cause #59). **ONE composite index for every kind**,
+     * which is the whole reason `kind` is a field rather than named deadline
+     * columns on the order: fifteen named deadline fields would mean fifteen
+     * queries per tick and fifteen new composite indexes on a collection that
+     * already carries 55. The two orphan `prizeRevealDeadline` indexes — on a
+     * field that exists in no TypeScript file — are a preview of that failure.
+     */
+    async listDue(now, limit = 100) {
+        const snap = await this.getCollection()
+            .where(OBLIGATION_FIELDS.STATE, "in", [...OBLIGATION_ACTIVE_STATES])
+            .where(OBLIGATION_FIELDS.DUE_AT, "<=", now)
+            .orderBy(OBLIGATION_FIELDS.DUE_AT, "asc")
+            .limit(limit)
+            .get();
+        return snap.docs.map((d) => this.mapDoc(d));
+    }
+    /** Open obligations approaching their deadline, for the warning pass. */
+    async listUpcoming(horizon, now, limit = 100) {
+        const snap = await this.getCollection()
+            .where(OBLIGATION_FIELDS.STATE, "in", [...OBLIGATION_ACTIVE_STATES])
+            .where(OBLIGATION_FIELDS.DUE_AT, "<=", horizon)
+            .orderBy(OBLIGATION_FIELDS.DUE_AT, "asc")
+            .limit(limit)
+            .get();
+        return snap.docs
+            .map((d) => this.mapDoc(d))
+            .filter((o) => o.dueAt.getTime() > now.getTime());
+    }
+    /**
+     * Every open obligation for one subject — the quiet-period check.
+     *
+     * 🛑 This is the QUIET PERIOD invariant's query, and the payout path must
+     * call it at BOTH batch-creation and settlement time. A refund posted between
+     * the two would otherwise silently shrink a payout an admin had already sent.
+     */
+    async listOpenForSubject(subjectId) {
+        const snap = await this.getCollection()
+            .where(OBLIGATION_FIELDS.SUBJECT_ID, "==", subjectId)
+            .where(OBLIGATION_FIELDS.STATE, "in", [...OBLIGATION_ACTIVE_STATES])
+            .get();
+        return snap.docs.map((d) => this.mapDoc(d));
+    }
+    /** Record that a warning was sent, so a re-run does not re-warn. */
+    async recordWarning(id, at) {
+        try {
+            const existing = await this.findById(id);
+            await this.getCollection()
+                .doc(id)
+                .update({
+                warnedAt: [...(existing?.warnedAt ?? []), at],
+                updatedAt: at,
+            });
+        }
+        catch (err) {
+            void normalizeError(err);
+        }
+    }
+    /** Refs for a subject's obligations — used when an order is hard-deleted. */
+    async refsForSubject(subjectId) {
+        const snap = await this.getCollection()
+            .where(OBLIGATION_FIELDS.SUBJECT_ID, "==", subjectId)
+            .limit(50)
+            .get();
+        return snap.docs.map((d) => d.ref);
+    }
+}
+let cached = null;
+export function obligationsRepository() {
+    if (!cached)
+        cached = new ObligationsRepository();
+    return cached;
+}

package/dist/features/obligations/schemas/firestore.d.ts

@@ -0,0 +1,160 @@
+/**
+ * `obligations` — deadlines with money consequences.
+ *
+ * ## Why a mechanism rather than more cron jobs
+ *
+ * The order lifecycle has roughly seventy timer-driven scenarios ("seller never
+ * accepts → auto-cancel + full refund at 3 days", "buyer cancels before
+ * shipping", "return approved but never posted"…). The approach before this was
+ * eight hand-written sweeps whose coverage could only be established by
+ * checking that every pair of `.filter()` predicates agreed — and
+ * Root Cause #27 is that reasoning having already failed at n=3: an order in
+ * `reupload_requested` was excluded by `getExpiredPaymentDeadlines` (it HAS a
+ * proof), by `getUnreviewedProofPastDeadline` (it HAS an outcome) and by
+ * `runPendingOrderTimeout` (it HAS a deadline). Three sweeps, pairwise
+ * disjoint, and the order held stock forever with no terminal state.
+ *
+ * This collection makes "which sweep owns this order" answerable by
+ * construction instead of by three filters happening to agree.
+ *
+ * ## 🛑 IT IS A DUE-DATE INDEX, NOT TRUTH
+ *
+ * The order is authoritative. An obligation row exists so the sweep can FIND
+ * candidates cheaply with one indexed query; having found one it **re-reads the
+ * subject and re-evaluates the policy's `precondition`**, and a row whose
+ * premise no longer holds closes as `superseded` rather than acting.
+ *
+ * That is what keeps this out of the stored-mirror drift class (Root Cause
+ * #42). A row saying "cancel this order at 15:00" is a HINT; the order saying
+ * "I was paid at 14:58" is the fact, and the fact wins.
+ *
+ * ## 🛑 NOT A FIRESTORE TRIGGER
+ *
+ * An `onOrderWrite` trigger that wrote `obligations`, whose sweep then wrote
+ * `orders`, is Root Cause #92's self-write loop exactly — the one that cost
+ * 1,017,548 invocations in 24 hours against a 2M/month free quota, plus a
+ * sibling function woken a million times just to return. Obligations are
+ * reconciled **inside the order's own write**, in `updateWithHistory`, where
+ * the current document is already in hand.
+ */
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+export declare const OBLIGATIONS_COLLECTION = "obligations";
+/**
+ * Every kind of deadline the system owes somebody.
+ *
+ * 🛑 A `Record<ObligationKind, ObligationPolicy>` in `constants/policies.ts`
+ * consumes this union, so **adding a kind without declaring its anchor,
+ * duration and guardrail tier is a compile error.** That is the property that
+ * makes the Nth scenario cheap instead of another bespoke cron job.
+ */
+export type ObligationKind = "seller-accept" | "seller-dispatch" | "proof-reupload" | "delivery-confirm" | "return-respond" | "return-post" | "return-receive" | "return-inspect" | "claim-shipping" | "claim-sale"
+/**
+ * The order is COMPLETE: 7 days have passed since delivery with no issue
+ * raised, so points are awarded and no new dispute may be opened.
+ *
+ * 🛑 Owner's requirement, 2026-10-21, verbatim: *"points only get issued on
+ * successful purchases after buyer put reviews, then only, if no review no
+ * points, that marks the complete order, they are also assigned if the user
+ * no issues or updates after 7 days of delivery — no further disputes should
+ * be entertained as well."*
+ *
+ * So completion has TWO triggers and this is the second: the first is the
+ * buyer posting a review (event-driven, no timer needed), and this is the
+ * silence fallback. Whichever fires first completes the order; the award must
+ * therefore be IDEMPOTENT, which is why it is keyed on the order in the
+ * points ledger rather than appended blindly.
+ *
+ * It is also the dispute cutoff, which is the part with teeth: after this
+ * fires, a new dispute is refused. Existing ones are unaffected — see the
+ * policy's own note on why "no further disputes" cannot mean "everything
+ * closes at 7 days".
+ */
+ | "order-complete" | "payout-release";
+/**
+ * Lifecycle of one obligation.
+ *
+ * | state | meaning |
+ * |---|---|
+ * | `open` | the clock is running |
+ * | `met` | the thing happened in time — closed by the order's own write |
+ * | `acted` | the deadline passed and the sweep did what the policy says |
+ * | `escalated` | the deadline passed and a human was asked instead |
+ * | `superseded` | the premise no longer holds; nothing was owed after all |
+ *
+ * 🛑 `superseded` is not a failure and must not be reported as one. It is the
+ * normal outcome of the index disagreeing with the subject, which is exactly
+ * the case the re-read exists to catch.
+ */
+export type ObligationState = "open" | "met" | "acted" | "escalated" | "superseded";
+/**
+ * What the sweep is allowed to do when a deadline passes.
+ *
+ * 🛑 THIS LIVES IN THE TYPE, not in the sweep's code, and that is deliberate:
+ * the guardrail tier is a property of the SCENARIO, so it belongs beside the
+ * duration rather than in a conditional somebody can quietly widen.
+ *
+ * - `act` — the ceiling is an amount we captured, the recipient is the payer,
+ *   and no counterparty is debited. A pre-dispatch cancellation with a full
+ *   refund qualifies; so does writing an anchor, closing a window, or
+ *   BLOCKING a payout (withholding is always safe).
+ * - `escalate` — goods have left the seller, or somebody other than the payer
+ *   is debited, or a prior refund exists. Open a case; a human decides.
+ */
+export type ObligationDueAction = "act" | "escalate";
+export interface ObligationDocument extends BaseDocument {
+    kind: ObligationKind;
+    /** Collection the subject lives in — `orders` for all of today's kinds. */
+    subjectCollection: string;
+    subjectId: string;
+    /**
+     * When it comes due. The ONE field the sweep queries on.
+     *
+     * 🛑 Required, not optional. The sweep filters `dueAt <= now`, and a
+     * Firestore inequality **excludes every document that lacks the field**
+     * (Root Cause #100) — so an optional `dueAt` would make the sweep
+     * structurally unable to see exactly the rows that failed to compute one.
+     */
+    dueAt: Date;
+    state: ObligationState;
+    /** Why it closed. Free text for a human; never parsed. */
+    closeReason?: string;
+    closedAt?: Date;
+    /** Warnings already sent, so a re-run does not re-warn. */
+    warnedAt?: Date[];
+    /**
+     * Mirrors the subject's own flag so the sweep can compress deadlines for a
+     * test fixture **without reading the subject first**.
+     *
+     * 🛑 Per-subject, never global. A global compression would shorten every
+     * live buyer's deadline the moment someone ran the tester.
+     */
+    isTestData?: boolean;
+    /** For the admin detail view, and for a case opened from here. */
+    note?: string;
+}
+export declare const OBLIGATION_FIELDS: {
+    readonly ID: "id";
+    readonly KIND: "kind";
+    readonly SUBJECT_COLLECTION: "subjectCollection";
+    readonly SUBJECT_ID: "subjectId";
+    readonly DUE_AT: "dueAt";
+    readonly STATE: "state";
+    readonly CLOSE_REASON: "closeReason";
+    readonly CLOSED_AT: "closedAt";
+    readonly IS_TEST_DATA: "isTestData";
+};
+/** States from which the sweep still has work to do. */
+export declare const OBLIGATION_ACTIVE_STATES: readonly ObligationState[];
+/**
+ * 🛑 THE IDEMPOTENCY KEY, and the invariant it buys.
+ *
+ * Deterministic `${subjectId}__${kind}` means **at most one open obligation per
+ * (subject, kind)**. A double create is a no-op write rather than a second
+ * timer, which is what makes it safe to reconcile obligations on EVERY order
+ * write — including the many writes that change nothing relevant.
+ *
+ * Double underscore, matching `createClaimedCouponId`'s convention, so a
+ * subject id containing a single underscore cannot collide with a kind.
+ */
+export declare function createObligationId(subjectId: string, kind: ObligationKind): string;
+export declare const ALL_OBLIGATION_KINDS: ObligationKind[];

package/dist/features/obligations/schemas/firestore.js

@@ -0,0 +1,87 @@
+/**
+ * `obligations` — deadlines with money consequences.
+ *
+ * ## Why a mechanism rather than more cron jobs
+ *
+ * The order lifecycle has roughly seventy timer-driven scenarios ("seller never
+ * accepts → auto-cancel + full refund at 3 days", "buyer cancels before
+ * shipping", "return approved but never posted"…). The approach before this was
+ * eight hand-written sweeps whose coverage could only be established by
+ * checking that every pair of `.filter()` predicates agreed — and
+ * Root Cause #27 is that reasoning having already failed at n=3: an order in
+ * `reupload_requested` was excluded by `getExpiredPaymentDeadlines` (it HAS a
+ * proof), by `getUnreviewedProofPastDeadline` (it HAS an outcome) and by
+ * `runPendingOrderTimeout` (it HAS a deadline). Three sweeps, pairwise
+ * disjoint, and the order held stock forever with no terminal state.
+ *
+ * This collection makes "which sweep owns this order" answerable by
+ * construction instead of by three filters happening to agree.
+ *
+ * ## 🛑 IT IS A DUE-DATE INDEX, NOT TRUTH
+ *
+ * The order is authoritative. An obligation row exists so the sweep can FIND
+ * candidates cheaply with one indexed query; having found one it **re-reads the
+ * subject and re-evaluates the policy's `precondition`**, and a row whose
+ * premise no longer holds closes as `superseded` rather than acting.
+ *
+ * That is what keeps this out of the stored-mirror drift class (Root Cause
+ * #42). A row saying "cancel this order at 15:00" is a HINT; the order saying
+ * "I was paid at 14:58" is the fact, and the fact wins.
+ *
+ * ## 🛑 NOT A FIRESTORE TRIGGER
+ *
+ * An `onOrderWrite` trigger that wrote `obligations`, whose sweep then wrote
+ * `orders`, is Root Cause #92's self-write loop exactly — the one that cost
+ * 1,017,548 invocations in 24 hours against a 2M/month free quota, plus a
+ * sibling function woken a million times just to return. Obligations are
+ * reconciled **inside the order's own write**, in `updateWithHistory`, where
+ * the current document is already in hand.
+ */
+export const OBLIGATIONS_COLLECTION = "obligations";
+export const OBLIGATION_FIELDS = {
+    ID: "id",
+    KIND: "kind",
+    SUBJECT_COLLECTION: "subjectCollection",
+    SUBJECT_ID: "subjectId",
+    DUE_AT: "dueAt",
+    STATE: "state",
+    CLOSE_REASON: "closeReason",
+    CLOSED_AT: "closedAt",
+    IS_TEST_DATA: "isTestData",
+};
+/** States from which the sweep still has work to do. */
+export const OBLIGATION_ACTIVE_STATES = ["open"];
+/**
+ * 🛑 THE IDEMPOTENCY KEY, and the invariant it buys.
+ *
+ * Deterministic `${subjectId}__${kind}` means **at most one open obligation per
+ * (subject, kind)**. A double create is a no-op write rather than a second
+ * timer, which is what makes it safe to reconcile obligations on EVERY order
+ * write — including the many writes that change nothing relevant.
+ *
+ * Double underscore, matching `createClaimedCouponId`'s convention, so a
+ * subject id containing a single underscore cannot collide with a kind.
+ */
+export function createObligationId(subjectId, kind) {
+    return `${subjectId}__${kind}`.replace(/[^A-Za-z0-9_.:-]/g, "_").slice(0, 1500);
+}
+/**
+ * Runtime companion, keyed `Record<Union, true>` so both mistakes are compile
+ * errors: a kind added to the union and forgotten here, and a key here that is
+ * not a real kind. An array literal catches neither (Root Cause #61).
+ */
+const OBLIGATION_KIND_MAP = {
+    "seller-accept": true,
+    "seller-dispatch": true,
+    "proof-reupload": true,
+    "delivery-confirm": true,
+    "return-respond": true,
+    "return-post": true,
+    "return-receive": true,
+    "return-inspect": true,
+    "claim-shipping": true,
+    "claim-sale": true,
+    "order-complete": true,
+    "payout-release": true,
+};
+export const ALL_OBLIGATION_KINDS = Object.keys(OBLIGATION_KIND_MAP);

package/dist/features/orders/actions/order-actions.d.ts

@@ -4,9 +4,25 @@
  * Pure business functions — auth, rate-limiting, and Next.js specifics
  * are handled by the calling server action in the consumer.
  */
-import type { OrderDocument } from "../schemas";
+import type { OrderDocument, OrderPlain } from "../schemas";
+import type { CancellationRefundOutcome } from "../types/index";
 import type { TrackingInfo } from "../../../contracts/shipping";
-export declare function cancelOrderForUser(userId: string, orderId: string, reason: string): Promise<void>;
+/**
+ * Cancel a whole order on the buyer's own request.
+ *
+ * 🛑 **Returns the refund outcome now, and used to return `void` (D14).** This
+ * called `orderRepository.cancelOrder(orderId, reason)` — omitting the optional
+ * third argument, as all four callers did — so a *paid* order was cancelled,
+ * its stock restored, and **the money kept**, while
+ * `previewCancellationRefund` had already shown the buyer a figure nothing
+ * honoured.
+ *
+ * Both halves live in `cancelOrderWithRefund`, deliberately not here: passing
+ * the amount alone would only record an intent `cancelOrder` has no code to
+ * settle, which reads in the database as a refund on its way and is worse than
+ * the honest silence it replaces. See that module's header for the full table.
+ */
+export declare function cancelOrderForUser(userId: string, orderId: string, reason: string): Promise<CancellationRefundOutcome>;
 /**
  * Cancels a subset of line items on an already-placed order and lets the rest
  * proceed. Matches today's whole-order cancellation behavior: marks the items
@@ -15,10 +31,33 @@ export declare function cancelOrderForUser(userId: string, orderId: string, reas
  * the order ends up cancelled, falls through to the same whole-order
  * `cancelOrder` path `cancelOrderForUser` uses, rather than leaving a
  * zero-item live order.
+ *
+ * 🛑 Returns `null` on the genuinely-partial path, and an outcome only when it
+ * fell through to cancelling the whole order. That is not a convenience: a
+ * partial cancellation's add-on and per-item refund arithmetic is **D15/D16**
+ * and is not built — it still sets `refundPending: true` and leaves the money
+ * to the admin refund flow, exactly as before. Returning a zero-amount outcome
+ * here would claim a decision had been made about money when none has.
  */
-export declare function cancelOrderItemsForUser(userId: string, orderId: string, itemIds: string[], reason: string): Promise<void>;
+export declare function cancelOrderItemsForUser(userId: string, orderId: string, itemIds: string[], reason: string): Promise<CancellationRefundOutcome | null>;
 export declare function listOrdersForUser(userId: string): Promise<OrderDocument[]>;
-export declare function getOrderByIdForUser(userId: string, orderId: string): Promise<OrderDocument>;
+/**
+ * One order, for the buyer who placed it.
+ *
+ * 🛑 RETURNS PLAINTEXT, and the return TYPE says so. See
+ * `getAddressByIdForUser` for the full reasoning — same defect, same shape.
+ *
+ * `OrderRepository.mapDoc` does not decrypt, so this returned `enc:v1:` blobs
+ * for `userName`, `userEmail` and the `shippingAddress` name and phone, to
+ * the buyer, about their own order. Its caller is a server action that hands
+ * the result straight to the client.
+ *
+ * Revealing here rather than at the caller, because this function is what
+ * knows the read is owner-scoped: it throws `NotFoundError` — not Forbidden,
+ * deliberately, so the response cannot confirm an order exists — for any
+ * order whose `userId` is not the caller's.
+ */
+export declare function getOrderByIdForUser(userId: string, orderId: string): Promise<OrderPlain>;
 /**
  * Retrieve live tracking info for an order via the registered IShippingProvider.
  * Returns null when no shipping provider is registered or no trackingNumber exists.

package/dist/features/orders/actions/order-actions.js

@@ -9,12 +9,28 @@ import { serverLogger } from "../../../monitoring/index.js";
 import { getProviders } from "../../../contracts/index.js";
 import { orderRepository } from "../repository/orders.repository.js";
 import { ORDER_CANCELLABLE_STATUSES } from "../../../_internal/shared/features/orders/config.js";
+import { cancelOrderWithRefund } from "../../../_internal/server/features/orders/cancellation-refund.js";
 const ERR_ORDER_NOT_FOUND = "Order not found";
 function assertCancellable(order) {
     if (!ORDER_CANCELLABLE_STATUSES.includes(order.status)) {
         throw new ValidationError("Only pending or confirmed orders can be cancelled");
     }
 }
+/**
+ * Cancel a whole order on the buyer's own request.
+ *
+ * 🛑 **Returns the refund outcome now, and used to return `void` (D14).** This
+ * called `orderRepository.cancelOrder(orderId, reason)` — omitting the optional
+ * third argument, as all four callers did — so a *paid* order was cancelled,
+ * its stock restored, and **the money kept**, while
+ * `previewCancellationRefund` had already shown the buyer a figure nothing
+ * honoured.
+ *
+ * Both halves live in `cancelOrderWithRefund`, deliberately not here: passing
+ * the amount alone would only record an intent `cancelOrder` has no code to
+ * settle, which reads in the database as a refund on its way and is worse than
+ * the honest silence it replaces. See that module's header for the full table.
+ */
 export async function cancelOrderForUser(userId, orderId, reason) {
     const order = await orderRepository.findById(orderId);
     if (!order)
@@ -22,8 +38,20 @@ export async function cancelOrderForUser(userId, orderId, reason) {
     if (order.userId !== userId)
         throw new AuthorizationError("You are not authorised to cancel this order");
     assertCancellable(order);
-    await orderRepository.cancelOrder(orderId, reason);
-    serverLogger.info("Order cancelled by user", { userId, orderId, reason });
+    const { refund } = await cancelOrderWithRefund(order, {
+        reason,
+        actorUid: userId,
+        actorRole: "buyer",
+        trigger: "cancelOrderForUser",
+    });
+    serverLogger.info("Order cancelled by user", {
+        userId,
+        orderId,
+        reason,
+        refundMoved: refund.moved,
+        refundAmount: refund.amount,
+    });
+    return refund;
 }
 /**
  * Cancels a subset of line items on an already-placed order and lets the rest
@@ -33,6 +61,13 @@ export async function cancelOrderForUser(userId, orderId, reason) {
  * the order ends up cancelled, falls through to the same whole-order
  * `cancelOrder` path `cancelOrderForUser` uses, rather than leaving a
  * zero-item live order.
+ *
+ * 🛑 Returns `null` on the genuinely-partial path, and an outcome only when it
+ * fell through to cancelling the whole order. That is not a convenience: a
+ * partial cancellation's add-on and per-item refund arithmetic is **D15/D16**
+ * and is not built — it still sets `refundPending: true` and leaves the money
+ * to the admin refund flow, exactly as before. Returning a zero-amount outcome
+ * here would claim a decision had been made about money when none has.
  */
 export async function cancelOrderItemsForUser(userId, orderId, itemIds, reason) {
     if (itemIds.length === 0) {
@@ -74,17 +109,39 @@ export async function cancelOrderItemsForUser(userId, orderId, itemIds, reason)
         itemIds: [...matchedIds],
         reason,
     });
+    /*
+     * Explicit, because the declared return type is a union and an implicit
+     * `undefined` is not a member of it. It also says the thing worth saying:
+     * no refund decision was taken here.
+     */
+    return null;
 }
 export async function listOrdersForUser(userId) {
     return orderRepository.findByUser(userId);
 }
+/**
+ * One order, for the buyer who placed it.
+ *
+ * 🛑 RETURNS PLAINTEXT, and the return TYPE says so. See
+ * `getAddressByIdForUser` for the full reasoning — same defect, same shape.
+ *
+ * `OrderRepository.mapDoc` does not decrypt, so this returned `enc:v1:` blobs
+ * for `userName`, `userEmail` and the `shippingAddress` name and phone, to
+ * the buyer, about their own order. Its caller is a server action that hands
+ * the result straight to the client.
+ *
+ * Revealing here rather than at the caller, because this function is what
+ * knows the read is owner-scoped: it throws `NotFoundError` — not Forbidden,
+ * deliberately, so the response cannot confirm an order exists — for any
+ * order whose `userId` is not the caller's.
+ */
 export async function getOrderByIdForUser(userId, orderId) {
     const order = await orderRepository.findById(orderId);
     if (!order)
         throw new NotFoundError(ERR_ORDER_NOT_FOUND);
     if (order.userId !== userId)
         throw new NotFoundError(ERR_ORDER_NOT_FOUND);
-    return order;
+    return orderRepository.revealOrder(order);
 }
 /**
  * Retrieve live tracking info for an order via the registered IShippingProvider.