@mohasinac/appkit 4.17.0 → 4.19.0

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

@@ -0,0 +1,141 @@
+/*
+ * WHY: A cluster of admin editors rendered `<Form>` with no schema. Two of
+ *      them write PII, and one changes a store's standing on the platform.
+ *
+ *      `AdminAddressEditorView` is the PII one: `fullName`, `phone` and the
+ *      address lines are all encrypted at rest, and none was checked — a
+ *      postal code could be any string, and `ownerId` (which decides WHOSE
+ *      address this is) was free text.
+ *
+ *      `AdminStoreEditorView` sets `storeStatus`, `isVerified`, `isFeatured`
+ *      and `capabilities`. Recurrent Root Cause #38 lived here: saving any
+ *      field re-sent every other one, so an unrelated edit could silently
+ *      un-verify a store.
+ *
+ * WHAT: One schema per editor.
+ *
+ * EXPORTS:
+ *   adminAddressFormSchema, adminStoreUpdateSchema, announcementBarSchema,
+ *   and their inferred value types
+ *
+ * @tag domain:admin
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:AdminAddressEditorView,AdminStoreEditorView,AdminSiteView
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta";
+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.
+ *
+ * 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.
+ */
+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.
+ *
+ * `suspensionReason` is required when — and only when — the status is
+ * `suspended`: suspending a seller without a recorded reason leaves them, and
+ * the next admin, with nothing to appeal or review.
+ */
+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",
+    }),
+    isVerified: annotate(z.boolean().optional(), {
+        section: "standing", order: 2, row: "quarter",
+    }),
+    isFeatured: annotate(z.boolean().optional(), {
+        section: "standing", order: 3, row: "quarter",
+    }),
+    suspensionReason: annotate(z.string().trim().max(500).optional(), {
+        section: "standing", order: 4, row: "full", kind: "textarea",
+    }),
+    capabilities: annotate(z.array(z.string().min(1)).max(50).optional(), {
+        section: "capabilities", sectionLabel: "Capabilities", order: 1, row: "full", kind: "list",
+    }),
+    adminNotes: annotate(z.string().trim().max(2000).optional(), {
+        section: "capabilities", order: 2, row: "full", kind: "textarea",
+        help: "Internal only — never shown to the store owner or the public.",
+    }),
+})
+    .superRefine((v, ctx) => {
+    if (v.storeStatus === "suspended" && !v.suspensionReason?.trim()) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["suspensionReason"],
+            message: "Record why this store is being suspended.",
+        });
+    }
+});
+/**
+ * The homepage announcement bar.
+ *
+ * 🛑 `message` is the canonical key. The main admin editor saved this copy
+ * under `text` until 2026-08-24 — a key no renderer has ever read — so
+ * admin-authored announcements saved successfully and never appeared. Naming
+ * it here is what stops that recurring.
+ */
+export const announcementBarSchema = z.object({
+    message: annotate(z.string().trim().max(300, "Keep the announcement under 300 characters.").optional(), {
+        section: "announcement", sectionLabel: "Announcement bar", sectionRequired: true,
+        quick: true, order: 1, row: "full",
+    }),
+    enabled: annotate(z.boolean().optional(), {
+        section: "announcement", order: 2, row: "quarter",
+    }),
+    link: annotate(z.string().trim().max(300).optional(), {
+        section: "announcement", order: 3, row: "full",
+    }),
+});

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

@@ -0,0 +1,123 @@
+import { z } from "zod";
+export declare const adminOrderUpdateSchema: z.ZodObject<{
+    status: z.ZodEnum<[string, ...string[]]>;
+    trackingNumber: z.ZodOptional<z.ZodString>;
+    carrier: z.ZodOptional<z.ZodString>;
+    refundAmount: z.ZodOptional<z.ZodNumber>;
+    notes: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: string;
+    notes?: string | undefined;
+    trackingNumber?: string | undefined;
+    refundAmount?: number | undefined;
+    carrier?: string | undefined;
+}, {
+    status: string;
+    notes?: string | undefined;
+    trackingNumber?: string | undefined;
+    refundAmount?: number | undefined;
+    carrier?: string | undefined;
+}>;
+export type AdminOrderUpdateValues = z.infer<typeof adminOrderUpdateSchema>;
+/** Inviting a team member — an email plus the permissions it grants. */
+export declare const employeeInviteSchema: z.ZodObject<{
+    email: z.ZodString;
+    permissionGroup: z.ZodString;
+    permissions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    email: string;
+    permissionGroup: string;
+    permissions?: string[] | undefined;
+}, {
+    email: string;
+    permissionGroup: string;
+    permissions?: string[] | undefined;
+}>;
+export type EmployeeInviteValues = z.infer<typeof employeeInviteSchema>;
+/**
+ * The reason recorded against a hard ban.
+ *
+ * A hard ban runs an eight-stage destructive cascade; this string is the only
+ * durable record of why. A 10-character floor, matching the admin offer-cancel
+ * reason, because "spam" is not an audit trail.
+ */
+export declare const hardBanReasonSchema: z.ZodObject<{
+    reason: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    reason: string;
+}, {
+    reason: string;
+}>;
+export type HardBanReasonValues = z.infer<typeof hardBanReasonSchema>;
+/**
+ * Feature flags.
+ *
+ * Deliberately open records: flags are added and removed constantly, and a
+ * closed schema here would silently STRIP a newly-added flag on the next save
+ * — the `productBaseSchema` failure applied to configuration. The values are
+ * still constrained, which is what stops a flag being set to an object.
+ */
+export declare const featureFlagsUpdateSchema: z.ZodObject<{
+    flags: z.ZodRecord<z.ZodString, z.ZodBoolean>;
+    rollouts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    flags: Record<string, boolean>;
+    rollouts?: Record<string, number> | undefined;
+}, {
+    flags: Record<string, boolean>;
+    rollouts?: Record<string, number> | undefined;
+}>;
+export type FeatureFlagsUpdateValues = z.infer<typeof featureFlagsUpdateSchema>;
+/** An ad placement. `priority` orders competing ads in the same slot. */
+export declare const adminAdFormSchema: z.ZodEffects<z.ZodObject<{
+    name: z.ZodString;
+    provider: z.ZodEnum<["manual", "adsense", "thirdParty"]>;
+    status: z.ZodEnum<["draft", "active", "scheduled", "paused"]>;
+    priority: z.ZodNumber;
+    placementIds: z.ZodArray<z.ZodString, "many">;
+    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>>>;
+}, "strip", z.ZodTypeAny, {
+    status: "draft" | "active" | "scheduled" | "paused";
+    name: string;
+    priority: number;
+    provider: "manual" | "adsense" | "thirdParty";
+    placementIds: string[];
+    requiresConsent: boolean;
+    startAt?: string | undefined;
+    endAt?: string | undefined;
+    creative?: Record<string, import("../../..").FirestoreValue> | undefined;
+}, {
+    status: "draft" | "active" | "scheduled" | "paused";
+    name: string;
+    priority: number;
+    provider: "manual" | "adsense" | "thirdParty";
+    placementIds: string[];
+    requiresConsent: boolean;
+    startAt?: string | undefined;
+    endAt?: string | undefined;
+    creative?: Record<string, import("../../..").FirestoreValue> | undefined;
+}>, {
+    status: "draft" | "active" | "scheduled" | "paused";
+    name: string;
+    priority: number;
+    provider: "manual" | "adsense" | "thirdParty";
+    placementIds: string[];
+    requiresConsent: boolean;
+    startAt?: string | undefined;
+    endAt?: string | undefined;
+    creative?: Record<string, import("../../..").FirestoreValue> | undefined;
+}, {
+    status: "draft" | "active" | "scheduled" | "paused";
+    name: string;
+    priority: number;
+    provider: "manual" | "adsense" | "thirdParty";
+    placementIds: string[];
+    requiresConsent: boolean;
+    startAt?: string | undefined;
+    endAt?: string | undefined;
+    creative?: Record<string, import("../../..").FirestoreValue> | undefined;
+}>;
+export type AdminAdFormValues = z.infer<typeof adminAdFormSchema>;

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

@@ -0,0 +1,147 @@
+/*
+ * WHY: Four more admin editors rendered `<Form>` with no schema. Each writes
+ *      something an admin cannot easily undo.
+ *
+ *      `AdminOrderEditorView` is the one that touches money: `refundAmount`
+ *      was parsed with a bare `parseFloat` and guarded only by
+ *      `!isNaN(amount) && amount > 0`, with no upper bound and no check
+ *      against the order — so a mistyped figure went straight through as a
+ *      refund instruction.
+ *
+ *      `AdminEmployeeEditorView` grants permissions, and `AdminUsersView`'s
+ *      hard-ban takes a reason that is the entire record of why an account
+ *      was destroyed.
+ *
+ * WHAT: One schema per editor.
+ *
+ * EXPORTS:
+ *   adminOrderUpdateSchema, employeeInviteSchema, hardBanReasonSchema,
+ *   featureFlagsUpdateSchema, adminAdFormSchema, and their value types
+ *
+ * @tag domain:admin
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:AdminOrderEditorView,AdminEmployeeEditorView,AdminUsersView,AdminFeatureFlagsView,AdminAdEditorView
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta";
+import { firestoreValueSchema } from "../../../schemas/firestore-value";
+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",
+    }),
+    trackingNumber: annotate(z.string().trim().max(120).optional(), {
+        section: "shipping", sectionLabel: "Shipping", order: 1, row: "pair",
+    }),
+    carrier: annotate(z.string().trim().max(80).optional(), {
+        section: "shipping", order: 2, row: "pair",
+    }),
+    /*
+     * 🛑 Bounded. This was `parseFloat` + `> 0` with no ceiling, so a slipped
+     * decimal point issued a refund an order of magnitude too large. The cap is
+     * a sanity bound, not a business rule — the route still checks the amount
+     * against the order itself.
+     */
+    refundAmount: annotate(z.coerce
+        .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" }),
+    notes: annotate(z.string().trim().max(2000).optional(), {
+        section: "shipping", order: 4, row: "full", kind: "textarea",
+    }),
+});
+/** Inviting a team member — an email plus the permissions it grants. */
+export const employeeInviteSchema = z.object({
+    email: annotate(z.string().trim().toLowerCase().min(1, "An email address is required.").email("That doesn't look like an email address."), { section: "member", sectionLabel: "Team member", sectionRequired: true, quick: true, order: 1, row: "pair" }),
+    permissionGroup: annotate(z.string().trim().min(1, "Choose a permission group."), {
+        section: "member", quick: true, order: 2, row: "pair",
+    }),
+    permissions: annotate(z.array(z.string().min(1)).max(200).optional(), {
+        section: "member", order: 3, row: "full", kind: "list",
+    }),
+});
+/**
+ * The reason recorded against a hard ban.
+ *
+ * A hard ban runs an eight-stage destructive cascade; this string is the only
+ * durable record of why. A 10-character floor, matching the admin offer-cancel
+ * reason, because "spam" is not an audit trail.
+ */
+export const hardBanReasonSchema = z.object({
+    reason: annotate(z.string().trim().min(10, "Record why this account is being banned — at least 10 characters.").max(500), { section: "ban", sectionLabel: "Reason", sectionRequired: true, quick: true, order: 1, row: "full", kind: "textarea" }),
+});
+/**
+ * Feature flags.
+ *
+ * Deliberately open records: flags are added and removed constantly, and a
+ * closed schema here would silently STRIP a newly-added flag on the next save
+ * — the `productBaseSchema` failure applied to configuration. The values are
+ * still constrained, which is what stops a flag being set to an object.
+ */
+export const featureFlagsUpdateSchema = z.object({
+    flags: annotate(z.record(z.string(), z.boolean()), {
+        section: "flags", sectionLabel: "Feature flags", sectionRequired: true, order: 1, row: "full", kind: "list",
+    }),
+    rollouts: annotate(z.record(z.string(), z.coerce.number().min(0).max(100)).optional(), {
+        section: "flags", order: 2, row: "full", kind: "list",
+        help: "Percentage rollout per flag, 0–100.",
+    }),
+});
+/** An ad placement. `priority` orders competing ads in the same slot. */
+export const adminAdFormSchema = z
+    .object({
+    name: annotate(z.string().trim().min(2, "Give the ad a name.").max(120), {
+        section: "basics", sectionLabel: "Ad", sectionRequired: true, quick: true, order: 1, row: "pair",
+    }),
+    provider: annotate(z.enum(["manual", "adsense", "thirdParty"]), {
+        section: "basics", quick: true, order: 2, row: "pair",
+    }),
+    status: annotate(z.enum(["draft", "active", "scheduled", "paused"]), {
+        section: "basics", quick: true, order: 3, row: "pair",
+    }),
+    priority: annotate(z.coerce.number().int().min(0).max(1000), {
+        section: "basics", order: 4, row: "pair", kind: "number",
+    }),
+    placementIds: annotate(z.array(z.string().min(1)).min(1, "Choose at least one placement."), {
+        section: "placement", sectionLabel: "Placement", sectionRequired: true, order: 1, row: "full", kind: "list",
+    }),
+    requiresConsent: annotate(z.boolean(), {
+        section: "placement", order: 2, row: "quarter",
+    }),
+    startAt: annotate(z.string().optional(), {
+        section: "schedule", sectionLabel: "Schedule", order: 1, row: "pair", kind: "date",
+    }),
+    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",
+    }),
+})
+    .superRefine((v, ctx) => {
+    // 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.",
+        });
+    }
+    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.",
+        });
+    }
+});

package/dist/features/admin/schemas/admin-user-form.d.ts

@@ -0,0 +1,82 @@
+import { z } from "zod";
+export declare const adminUserUpdateSchema: z.ZodObject<{
+    displayName: z.ZodOptional<z.ZodString>;
+    phoneNumber: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    isTester: z.ZodOptional<z.ZodBoolean>;
+    canTestAdmin: z.ZodOptional<z.ZodBoolean>;
+    adminNotes: z.ZodOptional<z.ZodString>;
+    publicProfile: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<import("../../..").FirestoreValue, z.ZodTypeDef, import("../../..").FirestoreValue>>>;
+}, "strip", z.ZodTypeAny, {
+    displayName?: string | undefined;
+    adminNotes?: string | undefined;
+    phoneNumber?: string | undefined;
+    isTester?: boolean | undefined;
+    canTestAdmin?: boolean | undefined;
+    publicProfile?: Record<string, import("../../..").FirestoreValue> | undefined;
+}, {
+    displayName?: string | undefined;
+    adminNotes?: string | undefined;
+    phoneNumber?: string | undefined;
+    isTester?: boolean | undefined;
+    canTestAdmin?: boolean | undefined;
+    publicProfile?: Record<string, import("../../..").FirestoreValue> | undefined;
+}>;
+export type AdminUserUpdateValues = z.infer<typeof adminUserUpdateSchema>;
+/**
+ * A store's WhatsApp Business connection.
+ *
+ * `accessToken` is optional because the form shows a masked placeholder and
+ * only sends the field when the seller types a NEW value — so "absent" means
+ * "unchanged", not "clear it". The `.min(20)` therefore applies only to a real
+ * replacement, and is there because a truncated token fails silently at sync
+ * time rather than on save.
+ */
+export declare const whatsappSettingsSchema: z.ZodObject<{
+    catalogSyncEnabled: z.ZodBoolean;
+    phoneNumber: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    wabaId: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    catalogId: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    accessToken: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+}, "strip", z.ZodTypeAny, {
+    catalogSyncEnabled: boolean;
+    phoneNumber?: string | undefined;
+    accessToken?: string | undefined;
+    wabaId?: string | undefined;
+    catalogId?: string | undefined;
+}, {
+    catalogSyncEnabled: boolean;
+    phoneNumber?: string | undefined;
+    accessToken?: string | undefined;
+    wabaId?: string | undefined;
+    catalogId?: string | undefined;
+}>;
+export type WhatsappSettingsValues = z.infer<typeof whatsappSettingsSchema>;
+/**
+ * A buyer's lottery entry.
+ *
+ * `purchasedItemNumber` was `parseInt(itemNumber, 10)` — `NaN` for anything
+ * non-numeric — and `paymentTime` was `new Date(...)`, which yields
+ * `Invalid Date` and then throws on `.toISOString()`. Both are coerced and
+ * checked here so the failure is an inline message rather than a crash or a
+ * `NaN` written to the entry.
+ */
+export declare const lotteryPullSchema: z.ZodObject<{
+    sourceType: z.ZodEnum<["event", "product"]>;
+    transactionId: z.ZodString;
+    paymentTime: z.ZodEffects<z.ZodString, string, string>;
+    purchasedItemNumber: z.ZodNumber;
+    userPhone: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+}, "strip", z.ZodTypeAny, {
+    transactionId: string;
+    sourceType: "event" | "product";
+    paymentTime: string;
+    purchasedItemNumber: number;
+    userPhone?: string | undefined;
+}, {
+    transactionId: string;
+    sourceType: "event" | "product";
+    paymentTime: string;
+    purchasedItemNumber: number;
+    userPhone?: string | undefined;
+}>;
+export type LotteryPullValues = z.infer<typeof lotteryPullSchema>;

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

@@ -0,0 +1,102 @@
+/*
+ * WHY: Three more forms, each writing something with a blast radius.
+ *
+ *      `AdminUserEditorView` edits another person's account — `displayName`
+ *      and `phoneNumber` are PII, encrypted at rest, and neither was checked.
+ *      `isTester`/`canTestAdmin` are the flags Recurrent Root Cause #38 was
+ *      about: the list endpoint dropped them, the editor defaulted them to
+ *      false, and saving any unrelated field silently stripped a real
+ *      tester's access.
+ *
+ *      `SellerWhatsAppSettingsView` writes `accessToken` — a live Meta
+ *      credential — plus the WABA and catalog ids the sync runs against. A
+ *      malformed id there fails at sync time, hours later, with no obvious
+ *      cause.
+ *
+ *      `LotteryPullForm` is a buyer-facing entry: a transaction id, a payment
+ *      time and an item number, all parsed with a bare `parseInt` and a `new
+ *      Date(...)` that yields `Invalid Date` on anything unparseable.
+ *
+ * EXPORTS:
+ *   adminUserUpdateSchema, whatsappSettingsSchema, lotteryPullSchema,
+ *   and their inferred value types
+ *
+ * @tag domain:admin,whatsapp,lottery
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:AdminUserEditorView,SellerWhatsAppSettingsView,LotteryPullForm
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta";
+import { firestoreValueSchema } from "../../../schemas/firestore-value";
+const PHONE_RE = /^(\+?91[-\s]?)?[6-9]\d{9}$/;
+export const adminUserUpdateSchema = z.object({
+    displayName: annotate(z.string().trim().min(1).max(120).optional(), {
+        section: "profile", sectionLabel: "Profile", sectionRequired: true, quick: true, order: 1, row: "pair",
+    }),
+    phoneNumber: annotate(z.string().trim().regex(PHONE_RE, "Enter a 10-digit Indian mobile number.").optional().or(z.literal("")), { section: "profile", order: 2, row: "pair" }),
+    /*
+     * The tester flags. Kept OPTIONAL rather than defaulted, deliberately: a
+     * PATCH that omits them must leave them alone. Defaulting either to `false`
+     * here would reproduce Root Cause #38 in the schema layer — the editor
+     * already did exactly that from the list row.
+     */
+    isTester: annotate(z.boolean().optional(), {
+        section: "access", sectionLabel: "Access", order: 1, row: "quarter",
+    }),
+    canTestAdmin: annotate(z.boolean().optional(), {
+        section: "access", order: 2, row: "quarter",
+    }),
+    adminNotes: annotate(z.string().trim().max(2000).optional(), {
+        section: "access", order: 3, row: "full", kind: "textarea",
+        help: "Internal only — never shown to the user.",
+    }),
+    // Open: the public profile carries per-user social links and bio fields that
+    // are added over time, and a closed shape would strip a newly-added one.
+    publicProfile: annotate(z.record(firestoreValueSchema).optional(), {
+        section: "access", order: 4, row: "full", kind: "list",
+    }),
+});
+/**
+ * A store's WhatsApp Business connection.
+ *
+ * `accessToken` is optional because the form shows a masked placeholder and
+ * only sends the field when the seller types a NEW value — so "absent" means
+ * "unchanged", not "clear it". The `.min(20)` therefore applies only to a real
+ * replacement, and is there because a truncated token fails silently at sync
+ * time rather than on save.
+ */
+export const whatsappSettingsSchema = z.object({
+    catalogSyncEnabled: annotate(z.boolean(), {
+        section: "sync", sectionLabel: "Catalog sync", sectionRequired: true, quick: true, order: 1, row: "quarter",
+    }),
+    phoneNumber: annotate(z.string().trim().regex(PHONE_RE, "Enter the 10-digit WhatsApp Business number.").optional().or(z.literal("")), { section: "connection", sectionLabel: "Connection", order: 1, row: "pair" }),
+    // Meta ids are numeric strings; a pasted URL or a stray space is the usual
+    // mistake and produces a sync that never runs.
+    wabaId: annotate(z.string().trim().regex(/^\d{5,32}$/, "A WABA ID is a numeric id, not a URL.").optional().or(z.literal("")), { section: "connection", order: 2, row: "pair" }),
+    catalogId: annotate(z.string().trim().regex(/^\d{5,32}$/, "A catalog ID is a numeric id, not a URL.").optional().or(z.literal("")), { section: "connection", order: 3, row: "pair" }),
+    accessToken: annotate(z.string().trim().min(20, "That access token looks truncated.").optional().or(z.literal("")), { section: "connection", order: 4, row: "full", help: "Leave blank to keep the current token." }),
+});
+/**
+ * A buyer's lottery entry.
+ *
+ * `purchasedItemNumber` was `parseInt(itemNumber, 10)` — `NaN` for anything
+ * non-numeric — and `paymentTime` was `new Date(...)`, which yields
+ * `Invalid Date` and then throws on `.toISOString()`. Both are coerced and
+ * checked here so the failure is an inline message rather than a crash or a
+ * `NaN` written to the entry.
+ */
+export const lotteryPullSchema = z.object({
+    sourceType: annotate(z.enum(["event", "product"]), {
+        section: "entry", sectionLabel: "Entry", sectionRequired: true, quick: true, order: 1, row: "pair",
+    }),
+    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" }),
+    purchasedItemNumber: annotate(z.coerce
+        .number({ invalid_type_error: "Enter the slot number you bought." })
+        .int("A slot number is a whole number.")
+        .min(1, "Slot numbers start at 1."), { section: "entry", quick: true, order: 4, row: "pair", kind: "number" }),
+    userPhone: annotate(z.string().trim().regex(PHONE_RE, "Enter a 10-digit Indian mobile number.").optional().or(z.literal("")), { section: "entry", order: 5, row: "pair" }),
+});