@mohasinac/appkit 4.13.1 → 4.15.0

package/dist/_internal/shared/history/history.js

@@ -0,0 +1,198 @@
+/**
+ * Tracked-field diffing and capped append for entity status history.
+ *
+ * These are deliberately plain functions rather than a `BaseRepository`
+ * override: the repository method that owns a transition already knows the
+ * actor and the trigger, and a generic hook would have to guess both. The
+ * repository calls `buildHistoryEntry` + `appendHistoryEntry` inside its own
+ * write primitive — which is the point, since that is what keeps the 32
+ * call sites above it unchanged.
+ */
+import { normalizeError } from "../../../errors/normalize";
+import { STATUS_HISTORY_MAX, } from "./types";
+/**
+ * Structural equality for field values.
+ *
+ * Tracked fields are not all scalars, so identity comparison would flag an
+ * unchanged object as changed on every write. Dates compare by instant,
+ * because Firestore hands back a fresh object on every read — without this,
+ * re-saving a document with no edits would append a history entry.
+ */
+function isSameValue(a, b) {
+    if (a === b)
+        return true;
+    if (a == null || b == null)
+        return a == null && b == null;
+    const aDate = toDateOrNull(a);
+    const bDate = toDateOrNull(b);
+    if (aDate && bDate)
+        return aDate.getTime() === bDate.getTime();
+    if (aDate || bDate)
+        return false;
+    if (typeof a !== "object" || typeof b !== "object")
+        return false;
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch (err) {
+        void normalizeError(err);
+        // Circular or non-serialisable — treat as changed rather than throwing
+        // inside a write path.
+        return false;
+    }
+}
+/** Firestore Timestamps expose `toDate()`; plain Dates are used directly. */
+function toDateOrNull(v) {
+    if (v instanceof Date)
+        return v;
+    if (typeof v === "object" && v !== null && typeof v.toDate === "function") {
+        try {
+            return v.toDate();
+        }
+        catch (err) {
+            void normalizeError(err);
+            // A Timestamp-like object whose toDate() threw is not a usable date;
+            // the caller treats null as "not a date" and falls through to structural
+            // comparison, so there is nothing to report.
+            return null;
+        }
+    }
+    return null;
+}
+/** Read a possibly-dotted path (`emiInstallments.0.status`) off an object. */
+function readPath(source, path) {
+    if (!source)
+        return undefined;
+    if (!path.includes("."))
+        return source[path];
+    let cursor = source;
+    for (const segment of path.split(".")) {
+        if (cursor == null || typeof cursor !== "object")
+            return undefined;
+        cursor = cursor[segment];
+    }
+    return cursor;
+}
+/**
+ * Diff only the fields an entity declares as tracked.
+ *
+ * The tracked list is explicit per entity, never "every field": a whole-
+ * document diff would record the `updatedAt` bump on every single write and
+ * exhaust the 50-entry cap within days, burying the transitions anyone
+ * actually wants to read.
+ *
+ * A field absent from `patch` is untouched — this diffs the patch against
+ * the current document, not two full documents.
+ */
+export function diffTrackedFields(current, patch, tracked) {
+    const changes = {};
+    for (const field of tracked) {
+        if (!(field in patch) && !field.includes("."))
+            continue;
+        const to = readPath(patch, field);
+        if (to === undefined)
+            continue;
+        const from = readPath(current, field);
+        if (isSameValue(from, to))
+            continue;
+        changes[field] = { from: from ?? null, to };
+    }
+    return changes;
+}
+/**
+ * Remove PII-named keys from a `changes` map, at any depth.
+ *
+ * Two passes are needed because PII can arrive two ways: as a tracked field
+ * that happens to be PII (`buyerEmail` in `changes`), or nested inside a
+ * value a caller contributed via `extraChanges` (a refund's `reason`, an
+ * offer note object). `encryptPiiFields` catches neither — it only ever
+ * looks at top-level string properties of the document itself.
+ *
+ * Scrubbed rather than redacted-in-place: an entry that silently omits a
+ * field is honest, whereas one containing `"[redacted]"` invites a reader to
+ * assume the real value is recoverable somewhere.
+ */
+function scrubPii(changes, piiFields) {
+    if (!piiFields?.length)
+        return changes;
+    const pii = new Set(piiFields);
+    const stripNested = (v) => {
+        if (v == null || typeof v !== "object")
+            return v;
+        if (v instanceof Date)
+            return v;
+        if (Array.isArray(v))
+            return v.map(stripNested);
+        const out = {};
+        for (const [k, val] of Object.entries(v)) {
+            if (pii.has(k))
+                continue;
+            out[k] = stripNested(val);
+        }
+        return out;
+    };
+    const result = {};
+    for (const [field, change] of Object.entries(changes)) {
+        if (pii.has(field))
+            continue; // the tracked field itself is PII
+        result[field] = { from: stripNested(change.from), to: stripNested(change.to) };
+    }
+    return result;
+}
+export function buildHistoryEntry(input) {
+    const entry = {
+        at: input.now ?? new Date(),
+        actorRole: input.actor.role,
+        changes: input.changes,
+        trigger: input.trigger,
+    };
+    if (input.actor.uid)
+        entry.actorUid = input.actor.uid;
+    if (input.reason)
+        entry.reason = input.reason;
+    if (input.note)
+        entry.note = input.note;
+    return entry;
+}
+/**
+ * Append with a FIFO cap. Returns the new array plus the running count of
+ * entries dropped over the document's lifetime, so the caller can persist it
+ * and the UI can be honest about what it is not showing.
+ */
+export function appendHistoryEntry(existing, entry, previousTruncatedCount = 0, cap = STATUS_HISTORY_MAX) {
+    const next = [...(existing ?? []), entry];
+    if (next.length <= cap) {
+        return { history: next, truncatedCount: previousTruncatedCount };
+    }
+    const overflow = next.length - cap;
+    return {
+        history: next.slice(overflow),
+        truncatedCount: previousTruncatedCount + overflow,
+    };
+}
+/**
+ * The whole flow in one call: diff, and return the patch additions needed to
+ * record it. Returns `null` when no tracked field changed — the caller then
+ * writes its patch unchanged, so an untracked update never grows the array.
+ */
+export function withHistory(current, patch, opts) {
+    const changes = scrubPii({ ...diffTrackedFields(current, patch, opts.tracked), ...opts.extraChanges }, opts.piiFields);
+    if (Object.keys(changes).length === 0)
+        return null;
+    const historyField = opts.historyField ?? "statusHistory";
+    const truncatedField = opts.truncatedField ?? "statusHistoryTruncated";
+    const entry = buildHistoryEntry({
+        actor: opts.actor,
+        trigger: opts.trigger,
+        changes,
+        reason: opts.reason,
+        note: opts.note,
+        now: opts.now,
+    });
+    const { history, truncatedCount } = appendHistoryEntry(readPath(current, historyField) ?? [], entry, readPath(current, truncatedField) ?? 0, opts.cap);
+    return {
+        ...patch,
+        [historyField]: history,
+        ...(truncatedCount > 0 ? { [truncatedField]: truncatedCount } : {}),
+    };
+}

package/dist/_internal/shared/history/index.d.ts

@@ -0,0 +1,4 @@
+export type { HistoryActorRole, HistoryActor, FieldChange, StatusChangeEntry, AppendHistoryResult, } from "./types";
+export { STATUS_HISTORY_MAX } from "./types";
+export type { BuildHistoryEntryInput } from "./history";
+export { diffTrackedFields, buildHistoryEntry, appendHistoryEntry, withHistory, } from "./history";

package/dist/_internal/shared/history/index.js

@@ -0,0 +1,2 @@
+export { STATUS_HISTORY_MAX } from "./types";
+export { diffTrackedFields, buildHistoryEntry, appendHistoryEntry, withHistory, } from "./history";

package/dist/_internal/shared/history/types.d.ts

@@ -0,0 +1,61 @@
+import type { FirestoreValue } from "../../../schemas/types";
+/**
+ * Generic entity status history — the shape shared by every entity that
+ * records how it got to its current state.
+ *
+ * Built for orders first (W2) and adopted by stores, payouts, offers, bids,
+ * support tickets, scammer profiles, catalogue approvals, shipments and
+ * returns in W15. Before this existed, exactly ONE of ~40 status-bearing
+ * entities had any history at all — `ads`, built inline in a route handler
+ * with no type and no reuse.
+ */
+export type HistoryActorRole = "buyer" | "seller" | "admin" | "system";
+export interface HistoryActor {
+    /** Firebase Auth uid. Absent for `system` (cron jobs, Firestore triggers). */
+    uid?: string;
+    role: HistoryActorRole;
+}
+/** A single field's before/after. `from` is `null` on the creation entry. */
+export interface FieldChange {
+    from: FirestoreValue;
+    to: FirestoreValue;
+}
+export interface StatusChangeEntry {
+    at: Date;
+    actorUid?: string;
+    actorRole: HistoryActorRole;
+    /**
+     * DELTA ONLY — the tracked fields that actually changed, never a copy of
+     * the whole document. A full snapshot per transition would duplicate the
+     * record on every status change; the whole point of this shape is that it
+     * does not.
+     */
+    changes: Record<string, FieldChange>;
+    /** Why, when a human supplied a reason (cancellation, rejection). */
+    reason?: string;
+    /** Free-text note from an admin/seller action. */
+    note?: string;
+    /**
+     * The function, route or job that caused the change — `"customShipOrder"`,
+     * `"paymentWindowTimeout"`, `"adminVerifyPayment"`. This is what the
+     * timeline renders by, which is why per-path events (proof uploaded,
+     * installment paid, winner revealed) need NO new status values.
+     */
+    trigger: string;
+}
+/**
+ * Cap for any history array. Matches `HISTORY_MAX`'s reasoning: an unbounded
+ * array on a hot document inflates every read of that document (Rule #6), and
+ * an order that changes status more than this has a different problem.
+ */
+export declare const STATUS_HISTORY_MAX = 50;
+export interface AppendHistoryResult {
+    history: StatusChangeEntry[];
+    /**
+     * How many entries have been dropped off the front across the document's
+     * lifetime. Surfaced so the UI can say "earlier history trimmed" instead
+     * of implying none existed — silent truncation reads as "this is all of
+     * it", which is the same lie as a silently dropped field.
+     */
+    truncatedCount: number;
+}

package/dist/_internal/shared/history/types.js

@@ -0,0 +1,6 @@
+/**
+ * Cap for any history array. Matches `HISTORY_MAX`'s reasoning: an unbounded
+ * array on a hot document inflates every read of that document (Rule #6), and
+ * an order that changes status more than this has a different problem.
+ */
+export const STATUS_HISTORY_MAX = 50;

package/dist/_internal/shared/listing-types/_registry.d.ts

@@ -22,8 +22,10 @@
  * that doesn't cover the full union.
  */
 import { LISTING_TYPE_CAPABILITIES } from "./capabilities";
+import { type AvailabilityRow, type UnavailableClause } from "./availability";
 import type { ListingType } from "../../../features/products/types/index";
 import type { SortOption } from "../../../features/products/constants/sieve";
+import { type AvailabilityFilter } from "../../../constants/field-names";
 /**
  * Which "Show X" quick-filter a listing type's browse surfaces default to
  * hiding. Drives both the toolbar toggle label and the SSR default filter,
@@ -78,8 +80,29 @@ export interface ListingTypePlugin {
      * /products when exactly this type is selected.
      */
     browseRoute: string | null;
-    /** Which "Show X" default this type's browse surfaces apply. */
+    /**
+     * Which "Show X" default this type's browse surfaces apply. Since 2026-08-24
+     * this drives the LABEL of the availability tab bar's middle tab
+     * (`availabilityTabsFor`) rather than a toggle pill's wording.
+     */
     hideDefault: ListingHideDefault;
+    /**
+     * Is this row still buyable / biddable / enterable? Type-specific checks
+     * ONLY — `baseAvailable` (isSold / availableQuantity / stockQuantity) is
+     * applied to every type by `isListingRowAvailable` before this runs, so a
+     * type with no extra rule returns `true`.
+     *
+     * Must stay pure and client-safe: the same predicate runs inside the SSR
+     * query, the homepage fetch and the related-items carousel.
+     */
+    isAvailable: (row: AvailabilityRow, now: Date) => boolean;
+    /**
+     * The query half of the same question — see `UnavailableClause`. Used to
+     * front-load the "Sold & Ended" scope, which is sparse and therefore
+     * expressible as an OR of equalities, unlike "available", which is dense and
+     * negation-shaped and stays an in-memory predicate.
+     */
+    unavailableClauses: readonly UnavailableClause[];
     /** Sort set offered on admin/seller dashboards for this type. */
     sortOptions: readonly SortOption[];
     /** Narrower sort set offered on public browse surfaces for this type. */
@@ -124,4 +147,34 @@ export declare function commonSortOptionsFor(types: readonly ListingType[], vari
  * so this returns every distinct default across the set.
  */
 export declare function hideDefaultsFor(types: readonly ListingType[]): ListingHideDefault[];
+export interface AvailabilityTab {
+    id: AvailabilityFilter;
+    label: string;
+}
+/**
+ * The three-tab availability bar for a set of listing types.
+ *
+ * The middle label is derived, not a constant: `/auctions` reads "Ended",
+ * `/art` reads "Sold", and `/products` — which spans both kinds — reads
+ * "Sold & Ended". Ordering is fixed rather than set-iteration order so the
+ * label can never flip to "Ended & Sold" between renders.
+ */
+export declare function availabilityTabsFor(types: readonly ListingType[]): AvailabilityTab[];
+/**
+ * THE definition of "this listing is still available", shared by the listing
+ * query, the homepage fetch and the related-items carousel. Before this there
+ * were four partial versions of it and they disagreed — see the header of
+ * `./availability`.
+ *
+ * An unrecognised `listingType` falls back to `standard` rather than throwing:
+ * these rows come from Firestore and a bad value must degrade to the base
+ * checks, not blank the page.
+ */
+export declare function isListingRowAvailable(row: AvailabilityRow, now: Date): boolean;
+/**
+ * Every distinct `UnavailableClause` across a set of listing types, deduped by
+ * field+op+value. `/products` (all nine types) collapses to five clauses, so
+ * the "Sold & Ended" scope costs five bounded queries, not nine.
+ */
+export declare function unavailableClausesFor(types: readonly ListingType[]): UnavailableClause[];
 export { LISTING_TYPE_CAPABILITIES };

package/dist/_internal/shared/listing-types/_registry.js

@@ -33,6 +33,8 @@ import * as live from "./live/config";
 import * as art from "./art/config";
 import * as stickers from "./stickers/config";
 import { LISTING_TYPE_CAPABILITIES } from "./capabilities";
+import { baseAvailable, } from "./availability";
+import { AVAILABILITY_VALUES, } from "../../../constants/field-names";
 // SB-UNI-D — bundle entry removed; bundles are a categoryType, not a listingType.
 // SB-UNI-F 2026-05-13 — classified / digital-code / live added.
 // EMI/art-stickers session — art / stickers added.
@@ -112,6 +114,71 @@ export function hideDefaultsFor(types) {
         seen.add(LISTING_TYPE_REGISTRY[type].hideDefault);
     return [...seen];
 }
+// ---------------------------------------------------------------------------
+// Availability scope
+// ---------------------------------------------------------------------------
+/**
+ * The user-facing noun for each hide-default. "ended" and "closed" are one
+ * query mechanic and one word to a buyer — an auction that ended and a prize
+ * draw that closed are both simply over.
+ *
+ * `Record<ListingHideDefault, …>` on purpose: adding a fourth hide-default is
+ * then a compile error rather than a tab that silently renders `undefined`.
+ */
+const HIDE_DEFAULT_NOUN = {
+    sold: "Sold",
+    ended: "Ended",
+    closed: "Ended",
+};
+/**
+ * The three-tab availability bar for a set of listing types.
+ *
+ * The middle label is derived, not a constant: `/auctions` reads "Ended",
+ * `/art` reads "Sold", and `/products` — which spans both kinds — reads
+ * "Sold & Ended". Ordering is fixed rather than set-iteration order so the
+ * label can never flip to "Ended & Sold" between renders.
+ */
+export function availabilityTabsFor(types) {
+    const nouns = new Set((types.length > 0 ? types : Object.keys(LISTING_TYPE_REGISTRY)).map((t) => HIDE_DEFAULT_NOUN[LISTING_TYPE_REGISTRY[t].hideDefault]));
+    const unavailableLabel = ["Sold", "Ended"].filter((n) => nouns.has(n)).join(" & ") || "Sold";
+    return [
+        { id: AVAILABILITY_VALUES.AVAILABLE, label: "Available" },
+        { id: AVAILABILITY_VALUES.UNAVAILABLE, label: unavailableLabel },
+        { id: AVAILABILITY_VALUES.ALL, label: "All" },
+    ];
+}
+/**
+ * THE definition of "this listing is still available", shared by the listing
+ * query, the homepage fetch and the related-items carousel. Before this there
+ * were four partial versions of it and they disagreed — see the header of
+ * `./availability`.
+ *
+ * An unrecognised `listingType` falls back to `standard` rather than throwing:
+ * these rows come from Firestore and a bad value must degrade to the base
+ * checks, not blank the page.
+ */
+export function isListingRowAvailable(row, now) {
+    if (!baseAvailable(row))
+        return false;
+    const raw = row.listingType;
+    const type = typeof raw === "string" && raw in LISTING_TYPE_REGISTRY ? raw : "standard";
+    return LISTING_TYPE_REGISTRY[type].isAvailable(row, now);
+}
+/**
+ * Every distinct `UnavailableClause` across a set of listing types, deduped by
+ * field+op+value. `/products` (all nine types) collapses to five clauses, so
+ * the "Sold & Ended" scope costs five bounded queries, not nine.
+ */
+export function unavailableClausesFor(types) {
+    const effective = types.length > 0 ? types : Object.keys(LISTING_TYPE_REGISTRY);
+    const seen = new Map();
+    for (const type of effective) {
+        for (const clause of LISTING_TYPE_REGISTRY[type].unavailableClauses) {
+            seen.set(`${clause.field}|${clause.op}|${String(clause.value)}`, clause);
+        }
+    }
+    return [...seen.values()];
+}
 // Re-export the capability map so consumers can pull both surfaces from
 // the same module path.
 export { LISTING_TYPE_CAPABILITIES };

package/dist/_internal/shared/listing-types/art/config.d.ts

@@ -1,3 +1,4 @@
+import { alwaysAvailable } from "../availability";
 export declare const LISTING_TYPE: "art";
 export declare const capability: import("../capabilities").ListingTypeCapability;
 export declare const config: {
@@ -17,6 +18,8 @@ export declare const config: {
     chipLabel: string;
     browseRoute: string;
     hideDefault: "sold";
+    isAvailable: typeof alwaysAvailable;
+    unavailableClauses: readonly import("../availability").UnavailableClause[];
     sortOptions: readonly [{
         readonly value: string;
         readonly label: "Newest First";

package/dist/_internal/shared/listing-types/art/config.js

@@ -1,4 +1,5 @@
 import { LISTING_TYPE_CAPABILITIES } from "../capabilities";
+import { alwaysAvailable, STOCK_ONLY_UNAVAILABLE_CLAUSES, } from "../availability";
 import { ROUTES } from "../../../../next/routing/route-map";
 import { STANDARD_SORT_OPTIONS, STANDARD_PUBLIC_SORT_OPTIONS, } from "../../../../features/products/constants/sieve";
 export const LISTING_TYPE = "art";
@@ -20,6 +21,10 @@ export const config = {
     // dedicated browse surface even though detailRoute points at /products.
     browseRoute: String(ROUTES.PUBLIC.ART),
     hideDefault: "sold",
+    // Runs out rather than ending — no time dimension, so the shared
+    // stock-only rules are the whole story for this type.
+    isAvailable: alwaysAvailable,
+    unavailableClauses: STOCK_ONLY_UNAVAILABLE_CLAUSES,
     sortOptions: STANDARD_SORT_OPTIONS,
     publicSortOptions: STANDARD_PUBLIC_SORT_OPTIONS,
     extraFacetKeys: [],

package/dist/_internal/shared/listing-types/auction/config.d.ts

@@ -1,3 +1,4 @@
+import { type AvailabilityRow } from "../availability";
 export declare const LISTING_TYPE: "auction";
 export declare const capability: import("../capabilities").ListingTypeCapability;
 export declare const config: {
@@ -17,6 +18,18 @@ export declare const config: {
     chipLabel: string;
     browseRoute: string;
     hideDefault: "ended";
+    isAvailable: (row: AvailabilityRow, now: Date) => boolean;
+    unavailableClauses: ({
+        field: "auctionEndDate";
+        op: "lt";
+        value: "NOW";
+        sortField: "auctionEndDate";
+    } | {
+        field: "isSold";
+        op: "eq";
+        value: boolean;
+        sortField?: undefined;
+    })[];
     sortOptions: readonly [{
         readonly value: string;
         readonly label: "Ending Soon";

package/dist/_internal/shared/listing-types/auction/config.js

@@ -1,6 +1,8 @@
 import { LISTING_TYPE_CAPABILITIES } from "../capabilities";
+import { toDate } from "../availability";
 import { ROUTES } from "../../../../next/routing/route-map";
 import { TABLE_KEYS } from "../../../../constants/table-keys";
+import { PRODUCT_FIELDS } from "../../../../constants/field-names";
 import { AUCTION_SORT_OPTIONS, AUCTION_PUBLIC_SORT_OPTIONS, } from "../../../../features/products/constants/sieve";
 export const LISTING_TYPE = "auction";
 export const capability = LISTING_TYPE_CAPABILITIES.auction;
@@ -20,6 +22,25 @@ export const config = {
     // An auction is never "sold out" — it ends. Hiding by stock would hide
     // every live auction, since auctions don't carry meaningful stock.
     hideDefault: "ended",
+    // There is no `auctionStatus` field — "ended" is purely the end date having
+    // passed. An auction with no end date at all is treated as live rather than
+    // hidden; a missing date is a data defect, not a signal that it is over.
+    isAvailable: (row, now) => {
+        const end = toDate(row[PRODUCT_FIELDS.AUCTION_END_DATE]);
+        return end === null || end > now;
+    },
+    unavailableClauses: [
+        // The ONLY inequality in the registry — safe because it names the sort
+        // field the query must order by, which is also the natural sort for an
+        // "ended auctions" archive ("Recently Ended").
+        {
+            field: PRODUCT_FIELDS.AUCTION_END_DATE,
+            op: "lt",
+            value: "NOW",
+            sortField: PRODUCT_FIELDS.AUCTION_END_DATE,
+        },
+        { field: PRODUCT_FIELDS.IS_SOLD, op: "eq", value: true },
+    ],
     sortOptions: AUCTION_SORT_OPTIONS,
     publicSortOptions: AUCTION_PUBLIC_SORT_OPTIONS,
     extraFacetKeys: [

package/dist/_internal/shared/listing-types/availability.d.ts

@@ -0,0 +1,79 @@
+import type { FirestoreValue } from "../../../schemas/types";
+/**
+ * A product row as it reaches a predicate.
+ *
+ * Deliberately the project’s sanctioned loose Firestore-row alias rather than
+ * `ProductDocument`: the same row arrives here in three shapes — a Firestore
+ * document (Date / Timestamp fields), an already-serialised payload from the
+ * colocated `listingProcessor` Function (ISO strings), and JSON from
+ * `/api/products`. Narrowing to any one of them would just push a cast to
+ * every call site.
+ */
+export type AvailabilityRow = Record<string, FirestoreValue>;
+/**
+ * Everything a timestamp field can be by the time it reaches `toDate`. The
+ * `{ toDate() }` arm is a Firestore `Timestamp`, which cannot be imported
+ * here — this module is client-safe and firebase-admin is not.
+ */
+export type DateLike = FirestoreValue | {
+    toDate: () => Date;
+};
+/**
+ * Firestore Timestamp | Date | ISO string | epoch millis → Date, or null when
+ * the value is absent or unparseable. Firestore hands back a `Timestamp` with
+ * a `toDate()` method server-side but a plain ISO string once serialised, and
+ * a predicate that handles only one of those silently returns the wrong answer
+ * on the other runtime.
+ */
+export declare function toDate(value: DateLike): Date | null;
+/** Read a numeric field, or `null` when absent/non-numeric. */
+export declare function num(value: DateLike): number | null;
+/**
+ * The checks every listing type shares, regardless of `listingType`.
+ *
+ * Note what is NOT here: `status`. Publication state (draft / in_review /
+ * archived) is a different axis from availability — an archived listing is
+ * hidden from the public entirely, while a sold one is still browsable in the
+ * "Sold & Ended" scope. Conflating them is what made `isValidRelatedItem`
+ * test for a `status: "sold"` value that has never existed.
+ *
+ * A field that is absent is treated as "not a reason to hide" — most rows
+ * carry `isSold: false` and a real quantity, but older documents predate both
+ * and must not vanish from the default scope.
+ */
+export declare function baseAvailable(row: AvailabilityRow): boolean;
+/**
+ * Whether a row may be shown on a public surface at all. Separate from
+ * availability on purpose — see `baseAvailable`.
+ */
+export declare function isPubliclyVisible(row: AvailabilityRow): boolean;
+/**
+ * The Firestore-expressible half of "this row is UNAVAILABLE".
+ *
+ * Every entry must be an EQUALITY, or an inequality that names its own
+ * `sortField` — because Firestore implicitly appends an inequality's field to
+ * the `orderBy`, so pairing one with an unrelated sort demands a composite
+ * index in an order nobody declares and fails with FAILED_PRECONDITION
+ * (Recurrent Root Cause #59). Equalities carry no such constraint, which is
+ * what makes the "Sold & Ended" fan-out safe on a mixed type selection.
+ */
+export interface UnavailableClause {
+    field: string;
+    op: "eq" | "lt";
+    /** `"NOW"` is substituted with the query's timestamp at build time. */
+    value: string | number | boolean | "NOW";
+    /** Required when `op !== "eq"` — the query MUST order by this field. */
+    sortField?: string;
+}
+/**
+ * For types whose only end-state is running out: standard, classified, live,
+ * art, stickers. Shared rather than copy-pasted into five plugin configs,
+ * which is exactly the duplication the registry exists to prevent.
+ */
+export declare const STOCK_ONLY_UNAVAILABLE_CLAUSES: readonly UnavailableClause[];
+/**
+ * `isAvailable` for a type with no rule beyond `baseAvailable`. Named rather
+ * than an inline `() => true` so the five configs that use it read as
+ * deliberately sharing one decision, not as five independent stubs.
+ */
+export declare function alwaysAvailable(): boolean;