@mohasinac/appkit 4.13.1 → 4.15.0

package/dist/client.js

@@ -178,6 +178,24 @@ export { useUrlTable } from "./react/hooks/useUrlTable";
 export { useBulkSelection } from "./react/hooks/useBulkSelection";
 export { useEntityDelete } from "./react/hooks/useEntityDelete";
 // Client-safe constants, UI primitives, and views
+// Storefront-category form schema — isomorphic (the page parses it client-side,
+// the route parses the same one server-side).
+export { storeCategoryFormSchema, storeCategoryCreateSchema, } from "./features/store-extensions/schemas/store-category-form";
+// Payout-method + listing-template form schemas — isomorphic: the pages parse
+// them client-side and the routes parse the SAME ones server-side.
+export { payoutMethodFormSchema, payoutMethodCreateSchema, payoutMethodUpdateSchema, } from "./features/store-extensions/schemas/payout-method-form";
+export { groupedListingFormSchema, groupedListingCreateSchema, groupedListingUpdateSchema, } from "./features/grouped/schemas/grouped-listing-form";
+export { navItemFormSchema, navItemCreateSchema, navItemUpdateSchema, } from "./features/admin/schemas/nav-item-form";
+export { customRoleFormSchema, customRoleCreateSchema, customRoleUpdateSchema, isKnownPermission, } from "./features/store-extensions/schemas/custom-role-form";
+// Client-only: deliberately NOT added to `features/store-extensions/index.ts`,
+// which the schema registry's import chain reaches — a "use client" React tree
+// re-exported from there would be pulled into every API route (the W4 trap).
+export { SCAMMER_STATUS_LABEL, SCAMMER_STATUS_BADGE, SCAMMER_STATUS_OPTIONS, toScammerStatus, } from "./features/scams/constants/scammer-status-display";
+export { ReviewDecisionModal, } from "./features/store-extensions/components/ReviewDecisionModal";
+export { moderationReviewFormSchema, moderationReviewUpdateSchema, MODERATION_REVIEWER_STATUSES, } from "./features/store-extensions/schemas/moderation-review-form";
+export { reportReviewFormSchema, reportReviewUpdateSchema, REPORT_REVIEWER_STATUSES, REPORT_TERMINAL_STATUSES, } from "./features/store-extensions/schemas/report-review-form";
+export { shippingConfigFormSchema, shippingConfigCreateSchema, shippingConfigUpdateSchema, } from "./features/store-extensions/schemas/shipping-config-form";
+export { listingTemplateFormSchema, listingTemplateCreateSchema, listingTemplateUpdateSchema, } from "./features/store-extensions/schemas/listing-template-form";
 export { ROUTES, PUBLIC_ROUTES, PROTECTED_ROUTES, AUTH_ROUTES } from "./constants/index";
 export { SORT_DIR, sortBy } from "./constants/sort";
 export { SIEVE_OP, sieveFilter, sieveAnd, sieveMultiEq } from "./utils/sieve-builder";
@@ -295,7 +313,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 +324,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";
@@ -368,7 +386,7 @@ export { SellerLiveView } from "./features/seller/components/SellerLiveView";
 // ── Central schema registry (W1) ──────────────────────────────────────────────
 // Pure Zod, isomorphic — re-exported here so client code can resolve schemas
 // without pulling in the full server barrel.
-export { SCHEMAS, lookupApiSchema, lookupFirestoreSchema, } from "./schemas/index";
+export { SCHEMAS, lookupApiSchema, lookupFormSchema, lookupFirestoreSchema, } from "./schemas/index";
 // ── W3 catch-clause normalizer ──────────────────────────────────────────────
 export { normalizeError, getErrorMessage, isApiNormalized, isAppNormalized, isFirebaseAuthNormalized, isFirebaseFirestoreNormalized, isFirebaseStorageNormalized, isNativeNormalized, isNetworkNormalized, isUnknownNormalized, isZodNormalized, } from "./errors/normalize";
 // [CLIENT-SAFE] Pure wa.me share-link message builder — imported directly
@@ -376,7 +394,7 @@ export { normalizeError, getErrorMessage, isApiNormalized, isAppNormalized, isFi
 // never touches the sibling crypto-importing helpers.
 export { buildPaymentProofReviewMessage } from "./features/whatsapp-bot/helpers/payment-proof-message";
 export { CommandPalette, useCommandPaletteHotkey } from "./features/shell/index";
-export { AdminBlogEditorView, AdminBundleEditorView, AdminCarouselEditorView, AdminCategoryEditorView, AdminCouponEditorView, AdminFaqEditorView, AdminOrderEditorView, AdminPayoutMarkPaidModal, AdminAuditLogView, ViewAuditLogEntryModal, AdminProductEditorView, AdminScammerEditorView, AdminStoreEditorView, AdminSublistingCategoryEditorView, AdminSupportTicketDetailView, } from "./features/admin/index";
+export { AdminBlogEditorView, AdminBundleEditorView, AdminCarouselEditorView, AdminCategoryEditorView, AdminCouponEditorView, AdminFaqEditorView, AdminFeatureEditorView, AdminOrderEditorView, AdminPayoutMarkPaidModal, AdminAuditLogView, ViewAuditLogEntryModal, AdminProductEditorView, AdminScammerEditorView, AdminStoreEditorView, AdminSublistingCategoryEditorView, AdminSupportTicketDetailView, } from "./features/admin/index";
 export { ADMIN_CHECKOUT_BYPASS_FLAG_KEY } from "./features/admin/schemas/firestore";
 export { SpinWheelView, EventRaffleEntryForm } from "./features/events/index";
 export { Card, CardBody } from "./ui/index";
@@ -388,7 +406,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
@@ -117,10 +151,9 @@ export declare const PRODUCT_FIELDS: {
         readonly WINNER: "winner";
     };
     readonly PRE_ORDER_PRODUCTION_STATUS_VALUES: {
+        readonly UPCOMING: "upcoming";
         readonly IN_PRODUCTION: "in_production";
-        readonly READY: "ready";
-        readonly DELAYED: "delayed";
-        readonly CANCELLED: "cancelled";
+        readonly READY_TO_SHIP: "ready_to_ship";
     };
     readonly PRIZE_REVEAL_STATUS_VALUES: {
         readonly PENDING: "pending";
@@ -212,9 +245,11 @@ export declare const ORDER_FIELDS: {
     };
     readonly PAYMENT_STATUS_VALUES: {
         readonly PENDING: "pending";
+        readonly PROCESSING: "processing";
         readonly PAID: "paid";
         readonly FAILED: "failed";
         readonly REFUNDED: "refunded";
+        readonly PARTIAL_REFUND: "partial_refund";
     };
     readonly PAYOUT_STATUS_VALUES: {
         readonly ELIGIBLE: "eligible";
@@ -288,6 +323,8 @@ export declare const BID_FIELDS: {
         readonly WON: "won";
         readonly LOST: "lost";
         readonly CANCELLED: "cancelled";
+        /** Won, then the buyer let the payment window lapse. Was missing here. */
+        readonly FORFEITED: "forfeited";
     };
 };
 export declare const AD_FIELDS: {
@@ -333,14 +370,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 +397,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";
@@ -397,7 +446,6 @@ export declare const PAYOUT_FIELDS: {
         readonly PROCESSING: "processing";
         readonly PAID: "paid";
         readonly FAILED: "failed";
-        readonly CANCELLED: "cancelled";
     };
 };
 export declare const STORE_FIELDS: {
@@ -641,9 +689,10 @@ export declare const SCAMMER_FIELDS: {
     readonly VERIFIED_BY: "verifiedBy";
     readonly CREATED_AT: "createdAt";
     readonly STATUS_VALUES: {
-        readonly PENDING: "pending";
+        readonly PENDING_REVIEW: "pending_review";
         readonly VERIFIED: "verified";
         readonly REJECTED: "rejected";
+        readonly REMOVED: "removed";
     };
 };
 export declare const SUPPORT_TICKET_FIELDS: {
@@ -666,7 +715,6 @@ export declare const SUPPORT_TICKET_FIELDS: {
     readonly PRIORITY_VALUES: {
         readonly LOW: "low";
         readonly NORMAL: "normal";
-        readonly MEDIUM: "medium";
         readonly HIGH: "high";
         readonly URGENT: "urgent";
     };
@@ -857,6 +905,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
@@ -121,11 +159,19 @@ export const PRODUCT_FIELDS = {
         SELLER: "seller",
         WINNER: "winner",
     },
+    /*
+     * Corrected 2026-08-24 (W3). This block used to read
+     * {in_production, ready, delayed, cancelled} — and `ready`, `delayed` and
+     * `cancelled` were values no product has ever held. `ProductDocument`
+     * declares "upcoming" | "in_production" | "ready_to_ship", the write schema
+     * agrees, and all 9 seeded pre-orders store one of those three. It had zero
+     * consumers, which is the only reason it never produced a visibly broken
+     * filter chip (Recurrent Root Cause #33).
+     */
     PRE_ORDER_PRODUCTION_STATUS_VALUES: {
+        UPCOMING: "upcoming",
         IN_PRODUCTION: "in_production",
-        READY: "ready",
-        DELAYED: "delayed",
-        CANCELLED: "cancelled",
+        READY_TO_SHIP: "ready_to_ship",
     },
     PRIZE_REVEAL_STATUS_VALUES: {
         PENDING: "pending",
@@ -223,11 +269,19 @@ export const ORDER_FIELDS = {
         RETURN_REQUESTED: "return_requested",
         REFUNDED: "refunded",
     },
+    /*
+     * Corrected 2026-08-24 (W3) — `processing` and `partial_refund` were
+     * missing, so this listed 4 of the real 6. `PaymentStatus`
+     * (features/orders/types/index.ts) is the source; a partial refund is a
+     * state real orders reach, and W2 put it on the order timeline.
+     */
     PAYMENT_STATUS_VALUES: {
         PENDING: "pending",
+        PROCESSING: "processing",
         PAID: "paid",
         FAILED: "failed",
         REFUNDED: "refunded",
+        PARTIAL_REFUND: "partial_refund",
     },
     PAYOUT_STATUS_VALUES: {
         ELIGIBLE: "eligible",
@@ -301,12 +355,22 @@ export const BID_FIELDS = {
     AUTO_MAX_BID: "autoMaxBid",
     CREATED_AT: "createdAt",
     UPDATED_AT: "updatedAt",
+    /*
+     * Corrected 2026-08-24 (W3). Verified against the feature's own union AND
+     * against what is actually stored. This file is a deliberate LEAF — it
+     * imports nothing, and `features/products/types/index.ts` imports IT — so it
+     * cannot re-export the feature unions without a cycle. The values are
+     * therefore duplicated on purpose, and `audit-field-names-union-parity`
+     * blocks them drifting again.
+     */
     STATUS_VALUES: {
         ACTIVE: "active",
         OUTBID: "outbid",
         WON: "won",
         LOST: "lost",
         CANCELLED: "cancelled",
+        /** Won, then the buyer let the payment window lapse. Was missing here. */
+        FORFEITED: "forfeited",
     },
 };
 // ============================================================================
@@ -361,14 +425,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 +452,7 @@ export const EVENT_FIELDS = {
         FEEDBACK: "feedback",
         RAFFLE: "raffle",
         SPIN_WHEEL: "spin_wheel",
+        LOTTERY: "lottery",
     },
     RAFFLE_TYPE_VALUES: {
         OPEN_RAFFLE: "open_raffle",
@@ -426,12 +502,17 @@ export const PAYOUT_FIELDS = {
     STATUS: "status",
     CREATED_AT: "createdAt",
     UPDATED_AT: "updatedAt",
+    /*
+     * Corrected 2026-08-24 (W3) — `cancelled` was listed here and is NOT a
+     * member of `PayoutStatus` (features/payments/schemas/firestore.ts:18,
+     * pending|processing|paid|failed). A chip or badge keyed on it could only
+     * ever match zero rows (Recurrent Root Cause #33).
+     */
     STATUS_VALUES: {
         PENDING: "pending",
         PROCESSING: "processing",
         PAID: "paid",
         FAILED: "failed",
-        CANCELLED: "cancelled",
     },
 };
 // ============================================================================
@@ -721,10 +802,17 @@ export const SCAMMER_FIELDS = {
     REPORTED_BY: "reportedBy",
     VERIFIED_BY: "verifiedBy",
     CREATED_AT: "createdAt",
+    /*
+     * Corrected 2026-08-24 (W3). Two defects: the real stored value is
+     * `pending_review`, not `pending` (the seeded scammer profile stores
+     * `pending_review`), and `removed` was missing entirely. Already flagged in
+     * CLAUDE.md's Root Cause #34 and never actioned.
+     */
     STATUS_VALUES: {
-        PENDING: "pending",
+        PENDING_REVIEW: "pending_review",
         VERIFIED: "verified",
         REJECTED: "rejected",
+        REMOVED: "removed",
     },
 };
 // ============================================================================
@@ -747,10 +835,14 @@ export const SUPPORT_TICKET_FIELDS = {
         RESOLVED: "resolved",
         CLOSED: "closed",
     },
+    /*
+     * Corrected 2026-08-24 (W3) — `medium` is not a member of
+     * `TicketPriorityValues` (low|normal|high|urgent). `normal` is the
+     * middle value.
+     */
     PRIORITY_VALUES: {
         LOW: "low",
         NORMAL: "normal",
-        MEDIUM: "medium",
         HIGH: "high",
         URGENT: "urgent",
     },
@@ -956,6 +1048,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.";