@mohasinac/appkit 4.62.1 → 4.63.0

package/dist/_internal/server/features/dashboard/data.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The one read a dashboard hub or landing page needs.
+ *
+ * ## 🛑 Read on the SERVER, not fetched from the client
+ *
+ * The plan named an endpoint — `/api/dashboard/attention` — and the shape it
+ * asked for is "one read covering every section", which this is. It is read
+ * here instead because every one of these pages is **already per-request**:
+ * `admin/layout.tsx` and `store/layout.tsx` `await getServerSessionUser()`, so
+ * the whole subtree is dynamic with or without an endpoint (§ "…a dynamic API
+ * in a DASHBOARD layout is the correct lever").
+ *
+ * An endpoint would therefore have added a SECOND billed invocation per hub
+ * visit to fetch data the page's own render could already have, which is
+ * exactly the shape of Root Cause #94 — a client fetch that reads as free in
+ * review and bills per mount. There is no endpoint, and one should not be added
+ * unless something outside a dashboard page needs these numbers.
+ *
+ * ## Two reads, and both fail OPEN
+ *
+ * `navConfig` decides which nav entries an admin has switched off, and the hub
+ * must agree with the sidebar about that — so it is read rather than ignored.
+ * On failure it resolves to `undefined`, which means "nothing is disabled" and
+ * shows MORE cards than it should. That is the right direction: a disabled nav
+ * entry is a configuration choice rather than a permission, and the page behind
+ * every card still enforces its own route guard. Hiding sections because a
+ * settings read blipped would be the damaging failure.
+ *
+ * The counts fail to `null` per card — see `attention.ts`, which exists to
+ * explain why `0` is the one answer a badge must never invent.
+ */
+import { type DashboardHubSection } from "../../../shared/features/dashboard/hub-sections";
+import type { SidebarNavGroup } from "../../../shared/features/layout/types";
+import { type AttentionCounts } from "./attention";
+export interface DashboardHubData {
+    /** Permission- and toggle-filtered, in nav order. Never empty-group padded. */
+    sections: DashboardHubSection[];
+    counts: AttentionCounts;
+}
+/**
+ * Resolve the sections a viewer may see, plus their attention counts.
+ *
+ * @param groups the portal's nav groups, unfiltered — this applies the filter
+ * @param permissions `null` means admin (the convention `filterNavGroups` owns)
+ * @param storeId the viewer's store SLUG, for seller-scoped counts
+ */
+export declare function getDashboardHubData(groups: readonly SidebarNavGroup[], permissions: string[] | null | undefined, storeId?: string): Promise<DashboardHubData>;

package/dist/_internal/server/features/dashboard/data.js

@@ -0,0 +1,82 @@
+/**
+ * The one read a dashboard hub or landing page needs.
+ *
+ * ## 🛑 Read on the SERVER, not fetched from the client
+ *
+ * The plan named an endpoint — `/api/dashboard/attention` — and the shape it
+ * asked for is "one read covering every section", which this is. It is read
+ * here instead because every one of these pages is **already per-request**:
+ * `admin/layout.tsx` and `store/layout.tsx` `await getServerSessionUser()`, so
+ * the whole subtree is dynamic with or without an endpoint (§ "…a dynamic API
+ * in a DASHBOARD layout is the correct lever").
+ *
+ * An endpoint would therefore have added a SECOND billed invocation per hub
+ * visit to fetch data the page's own render could already have, which is
+ * exactly the shape of Root Cause #94 — a client fetch that reads as free in
+ * review and bills per mount. There is no endpoint, and one should not be added
+ * unless something outside a dashboard page needs these numbers.
+ *
+ * ## Two reads, and both fail OPEN
+ *
+ * `navConfig` decides which nav entries an admin has switched off, and the hub
+ * must agree with the sidebar about that — so it is read rather than ignored.
+ * On failure it resolves to `undefined`, which means "nothing is disabled" and
+ * shows MORE cards than it should. That is the right direction: a disabled nav
+ * entry is a configuration choice rather than a permission, and the page behind
+ * every card still enforces its own route guard. Hiding sections because a
+ * settings read blipped would be the damaging failure.
+ *
+ * The counts fail to `null` per card — see `attention.ts`, which exists to
+ * explain why `0` is the one answer a badge must never invent.
+ */
+import { cache } from "react";
+import { safeRead } from "../../../../errors/safe-read.js";
+import { siteSettingsRepository } from "../../../../features/admin/repository/site-settings.repository.js";
+import { filterNavGroups } from "../../../client/features/layout/filterNavItems.js";
+import { hubSections, } from "../../../shared/features/dashboard/hub-sections.js";
+import { collectAttentionCounts } from "./attention.js";
+/**
+ * `navConfig` alone, cached per request.
+ *
+ * `React.cache` because a landing page renders the hub once but a hub page may
+ * also want the section list for its own heading, and the narrowest shared call
+ * is the one to cache (§ "`React.cache` discipline" — cache the repository
+ * read, not the viewer-specific wrapper around it, or two call sites with
+ * different arguments dedupe nothing).
+ */
+const getNavConfig = cache(async () => safeRead(async () => {
+    const settings = (await siteSettingsRepository.getSingleton());
+    return settings?.navConfig;
+}, {
+    route: "dashboard-hub",
+    key: "navConfig",
+    fallback: undefined,
+}));
+/**
+ * Resolve the sections a viewer may see, plus their attention counts.
+ *
+ * @param groups the portal's nav groups, unfiltered — this applies the filter
+ * @param permissions `null` means admin (the convention `filterNavGroups` owns)
+ * @param storeId the viewer's store SLUG, for seller-scoped counts
+ */
+export async function getDashboardHubData(groups, permissions, storeId) {
+    const navConfig = await getNavConfig();
+    /*
+     * Filter FIRST, then count — the visible ids are the scope (see
+     * `collectAttentionCounts`). Doing it the other way round costs an employee
+     * five queries to render one card, and computes figures from collections
+     * their permission set does not cover.
+     *
+     * Sequential rather than parallel with the settings read for the same
+     * reason: the second call's input is the first call's output. Two
+     * round trips, inside Rule #6's ~3.
+     */
+    const sections = hubSections(filterNavGroups([...groups], navConfig, permissions));
+    const visibleItemIds = sections.flatMap((s) => s.items.map((i) => i.id).filter(Boolean));
+    const counts = await safeRead(() => collectAttentionCounts(visibleItemIds, storeId), {
+        route: "dashboard-hub",
+        key: "attention",
+        fallback: {},
+    });
+    return { sections, counts };
+}

package/dist/_internal/server/features/inventory/reservations.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Hold stock for something that is not an order yet.
+ *
+ * ## What this is for
+ *
+ * The plan's Part 6 (shared purchase) names this "the largest hidden cost",
+ * and it is the only one of its three prerequisites that had NOTHING behind
+ * it. See the schema file for why the existing order-keyed mechanism cannot
+ * serve a multi-day arrangement.
+ *
+ * ## 🛑 Every function here moves the row and the counter TOGETHER
+ *
+ * `availableQuantity` is what a buyer can take; the gap between it and
+ * `stockQuantity` is the outstanding hold (`resolveStockResync`'s own words).
+ * A reservation row written without the decrement holds nothing at all, and a
+ * decrement written without a row is a hold nothing can expire — so both
+ * happen inside ONE `runTransaction`, with the product read inside it so two
+ * concurrent reserves cannot both see the same `availableQuantity`.
+ *
+ * ## 🛑 Firestore wants every READ before every WRITE
+ *
+ * So `endReservation` reads the reservation AND the product up front, even
+ * on the consume path where the product read is thrown away. The natural
+ * shape — read the reservation, decide, then read the product — throws
+ * `Firestore transactions require all reads to be executed before all
+ * writes`, and only at runtime, which is exactly the class of fault
+ * `restoreStockForOrder`'s header already warns about one directory over.
+ *
+ * ## Why it writes `availableQuantity` EXPLICITLY
+ *
+ * `ProductRepository.update`'s `resolveStockResync` returns `{}` the moment a
+ * write names `availableQuantity` — deliberately, so the checkout decrement,
+ * the stock-restore job and `updateAvailableQuantity` stay authoritative over
+ * their own number. This is a fourth member of that set and takes the same
+ * deal: it is the one deciding the value, so the resync must keep its hands
+ * off it. (These writes go through the raw collection rather than the
+ * repository for the same reason `deriveTaxonomy` reads categories through
+ * `this.db` — a transaction needs the ref, not a repository method.)
+ */
+import { type ReservationHolderKind, type StockReservationDocument } from "../../../../features/inventory/schemas/stock-reservation";
+export interface ReserveStockInput {
+    productId: string;
+    quantity: number;
+    holderKind: ReservationHolderKind;
+    holderId: string;
+    createdBy: string;
+    /** Defaults to `RESERVATION_DEFAULT_TTL_HOURS`; capped at the 30-day ceiling. */
+    ttlHours?: number;
+}
+/**
+ * Take a hold. Returns the reservation id.
+ *
+ * 🛑 Refuses rather than over-reserving. A seller's stock is a real number of
+ * real objects, so "reserve 5, only 3 left" is a **409** — the request is
+ * well-formed and the world moved, which is the same distinction the lottery
+ * config write makes for a slot somebody has already pulled.
+ */
+export declare function reserveStock(input: ReserveStockInput): Promise<string>;
+/**
+ * End a hold and PUT THE UNITS BACK — the holder changed their mind, an admin
+ * took it back, or the sweep found it expired.
+ */
+export declare function releaseReservation(reservationId: string, opts?: {
+    status?: "released" | "expired";
+    reason?: string;
+}): Promise<void>;
+/**
+ * End a hold and KEEP the units off the shelf — the arrangement completed and
+ * an order now owns them.
+ *
+ * 🛑 This is the one path that must NOT restore. The order's own decrement is
+ * what holds the units from here, so restoring first would hand the same
+ * stock to the next buyer for the moment between the two writes — and if the
+ * order write never lands, restoring would have been right. That race is why
+ * the caller should place the order and consume in one flow it can reason
+ * about; this function exists so it can do that rather than calling release
+ * and hoping.
+ */
+export declare function consumeReservation(reservationId: string): Promise<void>;
+/**
+ * Release every hold a holder owns. Used when a shared purchase is cancelled
+ * or abandoned — the arrangement knows its own id, and should not have to
+ * remember which reservations it took.
+ */
+export declare function releaseReservationsForHolder(holderKind: ReservationHolderKind, holderId: string, reason?: string): Promise<number>;
+/**
+ * The sweep. Expire every hold past its `expiresAt` and restore its units.
+ *
+ * 🛑 Bounded, and the bound is REPORTED. A silent cap reads as "nothing left
+ * to expire" on the one run where it mattered — the same lie a truncated
+ * recount tells (Root Cause #102).
+ */
+export declare function expireDueReservations(limit?: number): Promise<{
+    scanned: number;
+    expired: number;
+    truncated: boolean;
+}>;
+/** Units currently held on a product, for an admin explaining an unbuyable listing. */
+export declare function activeReservationsForProduct(productId: string): Promise<StockReservationDocument[]>;

package/dist/_internal/server/features/inventory/reservations.js

@@ -0,0 +1,273 @@
+/**
+ * Hold stock for something that is not an order yet.
+ *
+ * ## What this is for
+ *
+ * The plan's Part 6 (shared purchase) names this "the largest hidden cost",
+ * and it is the only one of its three prerequisites that had NOTHING behind
+ * it. See the schema file for why the existing order-keyed mechanism cannot
+ * serve a multi-day arrangement.
+ *
+ * ## 🛑 Every function here moves the row and the counter TOGETHER
+ *
+ * `availableQuantity` is what a buyer can take; the gap between it and
+ * `stockQuantity` is the outstanding hold (`resolveStockResync`'s own words).
+ * A reservation row written without the decrement holds nothing at all, and a
+ * decrement written without a row is a hold nothing can expire — so both
+ * happen inside ONE `runTransaction`, with the product read inside it so two
+ * concurrent reserves cannot both see the same `availableQuantity`.
+ *
+ * ## 🛑 Firestore wants every READ before every WRITE
+ *
+ * So `endReservation` reads the reservation AND the product up front, even
+ * on the consume path where the product read is thrown away. The natural
+ * shape — read the reservation, decide, then read the product — throws
+ * `Firestore transactions require all reads to be executed before all
+ * writes`, and only at runtime, which is exactly the class of fault
+ * `restoreStockForOrder`'s header already warns about one directory over.
+ *
+ * ## Why it writes `availableQuantity` EXPLICITLY
+ *
+ * `ProductRepository.update`'s `resolveStockResync` returns `{}` the moment a
+ * write names `availableQuantity` — deliberately, so the checkout decrement,
+ * the stock-restore job and `updateAvailableQuantity` stay authoritative over
+ * their own number. This is a fourth member of that set and takes the same
+ * deal: it is the one deciding the value, so the resync must keep its hands
+ * off it. (These writes go through the raw collection rather than the
+ * repository for the same reason `deriveTaxonomy` reads categories through
+ * `this.db` — a transaction needs the ref, not a repository method.)
+ */
+import { getAdminDb } from "../../../../providers/db-firebase/index.js";
+import { ValidationError } from "../../../../errors/validation-error.js";
+import { NotFoundError } from "../../../../errors/not-found-error.js";
+import { ConflictError } from "../../../../errors/conflict-error.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+import { PRODUCT_COLLECTION } from "../../../../features/products/schemas/firestore.js";
+import { STOCK_RESERVATION_FIELDS } from "../../../../constants/field-names.js";
+import { RESERVATION_DEFAULT_TTL_HOURS, RESERVATION_MAX_TTL_HOURS, STOCK_RESERVATION_COLLECTION, } from "../../../../features/inventory/schemas/stock-reservation.js";
+/**
+ * Take a hold. Returns the reservation id.
+ *
+ * 🛑 Refuses rather than over-reserving. A seller's stock is a real number of
+ * real objects, so "reserve 5, only 3 left" is a **409** — the request is
+ * well-formed and the world moved, which is the same distinction the lottery
+ * config write makes for a slot somebody has already pulled.
+ */
+export async function reserveStock(input) {
+    const quantity = Math.floor(input.quantity);
+    if (!Number.isFinite(quantity) || quantity < 1) {
+        throw new ValidationError("Reserve at least one unit.");
+    }
+    const ttlHours = clampTtl(input.ttlHours);
+    const db = getAdminDb();
+    const productRef = db.collection(PRODUCT_COLLECTION).doc(input.productId);
+    const reservationRef = db.collection(STOCK_RESERVATION_COLLECTION).doc();
+    await db.runTransaction(async (tx) => {
+        const snap = await tx.get(productRef);
+        if (!snap.exists)
+            throw new NotFoundError("Product not found.");
+        const available = readAvailable(snap.data());
+        if (available < quantity) {
+            throw new ConflictError(`Only ${Math.max(0, available)} left — cannot hold ${quantity}.`);
+        }
+        const now = new Date();
+        const doc = {
+            productId: input.productId,
+            quantity,
+            holderKind: input.holderKind,
+            holderId: input.holderId,
+            createdBy: input.createdBy,
+            status: "held",
+            expiresAt: new Date(now.getTime() + ttlHours * 60 * 60 * 1000),
+            createdAt: now,
+            updatedAt: now,
+        };
+        tx.set(reservationRef, doc);
+        tx.update(productRef, { availableQuantity: available - quantity, updatedAt: now });
+    });
+    return reservationRef.id;
+}
+/**
+ * End a hold and PUT THE UNITS BACK — the holder changed their mind, an admin
+ * took it back, or the sweep found it expired.
+ */
+export async function releaseReservation(reservationId, opts = {}) {
+    await endReservation(reservationId, opts.status ?? "released", true, opts.reason);
+}
+/**
+ * End a hold and KEEP the units off the shelf — the arrangement completed and
+ * an order now owns them.
+ *
+ * 🛑 This is the one path that must NOT restore. The order's own decrement is
+ * what holds the units from here, so restoring first would hand the same
+ * stock to the next buyer for the moment between the two writes — and if the
+ * order write never lands, restoring would have been right. That race is why
+ * the caller should place the order and consume in one flow it can reason
+ * about; this function exists so it can do that rather than calling release
+ * and hoping.
+ */
+export async function consumeReservation(reservationId) {
+    await endReservation(reservationId, "consumed", false);
+}
+/**
+ * Release every hold a holder owns. Used when a shared purchase is cancelled
+ * or abandoned — the arrangement knows its own id, and should not have to
+ * remember which reservations it took.
+ */
+export async function releaseReservationsForHolder(holderKind, holderId, reason) {
+    const db = getAdminDb();
+    const snap = await db
+        .collection(STOCK_RESERVATION_COLLECTION)
+        .where(STOCK_RESERVATION_FIELDS.HOLDER_KIND, "==", holderKind)
+        .where(STOCK_RESERVATION_FIELDS.HOLDER_ID, "==", holderId)
+        .where(STOCK_RESERVATION_FIELDS.STATUS, "==", "held")
+        .get();
+    let released = 0;
+    for (const doc of snap.docs) {
+        try {
+            await endReservation(doc.id, "released", true, reason);
+            released += 1;
+        }
+        catch (error) {
+            const normalized = normalizeError(error);
+            /*
+             * One bad row must not strand the rest. A holder with eight holds and
+             * one deleted product should still get the other seven back.
+             */
+            serverLogger.warn("releaseReservationsForHolder: skipped one", {
+                reservationId: doc.id,
+                message: normalized.message,
+            });
+        }
+    }
+    return released;
+}
+/**
+ * The sweep. Expire every hold past its `expiresAt` and restore its units.
+ *
+ * 🛑 Bounded, and the bound is REPORTED. A silent cap reads as "nothing left
+ * to expire" on the one run where it mattered — the same lie a truncated
+ * recount tells (Root Cause #102).
+ */
+export async function expireDueReservations(limit = 200) {
+    const db = getAdminDb();
+    const snap = await db
+        .collection(STOCK_RESERVATION_COLLECTION)
+        .where(STOCK_RESERVATION_FIELDS.STATUS, "==", "held")
+        .where(STOCK_RESERVATION_FIELDS.EXPIRES_AT, "<=", new Date())
+        .orderBy(STOCK_RESERVATION_FIELDS.EXPIRES_AT, "asc")
+        .limit(limit)
+        .get();
+    let expired = 0;
+    for (const doc of snap.docs) {
+        try {
+            await endReservation(doc.id, "expired", true, "TTL elapsed");
+            expired += 1;
+        }
+        catch (error) {
+            const normalized = normalizeError(error);
+            serverLogger.warn("expireDueReservations: skipped one", {
+                reservationId: doc.id,
+                message: normalized.message,
+            });
+        }
+    }
+    return { scanned: snap.size, expired, truncated: snap.size === limit };
+}
+/** Units currently held on a product, for an admin explaining an unbuyable listing. */
+export async function activeReservationsForProduct(productId) {
+    const db = getAdminDb();
+    const snap = await db
+        .collection(STOCK_RESERVATION_COLLECTION)
+        .where(STOCK_RESERVATION_FIELDS.PRODUCT_ID, "==", productId)
+        .where(STOCK_RESERVATION_FIELDS.STATUS, "==", "held")
+        .get();
+    return snap.docs.map((d) => ({ id: d.id, ...d.data() }));
+}
+function clampTtl(hours) {
+    if (hours === undefined)
+        return RESERVATION_DEFAULT_TTL_HOURS;
+    if (!Number.isFinite(hours) || hours <= 0) {
+        throw new ValidationError("A hold must last longer than zero hours.");
+    }
+    return Math.min(hours, RESERVATION_MAX_TTL_HOURS);
+}
+/**
+ * 🛑 `?? stockQuantity` and NOT `?? 0`.
+ *
+ * `availableQuantity` is optional on rows written before it existed, and
+ * treating an absent value as zero would refuse every reservation on a
+ * fully-stocked legacy listing — a sold-out answer for a product that has
+ * stock, which reads as a stock bug rather than a schema gap.
+ */
+function readAvailable(data) {
+    const product = (data ?? {});
+    return product.availableQuantity ?? product.stockQuantity ?? 0;
+}
+/**
+ * The one write path. Every transition goes through here so the
+ * row-and-counter pairing cannot be forgotten by a new caller — the same
+ * argument `deriveLinePrice` makes inside the cart repository.
+ */
+async function endReservation(reservationId, status, restore, reason) {
+    const db = getAdminDb();
+    const reservationRef = db.collection(STOCK_RESERVATION_COLLECTION).doc(reservationId);
+    await db.runTransaction(async (tx) => {
+        const snap = await tx.get(reservationRef);
+        if (!snap.exists)
+            throw new NotFoundError("Reservation not found.");
+        const reservation = snap.data();
+        /*
+         * 🛑 Idempotent by STATUS, not by a flag. The sweep and a manual release
+         * can reach the same row in the same second; a second restore would
+         * invent units that do not exist, which is worse than a hold that lingers
+         * one sweep longer.
+         */
+        if (reservation.status !== "held")
+            return;
+        /*
+         * Read the product BEFORE the first write, even when `restore` is false
+         * and the value is discarded — see this file's header. One wasted read on
+         * the consume path buys a function whose transaction shape cannot be
+         * broken by a later edit reordering the branches.
+         */
+        const productRef = db.collection(PRODUCT_COLLECTION).doc(reservation.productId);
+        const productSnap = restore ? await tx.get(productRef) : null;
+        const now = new Date();
+        tx.update(reservationRef, {
+            status,
+            endedAt: now,
+            updatedAt: now,
+            ...(reason ? { endedReason: reason } : {}),
+        });
+        if (!restore)
+            return;
+        if (!productSnap?.exists) {
+            /*
+             * The product is gone, so there is no counter to restore — but the row
+             * still has to close, or the sweep retries it forever. Recorded rather
+             * than thrown: an orphaned hold is a data problem, not a reason to fail
+             * the release of the others beside it.
+             */
+            serverLogger.warn("endReservation: product missing, counter not restored", {
+                reservationId,
+                productId: reservation.productId,
+            });
+            return;
+        }
+        const product = productSnap.data();
+        const available = readAvailable(product);
+        const stock = product.stockQuantity ?? available;
+        /*
+         * 🛑 Clamped at `stockQuantity`. A seller who lowered stock while units
+         * were held would otherwise get an `availableQuantity` ABOVE their own
+         * stock on release — a listing offering more than exists, which is the
+         * one direction a stock bug must never go.
+         */
+        tx.update(productRef, {
+            availableQuantity: Math.min(stock, available + reservation.quantity),
+            updatedAt: now,
+        });
+    });
+}

package/dist/_internal/server/features/offers/destinations.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Server-side verification that a coordinated purchase's destinations are real
+ * and belong to the people naming them.
+ *
+ * ## 🛑 Why this file exists at all
+ *
+ * `CoordinationMember.destinationAddressId` is a REFERENCE, which is the right
+ * shape — copying the address inline would put a name, a phone number and a
+ * street into an offer document with no encryption story and no retention
+ * story. But a reference has a failure mode a copy does not:
+ *
+ * **An id is guessable in a way an address is not.** Without this check a
+ * member supplies any `addresses` document id and the parcel ships to a
+ * stranger's house, at the coordinator's expense, with every other part of
+ * the flow behaving correctly. Nothing errors; the order is valid; the goods
+ * simply go somewhere nobody chose.
+ *
+ * So the rule is: **an id that crosses the wire is never trusted, and is
+ * resolved against its claimed owner before anything is written.**
+ */
+import type { CoordinationMember } from "../../../shared/features/offers/coordination";
+/**
+ * Every named destination must exist and belong to the member who named it.
+ *
+ * 🛑 **Owned by THAT MEMBER, not merely by someone.** Checking only that the
+ * address exists and has `ownerType: "user"` would let a member ship to any
+ * other user's saved address — the weaker check reads as a real one and
+ * closes nothing.
+ *
+ * 🛑 **Fails the whole request, naming the member.** Dropping a bad
+ * destination and shipping that member's parcel to the coordinator instead
+ * would be a silent substitution of somebody's delivery address, which is
+ * exactly the class of quiet wrongness this check exists to prevent. Grouped
+ * cart lines take the same position for the same reason.
+ *
+ * One `getAll` over the distinct ids, not one read per member: five members
+ * sharing two destinations is two reads, and Rule #6's budget is per request
+ * rather than per member.
+ */
+export declare function assertOwnedAddresses(members: readonly CoordinationMember[]): Promise<void>;

package/dist/_internal/server/features/offers/destinations.js

@@ -0,0 +1,65 @@
+/**
+ * Server-side verification that a coordinated purchase's destinations are real
+ * and belong to the people naming them.
+ *
+ * ## 🛑 Why this file exists at all
+ *
+ * `CoordinationMember.destinationAddressId` is a REFERENCE, which is the right
+ * shape — copying the address inline would put a name, a phone number and a
+ * street into an offer document with no encryption story and no retention
+ * story. But a reference has a failure mode a copy does not:
+ *
+ * **An id is guessable in a way an address is not.** Without this check a
+ * member supplies any `addresses` document id and the parcel ships to a
+ * stranger's house, at the coordinator's expense, with every other part of
+ * the flow behaving correctly. Nothing errors; the order is valid; the goods
+ * simply go somewhere nobody chose.
+ *
+ * So the rule is: **an id that crosses the wire is never trusted, and is
+ * resolved against its claimed owner before anything is written.**
+ */
+import { addressesRepository } from "../../../../features/addresses/repository/addresses.repository.js";
+import { ValidationError } from "../../../../errors/validation-error.js";
+/**
+ * Every named destination must exist and belong to the member who named it.
+ *
+ * 🛑 **Owned by THAT MEMBER, not merely by someone.** Checking only that the
+ * address exists and has `ownerType: "user"` would let a member ship to any
+ * other user's saved address — the weaker check reads as a real one and
+ * closes nothing.
+ *
+ * 🛑 **Fails the whole request, naming the member.** Dropping a bad
+ * destination and shipping that member's parcel to the coordinator instead
+ * would be a silent substitution of somebody's delivery address, which is
+ * exactly the class of quiet wrongness this check exists to prevent. Grouped
+ * cart lines take the same position for the same reason.
+ *
+ * One `getAll` over the distinct ids, not one read per member: five members
+ * sharing two destinations is two reads, and Rule #6's budget is per request
+ * rather than per member.
+ */
+export async function assertOwnedAddresses(members) {
+    const named = members.filter((m) => !!m.destinationAddressId);
+    if (named.length === 0)
+        return;
+    const ids = [...new Set(named.map((m) => m.destinationAddressId))];
+    const docs = await Promise.all(ids.map((id) => addressesRepository.findById(id)));
+    const byId = new Map(ids.map((id, i) => [id, docs[i]]));
+    for (const member of named) {
+        const address = byId.get(member.destinationAddressId);
+        /*
+         * 🛑 ONE message for "does not exist" and "is not yours".
+         *
+         * Distinguishing them turns this endpoint into an oracle for which
+         * `addresses` ids are real — a caller probes ids and reads existence off
+         * the error text. The member who typed a genuinely stale id and the
+         * member probing somebody else's get the same answer, and only the first
+         * of those has a legitimate next step anyway (pick again).
+         */
+        if (!address || address.ownerType !== "user" || address.ownerId !== member.uid) {
+            throw new ValidationError("A chosen delivery address is not available.", {
+                destinationAddressId: `${member.uid}: that address cannot be used.`,
+            });
+        }
+    }
+}

package/dist/_internal/server/features/orders/adapters.js

@@ -346,6 +346,27 @@ export function orderDocumentToOrder(doc) {
         timelineTruncated: doc.statusHistoryTruncated,
         /** How the buyer acquired the right to buy. Written once, at creation. */
         sourceContext: doc.sourceContext,
+        /*
+         * D55 — the pre-order balance, present only once a seller has opened it.
+         *
+         * 🛑 `reviewedBy` is deliberately NOT mapped. It is the reviewing staff
+         * member's uid and no buyer surface reads it, so it stays server-side by
+         * default (§ Public Data Projections — a field is private until someone
+         * names the client that reads it).
+         */
+        balance: doc.balance
+            ? {
+                amount: doc.balance.amount,
+                method: doc.balance.method,
+                status: doc.balance.status,
+                dueBy: toIsoOrUndefined(doc.balance.dueBy),
+                proofUrl: doc.balance.proofUrl,
+                transactionId: doc.balance.transactionId,
+                submittedAt: toIsoOrUndefined(doc.balance.submittedAt),
+                reviewedAt: toIsoOrUndefined(doc.balance.reviewedAt),
+                reviewNote: doc.balance.reviewNote,
+            }
+            : undefined,
         createdAt: doc.createdAt instanceof Date
             ? doc.createdAt.toISOString()
             : String(doc.createdAt),