@mohasinac/appkit 4.30.18 → 4.31.0

package/dist/constants/geo/countries.js

@@ -0,0 +1,129 @@
+/*
+ * WHY: A postal code was validated by **fifteen** different rules, and they
+ *      disagreed. Two of them are server-side rules on the SAME entity:
+ *      `src/actions/address.actions.ts` said `.min(4).max(10)` while
+ *      `src/validation/request-schemas.ts` said `/^\d{6}$/`. Another accepted
+ *      5-or-6 digits. And `src/app/api/admin/addresses/route.ts` used
+ *      `.min(6).max(6)` — a LENGTH check with no character class, so
+ *      `"abcdef"` was a valid Indian PIN code as far as it was concerned.
+ *
+ *      Meanwhile the client form said `z.string().min(1)`, so `abc` passed
+ *      every check the user could see and came back as a server 400 with
+ *      nothing on the field.
+ *
+ *      The India-only regex was itself a bug in waiting: `country` is a free
+ *      text field, so a Canadian address was being held to `/^\d{6}$/`.
+ *
+ * WHAT: One postal rule per country, and the country list that carries it.
+ *
+ * ## Why this is curated rather than all 250 ISO countries
+ *
+ * A pattern is only worth having if it is RIGHT. Hand-typing 250 of them from
+ * memory produces a table that looks authoritative and quietly rejects real
+ * addresses — which is worse than not knowing, because the user cannot
+ * override it. So the list covers the countries this marketplace actually
+ * ships to and to which its sellers source, and everything else resolves to
+ * `null`, which means "accept anything plausible".
+ *
+ * 🛑 An unknown country must never BLOCK a save. A postal rule exists to catch
+ * a typo, not to police the atlas.
+ *
+ * EXPORTS:
+ *   COUNTRIES, COUNTRY_CODES, DEFAULT_COUNTRY, type CountryCode,
+ *   type CountryDef, countryFor, postalPatternFor, isValidPostalCode,
+ *   postalLabelFor, POSTAL_MIN, POSTAL_MAX
+ *
+ * @tag domain:geo
+ * @tag layer:constants
+ * @tag pattern:registry
+ * @tag access:isomorphic
+ * @tag consumers:address forms,address routes,usePostalLookup
+ * @tag sideEffects:none
+ */
+/** The permissive bound applied when a country has no pattern. */
+export const POSTAL_MIN = 3;
+export const POSTAL_MAX = 12;
+/**
+ * 🛑 Patterns are anchored and case-insensitive where the country's format
+ * includes letters. An unanchored pattern would accept a code with trailing
+ * junk, which is exactly the class of typo this is meant to catch.
+ */
+const COUNTRY_LIST = [
+    { code: "IN", name: "India", postalPattern: /^[1-9]\d{5}$/, postalLabel: "PIN code", hasStates: true, dialCode: "91" },
+    { code: "US", name: "United States", postalPattern: /^\d{5}(-\d{4})?$/, postalLabel: "ZIP code", hasStates: true, dialCode: "1" },
+    { code: "GB", name: "United Kingdom", postalPattern: /^[A-Z]{1,2}\d[A-Z\d]?\s*\d[A-Z]{2}$/i, postalLabel: "Postcode", hasStates: false, dialCode: "44" },
+    { code: "CA", name: "Canada", postalPattern: /^[A-Z]\d[A-Z]\s*\d[A-Z]\d$/i, postalLabel: "Postal code", hasStates: true, dialCode: "1" },
+    { code: "AU", name: "Australia", postalPattern: /^\d{4}$/, postalLabel: "Postcode", hasStates: true, dialCode: "61" },
+    { code: "NZ", name: "New Zealand", postalPattern: /^\d{4}$/, postalLabel: "Postcode", hasStates: false, dialCode: "64" },
+    { code: "SG", name: "Singapore", postalPattern: /^\d{6}$/, postalLabel: "Postal code", hasStates: false, dialCode: "65" },
+    { code: "MY", name: "Malaysia", postalPattern: /^\d{5}$/, postalLabel: "Postcode", hasStates: false, dialCode: "60" },
+    { code: "JP", name: "Japan", postalPattern: /^\d{3}-?\d{4}$/, postalLabel: "Postal code", hasStates: false, dialCode: "81" },
+    { code: "DE", name: "Germany", postalPattern: /^\d{5}$/, postalLabel: "PLZ", hasStates: false, dialCode: "49" },
+    { code: "FR", name: "France", postalPattern: /^\d{5}$/, postalLabel: "Code postal", hasStates: false, dialCode: "33" },
+    { code: "NL", name: "Netherlands", postalPattern: /^\d{4}\s*[A-Z]{2}$/i, postalLabel: "Postcode", hasStates: false, dialCode: "31" },
+    { code: "IT", name: "Italy", postalPattern: /^\d{5}$/, postalLabel: "CAP", hasStates: false, dialCode: "39" },
+    { code: "ES", name: "Spain", postalPattern: /^\d{5}$/, postalLabel: "Código postal", hasStates: false, dialCode: "34" },
+    { code: "AE", name: "United Arab Emirates", postalPattern: null, postalLabel: "Postal code", hasStates: false, dialCode: "971" },
+    { code: "SA", name: "Saudi Arabia", postalPattern: /^\d{5}$/, postalLabel: "Postal code", hasStates: false, dialCode: "966" },
+    { code: "LK", name: "Sri Lanka", postalPattern: /^\d{5}$/, postalLabel: "Postal code", hasStates: false, dialCode: "94" },
+    { code: "BD", name: "Bangladesh", postalPattern: /^\d{4}$/, postalLabel: "Postal code", hasStates: false, dialCode: "880" },
+    { code: "NP", name: "Nepal", postalPattern: /^\d{5}$/, postalLabel: "Postal code", hasStates: false, dialCode: "977" },
+    { code: "PK", name: "Pakistan", postalPattern: /^\d{5}$/, postalLabel: "Postal code", hasStates: false, dialCode: "92" },
+    { code: "CN", name: "China", postalPattern: /^\d{6}$/, postalLabel: "Postal code", hasStates: false, dialCode: "86" },
+    { code: "HK", name: "Hong Kong", postalPattern: null, postalLabel: "Postal code", hasStates: false, dialCode: "852" },
+    { code: "TH", name: "Thailand", postalPattern: /^\d{5}$/, postalLabel: "Postal code", hasStates: false, dialCode: "66" },
+    { code: "ID", name: "Indonesia", postalPattern: /^\d{5}$/, postalLabel: "Postal code", hasStates: false, dialCode: "62" },
+    { code: "PH", name: "Philippines", postalPattern: /^\d{4}$/, postalLabel: "Postal code", hasStates: false, dialCode: "63" },
+    { code: "ZA", name: "South Africa", postalPattern: /^\d{4}$/, postalLabel: "Postal code", hasStates: false, dialCode: "27" },
+    { code: "BR", name: "Brazil", postalPattern: /^\d{5}-?\d{3}$/, postalLabel: "CEP", hasStates: false, dialCode: "55" },
+    { code: "MX", name: "Mexico", postalPattern: /^\d{5}$/, postalLabel: "Código postal", hasStates: false, dialCode: "52" },
+];
+export const COUNTRIES = Object.fromEntries(COUNTRY_LIST.map((c) => [c.code, c]));
+export const COUNTRY_CODES = COUNTRY_LIST.map((c) => c.code);
+/** Where this marketplace is, and what an address defaults to. */
+export const DEFAULT_COUNTRY = "IN";
+/**
+ * Resolve a country by code or by name.
+ *
+ * By NAME as well, because `AddressDocument.country` is a free-text string
+ * today and holds `"India"` on every seeded and user-entered row. A resolver
+ * that only understood codes would treat every existing address as an unknown
+ * country and silently drop to the permissive rule — the migration would look
+ * like it worked and would have switched validation off.
+ */
+export function countryFor(value) {
+    if (!value)
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    const byCode = COUNTRIES[trimmed.toUpperCase()];
+    if (byCode)
+        return byCode;
+    const lower = trimmed.toLowerCase();
+    return COUNTRY_LIST.find((c) => c.name.toLowerCase() === lower) ?? null;
+}
+/** The postal pattern for a country, or `null` when none is known. */
+export function postalPatternFor(country) {
+    return countryFor(country)?.postalPattern ?? null;
+}
+/** "PIN code" / "ZIP code" / "Postcode" — what to put on the label. */
+export function postalLabelFor(country) {
+    return countryFor(country)?.postalLabel ?? "Postal code";
+}
+/**
+ * The ONE postal check, used by every form and every route.
+ *
+ * An empty code is NOT valid — required-ness is the caller's business, but a
+ * blank string is never a postal code, and letting it through here is how the
+ * `.min(1)` client rule came to disagree with the server in the first place.
+ */
+export function isValidPostalCode(country, postalCode) {
+    const code = (postalCode ?? "").trim();
+    if (!code)
+        return false;
+    const pattern = postalPatternFor(country);
+    if (pattern)
+        return pattern.test(code);
+    return code.length >= POSTAL_MIN && code.length <= POSTAL_MAX;
+}

package/dist/constants/geo/subdivisions.d.ts

@@ -0,0 +1,13 @@
+/** India's 28 states + 8 union territories. */
+declare const INDIA: readonly ["Andhra Pradesh", "Arunachal Pradesh", "Assam", "Bihar", "Chhattisgarh", "Goa", "Gujarat", "Haryana", "Himachal Pradesh", "Jharkhand", "Karnataka", "Kerala", "Madhya Pradesh", "Maharashtra", "Manipur", "Meghalaya", "Mizoram", "Nagaland", "Odisha", "Punjab", "Rajasthan", "Sikkim", "Tamil Nadu", "Telangana", "Tripura", "Uttar Pradesh", "Uttarakhand", "West Bengal", "Andaman and Nicobar Islands", "Chandigarh", "Dadra and Nagar Haveli and Daman and Diu", "Delhi", "Jammu and Kashmir", "Ladakh", "Lakshadweep", "Puducherry"];
+export type IndianState = (typeof INDIA)[number];
+/** Country code → its subdivisions, alphabetical within each. */
+export declare const SUBDIVISIONS: Record<string, readonly string[]>;
+/**
+ * The subdivisions for a country, or an empty list when it has none.
+ *
+ * An empty list is the signal to render a free-text State input rather than a
+ * picker — see `hasStates` on the country definition.
+ */
+export declare function subdivisionsFor(countryCode: string | undefined | null): readonly string[];
+export {};

package/dist/constants/geo/subdivisions.js

@@ -0,0 +1,104 @@
+/*
+ * WHY: `INDIAN_STATES` existed and was used by **one** file — the admin
+ *      address editor — while the user-facing `AddressForm` and
+ *      `SellerAddressesView` both wrote the same `AddressDocument.state`
+ *      through a FREE TEXT input. So the same field held "Karnataka",
+ *      "karnataka", "KA" and "Karnatka" depending on which of the three
+ *      surfaces created the row, and nothing could group or filter on it.
+ * WHAT: Country → subdivisions, for every country whose `hasStates` is true.
+ *
+ * ## Only what is enumerated
+ *
+ * A country appears here when `COUNTRIES[code].hasStates` is true, and the two
+ * must agree — `audit-address-shape` checks that. A country with `hasStates`
+ * and no list would render an empty picker with no way to type a state, which
+ * is strictly worse than the free-text box this replaces.
+ *
+ * EXPORTS: SUBDIVISIONS, subdivisionsFor, type IndianState
+ *
+ * @tag domain:geo
+ * @tag layer:constants
+ * @tag pattern:registry
+ * @tag access:isomorphic
+ * @tag consumers:address forms
+ * @tag sideEffects:none
+ */
+/** India's 28 states + 8 union territories. */
+const INDIA = [
+    "Andhra Pradesh",
+    "Arunachal Pradesh",
+    "Assam",
+    "Bihar",
+    "Chhattisgarh",
+    "Goa",
+    "Gujarat",
+    "Haryana",
+    "Himachal Pradesh",
+    "Jharkhand",
+    "Karnataka",
+    "Kerala",
+    "Madhya Pradesh",
+    "Maharashtra",
+    "Manipur",
+    "Meghalaya",
+    "Mizoram",
+    "Nagaland",
+    "Odisha",
+    "Punjab",
+    "Rajasthan",
+    "Sikkim",
+    "Tamil Nadu",
+    "Telangana",
+    "Tripura",
+    "Uttar Pradesh",
+    "Uttarakhand",
+    "West Bengal",
+    "Andaman and Nicobar Islands",
+    "Chandigarh",
+    "Dadra and Nagar Haveli and Daman and Diu",
+    "Delhi",
+    "Jammu and Kashmir",
+    "Ladakh",
+    "Lakshadweep",
+    "Puducherry",
+];
+const US = [
+    "Alabama", "Alaska", "Arizona", "Arkansas", "California", "Colorado",
+    "Connecticut", "Delaware", "District of Columbia", "Florida", "Georgia",
+    "Hawaii", "Idaho", "Illinois", "Indiana", "Iowa", "Kansas", "Kentucky",
+    "Louisiana", "Maine", "Maryland", "Massachusetts", "Michigan", "Minnesota",
+    "Mississippi", "Missouri", "Montana", "Nebraska", "Nevada", "New Hampshire",
+    "New Jersey", "New Mexico", "New York", "North Carolina", "North Dakota",
+    "Ohio", "Oklahoma", "Oregon", "Pennsylvania", "Rhode Island",
+    "South Carolina", "South Dakota", "Tennessee", "Texas", "Utah", "Vermont",
+    "Virginia", "Washington", "West Virginia", "Wisconsin", "Wyoming",
+];
+const CA = [
+    "Alberta", "British Columbia", "Manitoba", "New Brunswick",
+    "Newfoundland and Labrador", "Northwest Territories", "Nova Scotia",
+    "Nunavut", "Ontario", "Prince Edward Island", "Quebec", "Saskatchewan",
+    "Yukon",
+];
+const AU = [
+    "Australian Capital Territory", "New South Wales", "Northern Territory",
+    "Queensland", "South Australia", "Tasmania", "Victoria",
+    "Western Australia",
+];
+/** Country code → its subdivisions, alphabetical within each. */
+export const SUBDIVISIONS = {
+    IN: INDIA,
+    US,
+    CA,
+    AU,
+};
+/**
+ * The subdivisions for a country, or an empty list when it has none.
+ *
+ * An empty list is the signal to render a free-text State input rather than a
+ * picker — see `hasStates` on the country definition.
+ */
+export function subdivisionsFor(countryCode) {
+    if (!countryCode)
+        return [];
+    return SUBDIVISIONS[countryCode.trim().toUpperCase()] ?? [];
+}

package/dist/constants/index.d.ts

@@ -9,7 +9,7 @@
  *   import { COLLECTION_CACHE_PATHS } from "@mohasinac/appkit/constants";
  *   import { resolveEndpoint } from "@mohasinac/appkit/constants";
  */
-export { API_ENDPOINTS, API_ROUTES, LOGS_ENDPOINTS, AUTH_ENDPOINTS, ACCOUNT_ENDPOINTS, NOTIFICATIONS_ENDPOINTS, SITE_SETTINGS_ENDPOINTS, ADMIN_ENDPOINTS, CHAT_ENDPOINTS, AUCTION_ENDPOINTS, BID_ENDPOINTS, CART_ENDPOINTS, CATEGORY_ENDPOINTS, CHECKOUT_ENDPOINTS, PAYMENT_ENDPOINTS, COLLECTION_ENDPOINTS, CONSULTATION_ENDPOINTS, COPILOT_ENDPOINTS, CORPORATE_ENDPOINTS, EVENT_ENDPOINTS, FAQ_ENDPOINTS, HOMEPAGE_ENDPOINTS, LOYALTY_ENDPOINTS, ANALYTICS_ENDPOINTS, MEDIA_ENDPOINTS, ORDER_ENDPOINTS, PREORDER_ENDPOINTS, PRODUCT_ENDPOINTS, PROMOTION_ENDPOINTS, REVIEW_ENDPOINTS, SEARCH_ENDPOINTS, SELLER_ENDPOINTS, BLOG_ENDPOINTS, STORE_ENDPOINTS, WISHLIST_ENDPOINTS, PROFILE_STATS_ENDPOINTS, } from "./api-endpoints";
+export { API_ENDPOINTS, API_ROUTES, LOGS_ENDPOINTS, AUTH_ENDPOINTS, ACCOUNT_ENDPOINTS, NOTIFICATIONS_ENDPOINTS, SITE_SETTINGS_ENDPOINTS, ADMIN_ENDPOINTS, AUCTION_ENDPOINTS, BID_ENDPOINTS, CART_ENDPOINTS, CATEGORY_ENDPOINTS, CHECKOUT_ENDPOINTS, PAYMENT_ENDPOINTS, COLLECTION_ENDPOINTS, CONSULTATION_ENDPOINTS, COPILOT_ENDPOINTS, CORPORATE_ENDPOINTS, EVENT_ENDPOINTS, FAQ_ENDPOINTS, HOMEPAGE_ENDPOINTS, LOYALTY_ENDPOINTS, ANALYTICS_ENDPOINTS, MEDIA_ENDPOINTS, ORDER_ENDPOINTS, PREORDER_ENDPOINTS, PRODUCT_ENDPOINTS, PROMOTION_ENDPOINTS, REVIEW_ENDPOINTS, SEARCH_ENDPOINTS, SELLER_ENDPOINTS, BLOG_ENDPOINTS, STORE_ENDPOINTS, WISHLIST_ENDPOINTS, PROFILE_STATS_ENDPOINTS, } from "./api-endpoints";
 export { COLLECTION_CACHE_PATHS } from "./cache-invalidation";
 export { PAGE_SIZES, MAX_PAGE_SIZE, FEATURED_LIMITS, SITEMAP_LIMITS, } from "./pagination-presets";
 export type { PageSizeKey } from "./pagination-presets";
@@ -18,6 +18,6 @@ export type { NotificationType } from "./notification-types";
 export { resolveEndpoint, resolveEndpointFn } from "./api-endpoint-resolver";
 export { ROUTES, PUBLIC_ROUTES, PROTECTED_ROUTES, AUTH_ROUTES } from "../next/routing/route-map";
 export { WISHLIST_MAX, HISTORY_MAX, CART_MAX_ITEMS, WISHLIST_DOC_ID, HISTORY_DOC_ID, WISHLIST_COLLECTION, HISTORY_COLLECTION, } from "./limits";
-export { PRODUCT_FIELDS, PRODUCT_STATUS_TRANSITIONS, ORDER_FIELDS, REVIEW_FIELDS, BID_FIELDS, AD_FIELDS, EVENT_FIELDS, EVENT_ENTRY_FIELDS, PAYOUT_FIELDS, STORE_FIELDS, CATEGORY_FIELDS, BLOG_FIELDS, USER_FIELDS, ADDRESS_FIELDS, BRAND_FIELDS, CART_FIELDS, WISHLIST_FIELDS, HISTORY_FIELDS, NOTIFICATION_FIELDS, SESSION_FIELDS, COUPON_USAGE_FIELDS, CONVERSATION_FIELDS, SCAMMER_FIELDS, SUPPORT_TICKET_FIELDS, CAROUSEL_FIELDS, COUPON_FIELDS, FAQ_FIELDS, HOMEPAGE_SECTION_FIELDS, SITE_SETTINGS_FIELDS, COMMON_FIELDS, OAUTH_STATE_VALUES, SCHEMA_DEFAULTS, } from "./field-names";
+export { PRODUCT_FIELDS, PRODUCT_STATUS_TRANSITIONS, ORDER_FIELDS, REVIEW_FIELDS, BID_FIELDS, AD_FIELDS, EVENT_FIELDS, EVENT_ENTRY_FIELDS, PAYOUT_FIELDS, STORE_FIELDS, CATEGORY_FIELDS, BLOG_FIELDS, USER_FIELDS, ADDRESS_FIELDS, BRAND_FIELDS, CART_FIELDS, WISHLIST_FIELDS, HISTORY_FIELDS, NOTIFICATION_FIELDS, SESSION_FIELDS, COUPON_USAGE_FIELDS, SCAMMER_FIELDS, SUPPORT_TICKET_FIELDS, CAROUSEL_FIELDS, COUPON_FIELDS, FAQ_FIELDS, HOMEPAGE_SECTION_FIELDS, SITE_SETTINGS_FIELDS, COMMON_FIELDS, OAUTH_STATE_VALUES, SCHEMA_DEFAULTS, } from "./field-names";
 export { SELLER_LISTING_TABS, type SellerListingTabId, } from "../features/products/constants/listing-tabs";
 export { ALL_TAB, EMPTY_TAB, ADMIN_PRODUCT_STATUS_TABS, ADMIN_PRODUCT_LISTING_TYPE_TABS, ADMIN_BLOG_STATUS_TABS, ADMIN_USER_STATUS_TABS, ADMIN_USER_ROLE_TABS, ADMIN_STORE_STATUS_TABS, ADMIN_PAYOUT_STATUS_TABS, ADMIN_ORDER_STATUS_TABS, ADMIN_REVIEW_STATUS_TABS, ADMIN_REVIEW_RATING_TABS, ADMIN_BID_STATUS_TABS, ADMIN_CONTACT_STATUS_TABS, ADMIN_NEWSLETTER_STATUS_TABS, ADMIN_EVENT_ENTRY_STATUS_TABS, ADMIN_EVENT_STATUS_TABS, ADMIN_CART_OWNERSHIP_TABS, ADMIN_COUPON_TYPE_TABS, SELLER_PRODUCT_STATUS_TABS, SELLER_AUCTION_STATUS_TABS, SELLER_ORDER_STATUS_TABS, SELLER_OFFER_STATUS_TABS, SELLER_BID_STATUS_TABS, } from "../features/admin/constants/filter-tabs";

package/dist/constants/index.js

@@ -9,7 +9,7 @@
  *   import { COLLECTION_CACHE_PATHS } from "@mohasinac/appkit/constants";
  *   import { resolveEndpoint } from "@mohasinac/appkit/constants";
  */
-export { API_ENDPOINTS, API_ROUTES, LOGS_ENDPOINTS, AUTH_ENDPOINTS, ACCOUNT_ENDPOINTS, NOTIFICATIONS_ENDPOINTS, SITE_SETTINGS_ENDPOINTS, ADMIN_ENDPOINTS, CHAT_ENDPOINTS, AUCTION_ENDPOINTS, BID_ENDPOINTS, CART_ENDPOINTS, CATEGORY_ENDPOINTS, CHECKOUT_ENDPOINTS, PAYMENT_ENDPOINTS, COLLECTION_ENDPOINTS, CONSULTATION_ENDPOINTS, COPILOT_ENDPOINTS, CORPORATE_ENDPOINTS, EVENT_ENDPOINTS, FAQ_ENDPOINTS, HOMEPAGE_ENDPOINTS, LOYALTY_ENDPOINTS, ANALYTICS_ENDPOINTS, MEDIA_ENDPOINTS, ORDER_ENDPOINTS, PREORDER_ENDPOINTS, PRODUCT_ENDPOINTS, PROMOTION_ENDPOINTS, REVIEW_ENDPOINTS, SEARCH_ENDPOINTS, SELLER_ENDPOINTS, BLOG_ENDPOINTS, STORE_ENDPOINTS, WISHLIST_ENDPOINTS, PROFILE_STATS_ENDPOINTS, } from "./api-endpoints";
+export { API_ENDPOINTS, API_ROUTES, LOGS_ENDPOINTS, AUTH_ENDPOINTS, ACCOUNT_ENDPOINTS, NOTIFICATIONS_ENDPOINTS, SITE_SETTINGS_ENDPOINTS, ADMIN_ENDPOINTS, AUCTION_ENDPOINTS, BID_ENDPOINTS, CART_ENDPOINTS, CATEGORY_ENDPOINTS, CHECKOUT_ENDPOINTS, PAYMENT_ENDPOINTS, COLLECTION_ENDPOINTS, CONSULTATION_ENDPOINTS, COPILOT_ENDPOINTS, CORPORATE_ENDPOINTS, EVENT_ENDPOINTS, FAQ_ENDPOINTS, HOMEPAGE_ENDPOINTS, LOYALTY_ENDPOINTS, ANALYTICS_ENDPOINTS, MEDIA_ENDPOINTS, ORDER_ENDPOINTS, PREORDER_ENDPOINTS, PRODUCT_ENDPOINTS, PROMOTION_ENDPOINTS, REVIEW_ENDPOINTS, SEARCH_ENDPOINTS, SELLER_ENDPOINTS, BLOG_ENDPOINTS, STORE_ENDPOINTS, WISHLIST_ENDPOINTS, PROFILE_STATS_ENDPOINTS, } from "./api-endpoints";
 export { COLLECTION_CACHE_PATHS } from "./cache-invalidation";
 export { PAGE_SIZES, MAX_PAGE_SIZE, FEATURED_LIMITS, SITEMAP_LIMITS, } from "./pagination-presets";
 export { NOTIFICATION_TYPES, NOTIFICATION_TYPE_TABS, } from "./notification-types";
@@ -21,7 +21,7 @@ export { WISHLIST_MAX, HISTORY_MAX, CART_MAX_ITEMS, WISHLIST_DOC_ID, HISTORY_DOC
 // derived objects (e.g. Object.values(...) for a Zod enum) at module-eval
 // time, which needs a small, synchronously-resolvable subpath rather than
 // the much larger client.ts barrel.
-export { PRODUCT_FIELDS, PRODUCT_STATUS_TRANSITIONS, ORDER_FIELDS, REVIEW_FIELDS, BID_FIELDS, AD_FIELDS, EVENT_FIELDS, EVENT_ENTRY_FIELDS, PAYOUT_FIELDS, STORE_FIELDS, CATEGORY_FIELDS, BLOG_FIELDS, USER_FIELDS, ADDRESS_FIELDS, BRAND_FIELDS, CART_FIELDS, WISHLIST_FIELDS, HISTORY_FIELDS, NOTIFICATION_FIELDS, SESSION_FIELDS, COUPON_USAGE_FIELDS, CONVERSATION_FIELDS, SCAMMER_FIELDS, SUPPORT_TICKET_FIELDS, CAROUSEL_FIELDS, COUPON_FIELDS, FAQ_FIELDS, HOMEPAGE_SECTION_FIELDS, SITE_SETTINGS_FIELDS, COMMON_FIELDS, OAUTH_STATE_VALUES, SCHEMA_DEFAULTS, } from "./field-names";
+export { PRODUCT_FIELDS, PRODUCT_STATUS_TRANSITIONS, ORDER_FIELDS, REVIEW_FIELDS, BID_FIELDS, AD_FIELDS, EVENT_FIELDS, EVENT_ENTRY_FIELDS, PAYOUT_FIELDS, STORE_FIELDS, CATEGORY_FIELDS, BLOG_FIELDS, USER_FIELDS, ADDRESS_FIELDS, BRAND_FIELDS, CART_FIELDS, WISHLIST_FIELDS, HISTORY_FIELDS, NOTIFICATION_FIELDS, SESSION_FIELDS, COUPON_USAGE_FIELDS, SCAMMER_FIELDS, SUPPORT_TICKET_FIELDS, CAROUSEL_FIELDS, COUPON_FIELDS, FAQ_FIELDS, HOMEPAGE_SECTION_FIELDS, SITE_SETTINGS_FIELDS, COMMON_FIELDS, OAUTH_STATE_VALUES, SCHEMA_DEFAULTS, } from "./field-names";
 // Dashboard filter-tab sets — same rationale as the field-name maps above.
 export { SELLER_LISTING_TABS, } from "../features/products/constants/listing-tabs";
 export { ALL_TAB, EMPTY_TAB, ADMIN_PRODUCT_STATUS_TABS, ADMIN_PRODUCT_LISTING_TYPE_TABS, ADMIN_BLOG_STATUS_TABS, ADMIN_USER_STATUS_TABS, ADMIN_USER_ROLE_TABS, ADMIN_STORE_STATUS_TABS, ADMIN_PAYOUT_STATUS_TABS, ADMIN_ORDER_STATUS_TABS, ADMIN_REVIEW_STATUS_TABS, ADMIN_REVIEW_RATING_TABS, ADMIN_BID_STATUS_TABS, ADMIN_CONTACT_STATUS_TABS, ADMIN_NEWSLETTER_STATUS_TABS, ADMIN_EVENT_ENTRY_STATUS_TABS, ADMIN_EVENT_STATUS_TABS, ADMIN_CART_OWNERSHIP_TABS, ADMIN_COUPON_TYPE_TABS, SELLER_PRODUCT_STATUS_TABS, SELLER_AUCTION_STATUS_TABS, SELLER_ORDER_STATUS_TABS, SELLER_OFFER_STATUS_TABS, SELLER_BID_STATUS_TABS, } from "../features/admin/constants/filter-tabs";

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

@@ -68,6 +68,30 @@ export declare const TABLE_KEYS: {
     readonly LIVE_TRANSPORT_METHOD: "liveTransportMethod";
 };
 export type TableKey = (typeof TABLE_KEYS)[keyof typeof TABLE_KEYS];
+/**
+ * The one delimiter joining several values of ONE filter key in a URL.
+ *
+ * 🛑 `"|"`, never `","`. sievejs reads same-field `|` as an OR-group, which the
+ * Firestore adapter upgrades to an `in` query. A comma is a clause SEPARATOR —
+ * `condition==new,condition==used` is an AND of two equalities on one field and
+ * can never match a document.
+ *
+ * Two filter systems disagreed on this. `ProductFilters` and the 11 sites like
+ * it wrote `vals.join("|")`; `usePendingFilters` and `FilterPanel` split and
+ * joined on `","` for the SAME URL keys. Nothing broke visibly, because a
+ * pipe-joined string survives a comma split as a single element and round-trips
+ * intact — but it counts as ONE, so the active-filter badge reported 1 for a
+ * three-category selection, and `usePendingTable.get`'s `[0]` returned the
+ * whole `"a|b|c"` string and appeared correct for the same wrong reason.
+ *
+ * Split and join through the two helpers below rather than inlining either
+ * character; that is what keeps the count, the wire format and Sieve agreeing.
+ */
+export declare const FILTER_VALUE_DELIMITER = "|";
+/** Parse a multi-value filter param. Empty string → no values, never `[""]`. */
+export declare function splitFilterValues(raw: string | null | undefined): string[];
+/** Serialise a multi-value filter param for the URL. */
+export declare function joinFilterValues(values: readonly string[]): string;
 export declare const VIEW_MODE: {
     readonly GRID: "grid";
     readonly LIST: "list";

package/dist/constants/table-keys.js

@@ -70,6 +70,34 @@ export const TABLE_KEYS = {
     LIVE_SEX: "liveSex",
     LIVE_TRANSPORT_METHOD: "liveTransportMethod",
 };
+/**
+ * The one delimiter joining several values of ONE filter key in a URL.
+ *
+ * 🛑 `"|"`, never `","`. sievejs reads same-field `|` as an OR-group, which the
+ * Firestore adapter upgrades to an `in` query. A comma is a clause SEPARATOR —
+ * `condition==new,condition==used` is an AND of two equalities on one field and
+ * can never match a document.
+ *
+ * Two filter systems disagreed on this. `ProductFilters` and the 11 sites like
+ * it wrote `vals.join("|")`; `usePendingFilters` and `FilterPanel` split and
+ * joined on `","` for the SAME URL keys. Nothing broke visibly, because a
+ * pipe-joined string survives a comma split as a single element and round-trips
+ * intact — but it counts as ONE, so the active-filter badge reported 1 for a
+ * three-category selection, and `usePendingTable.get`'s `[0]` returned the
+ * whole `"a|b|c"` string and appeared correct for the same wrong reason.
+ *
+ * Split and join through the two helpers below rather than inlining either
+ * character; that is what keeps the count, the wire format and Sieve agreeing.
+ */
+export const FILTER_VALUE_DELIMITER = "|";
+/** Parse a multi-value filter param. Empty string → no values, never `[""]`. */
+export function splitFilterValues(raw) {
+    return raw ? raw.split(FILTER_VALUE_DELIMITER).filter(Boolean) : [];
+}
+/** Serialise a multi-value filter param for the URL. */
+export function joinFilterValues(values) {
+    return values.filter(Boolean).join(FILTER_VALUE_DELIMITER);
+}
 export const VIEW_MODE = {
     GRID: "grid",
     LIST: "list",

package/dist/contracts/client-realtime.d.ts

@@ -13,6 +13,12 @@ export interface RealtimeSnapshot {
 /** Unsubscribe function returned by subscribe */
 export type Unsubscribe = () => void;
 export interface IClientRealtimeProvider {
+    /**
+     * A provider on its own Firebase app for this claim scope, so concurrent
+     * channels do not overwrite each other's auth. Optional: a provider that
+     * cannot isolate returns itself, keeping the old shared-app behaviour.
+     */
+    forScope?(scope: string): IClientRealtimeProvider;
     /** Authenticate the realtime connection with a custom token */
     signInWithToken(token: string): Promise<void>;
     /** Sign out of the realtime connection */

package/dist/contracts/extend.d.ts

@@ -52,15 +52,6 @@ export interface WithTransformOpts<Base, Target extends Base = Base> {
  * Convenience helper: build a response type for list endpoints that mirrors
  * the package's standard list-response shape but with a generic item type.
  */
-export interface GenericListResponse<T> {
-    items: T[];
-    total: number;
-    page: number;
-    pageSize?: number;
-    perPage?: number;
-    totalPages: number;
-    hasMore?: boolean;
-}
 /**
  * A single column definition for data tables.
  * Defined here in contracts so feat-* packages can export default column sets

package/dist/contracts/index.d.ts

@@ -17,7 +17,7 @@ export type { ExtraFormField, ExtraFieldRenderArgs } from "./form";
 export { registerFormFields, resolveFormFields, removeFormFields, _resetFormFields, } from "./form";
 export type { RouteStub, ApiRouteStub, FeatureManifest, FeaturesConfig, } from "./feature";
 export type { SiteConfig, NavItem } from "./config";
-export type { WithTransformOpts, GenericListResponse, TableColumn, ColumnPriority, ColumnExtensionOpts, LayoutSlots, FeatureExtension, } from "./extend";
+export type { WithTransformOpts, TableColumn, ColumnPriority, ColumnExtensionOpts, LayoutSlots, FeatureExtension, } from "./extend";
 export { COLUMN_PRIORITY_CLASS, COLUMN_PRIORITY_CLASS_BLOCK } from "./extend";
 export type { PaginationConfig, StickyConfig, TableConfig, TableViewMode, } from "./table";
 export { DEFAULT_PAGINATION_CONFIG, DEFAULT_STICKY_CONFIG, DEFAULT_TABLE_CONFIG, mergeTableConfig, } from "./table";

package/dist/contracts/realtime-session.d.ts

@@ -1,3 +1,4 @@
+import { type IClientRealtimeProvider } from "./client-realtime";
 export interface RealtimeToken {
     customToken: string;
     expiresAt: number;
@@ -12,16 +13,15 @@ export interface RealtimeToken {
  * @returns a release function. **Always call it** — the session is only torn
  *          down when every lease is released.
  */
-export declare function acquireRealtimeSession(scope: string, getToken: () => Promise<RealtimeToken>): Promise<() => void>;
-/**
- * Take a lease WITHOUT signing in — for a consumer that manages its own
- * sign-in but must still participate in the reference count.
- *
- * `useRealtimeEvent` is the case: its token carries a job-scoped `bulkJobId`
- * claim it receives from the caller, so it cannot use `acquireRealtimeSession`'s
- * fetcher. It still must not be able to sign the shared app out from under
- * another channel, which is precisely what its `cleanup()` used to do.
- */
-export declare function acquireExternalRealtimeLease(): () => void;
-/** Test/diagnostic only. */
+export interface RealtimeLease {
+    /**
+     * Subscribe through THIS provider, not the global one — it is bound to the
+     * app this scope signed in on. Using the global provider would read from an
+     * app with someone else's claims.
+     */
+    provider: IClientRealtimeProvider;
+    release: () => void;
+}
+export declare function acquireRealtimeSession(scope: string, getToken: () => Promise<RealtimeToken>): Promise<RealtimeLease>;
+/** Test/diagnostic only — total leases across every scope. */
 export declare function activeRealtimeLeases(): number;

package/dist/contracts/realtime-session.js

@@ -1,10 +1,21 @@
 import { normalizeError } from "../errors/normalize";
-import { getClientRealtimeProvider } from "./client-realtime";
+import { getClientRealtimeProvider, } from "./client-realtime";
 /**
- * Shared, REFERENCE-COUNTED sign-in for the one client realtime app.
+ * PER-SCOPE, reference-counted sign-in for the client realtime channels.
+ *
+ * Each claim scope gets its own Firebase app (via `provider.forScope`), because
+ * Firebase Auth state is per-app and two channels legitimately need two
+ * different claim sets at the same time.
  *
  * WHY THIS EXISTS — two distinct bugs, one cause.
  *
+ * 🛑 Both examples below are HISTORICAL: buyer↔seller messaging was deleted
+ * 2026-08-31, so `useConversation` / `useConversations` / `useChat` and the
+ * `chats/*` and `chat/*` RTDB paths no longer exist — don't go looking for
+ * them. The mechanism is not historical. `auth_events`, `payment_events` and
+ * `bulk_events` are all still live, still concurrent, and still each need their
+ * own claim scope, which is the whole reason this file is here.
+ *
  * 1. **Nobody signed in for messaging.** `useConversation` and
  *    `useConversations` subscribed to `chats/...` without ever calling
  *    `signInWithToken`, so `auth == null` and both RTDB rules evaluated false.
@@ -21,98 +32,89 @@ import { getClientRealtimeProvider } from "./client-realtime";
  *    bulk token (carrying `bulkJobId`), killing an in-flight job subscription.
  *    Whoever finished last broke whoever was still working.
  *
- * The fix for (2) is not "sign out more carefully" — it is that **no individual
- * consumer may decide to sign out at all**. Each acquires a lease and releases
- * it; the session ends only when the last lease is gone.
+ * (2) needed BOTH halves, and only one was done at first:
+ *   - sign-OUT: no consumer may decide to sign out. Each takes a lease; the
+ *     session ends only when the last lease for that scope is gone.
+ *   - sign-IN: ref-counting cannot help here, because nothing is being shared
+ *     by agreement — a bulk job and a message thread need different claims
+ *     simultaneously. The answer is separate apps, not coordination.
  *
- * Tokens differ per channel (different claims), so `acquire` takes a fetcher and
- * re-signs when the token it holds is for a different scope or has expired.
+ * 🛑 Subscribe through `lease.provider`, never `getClientRealtimeProvider()`.
+ * The global one is the root app; the lease's is the app your scope actually
+ * authenticated on.
  */
 /** Refresh a little early — a token that expires mid-subscription is a silent drop. */
 const EXPIRY_SKEW_MS = 60000;
-let leases = 0;
-let currentScope = null;
-let expiresAt = 0;
-let inFlight = null;
 /**
- * Ensure the shared realtime app is signed in for `scope`, and take a lease.
+ * One entry per claim scope, each on its OWN Firebase app.
  *
- * @param scope    an identifier for the claim set (e.g. `"messages"`,
- *                 `"chat:<id>"`). Signing in again for the SAME scope while a
- *                 valid token is held is a no-op.
- * @param getToken fetches a fresh custom token. Called only when needed.
- * @returns a release function. **Always call it** — the session is only torn
- *          down when every lease is released.
+ * 🛑 This used to be three module-level singletons — `currentScope`,
+ * `expiresAt`, `leases` — describing ONE shared app. That shape could not
+ * express the real situation: two channels legitimately need two different
+ * claim sets at the same time, and Firebase Auth state is per-app, so every
+ * sign-in replaced the previous one's claims. Ref-counting only stopped a
+ * finishing channel from signing the others OUT; it could not stop a starting
+ * channel from signing itself IN over them.
  */
+const scopes = new Map();
 export async function acquireRealtimeSession(scope, getToken) {
-    const lease = { scope };
-    leases++;
-    const needsSignIn = currentScope !== lease.scope || Date.now() > expiresAt - EXPIRY_SKEW_MS;
-    if (needsSignIn) {
-        // Collapse concurrent acquires — several hooks mount in the same tick and
-        // would otherwise each fetch a token and race to sign in.
-        inFlight ?? (inFlight = (async () => {
+    const root = getClientRealtimeProvider();
+    let state = scopes.get(scope);
+    if (!state) {
+        // `forScope` is optional on the contract: a provider that cannot isolate
+        // falls back to the shared app, which is the old behaviour rather than a
+        // crash.
+        state = {
+            leases: 0,
+            expiresAt: 0,
+            inFlight: null,
+            provider: root.forScope?.(scope) ?? root,
+        };
+        scopes.set(scope, state);
+    }
+    state.leases++;
+    if (Date.now() > state.expiresAt - EXPIRY_SKEW_MS) {
+        // Collapse concurrent acquires for the SAME scope — several hooks mount in
+        // one tick and would otherwise each fetch a token and race to sign in.
+        state.inFlight ?? (state.inFlight = (async () => {
             try {
                 const token = await getToken();
-                await getClientRealtimeProvider().signInWithToken(token.customToken);
-                currentScope = lease.scope;
-                expiresAt = token.expiresAt;
+                await state.provider.signInWithToken(token.customToken);
+                state.expiresAt = token.expiresAt;
             }
             finally {
-                inFlight = null;
+                state.inFlight = null;
             }
         })());
-        await inFlight;
+        await state.inFlight;
     }
     let released = false;
-    return () => {
-        if (released)
-            return; // React StrictMode double-invokes cleanups
-        released = true;
-        leases = Math.max(0, leases - 1);
-        if (leases > 0)
-            return;
-        currentScope = null;
-        expiresAt = 0;
-        getClientRealtimeProvider()
-            .signOut()
-            .catch((err) => {
-            void normalizeError(err);
-        });
-    };
-}
-/**
- * Take a lease WITHOUT signing in — for a consumer that manages its own
- * sign-in but must still participate in the reference count.
- *
- * `useRealtimeEvent` is the case: its token carries a job-scoped `bulkJobId`
- * claim it receives from the caller, so it cannot use `acquireRealtimeSession`'s
- * fetcher. It still must not be able to sign the shared app out from under
- * another channel, which is precisely what its `cleanup()` used to do.
- */
-export function acquireExternalRealtimeLease() {
-    leases++;
-    // Its own sign-in has replaced whatever scope was active; forget the cached
-    // one so the next acquire() re-authenticates rather than trusting a token
-    // that is no longer installed.
-    currentScope = null;
-    expiresAt = 0;
-    let released = false;
-    return () => {
-        if (released)
-            return;
-        released = true;
-        leases = Math.max(0, leases - 1);
-        if (leases > 0)
-            return;
-        getClientRealtimeProvider()
-            .signOut()
-            .catch((err) => {
-            void normalizeError(err);
-        });
+    return {
+        provider: state.provider,
+        release: () => {
+            if (released)
+                return; // React StrictMode double-invokes cleanups
+            released = true;
+            const cur = scopes.get(scope);
+            if (!cur)
+                return;
+            cur.leases = Math.max(0, cur.leases - 1);
+            if (cur.leases > 0)
+                return;
+            // Last holder of THIS scope. Signing out touches only this scope's app,
+            // so it cannot disturb any other channel.
+            cur.expiresAt = 0;
+            scopes.delete(scope);
+            cur.provider.signOut().catch((err) => {
+                void normalizeError(err);
+            });
+        },
     };
 }
-/** Test/diagnostic only. */
+/** Test/diagnostic only — total leases across every scope. */
 export function activeRealtimeLeases() {
-    return leases;
+    let total = 0;
+    for (const s of scopes.values())
+        total += s.leases;
+    return total;
 }

package/dist/core/browser.d.ts

@@ -8,7 +8,7 @@ export { EventBus, eventBus } from "./EventBus";
 export type { EventSubscription } from "./EventBus";
 export { CacheManager, cacheManager } from "./CacheManager";
 export type { CacheOptions, CacheEntry } from "./CacheManager";
-export { SITE_CONFIG, FEATURE_FLAGS, createSiteConfig, resolveSiteConfig, } from "./site-config";
+export { SITE_CONFIG, createSiteConfig, resolveSiteConfig, } from "./site-config";
 export type { RuntimeSiteConfig } from "./site-config";
 export { useSiteSettings } from "./hooks/useSiteSettings";
 export { MUTATION_EVENTS, emitMutation, onMutation, inferMutationEvent, } from "./mutation-events";