@mohasinac/appkit 4.13.1 → 4.14.0

package/dist/_internal/shared/listing-types/live/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 { TABLE_KEYS } from "../../../../constants/table-keys";
 import { STANDARD_SORT_OPTIONS, STANDARD_PUBLIC_SORT_OPTIONS, } from "../../../../features/products/constants/sieve";
@@ -18,6 +19,10 @@ export const config = {
     chipLabel: "Live Items",
     browseRoute: String(ROUTES.PUBLIC.LIVE),
     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/pre-order/config.d.ts

@@ -1,3 +1,4 @@
+import { type AvailabilityRow } from "../availability";
 export declare const LISTING_TYPE: "pre-order";
 export declare const capability: import("../capabilities").ListingTypeCapability;
 export declare const config: {
@@ -17,6 +18,8 @@ export declare const config: {
     chipLabel: string;
     browseRoute: string;
     hideDefault: "closed";
+    isAvailable: (row: AvailabilityRow) => boolean;
+    unavailableClauses: readonly import("../availability").UnavailableClause[];
     sortOptions: readonly [{
         readonly value: string;
         readonly label: "Earliest Delivery";

package/dist/_internal/shared/listing-types/pre-order/config.js

@@ -1,6 +1,8 @@
 import { LISTING_TYPE_CAPABILITIES } from "../capabilities";
+import { num, STOCK_ONLY_UNAVAILABLE_CLAUSES, } from "../availability";
 import { ROUTES } from "../../../../next/routing/route-map";
 import { TABLE_KEYS } from "../../../../constants/table-keys";
+import { PRODUCT_FIELDS } from "../../../../constants/field-names";
 import { PREORDER_SORT_OPTIONS, PREORDER_PUBLIC_SORT_OPTIONS, } from "../../../../features/products/constants/sieve";
 export const LISTING_TYPE = "pre-order";
 export const capability = LISTING_TYPE_CAPABILITIES["pre-order"];
@@ -18,6 +20,23 @@ export const config = {
     chipLabel: "Pre-Orders",
     browseRoute: String(ROUTES.PUBLIC.PRE_ORDERS),
     hideDefault: "closed",
+    // A pre-order closes when its allocation fills, NOT when its delivery date
+    // passes — a shipped-soon pre-order is still orderable. `preOrderClosed`
+    // exists on the schema but no write path has ever set it, so the count pair
+    // is the only real signal; it is checked defensively anyway in case one
+    // starts.
+    isAvailable: (row) => {
+        if (row[PRODUCT_FIELDS.PRE_ORDER_CLOSED] === true)
+            return false;
+        const current = num(row[PRODUCT_FIELDS.PRE_ORDER_CURRENT_COUNT]);
+        const max = num(row[PRODUCT_FIELDS.PRE_ORDER_MAX_QUANTITY]);
+        if (current !== null && max !== null && max > 0 && current >= max)
+            return false;
+        return true;
+    },
+    // A filled allocation always zeroes `availableQuantity`, so the shared
+    // stock clauses select exactly the closed set — no extra query needed.
+    unavailableClauses: STOCK_ONLY_UNAVAILABLE_CLAUSES,
     sortOptions: PREORDER_SORT_OPTIONS,
     publicSortOptions: PREORDER_PUBLIC_SORT_OPTIONS,
     extraFacetKeys: [

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

@@ -1,3 +1,4 @@
+import type { AvailabilityRow } from "../availability";
 export declare const LISTING_TYPE: "prize-draw";
 export declare const capability: import("../capabilities").ListingTypeCapability;
 export declare const config: {
@@ -17,6 +18,16 @@ export declare const config: {
     chipLabel: string;
     browseRoute: string;
     hideDefault: "closed";
+    isAvailable: (row: AvailabilityRow) => boolean;
+    unavailableClauses: ({
+        field: "prizeRevealStatus";
+        op: "eq";
+        value: "closed";
+    } | {
+        field: "availableQuantity";
+        op: "eq";
+        value: number;
+    })[];
     sortOptions: readonly [{
         readonly value: string;
         readonly label: "Newest First";

package/dist/_internal/shared/listing-types/prize-draw/config.js

@@ -1,6 +1,7 @@
 import { LISTING_TYPE_CAPABILITIES } from "../capabilities";
 import { ROUTES } from "../../../../next/routing/route-map";
 import { TABLE_KEYS } from "../../../../constants/table-keys";
+import { PRODUCT_FIELDS } from "../../../../constants/field-names";
 import { PRIZE_DRAW_SORT_OPTIONS, PRIZE_DRAW_PUBLIC_SORT_OPTIONS, } from "../../../../features/products/constants/sieve";
 export const LISTING_TYPE = "prize-draw";
 export const capability = LISTING_TYPE_CAPABILITIES["prize-draw"];
@@ -18,6 +19,20 @@ export const config = {
     chipLabel: "Prize Draws",
     browseRoute: String(ROUTES.PUBLIC.PRIZE_DRAWS),
     hideDefault: "closed",
+    // `prizeRevealStatus`, NOT remaining entries: a draw can close with slots
+    // unsold (the seller ends it early, or the reveal window lapses), and it can
+    // sell every slot while still open pending the reveal. Only the status field
+    // answers "can someone still enter this".
+    isAvailable: (row) => row[PRODUCT_FIELDS.PRIZE_REVEAL_STATUS] !==
+        PRODUCT_FIELDS.PRIZE_REVEAL_STATUS_VALUES.CLOSED,
+    unavailableClauses: [
+        {
+            field: PRODUCT_FIELDS.PRIZE_REVEAL_STATUS,
+            op: "eq",
+            value: PRODUCT_FIELDS.PRIZE_REVEAL_STATUS_VALUES.CLOSED,
+        },
+        { field: PRODUCT_FIELDS.AVAILABLE_QUANTITY, op: "eq", value: 0 },
+    ],
     sortOptions: PRIZE_DRAW_SORT_OPTIONS,
     publicSortOptions: PRIZE_DRAW_PUBLIC_SORT_OPTIONS,
     extraFacetKeys: [TABLE_KEYS.PRIZE_REVEAL_STATUS],

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

@@ -1,3 +1,4 @@
+import { alwaysAvailable } from "../availability";
 export declare const LISTING_TYPE: "standard";
 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/standard/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 = "standard";
@@ -17,6 +18,10 @@ export const config = {
     chipLabel: "Standard",
     browseRoute: String(ROUTES.PUBLIC.PRODUCTS),
     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/stickers/config.d.ts

@@ -1,3 +1,4 @@
+import { alwaysAvailable } from "../availability";
 export declare const LISTING_TYPE: "stickers";
 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/stickers/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 = "stickers";
@@ -20,6 +21,10 @@ export const config = {
     // a `/stickers` route that does not exist.
     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/client.d.ts

@@ -139,7 +139,7 @@ export { OtpInput } from "./ui/components/OtpInput";
 export type { OtpInputProps } from "./ui/components/OtpInput";
 export { DateInput, DateRangeInput } from "./ui/components/DateInput";
 export type { DateInputProps, DateRangeInputProps } from "./ui/components/DateInput";
-export type { FormShellProviderProps, FormShellStep, FormShellContextValue, UseFormShellStateResult } from "./ui/forms";
+export type { FormShellProviderProps, FormShellStep, FormShellNav, FormShellContextValue, UseFormShellStateResult } from "./ui/forms";
 export { FormShellProvider, FormShellContext, useFormShell, useFormShellState, applyZodIssues } from "./ui/forms";
 export type { FieldInputProps } from "./ui/forms";
 export { FieldInput } from "./ui/forms";
@@ -288,8 +288,6 @@ export { ProductFeaturesProvider, useProductFeatures, } from "./features/product
 export type { ProductFeaturesProviderProps } from "./features/products/components/ProductFeaturesContext";
 export { FeatureBadge, FeatureBadgeList } from "./features/products/components/FeatureBadge";
 export type { FeatureBadgeProps, FeatureBadgeListProps, } from "./features/products/components/FeatureBadge";
-export { SellerOffersPanel } from "./features/seller/components/SellerOffersPanel";
-export type { SellerOffersPanelProps, SellerOfferAction } from "./features/seller/components/SellerOffersPanel";
 export { UserOffersPanel } from "./features/account/components/UserOffersPanel";
 export type { UserOffersPanelProps } from "./features/account/components/UserOffersPanel";
 export { SellerDashboardView as StoreDashboardView, SellerDashboardView, useSellerDashboard as useStoreDashboard, useSellerDashboard } from "./features/seller/index";
@@ -308,6 +306,8 @@ export { OrderAddonBadges } from "./features/orders/components/OrderAddonBadges"
 export type { OrderAddonBadgesOrder, OrderAddonBadgesProps } from "./features/orders/components/OrderAddonBadges";
 export { MANUAL_PAYMENT_METHODS, isManualPaymentMethod, PAYMENT_REVIEW_QUEUE_MODES, isPaymentReviewQueueMode, PAYMENT_WINDOW_MINUTES, } from "./features/orders/constants/payment-window";
 export type { PaymentReviewQueueMode } from "./features/orders/constants/payment-window";
+export { ORDER_SCOPE_VALUES, ORDER_SCOPE_TABS, isOrderScope, statusesForScope, mergeOrderScopeFilter, } from "./features/orders/constants/order-scope";
+export type { OrderScope } from "./features/orders/constants/order-scope";
 export { UserOrderTrackView } from "./features/account/components/UserOrderTrackView";
 export type { UserOrderTrackViewProps, UserOrderTrackViewLabels } from "./features/account/components/UserOrderTrackView";
 export { useCouponValidate } from "./features/promotions/hooks/useCouponValidate";
@@ -408,8 +408,10 @@ export { useProduct } from "./features/products/index";
 export type { ProductDocument } from "./features/products/index";
 export { BUNDLE_COPY } from "./_internal/shared/features/categories/bundle-copy";
 export { useSiteSettings } from "./core/index";
-export { checkEmiEligibility, computeEmiSchedule, } from "./_internal/shared/features/emi/schedule";
-export type { EmiSettings } from "./_internal/shared/features/emi/schedule";
+export { checkEmiEligibility, computeEmiSchedule, computeBuyerEmiQuote, } from "./_internal/shared/features/emi/schedule";
+export type { EmiSettings, BuyerEmiQuote } from "./_internal/shared/features/emi/schedule";
+export type { BuyerFacingFees, BuyerEmiSettings, } from "./_internal/shared/features/site-settings/fees";
+export type { PublicSiteSettings } from "./_internal/shared/features/site-settings/types";
 export { computeCodHandlingFee } from "./_internal/shared/fees/calculator";
 export type { CodHandlingFeeRates, WhatsAppNotifyFeeRates, GiftWrapFeeRates, ShipmentProtectionFeeRates, } from "./_internal/shared/fees/calculator";
 export { FAQPageContent } from "./features/faq/index";

package/dist/client.js

@@ -295,7 +295,6 @@ export { ProductDetailActions } from "./features/products/components/ProductDeta
 // productFeatures (FI6) — client-safe components + context
 export { ProductFeaturesProvider, useProductFeatures, } from "./features/products/components/ProductFeaturesContext";
 export { FeatureBadge, FeatureBadgeList } from "./features/products/components/FeatureBadge";
-export { SellerOffersPanel } from "./features/seller/components/SellerOffersPanel";
 export { UserOffersPanel } from "./features/account/components/UserOffersPanel";
 export { SellerDashboardView as StoreDashboardView, SellerDashboardView, useSellerDashboard as useStoreDashboard, useSellerDashboard } from "./features/seller/index";
 export { SellerPayoutSettingsView, SellerShippingView, SellerReviewsView, SellerPayoutRequestView, SellerAnalyticsStats, SellerTopProducts, SellerAnalyticsView, SellerPayoutsView, SellerCouponEditorView, SellerBidsView, SellerAddressesView, SellerPreOrdersView, SellerPrizeDrawsView, PrintCenterView, SellerOffersView, SellerGroupedListingsView, StoreGroupedListingsView, SellerAnalyticsAlertsView, StoreAnalyticsAlertsView, BarcodeField, FulfillmentView } from "./features/seller/components/index";
@@ -307,6 +306,7 @@ export { OrderAddonBadges } from "./features/orders/components/OrderAddonBadges"
 // Manual-payment (cash / UPI / EMI) shared constants — pure data + predicates,
 // no server deps. Used by the buyer proof-upload page and order-detail CTAs.
 export { MANUAL_PAYMENT_METHODS, isManualPaymentMethod, PAYMENT_REVIEW_QUEUE_MODES, isPaymentReviewQueueMode, PAYMENT_WINDOW_MINUTES, } from "./features/orders/constants/payment-window";
+export { ORDER_SCOPE_VALUES, ORDER_SCOPE_TABS, isOrderScope, statusesForScope, mergeOrderScopeFilter, } from "./features/orders/constants/order-scope";
 export { UserOrderTrackView } from "./features/account/components/UserOrderTrackView";
 export { useCouponValidate } from "./features/promotions/hooks/useCouponValidate";
 export { BlogPostView } from "./features/blog/components/BlogPostView";
@@ -388,7 +388,7 @@ export { PrizeRevealModal } from "./features/products/components/PrizeRevealModa
 export { useProduct } from "./features/products/index";
 export { BUNDLE_COPY } from "./_internal/shared/features/categories/bundle-copy";
 export { useSiteSettings } from "./core/index";
-export { checkEmiEligibility, computeEmiSchedule, } from "./_internal/shared/features/emi/schedule";
+export { checkEmiEligibility, computeEmiSchedule, computeBuyerEmiQuote, } from "./_internal/shared/features/emi/schedule";
 export { computeCodHandlingFee } from "./_internal/shared/fees/calculator"; // reexport-from-internal-ok: pure fee-calc utility consumed directly by public checkout UI (CheckoutRouteClient.tsx), same category as the sibling computeEmiSchedule/checkEmiEligibility re-export two lines above
 export { FAQPageContent } from "./features/faq/index";
 export { CategoryInlineSelect } from "./features/seller/components/CategoryInlineSelect";

package/dist/constants/api-endpoints.d.ts

@@ -106,6 +106,8 @@ export declare const ADMIN_ENDPOINTS: {
     readonly REVIEW_BY_ID: (id: string) => string;
     readonly BIDS: "/api/admin/bids";
     readonly BID_BY_ID: (id: string) => string;
+    readonly OFFERS: "/api/admin/offers";
+    readonly OFFER_BY_ID: (id: string) => string;
     readonly BLOG: "/api/admin/blog";
     readonly BLOG_BY_ID: (id: string) => string;
     readonly BUNDLES: "/api/admin/bundles";
@@ -560,6 +562,8 @@ export declare const API_ENDPOINTS: {
         readonly REVIEW_BY_ID: (id: string) => string;
         readonly BIDS: "/api/admin/bids";
         readonly BID_BY_ID: (id: string) => string;
+        readonly OFFERS: "/api/admin/offers";
+        readonly OFFER_BY_ID: (id: string) => string;
         readonly BLOG: "/api/admin/blog";
         readonly BLOG_BY_ID: (id: string) => string;
         readonly BUNDLES: "/api/admin/bundles";
@@ -1016,6 +1020,8 @@ export declare const API_ROUTES: {
         readonly REVIEW_BY_ID: (id: string) => string;
         readonly BIDS: "/api/admin/bids";
         readonly BID_BY_ID: (id: string) => string;
+        readonly OFFERS: "/api/admin/offers";
+        readonly OFFER_BY_ID: (id: string) => string;
         readonly BLOG: "/api/admin/blog";
         readonly BLOG_BY_ID: (id: string) => string;
         readonly BUNDLES: "/api/admin/bundles";

package/dist/constants/api-endpoints.js

@@ -133,6 +133,8 @@ export const ADMIN_ENDPOINTS = {
     REVIEW_BY_ID: (id) => `/api/admin/reviews/${id}`,
     BIDS: "/api/admin/bids",
     BID_BY_ID: (id) => `/api/admin/bids/${id}`,
+    OFFERS: "/api/admin/offers",
+    OFFER_BY_ID: (id) => `/api/admin/offers/${id}`,
     BLOG: "/api/admin/blog",
     BLOG_BY_ID: (id) => `/api/admin/blog/${id}`,
     BUNDLES: "/api/admin/bundles",

package/dist/constants/field-names.d.ts

@@ -7,6 +7,30 @@
  *
  * Consumer app re-exports from "@mohasinac/appkit" — never edit src/constants/field-names.ts directly.
  */
+/**
+ * The three-state scope every listing surface (public browse, store tabs,
+ * category/brand panels, admin/seller dashboards) offers as a tab bar.
+ *
+ * DELIBERATELY NOT a Firestore field. "Unavailable" means different things to
+ * different listing types — an auction ENDS, a product SELLS OUT, a prize draw
+ * CLOSES, a code pool DEPLETES — so there is no single column to filter on.
+ * The per-type meaning lives on each listing-type plugin
+ * (`isAvailable` / `unavailableClauses` in `_internal/shared/listing-types/`),
+ * and `availabilityTabsFor()` derives the middle tab's label from the plugin's
+ * `hideDefault`. Do not add a mirror field to ProductDocument to "simplify"
+ * this — a denormalised mirror drifts the first time a write path forgets it
+ * (Recurrent Root Cause #42).
+ */
+export declare const AVAILABILITY_VALUES: {
+    /** Still buyable / biddable / enterable. The default when the param is absent. */
+    readonly AVAILABLE: "available";
+    /** Sold out, ended, closed, or depleted — the archive. */
+    readonly UNAVAILABLE: "unavailable";
+    /** No availability predicate at all. The only scope with an exact total. */
+    readonly ALL: "all";
+};
+export type AvailabilityFilter = (typeof AVAILABILITY_VALUES)[keyof typeof AVAILABILITY_VALUES];
+export declare function isAvailabilityFilter(value: string): value is AvailabilityFilter;
 export declare const PRODUCT_FIELDS: {
     readonly ID: "id";
     readonly TITLE: "title";
@@ -81,6 +105,16 @@ export declare const PRODUCT_FIELDS: {
     readonly IS_TEST_DATA: "isTestData";
     readonly BIDS_HAVE_STARTED: "bidsHaveStarted";
     readonly PRE_ORDER_CLOSED: "preOrderClosed";
+    /**
+     * Digital-code pool counters. NESTED under `digitalCode.*` on the document —
+     * reading `row.codesAvailable` at the top level silently returns `undefined`
+     * for every row, which is exactly the bug the old `isValidRelatedItem`
+     * carried. Both paths are allowlisted in the products repository's
+     * SIEVE_FIELDS.
+     */
+    readonly DIGITAL_CODES_AVAILABLE: "digitalCode.codesAvailable";
+    readonly DIGITAL_CODE_POOL_SIZE: "digitalCode.codePoolSize";
+    readonly DIGITAL_CODE_DELIVERY_METHOD: "digitalCode.codeDeliveryMethod";
     /**
      * The Firestore field. NOTE the `Id` suffix: the URL/table key is
      * `sublistingCategory` (TABLE_KEYS.SUBLISTING_CATEGORY) but the stored field
@@ -333,14 +367,25 @@ export declare const EVENT_FIELDS: {
     readonly ALLOW_GUEST_PARTICIPATION: "allowGuestParticipation";
     readonly CREATED_AT: "createdAt";
     readonly UPDATED_AT: "updatedAt";
+    /**
+     * Mirrors the `EventStatus` union in `features/events/types/index.ts`, which
+     * is the source of truth. A `PUBLISHED: "published"` entry lived here until
+     * 2026-08-24 — `EventStatus` never had that value, so any filter built from
+     * it matched zero rows forever. It had no consumers and was removed; verified
+     * by grep before deleting (Root Cause #34).
+     */
     readonly STATUS_VALUES: {
         readonly DRAFT: "draft";
-        readonly PUBLISHED: "published";
         readonly ACTIVE: "active";
+        readonly PAUSED: "paused";
         readonly ENDED: "ended";
         readonly CANCELLED: "cancelled";
-        readonly PAUSED: "paused";
     };
+    /**
+     * Mirrors the `EventType` union. `LOTTERY` was missing until 2026-08-24,
+     * which is why `events-seed-data.ts` had to write `type: "lottery"` as a raw
+     * string literal while every other row used this map.
+     */
     readonly TYPE_VALUES: {
         readonly SALE: "sale";
         readonly OFFER: "offer";
@@ -349,6 +394,7 @@ export declare const EVENT_FIELDS: {
         readonly FEEDBACK: "feedback";
         readonly RAFFLE: "raffle";
         readonly SPIN_WHEEL: "spin_wheel";
+        readonly LOTTERY: "lottery";
     };
     readonly RAFFLE_TYPE_VALUES: {
         readonly OPEN_RAFFLE: "open_raffle";
@@ -857,6 +903,7 @@ export declare const SITE_SETTINGS_FIELDS: {
         readonly NOTIFICATIONS: "featureFlags.notifications";
         readonly SELLER_REGISTRATION: "featureFlags.sellerRegistration";
         readonly PRE_ORDERS: "featureFlags.preOrders";
+        readonly OFFERS: "featureFlags.offers";
     };
     readonly LEGAL_PAGES: "legalPages";
     readonly SHIPPING: "shipping";

package/dist/constants/field-names.js

@@ -8,6 +8,34 @@
  * Consumer app re-exports from "@mohasinac/appkit" — never edit src/constants/field-names.ts directly.
  */
 // ============================================================================
+// AVAILABILITY SCOPE (not a stored field — a derived listing-surface scope)
+// ============================================================================
+/**
+ * The three-state scope every listing surface (public browse, store tabs,
+ * category/brand panels, admin/seller dashboards) offers as a tab bar.
+ *
+ * DELIBERATELY NOT a Firestore field. "Unavailable" means different things to
+ * different listing types — an auction ENDS, a product SELLS OUT, a prize draw
+ * CLOSES, a code pool DEPLETES — so there is no single column to filter on.
+ * The per-type meaning lives on each listing-type plugin
+ * (`isAvailable` / `unavailableClauses` in `_internal/shared/listing-types/`),
+ * and `availabilityTabsFor()` derives the middle tab's label from the plugin's
+ * `hideDefault`. Do not add a mirror field to ProductDocument to "simplify"
+ * this — a denormalised mirror drifts the first time a write path forgets it
+ * (Recurrent Root Cause #42).
+ */
+export const AVAILABILITY_VALUES = {
+    /** Still buyable / biddable / enterable. The default when the param is absent. */
+    AVAILABLE: "available",
+    /** Sold out, ended, closed, or depleted — the archive. */
+    UNAVAILABLE: "unavailable",
+    /** No availability predicate at all. The only scope with an exact total. */
+    ALL: "all",
+};
+export function isAvailabilityFilter(value) {
+    return Object.values(AVAILABILITY_VALUES).includes(value);
+}
+// ============================================================================
 // PRODUCT FIELDS
 // ============================================================================
 export const PRODUCT_FIELDS = {
@@ -86,6 +114,16 @@ export const PRODUCT_FIELDS = {
     IS_TEST_DATA: "isTestData",
     BIDS_HAVE_STARTED: "bidsHaveStarted",
     PRE_ORDER_CLOSED: "preOrderClosed",
+    /**
+     * Digital-code pool counters. NESTED under `digitalCode.*` on the document —
+     * reading `row.codesAvailable` at the top level silently returns `undefined`
+     * for every row, which is exactly the bug the old `isValidRelatedItem`
+     * carried. Both paths are allowlisted in the products repository's
+     * SIEVE_FIELDS.
+     */
+    DIGITAL_CODES_AVAILABLE: "digitalCode.codesAvailable",
+    DIGITAL_CODE_POOL_SIZE: "digitalCode.codePoolSize",
+    DIGITAL_CODE_DELIVERY_METHOD: "digitalCode.codeDeliveryMethod",
     /**
      * The Firestore field. NOTE the `Id` suffix: the URL/table key is
      * `sublistingCategory` (TABLE_KEYS.SUBLISTING_CATEGORY) but the stored field
@@ -361,14 +399,25 @@ export const EVENT_FIELDS = {
     ALLOW_GUEST_PARTICIPATION: "allowGuestParticipation",
     CREATED_AT: "createdAt",
     UPDATED_AT: "updatedAt",
+    /**
+     * Mirrors the `EventStatus` union in `features/events/types/index.ts`, which
+     * is the source of truth. A `PUBLISHED: "published"` entry lived here until
+     * 2026-08-24 — `EventStatus` never had that value, so any filter built from
+     * it matched zero rows forever. It had no consumers and was removed; verified
+     * by grep before deleting (Root Cause #34).
+     */
     STATUS_VALUES: {
         DRAFT: "draft",
-        PUBLISHED: "published",
         ACTIVE: "active",
+        PAUSED: "paused",
         ENDED: "ended",
         CANCELLED: "cancelled",
-        PAUSED: "paused",
     },
+    /**
+     * Mirrors the `EventType` union. `LOTTERY` was missing until 2026-08-24,
+     * which is why `events-seed-data.ts` had to write `type: "lottery"` as a raw
+     * string literal while every other row used this map.
+     */
     TYPE_VALUES: {
         SALE: "sale",
         OFFER: "offer",
@@ -377,6 +426,7 @@ export const EVENT_FIELDS = {
         FEEDBACK: "feedback",
         RAFFLE: "raffle",
         SPIN_WHEEL: "spin_wheel",
+        LOTTERY: "lottery",
     },
     RAFFLE_TYPE_VALUES: {
         OPEN_RAFFLE: "open_raffle",
@@ -956,6 +1006,7 @@ export const SITE_SETTINGS_FIELDS = {
         NOTIFICATIONS: "featureFlags.notifications",
         SELLER_REGISTRATION: "featureFlags.sellerRegistration",
         PRE_ORDERS: "featureFlags.preOrders",
+        OFFERS: "featureFlags.offers",
     },
     LEGAL_PAGES: "legalPages",
     SHIPPING: "shipping",

package/dist/constants/table-keys.d.ts

@@ -5,6 +5,8 @@ export declare const TABLE_KEYS: {
     readonly PAGE: "page";
     readonly PAGE_SIZE: "pageSize";
     readonly TAB: "tab";
+    /** Open section(s) of a `<SectionForm>`. Non-resetting — see NON_RESETTING_KEYS. */
+    readonly SECTION: "section";
     readonly QUERY: "q";
     readonly STATUS: "status";
     readonly CATEGORY: "category";
@@ -17,6 +19,21 @@ export declare const TABLE_KEYS: {
     readonly TAGS: "tags";
     readonly DATE_FROM: "dateFrom";
     readonly DATE_TO: "dateTo";
+    /**
+     * Three-state availability tab on every listing surface, public and
+     * dashboard: "available" (default) | "unavailable" | "all". Replaces the
+     * SHOW_SOLD/SHOW_ENDED/SHOW_CLOSED toggle trio below, which widened the
+     * list instead of scoping it and had three spellings of one intent.
+     */
+    readonly AVAILABILITY: "availability";
+    /** Order lifecycle scope tab: "active" | "closed" | "all". */
+    readonly ORDER_SCOPE: "orderScope";
+    /**
+     * Superseded by AVAILABILITY. Retained ONLY so `readAvailability()` can map
+     * bookmarked `?showSold=true` URLs onto `availability=all`, and because the
+     * seller auction/prize-draw dashboards still read them during migration.
+     * Never write these from new code.
+     */
     readonly SHOW_SOLD: "showSold";
     readonly SHOW_ENDED: "showEnded";
     readonly SHOW_CLOSED: "showClosed";

package/dist/constants/table-keys.js

@@ -5,6 +5,8 @@ export const TABLE_KEYS = {
     PAGE: "page",
     PAGE_SIZE: "pageSize",
     TAB: "tab",
+    /** Open section(s) of a `<SectionForm>`. Non-resetting — see NON_RESETTING_KEYS. */
+    SECTION: "section",
     QUERY: "q",
     STATUS: "status",
     CATEGORY: "category",
@@ -17,6 +19,21 @@ export const TABLE_KEYS = {
     TAGS: "tags",
     DATE_FROM: "dateFrom",
     DATE_TO: "dateTo",
+    /**
+     * Three-state availability tab on every listing surface, public and
+     * dashboard: "available" (default) | "unavailable" | "all". Replaces the
+     * SHOW_SOLD/SHOW_ENDED/SHOW_CLOSED toggle trio below, which widened the
+     * list instead of scoping it and had three spellings of one intent.
+     */
+    AVAILABILITY: "availability",
+    /** Order lifecycle scope tab: "active" | "closed" | "all". */
+    ORDER_SCOPE: "orderScope",
+    /**
+     * Superseded by AVAILABILITY. Retained ONLY so `readAvailability()` can map
+     * bookmarked `?showSold=true` URLs onto `availability=all`, and because the
+     * seller auction/prize-draw dashboards still read them during migration.
+     * Never write these from new code.
+     */
     SHOW_SOLD: "showSold",
     SHOW_ENDED: "showEnded",
     SHOW_CLOSED: "showClosed",

package/dist/errors/error-codes.d.ts

@@ -6,9 +6,21 @@ export declare const BID_ERROR_CODES: {
     readonly INCREMENT_VIOLATED: "BID_INCREMENT_TOO_LOW";
     readonly SELF_BID: "BID_SELF_BID";
     readonly USER_BANNED: "BID_USER_BANNED";
+    /**
+     * The buyout price is no longer better than the standing bid. Replaced
+     * `BUY_NOW_BIDS_STARTED` (deleted 2026-08-24), which fired the instant anyone
+     * bid at all — that eBay rule hid Buy Now on nearly every live auction.
+     */
     readonly BUY_NOW_UNAVAILABLE: "BID_BUY_NOW_UNAVAILABLE";
-    readonly BUY_NOW_BIDS_STARTED: "BID_BUY_NOW_BIDS_STARTED";
     readonly BUY_NOW_NO_PRICE: "BID_BUY_NOW_NO_PRICE";
+    /** The buyout hold expired (or was cancelled) before checkout completed. */
+    readonly BUYOUT_LAPSED: "BID_BUYOUT_LAPSED";
+    /** Bidding passed the buyout price while the buyer was in checkout. */
+    readonly BUYOUT_OUTBID: "BID_BUYOUT_OUTBID";
+    /** Another buyer's buyout claimed the auction first. */
+    readonly AUCTION_ALREADY_SOLD: "BID_AUCTION_ALREADY_SOLD";
+    /** The auction's clock ran out mid-checkout, so it settled to a real bidder. */
+    readonly AUCTION_ENDED_BEFORE_CHECKOUT: "BID_AUCTION_ENDED_BEFORE_CHECKOUT";
 };
 export declare const OFFER_ERROR_CODES: {
     readonly DISABLED: "OFFER_DISABLED";

package/dist/errors/error-codes.js

@@ -6,9 +6,21 @@ export const BID_ERROR_CODES = {
     INCREMENT_VIOLATED: "BID_INCREMENT_TOO_LOW",
     SELF_BID: "BID_SELF_BID",
     USER_BANNED: "BID_USER_BANNED",
+    /**
+     * The buyout price is no longer better than the standing bid. Replaced
+     * `BUY_NOW_BIDS_STARTED` (deleted 2026-08-24), which fired the instant anyone
+     * bid at all — that eBay rule hid Buy Now on nearly every live auction.
+     */
     BUY_NOW_UNAVAILABLE: "BID_BUY_NOW_UNAVAILABLE",
-    BUY_NOW_BIDS_STARTED: "BID_BUY_NOW_BIDS_STARTED",
     BUY_NOW_NO_PRICE: "BID_BUY_NOW_NO_PRICE",
+    /** The buyout hold expired (or was cancelled) before checkout completed. */
+    BUYOUT_LAPSED: "BID_BUYOUT_LAPSED",
+    /** Bidding passed the buyout price while the buyer was in checkout. */
+    BUYOUT_OUTBID: "BID_BUYOUT_OUTBID",
+    /** Another buyer's buyout claimed the auction first. */
+    AUCTION_ALREADY_SOLD: "BID_AUCTION_ALREADY_SOLD",
+    /** The auction's clock ran out mid-checkout, so it settled to a real bidder. */
+    AUCTION_ENDED_BEFORE_CHECKOUT: "BID_AUCTION_ENDED_BEFORE_CHECKOUT",
 };
 export const OFFER_ERROR_CODES = {
     DISABLED: "OFFER_DISABLED",

package/dist/errors/error-display-map.js

@@ -137,12 +137,21 @@ export const ERROR_DISPLAY_MAP = {
     [BID_ERROR_CODES.BUY_NOW_UNAVAILABLE]: {
         messageKey: k(BID_ERROR_CODES.BUY_NOW_UNAVAILABLE),
     },
-    [BID_ERROR_CODES.BUY_NOW_BIDS_STARTED]: {
-        messageKey: k(BID_ERROR_CODES.BUY_NOW_BIDS_STARTED),
-    },
     [BID_ERROR_CODES.BUY_NOW_NO_PRICE]: {
         messageKey: k(BID_ERROR_CODES.BUY_NOW_NO_PRICE),
     },
+    [BID_ERROR_CODES.BUYOUT_LAPSED]: {
+        messageKey: k(BID_ERROR_CODES.BUYOUT_LAPSED),
+    },
+    [BID_ERROR_CODES.BUYOUT_OUTBID]: {
+        messageKey: k(BID_ERROR_CODES.BUYOUT_OUTBID),
+    },
+    [BID_ERROR_CODES.AUCTION_ALREADY_SOLD]: {
+        messageKey: k(BID_ERROR_CODES.AUCTION_ALREADY_SOLD),
+    },
+    [BID_ERROR_CODES.AUCTION_ENDED_BEFORE_CHECKOUT]: {
+        messageKey: k(BID_ERROR_CODES.AUCTION_ENDED_BEFORE_CHECKOUT),
+    },
     // ---------- Offers ----------
     [OFFER_ERROR_CODES.DISABLED]: { messageKey: k(OFFER_ERROR_CODES.DISABLED) },
     [OFFER_ERROR_CODES.PRICE_TOO_LOW]: {

package/dist/errors/messages.d.ts

@@ -347,9 +347,12 @@ export declare const ERROR_MESSAGES: {
         readonly BID_TOO_LOW: "Your bid must be higher than the current bid";
         readonly INCREMENT_TOO_LOW: "Your bid does not meet the minimum increment requirement";
         readonly OWN_AUCTION: "You cannot bid on your own auction";
-        readonly BUY_NOW_UNAVAILABLE: "Buy Now is not available for this auction";
-        readonly BUY_NOW_BIDS_STARTED: "Buy Now is no longer available — bids have already been placed";
+        readonly BUY_NOW_UNAVAILABLE: "Buy Now is unavailable — bidding has already passed the Buy Now price";
         readonly BUY_NOW_NO_PRICE: "This auction does not have a Buy Now price";
+        readonly BUYOUT_LAPSED: "Your Buy Now claim expired. Head back to the auction to bid or try again.";
+        readonly BUYOUT_OUTBID: "Bidding passed the Buy Now price while you were checking out, so this purchase can no longer go through.";
+        readonly AUCTION_ALREADY_SOLD: "Another buyer completed their purchase first, so this auction is already sold.";
+        readonly AUCTION_ENDED_BEFORE_CHECKOUT: "The auction ended before you completed payment, so it went to the winning bidder.";
     };
     readonly CONTACT: {
         readonly SEND_FAILED: "Failed to send your message. Please try again.";
@@ -424,6 +427,11 @@ export declare const ERROR_MESSAGES: {
         readonly INVALID_STATUS_TRANSITION: "This status transition is not allowed";
     };
     readonly OFFER: {
+        /**
+         * The site-wide `featureFlags.offers` kill switch is off. Existing offers
+         * can still be responded to and paid for — only new ones are refused.
+         */
+        readonly DISABLED: "Offers are currently turned off across the site.";
         readonly LIMIT_REACHED: "You have reached the maximum of 3 offers for this product. Wait for the seller to update the listing.";
         readonly COUNTER_RANGE: "Your counter must be within 20% of the seller's counter price.";
         readonly NOT_COUNTERED: "There is no seller counter to respond to.";