@mohasinac/appkit 4.52.5 → 4.53.1

package/dist/next/routing/route-map.d.ts

@@ -50,6 +50,7 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly STORE_DIGITAL_CODES: (storeSlug: string) => string;
         readonly STORE_LIVE: (storeSlug: string) => string;
         readonly STORE_ART: (storeSlug: string) => string;
+        readonly STORE_SPARES: (storeSlug: string) => string;
         readonly CATEGORIES: "/categories";
         readonly CATEGORY_DETAIL: (slug: string) => string;
         readonly BRANDS: "/brands";
@@ -63,7 +64,6 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly ABOUT: "/about";
         readonly DEVELOPER: "/developer";
         readonly CONTACT: "/contact";
-        readonly BLOG: "/blog";
         readonly HELP: "/help";
         readonly HELP_SHOPPING: "/help/shopping";
         readonly HELP_AUCTIONS: "/help/auctions";
@@ -79,6 +79,19 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly COOKIE_POLICY: "/cookies";
         readonly REFUND_POLICY: "/refund-policy";
         readonly SHIPPING_POLICY: "/shipping-policy";
+        /**
+         * Cancellation policy. Distinct from the refund policy, which already
+         * covers cancellation in passing — PhonePe's merchant review asks for it
+         * by name, and so does the Consumer Protection (E-Commerce) Rules 2020
+         * disclosure list.
+         */
+        readonly CANCELLATION_POLICY: "/cancellation-policy";
+        /**
+         * Grievance officer. A MANDATORY published disclosure under the Consumer
+         * Protection (E-Commerce) Rules 2020 and the IT Rules 2021 — name,
+         * designation, contact and a response commitment.
+         */
+        readonly GRIEVANCE: "/grievance";
         readonly HOW_AUCTIONS_WORK: "/how-auctions-work";
         readonly HOW_PRE_ORDERS_WORK: "/how-pre-orders-work";
         readonly HOW_OFFERS_WORK: "/how-offers-work";
@@ -100,7 +113,6 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly EVENT_SPIN_RESULTS: (id: string) => string;
         readonly LOTTERIES: "/lottery";
         readonly LOTTERY_DETAIL: (id: string) => string;
-        readonly SUBLISTING_CATEGORIES: "/sublisting-categories";
         readonly SUBLISTING_CATEGORY: (slug: string) => string;
         readonly SUPPORT: "/support";
         readonly SCAMS: "/scams";
@@ -112,6 +124,8 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly ITEM_REQUESTS_NEW: "/item-requests/new";
         readonly TOOLS: "/tools";
         readonly TOOL_PRICE_INDEX: "/tools/price-index";
+        readonly TOOL_STICKER_TRACER: "/tools/sticker-tracer";
+        readonly TOOL_STICKER_SHEET: (sheetId: string) => string;
         readonly PARTS: "/parts";
         readonly PART_CLASSIFICATION: (classification: string) => string;
         readonly PART_DETAIL: (classification: string, code: string) => string;
@@ -124,6 +138,7 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly LIVE: "/live";
         readonly LIVE_DETAIL: (slug: string) => string;
         readonly ART: "/art";
+        readonly SPARES: "/spares";
         readonly CATALOGUE_ITEM_DETAIL: (ownerSlug: string, itemId: string) => string;
     };
     readonly ERRORS: {
@@ -246,6 +261,9 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly STICKERS: "/store/stickers";
         readonly STICKERS_NEW: "/store/stickers/new";
         readonly STICKERS_EDIT: (id: string) => string;
+        readonly SPARES: "/store/spares";
+        readonly SPARES_NEW: "/store/spares/new";
+        readonly SPARES_EDIT: (id: string) => string;
         readonly PRINT_CENTER: "/store/print-center";
         readonly FULFILLMENT: "/store/fulfillment";
         readonly PAYOUT_METHODS: "/store/payout-methods";
@@ -324,6 +342,7 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly LIVE: "/admin/live";
         readonly ART: "/admin/art";
         readonly STICKERS: "/admin/stickers";
+        readonly SPARES: "/admin/spares";
         readonly GROUPED_LISTINGS: "/admin/grouped-listings";
         readonly GROUPED_LISTINGS_NEW: "/admin/grouped-listings/new";
         readonly GROUPED_LISTINGS_EDIT: (id: string) => string;
@@ -466,6 +485,7 @@ export declare const ROUTES: {
         readonly STORE_DIGITAL_CODES: (storeSlug: string) => string;
         readonly STORE_LIVE: (storeSlug: string) => string;
         readonly STORE_ART: (storeSlug: string) => string;
+        readonly STORE_SPARES: (storeSlug: string) => string;
         readonly CATEGORIES: "/categories";
         readonly CATEGORY_DETAIL: (slug: string) => string;
         readonly BRANDS: "/brands";
@@ -479,7 +499,6 @@ export declare const ROUTES: {
         readonly ABOUT: "/about";
         readonly DEVELOPER: "/developer";
         readonly CONTACT: "/contact";
-        readonly BLOG: "/blog";
         readonly HELP: "/help";
         readonly HELP_SHOPPING: "/help/shopping";
         readonly HELP_AUCTIONS: "/help/auctions";
@@ -495,6 +514,19 @@ export declare const ROUTES: {
         readonly COOKIE_POLICY: "/cookies";
         readonly REFUND_POLICY: "/refund-policy";
         readonly SHIPPING_POLICY: "/shipping-policy";
+        /**
+         * Cancellation policy. Distinct from the refund policy, which already
+         * covers cancellation in passing — PhonePe's merchant review asks for it
+         * by name, and so does the Consumer Protection (E-Commerce) Rules 2020
+         * disclosure list.
+         */
+        readonly CANCELLATION_POLICY: "/cancellation-policy";
+        /**
+         * Grievance officer. A MANDATORY published disclosure under the Consumer
+         * Protection (E-Commerce) Rules 2020 and the IT Rules 2021 — name,
+         * designation, contact and a response commitment.
+         */
+        readonly GRIEVANCE: "/grievance";
         readonly HOW_AUCTIONS_WORK: "/how-auctions-work";
         readonly HOW_PRE_ORDERS_WORK: "/how-pre-orders-work";
         readonly HOW_OFFERS_WORK: "/how-offers-work";
@@ -516,7 +548,6 @@ export declare const ROUTES: {
         readonly EVENT_SPIN_RESULTS: (id: string) => string;
         readonly LOTTERIES: "/lottery";
         readonly LOTTERY_DETAIL: (id: string) => string;
-        readonly SUBLISTING_CATEGORIES: "/sublisting-categories";
         readonly SUBLISTING_CATEGORY: (slug: string) => string;
         readonly SUPPORT: "/support";
         readonly SCAMS: "/scams";
@@ -528,6 +559,8 @@ export declare const ROUTES: {
         readonly ITEM_REQUESTS_NEW: "/item-requests/new";
         readonly TOOLS: "/tools";
         readonly TOOL_PRICE_INDEX: "/tools/price-index";
+        readonly TOOL_STICKER_TRACER: "/tools/sticker-tracer";
+        readonly TOOL_STICKER_SHEET: (sheetId: string) => string;
         readonly PARTS: "/parts";
         readonly PART_CLASSIFICATION: (classification: string) => string;
         readonly PART_DETAIL: (classification: string, code: string) => string;
@@ -540,6 +573,7 @@ export declare const ROUTES: {
         readonly LIVE: "/live";
         readonly LIVE_DETAIL: (slug: string) => string;
         readonly ART: "/art";
+        readonly SPARES: "/spares";
         readonly CATALOGUE_ITEM_DETAIL: (ownerSlug: string, itemId: string) => string;
     };
     readonly ERRORS: {
@@ -662,6 +696,9 @@ export declare const ROUTES: {
         readonly STICKERS: "/store/stickers";
         readonly STICKERS_NEW: "/store/stickers/new";
         readonly STICKERS_EDIT: (id: string) => string;
+        readonly SPARES: "/store/spares";
+        readonly SPARES_NEW: "/store/spares/new";
+        readonly SPARES_EDIT: (id: string) => string;
         readonly PRINT_CENTER: "/store/print-center";
         readonly FULFILLMENT: "/store/fulfillment";
         readonly PAYOUT_METHODS: "/store/payout-methods";
@@ -740,6 +777,7 @@ export declare const ROUTES: {
         readonly LIVE: "/admin/live";
         readonly ART: "/admin/art";
         readonly STICKERS: "/admin/stickers";
+        readonly SPARES: "/admin/spares";
         readonly GROUPED_LISTINGS: "/admin/grouped-listings";
         readonly GROUPED_LISTINGS_NEW: "/admin/grouped-listings/new";
         readonly GROUPED_LISTINGS_EDIT: (id: string) => string;
@@ -903,6 +941,9 @@ export declare const SELLER_ROUTES: {
     readonly STICKERS: "/store/stickers";
     readonly STICKERS_NEW: "/store/stickers/new";
     readonly STICKERS_EDIT: (id: string) => string;
+    readonly SPARES: "/store/spares";
+    readonly SPARES_NEW: "/store/spares/new";
+    readonly SPARES_EDIT: (id: string) => string;
     readonly PRINT_CENTER: "/store/print-center";
     readonly FULFILLMENT: "/store/fulfillment";
     readonly PAYOUT_METHODS: "/store/payout-methods";
@@ -931,6 +972,6 @@ export declare const SELLER_ROUTES: {
     readonly GUIDE_SETTINGS: "/store/guide/settings";
     readonly GUIDE_WHATSAPP: "/store/guide/whatsapp";
 };
-export declare const PUBLIC_ROUTES: readonly ["/", string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, "/unauthorized", "/auth/login", "/auth/register", "/auth/forgot-password", "/auth/reset-password", "/auth/verify-email"];
+export declare const PUBLIC_ROUTES: readonly ["/", string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, "/unauthorized", "/auth/login", "/auth/register", "/auth/forgot-password", "/auth/reset-password", "/auth/verify-email"];
 export declare const PROTECTED_ROUTES: readonly [string, string, string, string, string, string, string];
 export declare const AUTH_ROUTES: readonly ["/auth/login", "/auth/register"];

package/dist/next/routing/route-map.js

@@ -43,6 +43,13 @@ export const DEFAULT_ROUTE_MAP = {
         // `standard` — so the tab showed a real non-zero count and then landed on
         // a page containing none of those items.
         STORE_ART: (storeSlug) => `/stores/${storeSlug}/art`,
+        /*
+         * 🛑 `STORE_PAGE_TABS` is DERIVED from the plugin registry, so this tab
+         * appears the moment the plugin exists — and a missing
+         * `stores/[storeSlug]/spares/page.tsx` is then a clickable 404 that no
+         * audit covers. The folder lands in the same commit as this key.
+         */
+        STORE_SPARES: (storeSlug) => `/stores/${storeSlug}/spares`,
         CATEGORIES: "/categories",
         CATEGORY_DETAIL: (slug) => `/categories/${slug}`,
         BRANDS: "/brands",
@@ -63,7 +70,14 @@ export const DEFAULT_ROUTE_MAP = {
         ABOUT: "/about",
         DEVELOPER: "/developer",
         CONTACT: "/contact",
-        BLOG: "/blog",
+        /*
+         * 🛑 No `PUBLIC.BLOG`. `BLOG.LIST` is the one key for "/blog", and it sits
+         * beside `BLOG.ARTICLE` — which is the ONLY blog detail key, so `BLOG` was
+         * always the canonical section and `PUBLIC.BLOG` was an alias of its index.
+         * Two keys for one path is Root Cause #61's family: the duplicate was
+         * reported by `audit-dead-route-key` on every run, and nine call sites had
+         * drifted onto the alias while one used the real key.
+         */
         HELP: "/help",
         HELP_SHOPPING: "/help/shopping",
         HELP_AUCTIONS: "/help/auctions",
@@ -79,6 +93,19 @@ export const DEFAULT_ROUTE_MAP = {
         COOKIE_POLICY: "/cookies",
         REFUND_POLICY: "/refund-policy",
         SHIPPING_POLICY: "/shipping-policy",
+        /**
+         * Cancellation policy. Distinct from the refund policy, which already
+         * covers cancellation in passing — PhonePe's merchant review asks for it
+         * by name, and so does the Consumer Protection (E-Commerce) Rules 2020
+         * disclosure list.
+         */
+        CANCELLATION_POLICY: "/cancellation-policy",
+        /**
+         * Grievance officer. A MANDATORY published disclosure under the Consumer
+         * Protection (E-Commerce) Rules 2020 and the IT Rules 2021 — name,
+         * designation, contact and a response commitment.
+         */
+        GRIEVANCE: "/grievance",
         HOW_AUCTIONS_WORK: "/how-auctions-work",
         HOW_PRE_ORDERS_WORK: "/how-pre-orders-work",
         HOW_OFFERS_WORK: "/how-offers-work",
@@ -119,7 +146,14 @@ export const DEFAULT_ROUTE_MAP = {
         EVENT_SPIN_RESULTS: (id) => `/events/${id}/spin-results`,
         LOTTERIES: "/lottery",
         LOTTERY_DETAIL: (id) => `/lottery/${id}`,
-        SUBLISTING_CATEGORIES: "/sublisting-categories",
+        /*
+          * 🛑 There is deliberately NO public `SUBLISTING_CATEGORIES` index key.
+          * `src/app/[locale]/sublisting-categories/` holds only `[slug]/`, so the
+          * index has never existed; the key promised a route with no page behind
+          * it, had zero references anywhere, and `audit-dead-route-key` carried it
+          * as its one grandfathered entry. A sub-listing is reached from the
+          * category or product it belongs to, not from a top-level list.
+          */
         SUBLISTING_CATEGORY: (slug) => `/sublisting-categories/${slug}`,
         SUPPORT: "/support",
         SCAMS: "/scams",
@@ -138,6 +172,14 @@ export const DEFAULT_ROUTE_MAP = {
          */
         TOOLS: "/tools",
         TOOL_PRICE_INDEX: "/tools/price-index",
+        /*
+         * Admin-only, and under a PUBLIC prefix on purpose — it is a tool, and
+         * /tools is where tools live. The guard is the layout, not the path: a
+         * non-admin is redirected server-side before any HTML is produced, so
+         * there is nothing indexable at this URL regardless of robots.txt.
+         */
+        TOOL_STICKER_TRACER: "/tools/sticker-tracer",
+        TOOL_STICKER_SHEET: (sheetId) => `/tools/sticker-tracer/${sheetId}`,
         /*
          * The PARTS database. A reference surface, so it lives beside the other
          * two things that answer a question rather than sell you something.
@@ -166,6 +208,21 @@ export const DEFAULT_ROUTE_MAP = {
         // detail page stays PRODUCT_DETAIL (`/products/{slug}`), already wired in
         // `_internal/shared/listing-types/{art,stickers}/config.ts`.
         ART: "/art",
+        /*
+         * Part Two — loose components off disassembled items.
+         *
+         * 🛑 A REAL page, not a redirect shim like `/live`. Its plugin sets
+         * `inGeneralCatalogue: false`, and the rule for that flag is nav
+         * reachability: a type kept out of `/products` must own a page that
+         * `MAIN_NAV_ITEMS` links, or it is reachable from nowhere at all (Root
+         * Cause #61). A shim pointing back at `/products` would re-open exactly
+         * that hole while looking like it had closed it.
+         *
+         * Detail route stays `PRODUCT_DETAIL` — a spare checks out like any
+         * standard item, so it needs no bespoke detail page, same reasoning as
+         * art/stickers above.
+         */
+        SPARES: "/spares",
         // Personal catalogue (Feature B) — a user's own photo inventory of owned
         // items, distinct from marketplace listings. Public when the owner sets
         // an item's visibility to "public". The owner's full catalogue listing
@@ -297,6 +354,10 @@ export const DEFAULT_ROUTE_MAP = {
         STICKERS: "/store/stickers",
         STICKERS_NEW: "/store/stickers/new",
         STICKERS_EDIT: (id) => `/store/stickers/${id}/edit`,
+        // Part Two — spares
+        SPARES: "/store/spares",
+        SPARES_NEW: "/store/spares/new",
+        SPARES_EDIT: (id) => `/store/spares/${id}/edit`,
         PRINT_CENTER: "/store/print-center",
         FULFILLMENT: "/store/fulfillment",
         // S-STORE Tier — new extension routes
@@ -390,6 +451,8 @@ export const DEFAULT_ROUTE_MAP = {
         // EMI/art-stickers session — art / stickers
         ART: "/admin/art",
         STICKERS: "/admin/stickers",
+        // Part Two — spares
+        SPARES: "/admin/spares",
         GROUPED_LISTINGS: "/admin/grouped-listings",
         GROUPED_LISTINGS_NEW: "/admin/grouped-listings/new",
         GROUPED_LISTINGS_EDIT: (id) => `/admin/grouped-listings/${id}/edit`,
@@ -552,12 +615,16 @@ export const PUBLIC_ROUTES = [
     ROUTES.PUBLIC.PROMOTIONS,
     ROUTES.PUBLIC.ABOUT,
     ROUTES.PUBLIC.CONTACT,
-    ROUTES.PUBLIC.BLOG,
+    ROUTES.BLOG.LIST,
     ROUTES.PUBLIC.HELP,
     ROUTES.PUBLIC.TERMS,
     ROUTES.PUBLIC.PRIVACY,
     ROUTES.PUBLIC.ETHICS,
     ROUTES.PUBLIC.CODE_OF_CONDUCT,
+    ROUTES.PUBLIC.CANCELLATION_POLICY,
+    // Public by necessity: a grievance officer a complainant must sign in to
+    // find is not a published disclosure.
+    ROUTES.PUBLIC.GRIEVANCE,
     ROUTES.ERRORS.UNAUTHORIZED,
     ROUTES.AUTH.LOGIN,
     ROUTES.AUTH.REGISTER,

package/dist/providers/db-firebase/base.d.ts

@@ -19,6 +19,7 @@
  */
 import type { CollectionReference, DocumentData, DocumentSnapshot, Firestore } from "firebase-admin/firestore";
 import type { IRepository, PagedResult, SieveQuery, WhereOp } from "../../contracts";
+import type { Plaintext } from "../../security/encrypted";
 export declare class FirebaseRepository<T extends DocumentData> implements IRepository<T> {
     protected readonly collection: string;
     constructor(collectionName: string);
@@ -29,8 +30,9 @@ export declare class FirebaseRepository<T extends DocumentData> implements IRepo
     findById(id: string): Promise<T | null>;
     findAll(query?: SieveQuery): Promise<PagedResult<T>>;
     findWhere(field: keyof T, op: WhereOp, value: unknown): Promise<T[]>;
-    create(data: Omit<T, "id" | "createdAt" | "updatedAt">): Promise<T>;
-    update(id: string, data: Partial<T>): Promise<T>;
+    create(data: Omit<Plaintext<T>, "id" | "createdAt" | "updatedAt">): Promise<T>;
+    /** Accepts the PLAINTEXT shape — see `create` for why. */
+    update(id: string, data: Partial<Plaintext<T>>): Promise<T>;
     delete(id: string): Promise<void>;
     batchCreate(items: Array<Omit<T, "id" | "createdAt" | "updatedAt">>): Promise<T[]>;
     batchDelete(ids: string[]): Promise<void>;

package/dist/providers/db-firebase/base.js

@@ -46,7 +46,7 @@ export class FirebaseRepository {
     }
     async findAll(query) {
         const page = Math.max(1, query?.page ?? 1);
-        const perPage = Math.max(1, Math.min(query?.perPage ?? 20, 500));
+        const pageSize = Math.max(1, Math.min(query?.pageSize ?? 20, 500));
         let q = this.getCollection();
         // -- Sort ------------------------------------------------------------------
         // SieveQuery.sort supports a leading "-" prefix for descending order
@@ -89,11 +89,11 @@ export class FirebaseRepository {
         // -- Count -----------------------------------------------------------------
         const total = await getFirestoreCount(q);
         // -- Paginate --------------------------------------------------------------
-        const offset = (page - 1) * perPage;
-        const pagedSnap = await q.offset(offset).limit(perPage).get();
+        const offset = (page - 1) * pageSize;
+        const pagedSnap = await q.offset(offset).limit(pageSize).get();
         const data = pagedSnap.docs.map((d) => this.mapDoc(d));
-        const totalPages = total === 0 ? 0 : Math.max(1, Math.ceil(total / perPage));
-        return { data, total, page, perPage, totalPages };
+        const totalPages = total === 0 ? 0 : Math.max(1, Math.ceil(total / pageSize));
+        return { data, total, page, pageSize, totalPages };
     }
     async findWhere(field, op, value) {
         const snap = await this.getCollection()
@@ -102,6 +102,21 @@ export class FirebaseRepository {
         return snap.docs.map((d) => this.mapDoc(d));
     }
     // -- IWriteRepository -------------------------------------------------------
+    /*
+     * 🛑 Accepts the PLAINTEXT shape, because this method ENCRYPTS.
+     *
+     * `applyWriteHooks` runs `encryptPiiFields` over the subclass's `piiFields`,
+     * so a caller legitimately hands over a real email and gets ciphertext in
+     * Firestore. Typing the parameter `Omit<T, …>` demanded `Encrypted<string>`
+     * from every caller — and the only way to produce one without encrypting is
+     * `asEncrypted(value)`, which labels plaintext as ciphertext and is the
+     * misuse that helper's own docstring forbids. The alternative was a cast at
+     * each of the dozens of write sites across fourteen repositories; one honest
+     * signature here is the same change made once.
+     *
+     * `Plaintext<T>` is the identity on any document with no branded field, so
+     * this is a no-op for every repository that holds no PII.
+     */
     async create(data) {
         const now = new Date();
         const payload = prepareForFirestore({
@@ -113,6 +128,7 @@ export class FirebaseRepository {
         const snap = await ref.get();
         return this.mapDoc(snap);
     }
+    /** Accepts the PLAINTEXT shape — see `create` for why. */
     async update(id, data) {
         const payload = prepareForFirestore({
             ...data,

package/dist/providers/db-firebase/base.repository.d.ts

@@ -1,3 +1,4 @@
+import type { Plaintext } from "../../security/encrypted";
 import type { FirestoreDocument } from "@mohasinac/appkit";
 import type { CollectionReference, DocumentData, DocumentReference, DocumentSnapshot, Firestore, Query, Transaction, WriteBatch } from "firebase-admin/firestore";
 import { type FirebaseSieveFields, type FirebaseSieveOptions, type FirebaseSieveResult, type SieveModel } from "./sieve";
@@ -48,6 +49,28 @@ export declare abstract class BaseRepository<T extends DocumentData> {
      * text, so indexing an encrypted field would undo the encryption.
      */
     protected buildSearchTxtFor(_data: Record<string, JsonValue>): string[] | null;
+    /**
+     * Build this document's `*TokensIndex` fields — whole-word HMAC digests
+     * over PII, for admin search without decryption. Return `null` to leave
+     * the document alone (the default).
+     *
+     * Mirrors `buildSearchTxtFor`'s shape exactly, and for the reason that
+     * shape exists: a hook run from `applyWriteHooks` reaches EVERY write path
+     * — create, createWithId, update, the `*InTx`/`*InBatch` family, and a
+     * seed load, which goes through the same repository methods. A one-off
+     * backfill script cannot reach any of those; it only catches documents
+     * that already existed when it ran.
+     *
+     * 🛑 This is NOT `buildSearchTxtFor`'s inverse rule. `searchTxt` must never
+     * carry PII; this hook exists FOR PII, and runs in the only place that
+     * sees the plaintext before `encryptPiiFields` replaces it. See
+     * `security/blind-index-tokens.ts` for why the tokens are whole-word only.
+     *
+     * Return shape is `{ fieldName: digests[] }` rather than a single array,
+     * because a document can carry more than one token field (a payout has
+     * `sellerTokensIndex`, nothing else does yet, but the hook is general).
+     */
+    protected buildTokensIndexFor(_data: Record<string, JsonValue>): Record<string, string[]> | null;
     /**
      * The one place writes are transformed. Every write path routes through here
      * so a new method cannot silently skip encryption.
@@ -111,7 +134,7 @@ export declare abstract class BaseRepository<T extends DocumentData> {
         doc: T | null | undefined;
         patch: Partial<T>;
     }>): Promise<number>;
-    create(data: Partial<T> | FirestoreDocument): Promise<T>;
+    create(data: Partial<Plaintext<T>> | FirestoreDocument): Promise<T>;
     /**
      * Write a document at a CALLER-CHOSEN id.
      *
@@ -143,8 +166,9 @@ export declare abstract class BaseRepository<T extends DocumentData> {
      * NAME: `createWithId` reads as "create" and behaves as "replace", and that
      * gap is what made the wrong conclusion so easy to reach.
      */
-    createWithId(id: string, data: Partial<T>): Promise<T>;
-    update(id: string, data: Partial<T>): Promise<T>;
+    createWithId(id: string, data: Partial<Plaintext<T>>): Promise<T>;
+    /** Accepts the PLAINTEXT shape — see `create` for why. */
+    update(id: string, data: Partial<Plaintext<T>>): Promise<T>;
     delete(id: string): Promise<void>;
     exists(id: string): Promise<boolean>;
     /**
@@ -195,12 +219,12 @@ export declare abstract class BaseRepository<T extends DocumentData> {
     }): Promise<Record<string, number | undefined>>;
     findByIdInTx(tx: Transaction, id: string): Promise<T | null>;
     findByIdOrFailInTx(tx: Transaction, id: string): Promise<T>;
-    createInTx(tx: Transaction, data: Partial<T> | FirestoreDocument): DocumentReference;
-    createWithIdInTx(tx: Transaction, id: string, data: Partial<T> | FirestoreDocument): DocumentReference;
-    updateInTx(tx: Transaction, id: string, data: Partial<T>): void;
+    createInTx(tx: Transaction, data: Partial<Plaintext<T>> | FirestoreDocument): DocumentReference;
+    createWithIdInTx(tx: Transaction, id: string, data: Partial<Plaintext<T>> | FirestoreDocument): DocumentReference;
+    updateInTx(tx: Transaction, id: string, data: Partial<Plaintext<T>>): void;
     deleteInTx(tx: Transaction, id: string): void;
-    createInBatch(batch: WriteBatch, data: Partial<T> | FirestoreDocument): DocumentReference;
-    createWithIdInBatch(batch: WriteBatch, id: string, data: Partial<T> | FirestoreDocument): void;
-    updateInBatch(batch: WriteBatch, id: string, data: Partial<T>): void;
+    createInBatch(batch: WriteBatch, data: Partial<Plaintext<T>> | FirestoreDocument): DocumentReference;
+    createWithIdInBatch(batch: WriteBatch, id: string, data: Partial<Plaintext<T>> | FirestoreDocument): void;
+    updateInBatch(batch: WriteBatch, id: string, data: Partial<Plaintext<T>>): void;
     deleteInBatch(batch: WriteBatch, id: string): void;
 }

package/dist/providers/db-firebase/base.repository.js

@@ -5,6 +5,7 @@ import { applySieveToFirestore, countSieveMatches, } from "./sieve.js";
 import { deserializeTimestamps, prepareForFirestore } from "./helpers.js";
 import { getAdminDb } from "./admin.js";
 import { encryptPiiFields, piiIndicesFor } from "../../security/pii-encrypt.js";
+import { BLIND_INDEX_KEY_VERSION_FIELD, CURRENT_BLIND_INDEX_KEY_VERSION, } from "../../security/blind-index-tokens.js";
 /**
  * The underlying failure's message, for interpolation into a DatabaseError.
  *
@@ -133,6 +134,30 @@ export class BaseRepository {
     buildSearchTxtFor(_data) {
         return null;
     }
+    /**
+     * Build this document's `*TokensIndex` fields — whole-word HMAC digests
+     * over PII, for admin search without decryption. Return `null` to leave
+     * the document alone (the default).
+     *
+     * Mirrors `buildSearchTxtFor`'s shape exactly, and for the reason that
+     * shape exists: a hook run from `applyWriteHooks` reaches EVERY write path
+     * — create, createWithId, update, the `*InTx`/`*InBatch` family, and a
+     * seed load, which goes through the same repository methods. A one-off
+     * backfill script cannot reach any of those; it only catches documents
+     * that already existed when it ran.
+     *
+     * 🛑 This is NOT `buildSearchTxtFor`'s inverse rule. `searchTxt` must never
+     * carry PII; this hook exists FOR PII, and runs in the only place that
+     * sees the plaintext before `encryptPiiFields` replaces it. See
+     * `security/blind-index-tokens.ts` for why the tokens are whole-word only.
+     *
+     * Return shape is `{ fieldName: digests[] }` rather than a single array,
+     * because a document can carry more than one token field (a payout has
+     * `sellerTokensIndex`, nothing else does yet, but the hook is general).
+     */
+    buildTokensIndexFor(_data) {
+        return null;
+    }
     /**
      * The one place writes are transformed. Every write path routes through here
      * so a new method cannot silently skip encryption.
@@ -154,6 +179,17 @@ export class BaseRepository {
         const searchTxt = this.buildSearchTxtFor(out);
         if (searchTxt)
             out.searchTxt = searchTxt;
+        /*
+         * `data`, not `out` — the plaintext source, same as `piiIndicesFor`
+         * above. By this point `out` may already hold ciphertext, and hashing
+         * ciphertext would make the index meaningless.
+         */
+        const tokensIndex = this.buildTokensIndexFor(data);
+        if (tokensIndex) {
+            Object.assign(out, tokensIndex, {
+                [BLIND_INDEX_KEY_VERSION_FIELD]: CURRENT_BLIND_INDEX_KEY_VERSION,
+            });
+        }
         return out;
     }
     /**
@@ -268,6 +304,21 @@ export class BaseRepository {
         await batch.commit();
         return present.length;
     }
+    /*
+     * 🛑 Accepts the PLAINTEXT shape, because this method ENCRYPTS.
+     *
+     * `applyWriteHooks` runs `encryptPiiFields` over the subclass's `piiFields`,
+     * so a caller legitimately hands over a real email and Firestore holds
+     * ciphertext. Typing this `Partial<T>` demanded `Encrypted<string>` from
+     * every caller once the PII fields were branded — and the only way to make
+     * one without encrypting is `asEncrypted(value)`, which labels plaintext as
+     * ciphertext and is the misuse that helper's docstring forbids. The
+     * alternative was a cast at each of the dozens of write sites across
+     * fourteen repositories; one honest signature here is that change made once.
+     *
+     * `Plaintext<T>` is the identity on a document with no branded member, so
+     * this is a no-op for every repository holding no PII.
+     */
     async create(data) {
         try {
             const cleanData = prepareForFirestore({
@@ -315,6 +366,7 @@ export class BaseRepository {
      * NAME: `createWithId` reads as "create" and behaves as "replace", and that
      * gap is what made the wrong conclusion so easy to reach.
      */
+    // Plaintext<T> — these methods ENCRYPT via applyWriteHooks; see `create`.
     async createWithId(id, data) {
         try {
             const now = new Date();
@@ -339,6 +391,7 @@ export class BaseRepository {
             throw new DatabaseError(`Failed to create document with ID: ${id}: ${detailOf(error)}`, error);
         }
     }
+    /** Accepts the PLAINTEXT shape — see `create` for why. */
     async update(id, data) {
         try {
             const cleanData = prepareForFirestore({
@@ -496,6 +549,7 @@ export class BaseRepository {
         }));
         return docRef;
     }
+    // Plaintext<T> — these methods ENCRYPT via applyWriteHooks; see `create`.
     updateInTx(tx, id, data) {
         const docRef = this.getCollection().doc(id);
         tx.update(docRef, prepareForFirestore({ ...this.applyWriteHooks(data), updatedAt: new Date() }));
@@ -523,6 +577,7 @@ export class BaseRepository {
             updatedAt: now,
         }));
     }
+    // Plaintext<T> — these methods ENCRYPT via applyWriteHooks; see `create`.
     updateInBatch(batch, id, data) {
         const docRef = this.getCollection().doc(id);
         batch.update(docRef, prepareForFirestore({ ...this.applyWriteHooks(data), updatedAt: new Date() }));

package/dist/providers/db-firebase/rtdb-paths.d.ts

@@ -34,4 +34,16 @@ export declare const RTDB_PATHS: {
      * Pruned by `cleanupRtdbEvents`'s sixth block.
      */
     readonly CHAT_EVENTS: "chat_events";
+    /**
+     * Per-run progress for the sticker kiss-cut tracer — stage, pct, parts and
+     * shards done. The DURABLE record is `stickerTraceRuns.events[]`; this is
+     * only the live bar, which is why losing it is survivable and why the run
+     * document is what a failure is diagnosed from weeks later.
+     *
+     * 🛑 Pruned at SIXTY minutes, not fifteen. A `max`-tier fan-out across sixty
+     * parts can outlast a fifteen-minute window, and a channel pruned mid-run
+     * reads to the client as "it died" — the same false negative `EMAIL_EVENTS`
+     * carries a longer window to avoid.
+     */
+    readonly STICKER_TRACE: "sticker_trace";
 };

package/dist/providers/db-firebase/rtdb-paths.js

@@ -34,4 +34,16 @@ export const RTDB_PATHS = {
      * Pruned by `cleanupRtdbEvents`'s sixth block.
      */
     CHAT_EVENTS: "chat_events",
+    /**
+     * Per-run progress for the sticker kiss-cut tracer — stage, pct, parts and
+     * shards done. The DURABLE record is `stickerTraceRuns.events[]`; this is
+     * only the live bar, which is why losing it is survivable and why the run
+     * document is what a failure is diagnosed from weeks later.
+     *
+     * 🛑 Pruned at SIXTY minutes, not fifteen. A `max`-tier fan-out across sixty
+     * parts can outlast a fifteen-minute window, and a channel pruned mid-run
+     * reads to the client as "it died" — the same false negative `EMAIL_EVENTS`
+     * carries a longer window to avoid.
+     */
+    STICKER_TRACE: "sticker_trace",
 };

package/dist/react/ErrorBoundary.js

@@ -10,7 +10,12 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 import { Component } from "react";
 import { Logger } from "../core/Logger.js";
-import { Button, Heading, Text } from "../ui/index.js";
+// Defining modules, not the sibling barrel — Root Cause #18. `ui/index.ts` and
+// `react/index.ts` re-exported into each other, which is the whole of
+// `audit-import-cycles` component 1: an 18-module knot held together entirely
+// by barrel hops, none of which needed the barrel.
+import { Button } from "../ui/components/Button.js";
+import { Heading, Text } from "../ui/components/Typography.js";
 import { trackError, ErrorCategory, ErrorSeverity, } from "../monitoring/error-tracking.js";
 function DefaultFallback({ error, onReset, }) {
     return (_jsxs("div", { role: "alert", style: {

package/dist/react/hooks/realtime-event-constants.d.ts

@@ -20,6 +20,7 @@ export declare const RealtimeEventType: {
     readonly CHAT: "chat";
     readonly BID: "bid";
     readonly BULK: "bulk";
+    readonly STICKER_TRACE: "sticker-trace";
 };
 export type RealtimeEventType = (typeof RealtimeEventType)[keyof typeof RealtimeEventType];
 export declare const RealtimeEventStatus: {

package/dist/react/hooks/realtime-event-constants.js

@@ -19,6 +19,14 @@ export const RealtimeEventType = {
     CHAT: "chat",
     BID: "bid",
     BULK: "bulk",
+    /*
+     * The sticker kiss-cut tracer's per-run progress channel. Added rather than
+     * reusing BULK: the type selects this event's message strings and its
+     * claim/path conventions, and a trace reports a STAGE out of eleven where a
+     * bulk job reports a count — borrowing BULK's vocabulary would make the
+     * progress row say the wrong thing about every failure.
+     */
+    STICKER_TRACE: "sticker-trace",
 };
 export const RealtimeEventStatus = {
     IDLE: "idle",