@mohasinac/appkit 4.44.0 → 4.46.0

package/dist/seed/seed-purpose.js

@@ -0,0 +1,416 @@
+/**
+ * ── Seed provenance: may a purge delete this row? ───────────────────────────
+ *
+ * Every document written by `appkit-seed` carries a `seedPurpose`, and it is
+ * the ONE declaration of whether a row is real content or clearable test data.
+ * The purge reads it; nothing else decides.
+ *
+ * ## The rule this exists to enforce
+ *
+ * 🛑 **Content comes from a seed FILE, never from a direct database write.**
+ * Not a one-off script, not a console paste, not a `node -e`. A row that exists
+ * only in Firestore cannot be reviewed in a diff, cannot be recreated after a
+ * purge, and cannot be found by anyone who did not watch it being written —
+ * and when it references other rows, nothing updates it when those move.
+ *
+ * `seedPurpose` makes that rule *checkable*: a document with no `seedPurpose`
+ * was not written by the seeder, so the purge will not touch it.
+ *
+ * ## 🛑 THE DEFAULT IS `test`, AND THE OPPOSITE WAS THIS FILE'S FIRST BUG
+ *
+ * The first version of this file defaulted every collection to `permanent`,
+ * reasoning that the dangerous direction is deleting something unrecoverable.
+ * **That reasoning was wrong here, and it made the purge a no-op.**
+ *
+ * This site has never gone live. There are no real customers, no real orders
+ * and no real payouts — every user, store, listing, auction, order, bid and
+ * review in the seed was added TO EXERCISE THE PLATFORM. Classifying them
+ * `permanent` means "cannot be cleared", which is precisely the opposite of
+ * why the field was asked for.
+ *
+ * So the default is `test`, and `permanent` is the **narrow** exception: the
+ * handful of collections that are genuinely content rather than scaffolding.
+ *
+ * ## 🛑 AND `isTestData` IS NOT DERIVED FROM THIS — that was the second bug
+ *
+ * The first version wrote `isTestData: true` for every `test` row. That would
+ * have **hidden the entire demo catalogue from the public**, because
+ * `hidePublicTestData` filters on exactly that field — 70 products, 416
+ * categories and every store would have vanished from every public page while
+ * the summary line read `created 2513, errors 0`.
+ *
+ * The two concerns are orthogonal and must stay separate:
+ *
+ * | Question | Field |
+ * |---|---|
+ * | May a purge delete this row? | **`seedPurpose`** (here) |
+ * | Should the public be able to SEE this row? | **`isTestData`** + `testDataExpiresAt` |
+ *
+ * A demo product is `test` (clearable) **and visible**. A tester-sandbox
+ * cross-store fixture is `test` **and hidden**. Those are different rows with
+ * different needs, and one field cannot answer both.
+ *
+ * `isTestData` therefore stays an explicit per-row opt-in, authored via
+ * `testDataExpiresAt()` in `./test-data-ttl.ts`, and this file never writes it.
+ *
+ * ## What it replaces
+ *
+ * Measured 2026-10-12, before this file existed: **47** seed data files, of
+ * which **one** carried any permanence marker; `isTestData` declared on **5**
+ * schemas; and `TEST_DATA_COLLECTIONS` listing **`offers`**, whose schema does
+ * not declare the field at all, so that entry could only ever match zero rows.
+ * `users`, `orders`, `faqs`, `reviews`, `bids`, `payouts` and `carts` had no
+ * marker and no purge path — and users and orders are the two that were named.
+ */
+/**
+ * `Record<SeedPurpose, true>`, so a third value is a compile error in every map
+ * keyed on the union rather than a silent gap (Root Cause #61).
+ */
+export const SEED_PURPOSE_VALUES = {
+    test: true,
+    permanent: true,
+};
+export const ALL_SEED_PURPOSES = Object.keys(SEED_PURPOSE_VALUES);
+export function isSeedPurpose(value) {
+    return typeof value === "string" && value in SEED_PURPOSE_VALUES;
+}
+/**
+ * 🛑 There is deliberately NO third `fixture` tier.
+ *
+ * An earlier draft had one, meaning "clearable but only by an explicit full
+ * purge", intended for the tester checklist. Once the cases were correctly
+ * classified as permanent content it had **nothing in it** — and a union member
+ * with no members is the dead-enum-value shape this codebase keeps paying for:
+ * a filter chip whose value no row carries returns zero rows forever and reads
+ * as a working control (Root Cause #33), and nine section types that exist in a
+ * dropdown and have never rendered (F1 #20).
+ *
+ * Two values answer the question that was actually asked. If a genuine third
+ * case appears, add it then — with a row that needs it.
+ */
+export const PURGEABLE = {
+    test: true,
+    permanent: false,
+};
+/**
+ * The per-collection default, keyed on `COLLECTION_MAP`'s keys in
+ * `appkit/scripts/seed-cli.mjs`.
+ *
+ * 🛑 Typed `Record<string, SeedPurpose>` rather than a closed union of
+ * collection names, and that is a deliberate trade: the collection list lives
+ * in a `.mjs` script that cannot be imported for its types, so a closed union
+ * here would be a fifth hand-written copy of it — the thing this file exists to
+ * stop. `audit-seed-purpose` cross-checks the two sets instead, which catches
+ * both a missing entry and a dead one.
+ *
+ * **Anything absent defaults to `test`**, so a collection added later is
+ * clearable rather than quietly permanent. That is the right fail direction on
+ * a site with no real data: the cost of clearing something re-seedable is one
+ * command, and the cost of being unable to clear it is the state this replaced.
+ */
+export const SEED_COLLECTION_PURPOSE = {
+    /*
+     * ── permanent: content, not scaffolding ─────────────────────────────────
+     *
+     * The test: if clearing it means someone has to WRITE it again rather than
+     * re-run a loader, it is permanent. Five collections pass that test.
+     */
+    /* 85 answers carrying real figures — the ₹10 fee cap, the 5% GST worked
+     * example, the 48-hour damage window. Explicitly asked to be permanent. */
+    faqs: "permanent",
+    /* 416 nodes, 6 roots. Every product's `categorySlugs` chain points into it,
+     * so clearing it orphans the catalogue — which is exactly what happened when
+     * a purge-then-load wrote 0 of 416 and 70 products pointed at nothing. */
+    categories: "permanent",
+    /* Real HSN codes and GST rates. A wrong rate on a real invoice is a
+     * compliance matter, not a fixture. */
+    taxCodes: "permanent",
+    /* The ~169-term feature vocabulary: condition, authenticity, release, type,
+     * spin, grade, chase. Hand-curated from the crawl. */
+    productFeatures: "permanent",
+    /* Branding, fees, commissions, watermark, legal pages, and the AES-encrypted
+     * credentials. 🛑 A purge here would destroy live API keys. */
+    siteSettings: "permanent",
+    /*
+     * ── permanent, second tranche: the site's own CONTENT and COMPOSITION ────
+     *
+     * Added on the user's explicit list. The same test applies and they pass it:
+     * clearing any of these means re-AUTHORING, not re-running a loader.
+     *
+     * 🛑 But "permanent" obliges us to make them REAL — see G1c in the plan.
+     * Marking a placeholder permanent only makes the placeholder unpurgeable, so
+     * each of these has to trace to a crawl source: blogPosts to the buying/rules
+     * guide split, homepageSections to worldhobbyshop's generation tiles and
+     * 25-link systems matrix, carouselSlides to beybladeartshop's 5-slide hero
+     * including the anti-counterfeit slide.
+     */
+    blogPosts: "permanent",
+    carousels: "permanent",
+    carouselSlides: "permanent",
+    homepageSections: "permanent",
+    /*
+     * 🛑 The tester checklist cases are PERMANENT CONTENT, not scaffolding.
+     *
+     * 1,162 authored cases, each a six-part procedure with an explicit
+     * before → after — the real catalogue of issues the testers test against and
+     * keep updating. Clearing them is not a re-seed, it is losing the authoring,
+     * and this project's primary quality gate is that catalogue.
+     *
+     * Their RESPONSES are the opposite: per-run verdicts, regenerated every
+     * sweep, and the whole point of clearing between runs. So the two halves of
+     * one feature land in different tiers, which is the case the collection-level
+     * default is for.
+     */
+    testerChecklistItems: "permanent",
+    /*
+     * E4/D12 — PERMANENT. These are extracted from a corpus by committed
+     * scripts, not fixtures: clearing them means re-running an extraction over a
+     * 7 GB local crawl, which is the test § G1c sets ("if clearing it means
+     * somebody has to WRITE it again rather than re-run a loader"). Re-running
+     * the extractor is possible but needs a corpus a clone will not have.
+     */
+    partGlossary: "permanent",
+    modelComposition: "permanent",
+    testerChecklistResponses: "test",
+    /*
+     * ── test: everything else ───────────────────────────────────────────────
+     *
+     * Listed explicitly rather than left to the fallback, because an explicit
+     * table is reviewable and `audit-seed-purpose` can then tell a MISSING entry
+     * from a deliberate one.
+     */
+    users: "test",
+    addresses: "test",
+    storeAddresses: "test",
+    sessions: "test",
+    stores: "test",
+    products: "test",
+    orders: "test",
+    reviews: "test",
+    bids: "test",
+    offers: "test",
+    carts: "test",
+    wishlists: "test",
+    history: "test",
+    payouts: "test",
+    coupons: "test",
+    couponUsage: "test",
+    notifications: "test",
+    supportTickets: "test",
+    catalogueItems: "test",
+    events: "test",
+    eventEntries: "test",
+    groupedListings: "test",
+    scammerProfiles: "test",
+    procurementShipments: "test",
+    shipmentLots: "test",
+    shipmentItems: "test",
+    payoutMethods: "test",
+    analyticsAlerts: "test",
+    storeCategories: "test",
+    listingTemplates: "test",
+    moderationQueue: "test",
+    reports: "test",
+    itemRequests: "test",
+    storeGoogleConfig: "test",
+};
+/**
+ * Individual rows that differ from their collection's default, by document id.
+ *
+ * 🛑 This is the "clear all out EXCEPT our admin creds and the original single
+ * store" instruction, made declarative. Both collections default to `test` —
+ * every persona and every other store is disposable — and exactly two rows are
+ * not.
+ *
+ * ✅ The precedent already existed and this replaces it: `cmdDelete` has
+ * carried `PROTECTED_USER_UIDS = new Set(["user-admin-letitrip"])` for a long
+ * time, skipping that uid on a wholesale delete. One mechanism is better than a
+ * list the purge path happens to know about privately.
+ *
+ * 🛑 Keyed **`"<collection>:<id>"`**, and the collection half is load-bearing.
+ *
+ * It was a bare id, and a live read-back caught the consequence: `carts`,
+ * `wishlists` and `history` are all keyed on the USER id (CLAUDE.md: "Doc id =
+ * userId"), so `"user-admin-letitrip"` matched the admin's **cart** as well as
+ * the admin's user row — making a disposable cart permanently unpurgeable.
+ * Subtle, silent, and it would have left a stale cart surviving every purge
+ * forever.
+ *
+ * The id half is the DOCUMENT id, which for `users` is the Auth uid (`uid` on
+ * the seed row) and for everything else is `id`. `resolveSeedPurpose` checks
+ * both, because a seeded user row carries `uid` and no `id`.
+ */
+export const SEED_ROW_PURPOSE = {
+    /* Our own admin account. Clearing it locks us out of our own site — and the
+     * Auth record is the half most easily missed, since `appkit-seed delete` does
+     * not touch Firebase Auth at all. */
+    "users:user-admin-letitrip": "permanent",
+    /* The platform's own default store. The other three seeded stores
+     * (beyblade-arena, blader-bazaar, vintage-vault-co) are test fixtures. */
+    "stores:store-letitrip-official": "permanent",
+};
+/**
+ * Collections whose purpose FOLLOWS a referenced row rather than being declared.
+ *
+ * 🛑 This exists to hold one invariant: **a `permanent` row may not reference a
+ * `test` row**, because the purge would leave it behind as a dangling FK that
+ * still looks like real config.
+ *
+ * Measured in `store-extensions-seed-data.ts`: **14** rows reference
+ * `store-beyblade-arena` (test) and **9** reference `store-letitrip-official`
+ * (permanent). So marking `shippingConfigs` / `analyticsCards` permanent at the
+ * COLLECTION level — which the user's list implies and an earlier draft of the
+ * plan did — would strand 14 rows pointing at a store the purge deletes.
+ *
+ * Deriving is better than 23 hand-maintained per-row overrides for the usual
+ * reason: a hand-kept mirror drifts the moment a store is added (Root Cause
+ * #42), and a derivation is correct for stores that do not exist yet.
+ */
+export const SEED_PURPOSE_DERIVED_FROM = {
+    shippingConfigs: { field: "storeId", collection: "stores" },
+    /*
+     * 🛑 `ownerId` → `users`, NOT `storeId` → `stores`. I wrote the store form
+     * first and the data disproved it: measured, `analyticsCardsSeedData` carries
+     * **zero** `storeId` fields — every row is `{ scope: "seller", ownerId:
+     * "user-tyson-blader", … }`. So these follow the USER whose dashboard they
+     * compose, and since that user is a test persona all nine correctly resolve
+     * `test`.
+     *
+     * Worth recording because the wrong field does not error: a derived row whose
+     * named field is absent falls to `test`, which happened to be the right
+     * answer here and would have silently been the WRONG one for a card owned by
+     * the admin.
+     */
+    analyticsCards: { field: "ownerId", collection: "users" },
+};
+/**
+ * Resolution order, most specific first:
+ *
+ *   1. the row's own inline `seedPurpose`
+ *   2. a per-row override in `SEED_ROW_PURPOSE`, by `id` or `uid`
+ *   3. for a DERIVED collection, the purpose of the row it references
+ *   4. the collection default
+ *   5. `test`
+ *
+ * 🛑 Step 3 is what holds the referential invariant. A `shippingConfig` for
+ * `store-letitrip-official` resolves `permanent`; one for
+ * `store-beyblade-arena` resolves `test` and is purged alongside the store it
+ * configures, rather than outliving it.
+ */
+export function resolveSeedPurpose(collection, row, 
+/**
+ * The document id, when the caller has it and the row does not.
+ *
+ * 🛑 Required by `loadGeneric`, which does `let { id, ...data } = docData`
+ * and therefore hands this function a row with **no `id` at all**. Without
+ * this parameter the per-row overrides silently did not apply: measured,
+ * `store-letitrip-official` loaded as `test` — i.e. the platform's own store
+ * would have been purged, which is exactly the row the keep-list exists to
+ * protect. `loadUsers` was unaffected because `{ ...u }` keeps `uid`, which
+ * is why the admin override worked and the store one did not.
+ */
+docId) {
+    if (row && isSeedPurpose(row.seedPurpose))
+        return row.seedPurpose;
+    /* `"<collection>:<id>"` — the collection half is what stops a users
+     * override also matching that user's CART, which is keyed on the same id. */
+    const rowKey = (coll, id) => `${coll}:${id}`;
+    if (docId && isSeedPurpose(SEED_ROW_PURPOSE[rowKey(collection, docId)]))
+        return SEED_ROW_PURPOSE[rowKey(collection, docId)];
+    if (row) {
+        /* `users` seed rows carry `uid` and no `id`; everything else carries `id`. */
+        const ownId = typeof row.id === "string" ? row.id : typeof row.uid === "string" ? row.uid : null;
+        if (ownId && isSeedPurpose(SEED_ROW_PURPOSE[rowKey(collection, ownId)]))
+            return SEED_ROW_PURPOSE[rowKey(collection, ownId)];
+        const derived = SEED_PURPOSE_DERIVED_FROM[collection];
+        if (derived) {
+            const refId = row[derived.field];
+            if (typeof refId === "string") {
+                const refOverride = SEED_ROW_PURPOSE[rowKey(derived.collection, refId)];
+                if (isSeedPurpose(refOverride))
+                    return refOverride;
+                const refDefault = SEED_COLLECTION_PURPOSE[derived.collection];
+                return isSeedPurpose(refDefault) ? refDefault : "test";
+            }
+            /*
+             * A derived row with no reference cannot inherit, and guessing
+             * `permanent` would be the dangling-FK failure this map exists to
+             * prevent. `test` is the safe answer: it is re-seedable.
+             */
+            return "test";
+        }
+    }
+    const declared = SEED_COLLECTION_PURPOSE[collection];
+    return isSeedPurpose(declared) ? declared : "test";
+}
+/**
+ * The fields to write for a purpose — exactly one.
+ *
+ * 🛑 It does **not** touch `isTestData` or `testDataExpiresAt`, and that
+ * restraint is the whole correction described in the header: deriving
+ * `isTestData` from `test` would have hidden every seeded product, category and
+ * store from the public site while reporting a clean load.
+ *
+ * Kept as a function rather than inlined so there is one place to look when
+ * someone asks "what does a purpose actually write?", and so the next field
+ * (if one is ever justified) lands in one place.
+ */
+export function seedPurposeFields(purpose) {
+    return { seedPurpose: purpose };
+}
+/**
+ * Stamp a row for writing. The one function every loader calls, so the CLI and
+ * `runSeed` cannot disagree about what a purpose means — Root Cause #75's shape
+ * on the seed axis (a rule reachable by copy-paste gets copied, and the copy
+ * made before a branch was added never learns about it).
+ *
+ * Returns a NEW object; the seed arrays are module-level constants re-imported
+ * on every CLI invocation and must not be mutated.
+ */
+export function stampSeedPurpose(collection, row, 
+/** Pass this whenever the caller holds the id and the row does not — see
+ *  `resolveSeedPurpose`'s `docId` for why `loadGeneric` must. */
+docId) {
+    /*
+     * The cast is to `Record<string, unknown>` only, which is a WIDENING — every
+     * object satisfies it structurally, and `resolveSeedPurpose` reads `id`,
+     * `uid` and the derived `field` with `typeof` guards rather than trusting the
+     * type. 🛑 Deliberately NOT `as any`: that would silence the `collection`
+     * argument's check too, which is the mistake the plan records at the
+     * `sendNotification`/`as never` sites.
+     */
+    const purpose = resolveSeedPurpose(collection, row, docId);
+    return { ...row, ...seedPurposeFields(purpose) };
+}
+/**
+ * Mark a whole array as something other than its collection default — the
+ * readable way to say "this file is permanent" (or "this file is fixtures")
+ * without repeating the field on every row.
+ *
+ * Sets the row-level override, so it beats the collection default and is
+ * visible at the call site.
+ */
+export function asSeedPurpose(purpose, rows) {
+    return rows.map((row) => ({ ...row, seedPurpose: purpose }));
+}
+/**
+ * How long a `test` row survives before a purge may take it.
+ *
+ * 🛑 STOP-GAP, added 2026-10-12 to unbreak the build — NOT a design decision,
+ * and whoever owns `seedPurpose` should replace it with the real declaration.
+ *
+ * This file arrived with `src/seed/index.ts:247` and `src/index.ts:1935` ALREADY
+ * re-exporting `SEED_TEST_TTL_DAYS` from here while nothing declared it, so
+ * `tsc` failed with TS2305 and appkit did not compile at all — the half-finished
+ * public-surface rename of Root Cause #20, where the barrel landed without the
+ * definition. (The same commit also carried `sxdexport const` on line 149,
+ * i.e. stray keystrokes, which is the likelier reading of what happened here.)
+ *
+ * Aliased to the EXISTING value rather than given a fresh number: a retention
+ * window is a product decision and inventing one would have been worse than the
+ * compile error. `TEST_DATA_TTL_DAYS` is 7 and is what `testDataExpiresAt()`
+ * already stamps on every test row, so this is behaviour-preserving by
+ * construction — and when the two names are reconciled, there is exactly one
+ * number to change.
+ */
+export { TEST_DATA_TTL_DAYS as SEED_TEST_TTL_DAYS } from "./test-data-ttl.js";

package/dist/seed/sessions-seed-data.js

@@ -13,9 +13,9 @@
  * @tag consumers:seed/index.ts,seed/runner.ts
  * @tag sideEffects:none
  */
-import { getSeedLocale } from "./seed-market-config";
+import { getSeedLocale } from "./seed-market-config.js";
 const _locale = getSeedLocale();
-import { SESSION_COLLECTION, } from "../features/auth/schemas";
+import { SESSION_COLLECTION, } from "../features/auth/schemas/index.js";
 const NOW = new Date();
 const daysAgo = (n) => new Date(NOW.getTime() - n * 86400000);
 const daysAhead = (n) => new Date(NOW.getTime() + n * 86400000);

package/dist/seed/shipments-seed-data.js

@@ -15,7 +15,7 @@
  *   shipmentLotsSeedData  — Array of Partial<ShipmentLot>
  *   shipmentItemsSeedData — Array of Partial<ShipmentItem>
  */
-import { allocateShipmentCosts } from "../features/shipments/utils/cost-allocation";
+import { allocateShipmentCosts } from "../features/shipments/utils/cost-allocation.js";
 const NOW = new Date();
 const daysAgo = (n) => new Date(NOW.getTime() - n * 86400000);
 const daysFromNow = (n) => new Date(NOW.getTime() + n * 86400000);

package/dist/seed/site-settings-seed-data.js

@@ -12,9 +12,9 @@
  * @tag consumers:seed/index.ts,seed/runner.ts
  * @tag sideEffects:none
  */
-import { seedExtMedia, seedPhoto } from "./_helpers/media";
-import { ROUTES } from "../next/routing/route-map";
-import { DEFAULT_AUCTION_BID_INCREMENT_TIERS } from "../_internal/shared/features/auctions/config";
+import { seedExtMedia, seedPhoto } from "./_helpers/media.js";
+import { ROUTES } from "../next/routing/route-map.js";
+import { DEFAULT_AUCTION_BID_INCREMENT_TIERS } from "../_internal/shared/features/auctions/config.js";
 const NOW = new Date();
 const daysAgo = (n) => new Date(NOW.getTime() - n * 86400000);
 const adPlacementsSeed = [
@@ -311,6 +311,9 @@ export const siteSettingsSeedData = {
     shipping: {
         estimatedDays: 7,
         minOrderForFree: 999,
+        // C5c — manual until a Shiprocket provider AND credentials exist. A
+        // seeded `shiprocket` would throw at boot by design.
+        provider: "manual",
     },
     returns: {
         windowDays: 7,
@@ -470,6 +473,9 @@ export const siteSettingsSeedData = {
         shipmentProtectionFeeEnabled: true,
         shipmentProtectionFeePercent: 2,
         shipmentProtectionFeeMin: 30,
+        saleProtectionFeeEnabled: true,
+        saleProtectionFeePercent: 3,
+        saleProtectionFeeMin: 49,
         sellerShippingFixed: 0,
         platformShippingPercent: 0,
         platformShippingFixedMin: 0,

package/dist/seed/store-addresses-seed-data.js

@@ -13,7 +13,7 @@
  * @tag consumers:seed/index.ts,seed/runner.ts
  * @tag sideEffects:none
  */
-import { getSeedLocale, getDefaultPhonePrefix } from "./seed-market-config";
+import { getSeedLocale, getDefaultPhonePrefix } from "./seed-market-config.js";
 const _locale = getSeedLocale();
 const _phonePrefix = getDefaultPhonePrefix();
 const NOW = new Date();

package/dist/seed/store-extensions-seed-data.js

@@ -16,7 +16,7 @@
  * @tag consumers:seed/index.ts,seed/runner.ts
  * @tag sideEffects:none
  */
-import { seedPhoto } from "./_helpers/media";
+import { seedPhoto } from "./_helpers/media.js";
 const NOW = new Date();
 // ───── payoutMethods (4 records) ──────────────────────────────────────────
 export const payoutMethodsSeedData = [

package/dist/seed/stores-seed-data.js

@@ -16,9 +16,9 @@
  * @tag consumers:seed/runner.ts
  * @tag sideEffects:none
  */
-import { withStoreSearchTxt } from "./_helpers/search-txt-wrappers";
-import { STORE_FIELDS } from "../constants/field-names";
-import { seedPhoto } from "./_helpers/media";
+import { withStoreSearchTxt } from "./_helpers/search-txt-wrappers.js";
+import { STORE_FIELDS } from "../constants/field-names.js";
+import { seedPhoto } from "./_helpers/media.js";
 const NOW = new Date();
 const daysAgo = (n) => new Date(NOW.getTime() - n * 86400000);
 /**

package/dist/seed/support-tickets-seed-data.js

@@ -12,8 +12,8 @@
  * @tag consumers:seed/index.ts,seed/runner.ts
  * @tag sideEffects:none
  */
-import { SUPPORT_TICKET_FIELDS } from "../constants/field-names";
-import { buildSearchTxt } from "../utils/search-txt";
+import { SUPPORT_TICKET_FIELDS } from "../constants/field-names.js";
+import { buildSearchTxt } from "../utils/search-txt.js";
 function msg(id, authorId, authorRole, body, daysAgo) {
     const createdAt = new Date(Date.now() - daysAgo * 24 * 60 * 60 * 1000);
     return { id, authorId, authorRole, body, createdAt };

package/dist/seed/test-utils.js

@@ -1,11 +1,11 @@
-import { runSeed } from "./runner";
-import { encryptPiiFields, decryptPiiFields, ENC_PREFIX } from "../security/pii-encrypt";
-import { hasEncPrefix } from "../security/pii-mask";
-import { DEFAULT_CATEGORIES } from "./defaults/categories";
-import { DEFAULT_FAQS } from "./defaults/faqs";
-import { makeProduct } from "./factories/product.factory";
-import { USER_FIXTURES } from "./factories/user.factory";
-import { makeStore } from "./factories/store.factory";
+import { runSeed } from "./runner.js";
+import { encryptPiiFields, decryptPiiFields, ENC_PREFIX } from "../security/pii-encrypt.js";
+import { hasEncPrefix } from "../security/pii-mask.js";
+import { DEFAULT_CATEGORIES } from "./defaults/categories.js";
+import { DEFAULT_FAQS } from "./defaults/faqs.js";
+import { makeProduct } from "./factories/product.factory.js";
+import { USER_FIXTURES } from "./factories/user.factory.js";
+import { makeStore } from "./factories/store.factory.js";
 // ---------------------------------------------------------------------------
 // PII round-trip assertion
 // ---------------------------------------------------------------------------

package/dist/seed/users-seed-data.js

@@ -18,10 +18,10 @@
  * @tag consumers:seed/runner.ts
  * @tag sideEffects:none
  */
-import { getDefaultPhonePrefix } from "./seed-market-config";
-import { PERMISSION_GROUPS } from "../features/auth/permissions/constants";
-import { USER_FIELDS } from "../constants/field-names";
-import { seedPhoto } from "./_helpers/media";
+import { getDefaultPhonePrefix } from "./seed-market-config.js";
+import { PERMISSION_GROUPS } from "../features/auth/permissions/constants.js";
+import { USER_FIELDS } from "../constants/field-names.js";
+import { seedPhoto } from "./_helpers/media.js";
 const _ph = getDefaultPhonePrefix();
 const NOW = new Date();
 const daysAgo = (n) => new Date(NOW.getTime() - n * 86400000);

package/dist/seo/index.js

@@ -1,2 +1,2 @@
-export * from "./json-ld";
-export * from "./metadata";
+export * from "./json-ld.js";
+export * from "./metadata.js";

package/dist/seo/json-ld.d.ts

@@ -93,7 +93,16 @@ export interface FaqJsonLdInput {
 }
 export interface BreadcrumbJsonLdItem {
     name: string;
-    url: string;
+    /**
+     * Absent on the LAST crumb — the page you are already on.
+     *
+     * 🛑 This was required, and `url.startsWith(...)` threw on a missing one. It
+     * is optional because schema.org's own breadcrumb guidance is that the final
+     * element identifies the current page and its `item` may be omitted; a
+     * self-link there is accepted but says nothing. Every existing caller passes
+     * a url, so widening it breaks none of them.
+     */
+    url?: string;
 }
 export interface BlogPostJsonLdInput {
     title: string;
@@ -163,4 +172,66 @@ export interface SiteIdentityOptions {
 export declare function organizationJsonLd(opts?: SiteIdentityOptions): Record<string, JsonLdValue>;
 export declare function searchBoxJsonLd(opts?: SiteIdentityOptions): Record<string, JsonLdValue>;
 export declare function auctionJsonLd(auction: ProductJsonLdInput): Record<string, JsonLdValue>;
+export interface ItemListJsonLdEntry {
+    name: string;
+    /** Path or absolute URL. Absolutised against the ONE canonical host. */
+    url: string;
+    image?: string;
+}
+/**
+ * `ItemList` — the names and URLs of what a listing page shows.
+ *
+ * 🛑 NO `offers`, NO price, and this is not a style choice.
+ *
+ * Two independent reasons, and either alone settles it. Prices are hidden from
+ * signed-out visitors and Googlebot crawls signed out, so a price here would be
+ * markup the user cannot see — the mismatch `gatedPriceWebPageJsonLd` exists to
+ * declare, except there is nothing to declare on a list because the list never
+ * shows a price at all. And `audit-guest-price-leak` R3 blocks it outright.
+ *
+ * It is also exactly what hobbykartindia.com does — server-side `ItemList`
+ * carrying price — and §2 records it as the thing not to copy.
+ *
+ * A list of names and URLs is still worth emitting: it tells a crawler what the
+ * page is a list OF, which is the one thing a grid of cards does not say in
+ * markup.
+ */
+export declare function itemListJsonLd(entries: readonly ItemListJsonLdEntry[]): Record<string, JsonLdValue>;
+export interface CollectionPageJsonLdInput {
+    name: string;
+    /** Path or absolute URL for this collection. */
+    url: string;
+    description?: string;
+    /**
+     * The items shown, if any. Omitted or empty emits a `CollectionPage` with no
+     * `mainEntity` — which is correct for a collection whose contents are
+     * paginated or filtered, and far better than an `ItemList` of zero claiming
+     * the collection is empty.
+     */
+    items?: readonly ItemListJsonLdEntry[];
+    /**
+     * Total across all pages, when it differs from `items.length`.
+     *
+     * 🛑 `truncated` matters here for the same reason it does in the list
+     * envelope: a `CollectionPage` on page 1 of 12 that declares
+     * `numberOfItems: 24` is telling a crawler the collection has 24 items. Pass
+     * the real total and the markup stops lying about scale.
+     */
+    totalItems?: number;
+}
+/**
+ * `CollectionPage` — what a category, brand or listing index actually is.
+ *
+ * 🛑 The category tab page emitted NO JSON-LD whatsoever (verified: zero
+ * `ld+json` under `features/categories/`), while worldhobbyshop — the SEO
+ * leader of the fifteen crawled — ships a 6-level `BreadcrumbList` and a
+ * `CollectionPage`, and no Shopify competitor has either. §5 ranks this the
+ * highest-impact SEO change in the plan, and it costs nothing at render: the
+ * route is already dynamic SSR and `ancestors[]` rides a read it already does.
+ *
+ * Pair it with `breadcrumbJsonLd` — the two answer different questions ("what
+ * is this page" and "where does it sit"), and the breadcrumb is the half the
+ * competition does not have.
+ */
+export declare function collectionPageJsonLd(input: CollectionPageJsonLdInput): Record<string, JsonLdValue>;
 export {};