@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/features/seller/schemas/order-forms.js

@@ -92,15 +92,48 @@ export const sellerOrderUpdateSchema = z
  * it is also called directly from a server action, where no route ran first.
  */
 /**
- * Manual shipment entry. `method` is a literal rather than an enum because
- * `ManualShippingProvider` is the only provider — see § "Provider Resolution".
+ * Shipment entry — manual, or booked through the platform.
+ *
+ * 🛑 **`method` was `z.literal("custom")`, and that literal WAS bug 0e.**
+ *
+ * Its comment said *"a literal rather than an enum because
+ * `ManualShippingProvider` is the only provider"* — no longer true:
+ * `providers/shipping-shiprocket/` is 570 lines with all six methods, and
+ * `providers.config.ts` already resolves it from
+ * `siteSettings.shipping.provider`. The seller simply could not EXPRESS
+ * "book this through us", so there was no option to offer, and
+ * `platformBookedShipment` — which `order-math.ts` gates reimbursement on —
+ * had zero writers.
+ *
+ * A DISCRIMINATED UNION rather than an enum plus optional fields, because
+ * the two branches need different things and an optional-everything shape
+ * cannot say so:
+ *
+ * · `custom` — the seller posted it and types the carrier and tracking id.
+ *   Those are REQUIRED, which is the rule enforced in three places today.
+ * · `platform` — we book it, so there is no tracking id to type; it comes
+ *   back from the carrier. Requiring one here would be asking the seller to
+ *   invent the thing the booking produces.
  */
-export const shipOrderSchema = z.object({
-    method: z.literal("custom"),
-    shippingCarrier: z.string().min(1),
-    trackingNumber: z.string().min(1),
-    trackingUrl: z.string().url(),
-});
+export const shipOrderSchema = z.discriminatedUnion("method", [
+    z.object({
+        method: z.literal("custom"),
+        shippingCarrier: z.string().min(1),
+        trackingNumber: z.string().min(1),
+        trackingUrl: z.string().url(),
+    }),
+    z.object({
+        method: z.literal("platform"),
+        /* The store address the courier collects from. */
+        pickupAddressId: z.string().min(1),
+        dimensions: z.object({
+            weight: z.number().positive().max(50),
+            length: z.number().positive().max(200),
+            width: z.number().positive().max(200),
+            height: z.number().positive().max(200),
+        }),
+    }),
+]);
 /**
  * Marking one EMI installment paid. `installmentIndex` is 1-based, matching
  * how the schedule is presented to the buyer.

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

@@ -43,7 +43,32 @@ export interface ShipmentTotals {
 export declare const DEFAULT_SHIPMENT_TOTALS: ShipmentTotals;
 export interface ShipmentDocument extends BaseDocument {
     shipmentNumber: string;
+    /**
+     * The supplier as TYPED. Kept, and kept required, for display.
+     *
+     * 🛑 It is free text, so four shipments from one supplier are four
+     * unjoined strings — "Acme Toys", "acme toys", "Acme Toys Ltd", "ACME".
+     * Nothing can total what we have spent with anyone, which is the first
+     * question anybody asks of procurement data.
+     */
     supplierName: string;
+    /**
+     * The joinable identity — a `vendors` row.
+     *
+     * 🛑 OPTIONAL, and that is deliberate rather than a migration left half
+     * done. Every existing shipment has only the string, and backfilling by
+     * fuzzy-matching names is precisely how two real suppliers get merged into
+     * one spend figure that nobody can unpick afterwards. A shipment gains an
+     * id when a human links it; until then it is honestly unattributed, and
+     * the vendor report can say how many are.
+     *
+     * 🛑 The NAME is not derived from the vendor row on read. Two reasons: a
+     * vendor rename would retroactively rewrite what every past shipment says
+     * it was bought from, and the typed string is evidence of what the invoice
+     * actually said. Same stance the order item's frozen listing snapshot
+     * takes (Part 14).
+     */
+    supplierId?: string;
     originCountry?: string;
     status: ShipmentStatus;
     trackingNumber?: string;

package/dist/features/shipments/schemas/validation.d.ts

@@ -15,7 +15,7 @@ export declare const createShipmentSchema: z.ZodObject<{
     laborRatePerHour: z.ZodOptional<z.ZodNumber>;
     notes: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    status: "received" | "completed" | "processing" | "cancelled" | "ordered" | "in_transit" | "planning" | "customs";
+    status: "received" | "completed" | "processing" | "cancelled" | "in_transit" | "ordered" | "planning" | "customs";
     shipmentNumber: string;
     supplierName: string;
     customsTotal: number;
@@ -29,7 +29,7 @@ export declare const createShipmentSchema: z.ZodObject<{
     laborHoursSpent?: number | undefined;
     laborRatePerHour?: number | undefined;
 }, {
-    status: "received" | "completed" | "processing" | "cancelled" | "ordered" | "in_transit" | "planning" | "customs";
+    status: "received" | "completed" | "processing" | "cancelled" | "in_transit" | "ordered" | "planning" | "customs";
     shipmentNumber: string;
     supplierName: string;
     customsTotal: number;
@@ -58,7 +58,7 @@ export declare const updateShipmentSchema: z.ZodObject<{
     laborRatePerHour: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
     notes: z.ZodOptional<z.ZodOptional<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
-    status?: "received" | "completed" | "processing" | "cancelled" | "ordered" | "in_transit" | "planning" | "customs" | undefined;
+    status?: "received" | "completed" | "processing" | "cancelled" | "in_transit" | "ordered" | "planning" | "customs" | undefined;
     trackingNumber?: string | undefined;
     notes?: string | undefined;
     carrier?: string | undefined;
@@ -72,7 +72,7 @@ export declare const updateShipmentSchema: z.ZodObject<{
     laborHoursSpent?: number | undefined;
     laborRatePerHour?: number | undefined;
 }, {
-    status?: "received" | "completed" | "processing" | "cancelled" | "ordered" | "in_transit" | "planning" | "customs" | undefined;
+    status?: "received" | "completed" | "processing" | "cancelled" | "in_transit" | "ordered" | "planning" | "customs" | undefined;
     trackingNumber?: string | undefined;
     notes?: string | undefined;
     carrier?: string | undefined;

package/dist/features/shipping-boxes/repository/shipping-boxes.repository.d.ts

@@ -0,0 +1,82 @@
+import type { FirebaseSieveFields, FirebaseSieveResult, SieveModel } from "../../../providers/db-firebase";
+import { BaseRepository } from "../../../providers/db-firebase";
+import { type ShippingBoxDocument } from "../schemas/firestore";
+/**
+ * The shared carton library. See the schema header for why it is global.
+ */
+export declare class ShippingBoxesRepository extends BaseRepository<ShippingBoxDocument> {
+    static readonly SIEVE_FIELDS: FirebaseSieveFields;
+    constructor();
+    /**
+     * The picker's list. Active only, by name.
+     *
+     * 🛑 Retired presets are excluded here and NOT deleted, so a draft shipment
+     * holding one does not lose it mid-dispatch.
+     */
+    listActive(model: SieveModel): Promise<FirebaseSieveResult<ShippingBoxDocument>>;
+    /**
+     * Create a preset, keyed on a slug of its name.
+     *
+     * 🛑 `box-<slug>` as the document id, so the SAME carton name cannot be added
+     * twice by two sellers. That is the whole value of a shared library — two
+     * rows called "Standard carton" with different numbers is worse than one
+     * row, because the picker gives no way to tell them apart.
+     *
+     * A colliding create is reported to the caller rather than silently
+     * overwriting: the existing row has an author and may be in use, and the
+     * second seller's intent ("I want a preset for this") is already satisfied
+     * by the row that exists.
+     */
+    createPreset(input: {
+        name: string;
+        length: number;
+        width: number;
+        height: number;
+        tareWeight?: number;
+        createdByUid: string;
+        createdByName: string;
+    }): Promise<{
+        box: ShippingBoxDocument;
+        created: boolean;
+    }>;
+    /**
+     * Every preset, retired included — the staff management list.
+     *
+     * Separate from `listActive` for the same reason the dispute reasons are: the
+     * picker must never offer a retired row, and a management view must be able
+     * to find one in order to put it back.
+     */
+    listAll(model: SieveModel): Promise<FirebaseSieveResult<ShippingBoxDocument>>;
+    /**
+     * Correct a preset's dimensions. **Staff only** — enforced at the route.
+     *
+     * ## 🛑 This does NOT change any dispatched parcel, by construction
+     *
+     * The dimensions are COPIED onto the shipment at use time (the schema's own
+     * header: *"a preset is a DEFAULT, never a lock"*), so there is no stored
+     * reference for this to reach through. That is precisely why staff editing is
+     * safe to offer at all: a seller's past declaration is a snapshot, and the
+     * courier billed against the figures at dispatch.
+     *
+     * It is staff-only for the mirror reason — these numbers are what the NEXT
+     * seller's dispatch form defaults to, so a wrong edit misdeclares other
+     * people's parcels. A seller who finds a preset wrong adds a new one; staff
+     * decide whether the shared row changes.
+     *
+     * 🛑 The NAME is deliberately not editable. The id is `box-<slug of name>`,
+     * so renaming would either leave the id disagreeing with the name (the
+     * mirror-drift trap) or require a new document, which is just a create. Add
+     * the correctly-named preset and retire this one.
+     */
+    updatePreset(id: string, input: {
+        length?: number;
+        width?: number;
+        height?: number;
+        tareWeight?: number;
+    }): Promise<void>;
+    /** Soft-retire. See the schema for why this is never a delete. */
+    retire(id: string): Promise<void>;
+    /** Put a retired preset back in the picker. */
+    reactivate(id: string): Promise<void>;
+}
+export declare const shippingBoxesRepository: ShippingBoxesRepository;

package/dist/features/shipping-boxes/repository/shipping-boxes.repository.js

@@ -0,0 +1,145 @@
+import { BaseRepository } from "../../../providers/db-firebase/index.js";
+import { slugify } from "../../../utils/string.formatter.js";
+import { SHIPPING_BOX_COLLECTION, SHIPPING_BOX_FIELDS, SHIPPING_BOX_LIMITS, } from "../schemas/firestore.js";
+/**
+ * The shared carton library. See the schema header for why it is global.
+ */
+export class ShippingBoxesRepository extends BaseRepository {
+    constructor() {
+        super(SHIPPING_BOX_COLLECTION);
+    }
+    /**
+     * The picker's list. Active only, by name.
+     *
+     * 🛑 Retired presets are excluded here and NOT deleted, so a draft shipment
+     * holding one does not lose it mid-dispatch.
+     */
+    async listActive(model) {
+        const baseQuery = this.getCollection().where(SHIPPING_BOX_FIELDS.IS_ACTIVE, "==", true);
+        return this.sieveQuery(model, ShippingBoxesRepository.SIEVE_FIELDS, {
+            baseQuery,
+            defaultPageSize: 20,
+            maxPageSize: 50,
+        });
+    }
+    /**
+     * Create a preset, keyed on a slug of its name.
+     *
+     * 🛑 `box-<slug>` as the document id, so the SAME carton name cannot be added
+     * twice by two sellers. That is the whole value of a shared library — two
+     * rows called "Standard carton" with different numbers is worse than one
+     * row, because the picker gives no way to tell them apart.
+     *
+     * A colliding create is reported to the caller rather than silently
+     * overwriting: the existing row has an author and may be in use, and the
+     * second seller's intent ("I want a preset for this") is already satisfied
+     * by the row that exists.
+     */
+    async createPreset(input) {
+        const name = input.name.trim();
+        const id = `box-${slugify(name)}`;
+        const existing = await this.findById(id);
+        if (existing)
+            return { box: existing, created: false };
+        const now = new Date();
+        const box = {
+            id,
+            name,
+            length: clampCm(input.length),
+            width: clampCm(input.width),
+            height: clampCm(input.height),
+            ...(input.tareWeight === undefined ? {} : { tareWeight: clampKg(input.tareWeight) }),
+            createdByUid: input.createdByUid,
+            createdByName: input.createdByName,
+            isActive: true,
+            createdAt: now,
+            updatedAt: now,
+        };
+        await this.createWithId(id, box);
+        return { box, created: true };
+    }
+    /**
+     * Every preset, retired included — the staff management list.
+     *
+     * Separate from `listActive` for the same reason the dispute reasons are: the
+     * picker must never offer a retired row, and a management view must be able
+     * to find one in order to put it back.
+     */
+    async listAll(model) {
+        return this.sieveQuery(model, ShippingBoxesRepository.SIEVE_FIELDS, {
+            baseQuery: this.getCollection(),
+            defaultPageSize: 20,
+            maxPageSize: 50,
+        });
+    }
+    /**
+     * Correct a preset's dimensions. **Staff only** — enforced at the route.
+     *
+     * ## 🛑 This does NOT change any dispatched parcel, by construction
+     *
+     * The dimensions are COPIED onto the shipment at use time (the schema's own
+     * header: *"a preset is a DEFAULT, never a lock"*), so there is no stored
+     * reference for this to reach through. That is precisely why staff editing is
+     * safe to offer at all: a seller's past declaration is a snapshot, and the
+     * courier billed against the figures at dispatch.
+     *
+     * It is staff-only for the mirror reason — these numbers are what the NEXT
+     * seller's dispatch form defaults to, so a wrong edit misdeclares other
+     * people's parcels. A seller who finds a preset wrong adds a new one; staff
+     * decide whether the shared row changes.
+     *
+     * 🛑 The NAME is deliberately not editable. The id is `box-<slug of name>`,
+     * so renaming would either leave the id disagreeing with the name (the
+     * mirror-drift trap) or require a new document, which is just a create. Add
+     * the correctly-named preset and retire this one.
+     */
+    async updatePreset(id, input) {
+        const patch = { updatedAt: new Date() };
+        if (input.length !== undefined)
+            patch.length = clampCm(input.length);
+        if (input.width !== undefined)
+            patch.width = clampCm(input.width);
+        if (input.height !== undefined)
+            patch.height = clampCm(input.height);
+        if (input.tareWeight !== undefined)
+            patch.tareWeight = clampKg(input.tareWeight);
+        await this.update(id, patch);
+    }
+    /** Soft-retire. See the schema for why this is never a delete. */
+    async retire(id) {
+        await this.update(id, { isActive: false, updatedAt: new Date() });
+    }
+    /** Put a retired preset back in the picker. */
+    async reactivate(id) {
+        await this.update(id, { isActive: true, updatedAt: new Date() });
+    }
+}
+ShippingBoxesRepository.SIEVE_FIELDS = {
+    /*
+     * `name` is sortable AND filterable because this list is picked from by
+     * typing — `PaginatedSelect` searches it. A field the picker searches that
+     * is not allowlisted here would have its clause silently DROPPED and the
+     * search would return the whole library while looking like it filtered
+     * (Root Cause #62).
+     */
+    name: { canFilter: true, canSort: true },
+    isActive: { canFilter: true, canSort: false },
+    createdByUid: { canFilter: true, canSort: false },
+};
+/*
+ * Clamped rather than rejected. These bounds exist so a typo cannot reach a
+ * courier API as a 4-metre parcel; they are not a tariff, and refusing a
+ * legitimate large parcel client-side is worse than letting it through to be
+ * priced by `checkServiceability` against the real figures.
+ */
+function clampCm(v) {
+    if (!Number.isFinite(v))
+        return SHIPPING_BOX_LIMITS.minCm;
+    return Math.min(SHIPPING_BOX_LIMITS.maxCm, Math.max(SHIPPING_BOX_LIMITS.minCm, v));
+}
+function clampKg(v) {
+    if (!Number.isFinite(v))
+        return SHIPPING_BOX_LIMITS.minKg;
+    return Math.min(SHIPPING_BOX_LIMITS.maxKg, Math.max(SHIPPING_BOX_LIMITS.minKg, v));
+}
+export const shippingBoxesRepository = new ShippingBoxesRepository();

package/dist/features/shipping-boxes/schemas/firestore.d.ts

@@ -0,0 +1,80 @@
+/**
+ * `shippingBoxes` — a GLOBAL library of named carton presets.
+ *
+ * ## Why global rather than per-store
+ *
+ * A box is a real physical carton size. Scoping presets per store would give
+ * every seller their own private copy of "Medium", each with slightly
+ * different numbers, and the second seller to ship a Beyblade in a standard
+ * carton would re-measure instead of picking what already exists.
+ *
+ * `createdByName` is what keeps a shared library accountable: a wrong preset
+ * has an author, and the next seller can see who added the one they are about
+ * to trust.
+ *
+ * ## 🛑 A preset is a DEFAULT, never a lock
+ *
+ * The dimensions are COPIED onto the shipment when a seller uses one. Editing
+ * a preset later must not retroactively change what an already-dispatched
+ * parcel was declared as — the courier billed against the figures at dispatch,
+ * and a stored reference would make a past declaration mutable. Same snapshot
+ * discipline as the checkout's fee terms (D61).
+ *
+ * ## 🛑 Weight is not a formality
+ *
+ * An understated weight is re-billed by the courier AFTER delivery as a
+ * weight-discrepancy adjustment — real money, arriving on a reconciliation we
+ * cannot dispute without the parcel. The form says so rather than treating it
+ * as a required field to get past.
+ */
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+/** `box-` prefixed slug, so the id reads as what it is. */
+export declare const SHIPPING_BOX_COLLECTION = "shippingBoxes";
+export interface ShippingBoxDocument extends BaseDocument {
+    /** What a seller picks it by: "Standard Beyblade carton", "Poly mailer S". */
+    name: string;
+    /** cm. */
+    length: number;
+    width: number;
+    height: number;
+    /**
+     * kg, the EMPTY box. The parcel's weight is this plus contents, entered on
+     * the dispatch form — a preset cannot know what went inside it.
+     *
+     * 🛑 Separate from the shipment's `weight` for exactly that reason. Storing
+     * one "weight" on a preset and reusing it as the parcel weight is how every
+     * parcel gets declared at the same figure regardless of contents.
+     */
+    tareWeight?: number;
+    /** Who added it. Display name, so a seller can see whose preset this is. */
+    createdByName: string;
+    /** The uid, for moderation. Never rendered. */
+    createdByUid: string;
+    /**
+     * Soft-retire rather than delete. A preset in use by a draft shipment must
+     * not vanish mid-dispatch, and a deleted row takes its author with it.
+     */
+    isActive: boolean;
+}
+export declare const SHIPPING_BOX_FIELDS: {
+    readonly ID: "id";
+    readonly NAME: "name";
+    readonly IS_ACTIVE: "isActive";
+    readonly CREATED_BY_UID: "createdByUid";
+    readonly CREATED_AT: "createdAt";
+};
+/**
+ * Bounds, so a typo cannot reach a courier API as a 4-metre parcel.
+ *
+ * 🛑 Generous on purpose — these are a sanity check, not a tariff. India Post
+ * and most couriers cap a single parcel well below these, and the right place
+ * to learn a real limit is `checkServiceability`, which quotes against the
+ * actual weight. A client-side rule that refuses a legitimate large parcel is
+ * worse than one that lets it through to be priced.
+ */
+export declare const SHIPPING_BOX_LIMITS: {
+    readonly minCm: 1;
+    readonly maxCm: 200;
+    readonly minKg: 0;
+    readonly maxKg: 50;
+};

package/dist/features/shipping-boxes/schemas/firestore.js

@@ -0,0 +1,53 @@
+/**
+ * `shippingBoxes` — a GLOBAL library of named carton presets.
+ *
+ * ## Why global rather than per-store
+ *
+ * A box is a real physical carton size. Scoping presets per store would give
+ * every seller their own private copy of "Medium", each with slightly
+ * different numbers, and the second seller to ship a Beyblade in a standard
+ * carton would re-measure instead of picking what already exists.
+ *
+ * `createdByName` is what keeps a shared library accountable: a wrong preset
+ * has an author, and the next seller can see who added the one they are about
+ * to trust.
+ *
+ * ## 🛑 A preset is a DEFAULT, never a lock
+ *
+ * The dimensions are COPIED onto the shipment when a seller uses one. Editing
+ * a preset later must not retroactively change what an already-dispatched
+ * parcel was declared as — the courier billed against the figures at dispatch,
+ * and a stored reference would make a past declaration mutable. Same snapshot
+ * discipline as the checkout's fee terms (D61).
+ *
+ * ## 🛑 Weight is not a formality
+ *
+ * An understated weight is re-billed by the courier AFTER delivery as a
+ * weight-discrepancy adjustment — real money, arriving on a reconciliation we
+ * cannot dispute without the parcel. The form says so rather than treating it
+ * as a required field to get past.
+ */
+/** `box-` prefixed slug, so the id reads as what it is. */
+export const SHIPPING_BOX_COLLECTION = "shippingBoxes";
+export const SHIPPING_BOX_FIELDS = {
+    ID: "id",
+    NAME: "name",
+    IS_ACTIVE: "isActive",
+    CREATED_BY_UID: "createdByUid",
+    CREATED_AT: "createdAt",
+};
+/**
+ * Bounds, so a typo cannot reach a courier API as a 4-metre parcel.
+ *
+ * 🛑 Generous on purpose — these are a sanity check, not a tariff. India Post
+ * and most couriers cap a single parcel well below these, and the right place
+ * to learn a real limit is `checkServiceability`, which quotes against the
+ * actual weight. A client-side rule that refuses a legitimate large parcel is
+ * worse than one that lets it through to be priced.
+ */
+export const SHIPPING_BOX_LIMITS = {
+    minCm: 1,
+    maxCm: 200,
+    minKg: 0,
+    maxKg: 50,
+};

package/dist/features/store-extensions/schemas/report-create-form.d.ts

@@ -12,14 +12,14 @@ export declare const reportCreateSchema: z.ZodObject<{
 }, "strict", z.ZodTypeAny, {
     entityId: string;
     entityType: import("./firestore").ReportEntityType;
-    detail: string;
     reason: import("./firestore").ReportReason;
+    detail: string;
     evidenceUrls?: string[] | undefined;
 }, {
     entityId: string;
     entityType: import("./firestore").ReportEntityType;
-    detail: string;
     reason: import("./firestore").ReportReason;
+    detail: string;
     evidenceUrls?: string[] | undefined;
 }>;
 export type ReportCreateValues = z.infer<typeof reportCreateSchema>;

package/dist/features/store-extensions/schemas/shipping-config-form.d.ts

@@ -133,8 +133,8 @@ export declare const shippingConfigUpdateSchema: z.ZodObject<{
     label?: string | undefined;
     isActive?: boolean | undefined;
     isDefault?: boolean | undefined;
-    method?: ShippingMethod | undefined;
     estimatedDays?: number | undefined;
+    method?: ShippingMethod | undefined;
     flatRate?: number | undefined;
     pricePerKg?: number | undefined;
     freeAbove?: number | undefined;
@@ -144,8 +144,8 @@ export declare const shippingConfigUpdateSchema: z.ZodObject<{
     label?: string | undefined;
     isActive?: boolean | undefined;
     isDefault?: boolean | undefined;
-    method?: ShippingMethod | undefined;
     estimatedDays?: number | undefined;
+    method?: ShippingMethod | undefined;
     flatRate?: number | undefined;
     pricePerKg?: number | undefined;
     freeAbove?: number | undefined;

package/dist/features/stores/components/StoreOrdersGuideView.js

@@ -2,6 +2,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { ArrowLeft } from "lucide-react";
 import { Accordion, Alert, Code, Div, Heading, Li, Ol, Row, Section, Span, Stack, Table, Tbody, Td, Text, TextLink, Th, Thead, Tr, Ul } from "../../../ui/index.js";
 import { ROUTES } from "../../../next/routing/route-map.js";
+import { resolvePublishedValues } from "../../../_internal/shared/content/published-values.js";
+/* Phase 9 — one definition of the refund timeline. */
+const { refundBusinessDaysMin: REFUND_DAYS_MIN, refundBusinessDaysMax: REFUND_DAYS_MAX } = resolvePublishedValues();
 const SUBHEADING = "mb-1 font-semibold text-[var(--appkit-color-text)]";
 const LIST_DISC = "list-disc leading-relaxed";
 const SECTION_BODY = "space-y-4 text-[length:var(--appkit-text-sm)] text-[var(--appkit-color-text-muted)]";
@@ -41,7 +44,9 @@ const STATUS_ROWS = [
     {
         status: "CANCELLED",
         meaning: "Order was cancelled before shipping (by buyer or seller).",
-        action: "Refund is automatic via Razorpay (3–7 business days).",
+        // Phase 9 — one definition, and no gateway name. See the identical note in
+        // AdminOrdersGuideView.
+        action: `Refund is automatic (${REFUND_DAYS_MIN}–${REFUND_DAYS_MAX} business days).`,
     },
     {
         status: "RETURN_REQUESTED",

package/dist/features/stores/repository/store.repository.d.ts

@@ -29,6 +29,24 @@ export declare class StoreRepository extends BaseRepository<StoreDocument> {
      * Find a store by its URL slug (also the document ID).
      */
     findBySlug(storeSlug: string): Promise<StoreDocument | null>;
+    /**
+     * The slugs of every store paid at shipping rather than at delivery.
+     *
+     * 🛑 A `Set` of IDS, not the documents. The payout sweep needs only
+     * membership, and loading full store documents for a question answered by a
+     * string would spend the ~3-round-trip budget (Rule #6) on data it discards.
+     *
+     * 🛑 An EQUALITY on `trustedSeller == true`, never `!= false`. A Firestore
+     * inequality excludes every document that LACKS the field — which is every
+     * store, since the flag is new and optional — so `!=` would return the
+     * trusted set and nothing else, or everything, depending on which way you
+     * wrote it. Both are wrong and neither raises.
+     *
+     * Bounded at 500: trust is granted by hand, one store at a time, on risk
+     * grounds. If this ever saturates, the grant has stopped being deliberate
+     * and that is the thing to fix rather than the limit.
+     */
+    findTrustedStoreIds(): Promise<Set<string>>;
     /**
      * Find the store owned by a specific user UID.
      */

package/dist/features/stores/repository/store.repository.js

@@ -59,6 +59,32 @@ export class StoreRepository extends BaseRepository {
     async findBySlug(storeSlug) {
         return this.findById(storeSlug);
     }
+    /**
+     * The slugs of every store paid at shipping rather than at delivery.
+     *
+     * 🛑 A `Set` of IDS, not the documents. The payout sweep needs only
+     * membership, and loading full store documents for a question answered by a
+     * string would spend the ~3-round-trip budget (Rule #6) on data it discards.
+     *
+     * 🛑 An EQUALITY on `trustedSeller == true`, never `!= false`. A Firestore
+     * inequality excludes every document that LACKS the field — which is every
+     * store, since the flag is new and optional — so `!=` would return the
+     * trusted set and nothing else, or everything, depending on which way you
+     * wrote it. Both are wrong and neither raises.
+     *
+     * Bounded at 500: trust is granted by hand, one store at a time, on risk
+     * grounds. If this ever saturates, the grant has stopped being deliberate
+     * and that is the thing to fix rather than the limit.
+     */
+    async findTrustedStoreIds() {
+        const snap = await this.db
+            .collection(this.collection)
+            .where(STORE_FIELDS.TRUSTED_SELLER, "==", true)
+            .select()
+            .limit(500)
+            .get();
+        return new Set(snap.docs.map((d) => d.id));
+    }
     /**
      * Find the store owned by a specific user UID.
      */
@@ -117,7 +143,7 @@ export class StoreRepository extends BaseRepository {
             trigger: ctx?.trigger ?? defaultTrigger,
             reason: ctx?.reason,
             note: ctx?.note,
-            // `encryptPiiFields` never descends into arrays, so a nested secret
+            // `encryptPiiFields` covers only NAMED paths, so an undeclared nested secret
             // would be stored in plaintext — the list below is the scrub.
             piiFields: STORE_HISTORY_PII_FIELDS,
         });