@mohasinac/appkit 4.30.18 → 4.31.0

package/dist/features/admin/schemas/admin-editor-forms.js

@@ -15,7 +15,7 @@
  * WHAT: One schema per editor.
  *
  * EXPORTS:
- *   adminAddressFormSchema, adminStoreUpdateSchema, announcementBarSchema,
+ *   adminStoreUpdateSchema, announcementBarSchema,
  *   and their inferred value types
  *
  * @tag domain:admin
@@ -27,60 +27,18 @@
  */
 import { z } from "zod";
 import { annotate } from "../../shell/field-ui-meta";
+import { mediaUrlSchema } from "../../../validation/schemas";
+import { StoreStatusValues } from "../../stores/schemas/firestore";
 const PHONE_RE = /^(\+?91[-\s]?)?[6-9]\d{9}$/;
-/** Indian PIN: six digits, never starting at zero. */
-const PIN_RE = /^[1-9]\d{5}$/;
-/**
- * An address written by an admin on someone's behalf.
+/*
+ * `adminAddressFormSchema` is DELETED (W5 / D19).
  *
- * Shapes match `AddressDocument` (`addressLine1`, not `line1`) — deliberately
- * NOT `userAddressSchema`, which is the account-side view of the same data
- * under different field names. Reusing that one here would have meant
- * translating on every write.
+ * It was a twelfth restatement of the same eleven address fields, with an
+ * India-only `postalCode: /^\d{6}$/` on a form whose `country` was free text.
+ * The one address shape and the one country-aware postal rule now live in
+ * `features/addresses/schemas/address-form.ts`, and this editor imports
+ * `adminAddressCreateSchema` from there.
  */
-export const adminAddressFormSchema = z.object({
-    ownerType: annotate(z.enum(["user", "store"]), {
-        section: "owner", sectionLabel: "Belongs to", sectionRequired: true, quick: true, order: 1, row: "pair",
-    }),
-    ownerId: annotate(z.string().trim().min(1, "Choose who this address belongs to."), {
-        section: "owner", quick: true, order: 2, row: "pair",
-    }),
-    label: annotate(z.string().trim().max(60, "Keep the label short — e.g. Home, Warehouse.").optional(), {
-        section: "address", sectionLabel: "Address", order: 1, row: "pair",
-    }),
-    fullName: annotate(z.string().trim().min(2, "A recipient name is required.").max(120), {
-        section: "address", sectionRequired: true, quick: true, order: 2, row: "pair",
-    }),
-    phone: annotate(z.string().trim().regex(PHONE_RE, "Enter a 10-digit Indian mobile number."), {
-        section: "address", quick: true, order: 3, row: "pair",
-    }),
-    addressLine1: annotate(z.string().trim().min(3, "Street address is required.").max(200), {
-        section: "address", quick: true, order: 4, row: "full",
-    }),
-    addressLine2: annotate(z.string().trim().max(200).optional(), {
-        section: "address", order: 5, row: "full",
-    }),
-    landmark: annotate(z.string().trim().max(120).optional(), {
-        section: "address", order: 6, row: "pair",
-    }),
-    city: annotate(z.string().trim().min(2, "City is required.").max(80), {
-        section: "address", order: 7, row: "pair",
-    }),
-    state: annotate(z.string().trim().min(2, "State is required.").max(80), {
-        section: "address", order: 8, row: "pair",
-    }),
-    // A wrong PIN is the single most common reason a parcel is undeliverable,
-    // and it was previously any string at all.
-    postalCode: annotate(z.string().trim().regex(PIN_RE, "Enter a 6-digit PIN code."), {
-        section: "address", order: 9, row: "pair",
-    }),
-    country: annotate(z.string().trim().min(2).max(60), {
-        section: "address", order: 10, row: "pair",
-    }),
-    isDefault: annotate(z.boolean().optional(), {
-        section: "address", order: 11, row: "quarter",
-    }),
-});
 /**
  * An admin changing a store's standing.
  *
@@ -90,8 +48,25 @@ export const adminAddressFormSchema = z.object({
  */
 export const adminStoreUpdateSchema = z
     .object({
-    storeStatus: annotate(z.enum(["pending", "active", "suspended", "closed"]), {
-        section: "standing", sectionLabel: "Store standing", sectionRequired: true, quick: true, order: 1, row: "pair",
+    /*
+     * 🛑 DERIVED from `StoreStatusValues`, never hand-written.
+     *
+     * This was `["pending","active","suspended","closed"]` — and `"closed"` is
+     * not a store status. The real union (`stores/schemas/firestore.ts:57`) is
+     * pending · active · suspended · **rejected**, which is what
+     * `AdminStoreEditorView`'s dropdown has always offered and what the API
+     * has always stored. So the schema declared a value nothing can produce and
+     * omitted the one the UI actually sends.
+     *
+     * It went unnoticed because the `<Form schema>` prop was never parsed —
+     * selecting "Rejected" reached the API unchecked. Under `<SectionForm>`,
+     * which parses on every change, it would have become a hard failure on a
+     * legitimate value. A fifth hand-written copy of this union is exactly how
+     * that happens again.
+     */
+    storeStatus: annotate(z.enum(Object.values(StoreStatusValues)), {
+        section: "standing", sectionLabel: "Store standing", sectionRequired: true,
+        quick: true, order: 1, row: "pair", kind: "select",
     }),
     isVerified: annotate(z.boolean().optional(), {
         section: "standing", order: 2, row: "quarter",
@@ -99,8 +74,15 @@ export const adminStoreUpdateSchema = z
     isFeatured: annotate(z.boolean().optional(), {
         section: "standing", order: 3, row: "quarter",
     }),
+    /*
+     * `when` mirrors the superRefine below, which is what stops the two from
+     * disagreeing. The page used to keep this textarea live at all times and
+     * then drop its value unless the status was exactly "suspended" — choose
+     * "rejected", write the reason, save, and it vanished silently.
+     */
     suspensionReason: annotate(z.string().trim().max(500).optional(), {
         section: "standing", order: 4, row: "full", kind: "textarea",
+        when: (v) => v.storeStatus === "suspended",
     }),
     capabilities: annotate(z.array(z.string().min(1)).max(50).optional(), {
         section: "capabilities", sectionLabel: "Capabilities", order: 1, row: "full", kind: "list",
@@ -139,3 +121,64 @@ export const announcementBarSchema = z.object({
         section: "announcement", order: 3, row: "full",
     }),
 });
+/**
+ * A brand, as an admin edits it.
+ *
+ * Lifted out of `AdminBrandEditorView`, where it was declared locally and
+ * unannotated — so it could not drive a generated form, and, more to the point,
+ * it never ran: the submit handler checked `name.trim()` and called the
+ * mutation. `website: z.string().url()` had therefore never rejected anything,
+ * and the raw `<Input>`s it would have reported on carry no `name`, so
+ * `applyZodIssues` had nowhere to put an error even if it had.
+ *
+ * ## "Logo" is the cover image, and the labels used to say the opposite
+ *
+ * `logoURL` maps to `display.coverImage` — the brand page's full-bleed hero
+ * banner. The form once offered a "Logo" input beside a "Banner" input, where
+ * the first drove the banner and the second wrote `brandBannerImage`, a field
+ * with no reader anywhere (Root Cause #51). The dead field is gone and the
+ * label now describes what it controls.
+ */
+export const brandFormSchema = z.object({
+    name: annotate(z.string().min(1, "Brand name is required").max(120), {
+        section: "basics", sectionLabel: "Brand", sectionRequired: true, quick: true,
+        order: 1, row: "pair", label: "Brand name",
+    }),
+    /*
+     * Derived from the name, and create-only.
+     *
+     * Slug immutability after creation is the convention every other taxonomy in
+     * this codebase follows (categories, bundles — Root Cause #39), and it is
+     * what keeps existing links and `brand:` product references resolving. The
+     * editor used to expose it as a free-text box on the EDIT form too, which is
+     * a live rename waiting to orphan a whole catalogue: `BrandDetailPageView`
+     * matches products by display NAME, and nothing re-points them.
+     */
+    slug: annotate(z.string().regex(/^[a-z0-9-]+$/i).optional().or(z.literal("")), {
+        section: "basics", order: 2, row: "pair", derived: true, tier: "t1-derive",
+        help: "Generated from the brand name.",
+    }),
+    description: annotate(z.string().max(2000).optional().or(z.literal("")), {
+        section: "basics", order: 3, row: "full", kind: "textarea",
+    }),
+    logoURL: annotate(mediaUrlSchema.optional().or(z.literal("")), {
+        section: "media", sectionLabel: "Cover image", order: 1, row: "full",
+        kind: "media", sectionKeepMounted: true, label: "Cover image",
+        help: "Renders as the full-bleed banner at the top of the brand page.",
+    }),
+    website: annotate(z.string().url("Enter a full URL, including https://").optional().or(z.literal("")), {
+        section: "identity", sectionLabel: "About this brand", order: 1, row: "pair",
+        inputType: "url",
+    }),
+    country: annotate(z.string().max(80).optional().or(z.literal("")), {
+        section: "identity", order: 2, row: "pair", label: "Country of origin",
+    }),
+    founded: annotate(z.number().int().min(1800, "That is earlier than any brand on record.").max(new Date().getFullYear(), "A founding year cannot be in the future.").optional(), { section: "identity", order: 3, row: "pair", kind: "number", label: "Founded year" }),
+    isActive: annotate(z.boolean(), {
+        section: "visibility", sectionLabel: "Visibility", order: 1, row: "quarter",
+        label: "Active",
+    }),
+    displayOrder: annotate(z.number().int().min(0).optional(), {
+        section: "visibility", order: 2, row: "pair", kind: "number", label: "Display order",
+    }),
+});

package/dist/features/admin/schemas/admin-ops-forms.d.ts

@@ -34,6 +34,28 @@ export declare const employeeInviteSchema: z.ZodObject<{
     permissions?: string[] | undefined;
 }>;
 export type EmployeeInviteValues = z.infer<typeof employeeInviteSchema>;
+/**
+ * Editing an existing team member's access.
+ *
+ * Derived by omission rather than declared, so the two cannot drift: it is the
+ * invite form minus the one field that only makes sense while inviting. The
+ * editor rendered the email input under `mode === "invite"` and parsed the
+ * full schema regardless, so an edit could only ever have failed validation on
+ * a control that was not on screen — which nothing noticed, because nothing
+ * parsed it.
+ */
+export declare const employeePermissionsSchema: z.ZodObject<Omit<{
+    email: z.ZodString;
+    permissionGroup: z.ZodString;
+    permissions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "email">, "strip", z.ZodTypeAny, {
+    permissionGroup: string;
+    permissions?: string[] | undefined;
+}, {
+    permissionGroup: string;
+    permissions?: string[] | undefined;
+}>;
+export type EmployeePermissionsValues = z.infer<typeof employeePermissionsSchema>;
 /**
  * The reason recorded against a hard ban.
  *
@@ -78,7 +100,13 @@ export declare const adminAdFormSchema: z.ZodEffects<z.ZodObject<{
     requiresConsent: z.ZodBoolean;
     startAt: z.ZodOptional<z.ZodString>;
     endAt: z.ZodOptional<z.ZodString>;
-    creative: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<import("../../..").FirestoreValue, z.ZodTypeDef, import("../../..").FirestoreValue>>>;
+    creativeTitle: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    creativeBody: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    creativeImageUrl: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    ctaLabel: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    ctaHref: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    adsenseSlot: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    thirdPartyUrl: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
 }, "strip", z.ZodTypeAny, {
     status: "draft" | "active" | "scheduled" | "paused";
     name: string;
@@ -88,7 +116,13 @@ export declare const adminAdFormSchema: z.ZodEffects<z.ZodObject<{
     requiresConsent: boolean;
     startAt?: string | undefined;
     endAt?: string | undefined;
-    creative?: Record<string, import("../../..").FirestoreValue> | undefined;
+    creativeTitle?: string | undefined;
+    creativeBody?: string | undefined;
+    creativeImageUrl?: string | undefined;
+    ctaLabel?: string | undefined;
+    ctaHref?: string | undefined;
+    adsenseSlot?: string | undefined;
+    thirdPartyUrl?: string | undefined;
 }, {
     status: "draft" | "active" | "scheduled" | "paused";
     name: string;
@@ -98,7 +132,13 @@ export declare const adminAdFormSchema: z.ZodEffects<z.ZodObject<{
     requiresConsent: boolean;
     startAt?: string | undefined;
     endAt?: string | undefined;
-    creative?: Record<string, import("../../..").FirestoreValue> | undefined;
+    creativeTitle?: string | undefined;
+    creativeBody?: string | undefined;
+    creativeImageUrl?: string | undefined;
+    ctaLabel?: string | undefined;
+    ctaHref?: string | undefined;
+    adsenseSlot?: string | undefined;
+    thirdPartyUrl?: string | undefined;
 }>, {
     status: "draft" | "active" | "scheduled" | "paused";
     name: string;
@@ -108,7 +148,13 @@ export declare const adminAdFormSchema: z.ZodEffects<z.ZodObject<{
     requiresConsent: boolean;
     startAt?: string | undefined;
     endAt?: string | undefined;
-    creative?: Record<string, import("../../..").FirestoreValue> | undefined;
+    creativeTitle?: string | undefined;
+    creativeBody?: string | undefined;
+    creativeImageUrl?: string | undefined;
+    ctaLabel?: string | undefined;
+    ctaHref?: string | undefined;
+    adsenseSlot?: string | undefined;
+    thirdPartyUrl?: string | undefined;
 }, {
     status: "draft" | "active" | "scheduled" | "paused";
     name: string;
@@ -118,6 +164,12 @@ export declare const adminAdFormSchema: z.ZodEffects<z.ZodObject<{
     requiresConsent: boolean;
     startAt?: string | undefined;
     endAt?: string | undefined;
-    creative?: Record<string, import("../../..").FirestoreValue> | undefined;
+    creativeTitle?: string | undefined;
+    creativeBody?: string | undefined;
+    creativeImageUrl?: string | undefined;
+    ctaLabel?: string | undefined;
+    ctaHref?: string | undefined;
+    adsenseSlot?: string | undefined;
+    thirdPartyUrl?: string | undefined;
 }>;
 export type AdminAdFormValues = z.infer<typeof adminAdFormSchema>;

package/dist/features/admin/schemas/admin-ops-forms.js

@@ -22,18 +22,19 @@
  * @tag layer:schema
  * @tag pattern:none
  * @tag access:isomorphic
- * @tag consumers:AdminOrderEditorView,AdminEmployeeEditorView,AdminUsersView,AdminFeatureFlagsView,AdminAdEditorView
+ * @tag consumers:AdminOrderEditorView,AdminEmployeeEditorView,AdminUsersView,AdminAdEditorView
  * @tag sideEffects:none
  */
 import { z } from "zod";
 import { annotate } from "../../shell/field-ui-meta";
-import { firestoreValueSchema } from "../../../schemas/firestore-value";
+import { normalizeError } from "../../../errors/normalize";
 import { OrderStatusValues } from "../../orders/schemas/firestore";
 /** Derived from the real 9-value union, never restated (Root Cause #36). */
 const orderStatusSchema = z.enum(Object.values(OrderStatusValues));
 export const adminOrderUpdateSchema = z.object({
     status: annotate(orderStatusSchema, {
-        section: "status", sectionLabel: "Order", sectionRequired: true, quick: true, order: 1, row: "pair",
+        section: "status", sectionLabel: "Order", sectionRequired: true, quick: true,
+        order: 1, row: "pair", kind: "select",
     }),
     trackingNumber: annotate(z.string().trim().max(120).optional(), {
         section: "shipping", sectionLabel: "Shipping", order: 1, row: "pair",
@@ -51,7 +52,12 @@ export const adminOrderUpdateSchema = z.object({
         .number({ invalid_type_error: "Enter the refund amount as a number." })
         .positive("A refund must be greater than zero.")
         .max(10000000, "That looks like a typo — check the decimal point.")
-        .optional(), { section: "shipping", order: 3, row: "pair", kind: "number" }),
+        .optional(), {
+        section: "shipping", order: 3, row: "pair", kind: "number",
+        // Only meaningful on a refunding status, which is the condition the page
+        // already used to decide whether to render the input.
+        when: (v) => v.status === "refunded" || v.status === "return_requested",
+    }),
     notes: annotate(z.string().trim().max(2000).optional(), {
         section: "shipping", order: 4, row: "full", kind: "textarea",
     }),
@@ -66,6 +72,17 @@ export const employeeInviteSchema = z.object({
         section: "member", order: 3, row: "full", kind: "list",
     }),
 });
+/**
+ * Editing an existing team member's access.
+ *
+ * Derived by omission rather than declared, so the two cannot drift: it is the
+ * invite form minus the one field that only makes sense while inviting. The
+ * editor rendered the email input under `mode === "invite"` and parsed the
+ * full schema regardless, so an edit could only ever have failed validation on
+ * a control that was not on screen — which nothing noticed, because nothing
+ * parsed it.
+ */
+export const employeePermissionsSchema = employeeInviteSchema.omit({ email: true });
 /**
  * The reason recorded against a hard ban.
  *
@@ -120,28 +137,95 @@ export const adminAdFormSchema = z
     endAt: annotate(z.string().optional(), {
         section: "schedule", order: 2, row: "pair", kind: "date",
     }),
-    // Creative shape varies by provider, so it stays open — an AdSense slot and
-    // a manual banner share almost no fields. Open to a Firestore VALUE tree,
-    // not to anything: `z.unknown()` would pass a function straight to the
-    // driver, which then throws at write time rather than at parse time.
-    creative: annotate(z.record(firestoreValueSchema).optional(), {
-        section: "creative", sectionLabel: "Creative", order: 1, row: "full", kind: "list",
+    /*
+     * The creative, FLAT.
+     *
+     * It was one open `z.record(firestoreValueSchema)` — "the shape varies by
+     * provider, so it stays open" — which is true of the STORED shape and was
+     * the wrong conclusion for the FORM. Open meant the seven inputs the
+     * editor renders were validated by nothing, and the two provider-specific
+     * ones were filtered out of the payload by a hand-written ternary instead
+     * of by the predicate that hides them. The nested shape is reassembled at
+     * the payload boundary, where the API wants it.
+     */
+    creativeTitle: annotate(z.string().trim().max(200).optional().or(z.literal("")), {
+        section: "creative", sectionLabel: "Creative", order: 1, row: "pair",
+        label: "Creative title",
+    }),
+    creativeBody: annotate(z.string().trim().max(500).optional().or(z.literal("")), {
+        section: "creative", order: 2, row: "pair", label: "Creative body",
+    }),
+    creativeImageUrl: annotate(z.string().trim().max(2000).optional().or(z.literal("")), {
+        section: "creative", order: 3, row: "pair", label: "Image URL", inputType: "url",
+    }),
+    ctaLabel: annotate(z.string().trim().max(80).optional().or(z.literal("")), {
+        section: "creative", order: 4, row: "pair", label: "CTA label",
+    }),
+    ctaHref: annotate(z.string().trim().max(2000).optional().or(z.literal("")), {
+        section: "creative", order: 5, row: "pair", label: "CTA URL",
+    }),
+    adsenseSlot: annotate(z.string().trim().max(120).optional().or(z.literal("")), {
+        section: "creative", order: 6, row: "pair", label: "AdSense slot",
+        when: (v) => v.provider === "adsense",
+    }),
+    thirdPartyUrl: annotate(z.string().trim().max(2000).optional().or(z.literal("")), {
+        section: "creative", order: 7, row: "pair", label: "Third-party URL",
+        when: (v) => v.provider === "thirdParty",
     }),
 })
     .superRefine((v, ctx) => {
+    const issue = (path, message) => ctx.addIssue({ code: z.ZodIssueCode.custom, path: [path], message });
     // A scheduled ad with no start date never runs, and nothing would say so.
     if (v.status === "scheduled" && !v.startAt) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ["startAt"],
-            message: "A scheduled ad needs a start date.",
-        });
+        issue("startAt", "A scheduled ad needs a start date.");
     }
     if (v.startAt && v.endAt && v.endAt <= v.startAt) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ["endAt"],
-            message: "The end date must be after the start date.",
-        });
+        issue("endAt", "The end date must be after the start date.");
+    }
+    /*
+     * The three provider rules, moved off the page's `publishIssues` list.
+     *
+     * There they were strings in a warning banner that only appeared once the
+     * status was already `active` or `scheduled` — so a DRAFT AdSense ad could
+     * be saved with no slot, and the omission surfaced later, as a block on
+     * publishing, far from the empty field. Stated here they reach the field
+     * that is wrong, whatever the status.
+     *
+     * The rest of that list stays on the page: it depends on the live
+     * placements and on whether the provider's credentials are configured,
+     * neither of which a schema can see.
+     */
+    if (v.provider === "manual") {
+        const hasCreative = v.creativeTitle?.trim() ||
+            v.creativeBody?.trim() ||
+            v.creativeImageUrl?.trim() ||
+            v.ctaHref?.trim();
+        if (!hasCreative) {
+            issue("creativeTitle", "A manual ad needs at least one of: title, body, image or CTA URL.");
+        }
+    }
+    if (v.provider === "adsense" && !v.adsenseSlot?.trim()) {
+        issue("adsenseSlot", "An AdSense ad needs a slot id.");
+    }
+    if (v.provider === "thirdParty") {
+        const url = v.thirdPartyUrl?.trim();
+        if (!url) {
+            issue("thirdPartyUrl", "A third-party ad needs a URL.");
+        }
+        else {
+            let parsed = null;
+            try {
+                parsed = new URL(url);
+            }
+            catch (err) {
+                void normalizeError(err);
+                parsed = null;
+            }
+            if (!parsed)
+                issue("thirdPartyUrl", "That is not a valid URL.");
+            else if (parsed.protocol !== "https:") {
+                issue("thirdPartyUrl", "A third-party ad URL must use https.");
+            }
+        }
     }
 });

package/dist/features/admin/schemas/admin-user-form.js

@@ -89,8 +89,15 @@ export const whatsappSettingsSchema = z.object({
  * `NaN` written to the entry.
  */
 export const lotteryPullSchema = z.object({
+    /*
+     * Context, not input. Whether this pull belongs to an event or a product is
+     * decided by the page that mounts the form, so rendering a picker for it
+     * would offer the user a choice that can only be wrong. `t2-server` keeps it
+     * in the parsed payload and out of the UI.
+     */
     sourceType: annotate(z.enum(["event", "product"]), {
         section: "entry", sectionLabel: "Entry", sectionRequired: true, quick: true, order: 1, row: "pair",
+        derived: true, tier: "t2-server",
     }),
     transactionId: annotate(z.string().trim().min(4, "Enter the payment reference from your app.").max(120), { section: "entry", quick: true, order: 2, row: "pair" }),
     paymentTime: annotate(z.string().trim().min(1, "When did you pay?").refine((v) => !Number.isNaN(Date.parse(v)), "That isn't a valid date and time."), { section: "entry", quick: true, order: 3, row: "pair", kind: "date" }),

package/dist/features/admin/schemas/firestore.d.ts

@@ -79,54 +79,6 @@ export declare const notificationQueryHelpers: {
     readonly unread: (userId: string) => readonly [readonly ["userId", "==", string], readonly ["isRead", "==", false]];
     readonly byType: (type: NotificationType) => readonly ["type", "==", "system" | "welcome" | "promotion" | "order_placed" | "order_confirmed" | "order_shipped" | "order_delivered" | "order_cancelled" | "bid_placed" | "bid_outbid" | "bid_won" | "bid_lost" | "auction_ended" | "review_approved" | "review_replied" | "product_available" | "account_action" | "offer_received" | "offer_responded" | "offer_expired" | "offer_counter_accepted" | "refund_initiated" | "prize_won" | "prize_reveal_expired" | "emi_installment_due_soon" | "emi_installment_overdue" | "payment_review" | "catalogue_images_stale"];
 };
-export interface ChatRoomDocument extends BaseDocument {
-    buyerId: string;
-    ownerId: string;
-    orderId: string;
-    productId?: string;
-    productTitle?: string;
-    buyerName: string;
-    ownerName: string;
-    lastMessage?: string;
-    lastMessageAt?: Date;
-    /** UIDs of participants who soft-deleted this room on their side. */
-    deletedBy: string[];
-    /** True for admin-created group chats (> 2 participants). */
-    isGroup: boolean;
-    /** All participant UIDs. For 1-1 rooms: [buyerId, ownerId]. */
-    participantIds: string[];
-    /** Set by admin to permanently revoke all access. */
-    adminDeleted: boolean;
-}
-export declare const CHAT_ROOM_COLLECTION: "chatRooms";
-export declare const CHAT_ROOM_INDEXED_FIELDS: readonly ["buyerId", "ownerId", "orderId", "participantIds", "adminDeleted", "updatedAt"];
-export declare const CHAT_ROOM_FIELDS: {
-    readonly ID: "id";
-    readonly BUYER_ID: "buyerId";
-    readonly OWNER_ID: "ownerId";
-    readonly ORDER_ID: "orderId";
-    readonly PRODUCT_ID: "productId";
-    readonly PRODUCT_TITLE: "productTitle";
-    readonly BUYER_NAME: "buyerName";
-    readonly OWNER_NAME: "ownerName";
-    readonly LAST_MESSAGE: "lastMessage";
-    readonly LAST_MESSAGE_AT: "lastMessageAt";
-    readonly CREATED_AT: "createdAt";
-    readonly UPDATED_AT: "updatedAt";
-    readonly DELETED_BY: "deletedBy";
-    readonly IS_GROUP: "isGroup";
-    readonly PARTICIPANT_IDS: "participantIds";
-    readonly ADMIN_DELETED: "adminDeleted";
-};
-export declare const DEFAULT_CHAT_ROOM_DATA: Omit<ChatRoomDocument, "id" | "createdAt" | "updatedAt" | "lastMessage" | "lastMessageAt" | "productId" | "productTitle">;
-export type ChatRoomCreateInput = Omit<ChatRoomDocument, "id" | "createdAt" | "updatedAt" | "lastMessage" | "lastMessageAt" | "deletedBy" | "adminDeleted">;
-export type ChatRoomUpdateInput = Pick<ChatRoomDocument, "lastMessage" | "lastMessageAt" | "updatedAt">;
-export declare const chatRoomQueryHelpers: {
-    readonly byBuyer: (buyerId: string) => readonly ["buyerId", "==", string];
-    readonly byOwner: (ownerId: string) => readonly ["ownerId", "==", string];
-    readonly byOrder: (orderId: string) => readonly ["orderId", "==", string];
-    readonly active: () => readonly ["adminDeleted", "==", false];
-};
 export interface TrustBarItem {
     icon: string;
     label: string;
@@ -381,6 +333,32 @@ export interface SiteSettingsDocument extends BaseDocument {
         codEnabled: boolean;
         /** Tier PP — cart total (rupees) at/above which checkout requires OTP verification. Applies to all payment methods except COD. Optional — falls back to no OTP gate when unset. */
         otpCheckoutThreshold?: number;
+        /**
+         * Phone-number OTP verification during signup/checkout. Real per-SMS cost
+         * via the Firebase phone-auth quota, so it stays OFF by default.
+         *
+         * Toggling it false->true resets every user's `phoneVerified` and clears
+         * rate-limit state via the `resetOtpVerification` job — a verification that
+         * happened while the gate was off was not a verification.
+         *
+         * Was `featureFlags.smsVerification`. It is a real setting with real cost
+         * and a real side effect, which is why it survived that group's deletion.
+         */
+        smsVerification?: boolean;
+        /**
+         * Lets an admin place an order skipping OTP and payment capture.
+         *
+         * Kept as a SETTING rather than folded into the `admin:checkout:bypass`
+         * permission, and the distinction matters: admins bypass every permission
+         * check (`isEffectiveAdminUser`), so a permission alone would turn this on
+         * for every admin the moment it shipped. Two independent gates — the
+         * permission decides WHO may use it, this decides WHETHER it is available
+         * at all — preserve the default-off posture a checkout bypass needs.
+         *
+         * Writable only through `/api/admin/checkout-bypass`, which logs actorUid
+         * and reason on every use (audit-checkout-bypass rule 1).
+         */
+        adminCheckoutBypass?: boolean;
     };
     /** Site-wide EMI (installment) settings. A seller must ALSO have `StoreDocument.emiEnabled` on for EMI to appear at checkout for their items. */
     emi: {
@@ -501,44 +479,28 @@ export interface SiteSettingsDocument extends BaseDocument {
         icon: string;
         enabled: boolean;
     }[];
-    featureFlags: {
-        chats: boolean;
-        smsVerification: boolean;
-        translations: boolean;
-        wishlists: boolean;
-        auctions: boolean;
-        reviews: boolean;
-        events: boolean;
-        blog: boolean;
-        coupons: boolean;
-        notifications: boolean;
-        sellerRegistration: boolean;
-        preOrders: boolean;
-        /**
-         * Buyer price negotiation (Make an Offer / counter-offer).
-         *
-         * The global kill switch. Per-listing opt-in still applies on top of it via
-         * `ProductDocument.allowOffers`, and only certain listing types support
-         * offers at all (`LISTING_TYPE_CAPABILITIES.canMakeOffer`) — a product needs
-         * all three to show the CTA.
-         *
-         * Guards NEW offers only. Switching it off must not strand in-flight ones:
-         * sellers keep responding, buyers keep checking out accepted offers, and
-         * both dashboards stay reachable.
-         */
-        offers: boolean;
-        /** When true, admin users see a bypass button in checkout that skips OTP and payment. Server-enforced. */
-        adminCheckoutBypass?: boolean;
-        listingTypes?: {
-            standard?: boolean;
-            auction?: boolean;
-            "pre-order"?: boolean;
-            "prize-draw"?: boolean;
-            bundle?: boolean;
-            classified?: boolean;
-            "digital-code"?: boolean;
-            live?: boolean;
-        };
+    /**
+     * Which listing and category types the marketplace offers.
+     *
+     * 🛑 This is a PRODUCT CONTROL, not a feature flag. It was
+     * `featureFlags.listingTypes` / `.categoryTypes` until 2026-08-29, when the
+     * `featureFlags` group was deleted: 11 of its 14 keys had zero readers, and
+     * the survivors were not flags at all. A flag is a temporary switch around
+     * unfinished work; "we don't sell live animals" is a standing decision about
+     * the catalogue, and it belongs somewhere an admin can find it.
+     *
+     * Disabled types are hidden from every listing surface and rejected on
+     * create/add-to-cart via `isListingTypeEnabled` / `isCategoryTypeEnabled`.
+     *
+     * ⚠️ `listingTypes` is DELIBERATELY optional-per-key and absent-means-enabled.
+     * `ALL_LISTING_TYPES_MAP` (`_internal/shared/listing-types/feature-flags.ts`)
+     * is the `Record<ListingType, true>` that makes omitting a union member a
+     * compile error — this interface is not, and historically drifted: it still
+     * listed 8 types after the union reached 10 (`art` and `stickers` missing),
+     * which is Root Cause #58's shape. Add new types to that Record, not here.
+     */
+    listings?: {
+        listingTypes?: Partial<Record<string, boolean>>;
         categoryTypes?: {
             category?: boolean;
             sublisting?: boolean;
@@ -693,14 +655,6 @@ export interface SiteSettingsDocument extends BaseDocument {
      */
     notificationChannels?: NotificationChannelConfig;
 }
-export type FeatureFlagKey = keyof SiteSettingsDocument["featureFlags"];
-export interface FeatureFlagMeta {
-    key: FeatureFlagKey;
-    labelKey: string;
-    descKey: string;
-    icon: string;
-    category: "platform" | "payment";
-}
 export declare const SITE_SETTINGS_COLLECTION: "siteSettings";
 export declare const SITE_SETTINGS_INDEXED_FIELDS: readonly [];
 /**
@@ -714,4 +668,3 @@ export declare const DEFAULT_SITE_SETTINGS_DATA: Partial<SiteSettingsDocument>;
 export declare const SITE_SETTINGS_PUBLIC_FIELDS: readonly ["siteName", "motto", "logo", "background", "contact.email", "contact.phone", "payment", "commissions", "socialLinks", "seo", "features", "featureFlags", "faq.variables", "announcementBar"];
 export type SiteSettingsUpdateInput = Partial<Omit<SiteSettingsDocument, "id" | "createdAt" | "updatedAt">>;
 export declare const DEFAULT_TRUST_BAR_ITEMS: TrustBarItem[];
-export declare const FEATURE_FLAG_META: FeatureFlagMeta[];