@mohasinac/appkit 4.71.0 → 4.72.0

package/dist/features/giveaway/schemas/config-write.d.ts

@@ -0,0 +1,145 @@
+import { z } from "zod";
+import type { GiveawayConfig } from "../types/index";
+/**
+ * What an admin may say about one slot. Booking state is deliberately absent
+ * — see the header. `.strict()`, so `isBooked` is a 400.
+ */
+export declare const giveawaySlotWriteSchema: z.ZodObject<{
+    slotNumber: z.ZodNumber;
+    name: z.ZodString;
+    image: z.ZodOptional<z.ZodString>;
+    price: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    price: number;
+    name: string;
+    slotNumber: number;
+    image?: string | undefined;
+}, {
+    price: number;
+    name: string;
+    slotNumber: number;
+    image?: string | undefined;
+}>;
+/**
+ * 🛑 `annotate()` must be the OUTERMOST call on each field — it keys a WeakMap
+ * by schema instance and every zod wrapper returns a new one.
+ */
+export declare const giveawayConfigWriteSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
+    pricingMode: z.ZodEnum<["uniform", "variable"]>;
+    uniformPrice: z.ZodOptional<z.ZodNumber>;
+    drawWindowDurationMinutes: z.ZodNumber;
+    maxPullsPerTransaction: z.ZodNumber;
+    maxPullsPerUser: z.ZodNumber;
+    slots: z.ZodArray<z.ZodObject<{
+        slotNumber: z.ZodNumber;
+        name: z.ZodString;
+        image: z.ZodOptional<z.ZodString>;
+        price: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        price: number;
+        name: string;
+        slotNumber: number;
+        image?: string | undefined;
+    }, {
+        price: number;
+        name: string;
+        slotNumber: number;
+        image?: string | undefined;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    slots: {
+        price: number;
+        name: string;
+        slotNumber: number;
+        image?: string | undefined;
+    }[];
+    pricingMode: "uniform" | "variable";
+    drawWindowDurationMinutes: number;
+    maxPullsPerTransaction: number;
+    maxPullsPerUser: number;
+    uniformPrice?: number | undefined;
+}, {
+    slots: {
+        price: number;
+        name: string;
+        slotNumber: number;
+        image?: string | undefined;
+    }[];
+    pricingMode: "uniform" | "variable";
+    drawWindowDurationMinutes: number;
+    maxPullsPerTransaction: number;
+    maxPullsPerUser: number;
+    uniformPrice?: number | undefined;
+}>, {
+    slots: {
+        price: number;
+        name: string;
+        slotNumber: number;
+        image?: string | undefined;
+    }[];
+    pricingMode: "uniform" | "variable";
+    drawWindowDurationMinutes: number;
+    maxPullsPerTransaction: number;
+    maxPullsPerUser: number;
+    uniformPrice?: number | undefined;
+}, {
+    slots: {
+        price: number;
+        name: string;
+        slotNumber: number;
+        image?: string | undefined;
+    }[];
+    pricingMode: "uniform" | "variable";
+    drawWindowDurationMinutes: number;
+    maxPullsPerTransaction: number;
+    maxPullsPerUser: number;
+    uniformPrice?: number | undefined;
+}>, {
+    slots: {
+        price: number;
+        name: string;
+        slotNumber: number;
+        image?: string | undefined;
+    }[];
+    pricingMode: "uniform" | "variable";
+    drawWindowDurationMinutes: number;
+    maxPullsPerTransaction: number;
+    maxPullsPerUser: number;
+    uniformPrice?: number | undefined;
+}, {
+    slots: {
+        price: number;
+        name: string;
+        slotNumber: number;
+        image?: string | undefined;
+    }[];
+    pricingMode: "uniform" | "variable";
+    drawWindowDurationMinutes: number;
+    maxPullsPerTransaction: number;
+    maxPullsPerUser: number;
+    uniformPrice?: number | undefined;
+}>;
+export type GiveawayConfigWriteInput = z.infer<typeof giveawayConfigWriteSchema>;
+/** Why a merge was refused. Distinct from a validation failure. */
+export interface GiveawayMergeRejection {
+    ok: false;
+    code: "BOOKED_SLOT_REMOVED";
+    message: string;
+    slotNumbers: number[];
+}
+export type GiveawayMergeResult = {
+    ok: true;
+    config: GiveawayConfig;
+} | GiveawayMergeRejection;
+/**
+ * Apply an admin's edit to the stored config, carrying every booking across.
+ *
+ * `existing` is undefined when the giveaway is being created, in which case
+ * there is nothing to preserve and every slot starts unbooked.
+ *
+ * `totalSlots` is DERIVED from `slots.length` and never accepted from input —
+ * a caller-supplied count that disagrees with the array is exactly the
+ * mirror-drift trap (Root Cause #42), and `totalSlots` is what the fullness
+ * check reads.
+ */
+export declare function mergeGiveawayConfig(input: GiveawayConfigWriteInput, existing?: GiveawayConfig): GiveawayMergeResult;

package/dist/features/giveaway/schemas/config-write.js

@@ -0,0 +1,199 @@
+/*
+ * WHY: `giveawayConfig` had NO write schema. The only authoring UI
+ *      (`GiveawayAdminEditView`) was orphaned, and the route it would have
+ *      posted to — `PATCH /api/admin/events/[id]` — is `.passthrough()`, so
+ *      the whole config wrote through completely unvalidated.
+ * WHAT: The write contract, plus `mergeGiveawayConfig` — the one function that
+ *       is allowed to turn an admin's edit into a stored config.
+ *
+ * ## 🛑 The author-side slot shape CANNOT carry booking state
+ *
+ * `GiveawayAdminEditView.handleSubmit` sent `isBooked: false` and `weight: 0`
+ * for every slot, and dropped `bookedByUserId` / `bookedByDisplayName` /
+ * `bookedByUserGiveawayNumber` entirely. Against a `.passthrough()` PATCH that
+ * is not a validation gap — it is a **destructive write**: the first save of
+ * a live giveaway marks every purchased slot as available again, and the
+ * buyers who paid for them are simply gone from the record.
+ *
+ * So the input type deliberately has NO booking fields at all. An admin
+ * editing a giveaway is describing PRIZES, not attendance, and the schema
+ * refuses to express the latter — a `.strict()` object, so sending
+ * `isBooked` is a 400 rather than something a merge has to defend against.
+ *
+ * `weight` is absent for the same reason: it is derived from price
+ * server-side and is never client input.
+ *
+ * ## One schema, not two
+ *
+ * There was a second one — `giveawayConfigFormSchema`, in
+ * `_internal/shared/features/giveaway/config-form.ts`. `GiveawayAdminEditView`
+ * passed THAT to `<Form>` and parsed THIS in its submit handler, so the form
+ * schema's rules (the duplicate-slot check, the free-giveaway check) had never
+ * once executed. It was deleted 2026-08-30 and its annotations moved here:
+ * `annotate()` keys a WeakMap by schema instance and the server ignores the
+ * registry entirely, so carrying layout metadata on the write contract costs
+ * the route nothing and removes the opportunity for the two to disagree.
+ *
+ * ## Merging is BY `slotNumber`, not by index
+ *
+ * Array position is not identity. An admin who deletes slot 3 shifts every
+ * later slot's index by one, and an index-wise merge would hand slot 7's
+ * buyer the prize that used to be slot 8. `slotNumber` is the stable key
+ * users actually see and pull against.
+ *
+ * A slot that is booked cannot be REMOVED either. Dropping it would erase a
+ * paid entry with no trace; the merge rejects that rather than silently
+ * carrying the slot along, because an admin who thinks they deleted a prize
+ * and did not is a worse outcome than an error.
+ *
+ * EXPORTS: giveawayConfigWriteSchema, giveawaySlotWriteSchema,
+ *          mergeGiveawayConfig, type GiveawayConfigWriteInput
+ *
+ * @tag domain:giveaway
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:/api/admin/events/[id]/giveaway-config,GiveawayAdminEditView
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta.js";
+/** Mirrors `GiveawayPricingMode`. */
+const pricingModeSchema = z.enum(["uniform", "variable"]);
+/**
+ * What an admin may say about one slot. Booking state is deliberately absent
+ * — see the header. `.strict()`, so `isBooked` is a 400.
+ */
+export const giveawaySlotWriteSchema = z
+    .object({
+    slotNumber: z.coerce.number().int().min(1).max(200),
+    name: z.string().min(1, "Every slot needs a prize name.").max(200),
+    image: z.string().max(2000).optional(),
+    price: z.coerce.number().min(0, "A price cannot be negative."),
+})
+    .strict();
+/**
+ * 🛑 `annotate()` must be the OUTERMOST call on each field — it keys a WeakMap
+ * by schema instance and every zod wrapper returns a new one.
+ */
+export const giveawayConfigWriteSchema = z
+    .object({
+    pricingMode: annotate(pricingModeSchema, {
+        section: "pricing", sectionLabel: "Pricing", sectionRequired: true,
+        quick: true, order: 1, row: "pair", label: "Pricing mode",
+    }),
+    /*
+     * Hidden under variable pricing, and therefore not sent — `visibleValues`
+     * drops it, and the refine below only demands it in uniform mode. The two
+     * halves have to agree or a hidden field fails validation invisibly.
+     */
+    uniformPrice: annotate(z.coerce.number().min(0).optional(), {
+        section: "pricing", order: 2, row: "pair", kind: "number",
+        label: "Price per slot (₹)",
+        when: (v) => v.pricingMode === "uniform",
+    }),
+    drawWindowDurationMinutes: annotate(z.coerce.number().int().min(1).max(1440), {
+        section: "limits", sectionLabel: "Draw rules", order: 1, row: "third",
+        kind: "number", label: "Draw window (minutes)",
+        help: "How long a buyer has to complete a pull once it starts.",
+    }),
+    maxPullsPerTransaction: annotate(z.coerce.number().int().min(1).max(200), {
+        section: "limits", order: 2, row: "third", kind: "number",
+        label: "Max pulls per transaction",
+    }),
+    maxPullsPerUser: annotate(z.coerce.number().int().min(1).max(200), {
+        section: "limits", order: 3, row: "third", kind: "number",
+        label: "Max pulls per user",
+    }),
+    slots: annotate(z
+        .array(giveawaySlotWriteSchema)
+        .min(1, "A giveaway needs at least one slot.")
+        .max(200, "A giveaway cannot exceed 200 slots."), {
+        section: "slots", sectionLabel: "Slots", sectionRequired: true,
+        order: 1, row: "full", kind: "list", label: "Prize slots",
+        /*
+         * The slot table holds uncommitted rows — a name half-typed, an image
+         * URL pasted but not yet saved. `<Collapse>` unmounts its children, so
+         * without this a collapse discards them.
+         */
+        sectionKeepMounted: true,
+    }),
+})
+    .strict()
+    .refine((c) => new Set(c.slots.map((s) => s.slotNumber)).size === c.slots.length, { message: "Two slots share a slot number.", path: ["slots"] })
+    /*
+     * ABOVE zero, not merely present.
+     *
+     * This read `typeof c.uniformPrice === "number"`, so `0` passed — and the
+     * editor's payload builds the value as
+     * `Math.round(parseFloat(uniformPrice) * 100) / 100 || 0`, which turns
+     * "12,00" or "twelve" into exactly that. A typo became a FREE giveaway,
+     * indistinguishable from deliberately pricing one at zero.
+     *
+     * `giveawayConfigFormSchema` has carried the correct `> 0` rule all along and
+     * has never executed: the editor passes it to `<Form>` and parses THIS schema
+     * instead. The rule belongs on the schema that runs.
+     */
+    .refine((c) => c.pricingMode !== "uniform" || (typeof c.uniformPrice === "number" && c.uniformPrice > 0), {
+    message: "Set a slot price above zero, or switch to variable pricing.",
+    path: ["uniformPrice"],
+});
+/**
+ * Apply an admin's edit to the stored config, carrying every booking across.
+ *
+ * `existing` is undefined when the giveaway is being created, in which case
+ * there is nothing to preserve and every slot starts unbooked.
+ *
+ * `totalSlots` is DERIVED from `slots.length` and never accepted from input —
+ * a caller-supplied count that disagrees with the array is exactly the
+ * mirror-drift trap (Root Cause #42), and `totalSlots` is what the fullness
+ * check reads.
+ */
+export function mergeGiveawayConfig(input, existing) {
+    const priorBySlot = new Map();
+    for (const slot of existing?.slots ?? [])
+        priorBySlot.set(slot.slotNumber, slot);
+    const incoming = new Set(input.slots.map((s) => s.slotNumber));
+    const droppedBooked = [...priorBySlot.values()]
+        .filter((s) => s.isBooked && !incoming.has(s.slotNumber))
+        .map((s) => s.slotNumber);
+    if (droppedBooked.length > 0) {
+        return {
+            ok: false,
+            code: "BOOKED_SLOT_REMOVED",
+            message: `Slot ${droppedBooked.join(", ")} has already been pulled and cannot be ` +
+                `removed. Reopen it first if the pull needs to be undone.`,
+            slotNumbers: droppedBooked,
+        };
+    }
+    const slots = input.slots.map((s) => {
+        const prior = priorBySlot.get(s.slotNumber);
+        return {
+            slotNumber: s.slotNumber,
+            name: s.name,
+            image: s.image?.trim() || undefined,
+            price: input.pricingMode === "uniform" ? (input.uniformPrice ?? 0) : s.price,
+            // Server-derived, never input. Recomputed by the pricing pass; carried
+            // from the prior slot so an edit does not zero a live weighting.
+            weight: prior?.weight ?? 0,
+            // 🛑 THE WHOLE POINT: booking state comes from the STORED slot, never
+            // from the request. A slot the admin renames keeps its buyer.
+            isBooked: prior?.isBooked ?? false,
+            bookedByUserId: prior?.bookedByUserId,
+            bookedByDisplayName: prior?.bookedByDisplayName,
+            bookedByUserGiveawayNumber: prior?.bookedByUserGiveawayNumber,
+        };
+    });
+    return {
+        ok: true,
+        config: {
+            slots,
+            totalSlots: slots.length,
+            pricingMode: input.pricingMode,
+            uniformPrice: input.pricingMode === "uniform" ? input.uniformPrice : undefined,
+            drawWindowDurationMinutes: input.drawWindowDurationMinutes,
+            maxPullsPerTransaction: input.maxPullsPerTransaction,
+            maxPullsPerUser: input.maxPullsPerUser,
+        },
+    };
+}

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

@@ -0,0 +1,77 @@
+/**
+ * GiveawayEntry Firestore Document Type & Constants
+ */
+import type { GiveawayEntryStatus } from "../types";
+import type { Encrypted, Plaintext } from "../../../security/encrypted";
+export declare const GIVEAWAY_ENTRIES_COLLECTION: "lotteryEntries";
+/**
+ * The same entry with its PII as plain `string` — what the two named
+ * repository accessors return.
+ *
+ * 🛑 Derived with a mapped type, never hand-written. A second literal listing
+ * the same ~18 fields would drift the first time one was added to only one of
+ * them, and the drift is invisible: both compile, and the one nobody updated
+ * silently drops the new field from every reveal/mask call site.
+ *
+ * It is deliberately NOT distinguishable from a MASKED entry. `maskPii` also
+ * returns plain strings, and a type cannot express "these characters are
+ * asterisks" — the distinction lives in WHICH named method you called, which
+ * is why they are two methods rather than one taking a boolean.
+ */
+export type GiveawayEntryPlain = Plaintext<GiveawayEntryDocument>;
+export type GiveawayEntryDocument = {
+    id: string;
+    sourceType: "event" | "product";
+    /** Set when sourceType === "event" */
+    eventId?: string;
+    /** Set when sourceType === "product" */
+    productId?: string;
+    userId: string;
+    /**
+     * PII — CIPHERTEXT as it sits here.
+     *
+     * 🛑 `Encrypted<string>` is a promise about the VALUE, kept by
+     * `GiveawayEntryRepository` no longer decrypting in `mapDoc`. Branding a field
+     * that is still decrypted on read asserts something false, and `decryptValue`
+     * passes a non-`enc:v1:` string straight through — so the lie would silently
+     * "work" and surface only on the rows that were genuinely encrypted.
+     *
+     * Readers call `giveawayEntryRepository.maskedEntry(doc)` (the UI default) or
+     * `revealEntry(doc)` (opt-in, named, greppable).
+     */
+    userDisplayName?: Encrypted<string>;
+    /** PII — ciphertext at rest; see `userDisplayName` */
+    userEmail?: Encrypted<string>;
+    /** PII — ciphertext at rest; required. See `userDisplayName` */
+    userPhone: Encrypted<string>;
+    /** User-provided external payment TX ID */
+    transactionId: string;
+    /** User-provided time of payment */
+    paymentTime: Date;
+    /** Slot/item number the user submitted for */
+    purchasedItemNumber: number;
+    /** Sequential per source (1, 2, 3…) — assigned atomically */
+    userGiveawayNumber: number;
+    /** Filled after draw — assigned slot number */
+    assignedPrizeSlotNumber?: number;
+    status: GiveawayEntryStatus;
+    isFlagged: boolean;
+    flagNote?: string;
+    flaggedBy?: string;
+    flaggedAt?: Date;
+    submittedAt: Date;
+    drawnAt?: Date;
+};
+export declare const GIVEAWAY_ENTRY_INDEXED_FIELDS: readonly ["sourceType", "eventId", "productId", "userId", "status", "submittedAt", "userGiveawayNumber"];
+/** Canonical field name constants for giveawayEntries collection — use instead of hardcoded strings. */
+export declare const GIVEAWAY_ENTRY_FIELDS: {
+    readonly SOURCE_TYPE: "sourceType";
+    readonly EVENT_ID: "eventId";
+    readonly PRODUCT_ID: "productId";
+    readonly USER_ID: "userId";
+    readonly STATUS: "status";
+    readonly TRANSACTION_ID: "transactionId";
+    readonly SUBMITTED_AT: "submittedAt";
+    readonly USER_GIVEAWAY_NUMBER: "userGiveawayNumber";
+    readonly IS_FLAGGED: "isFlagged";
+};

package/dist/features/giveaway/schemas/firestore.js

@@ -0,0 +1,42 @@
+/**
+ * GiveawayEntry Firestore Document Type & Constants
+ */
+/*
+ * 🛑 BOUNDARY OF THE GIVEAWAY RENAME, deliberately left as-is — the same call
+ * made for the `auctions/` Storage prefix in `AdminMediaView.tsx`.
+ *
+ * The CONSTANT is renamed; the STRING is not. This value names a Firestore
+ * collection that may already hold live documents, and a collection is not
+ * renamed by editing a literal — the documents do not move. Changing it here
+ * would silently point every read and write at a new, empty collection while
+ * the real entries sat unreachable under the old name, which is worse than the
+ * word we are trying to remove.
+ *
+ * Renaming it for real is a data migration: copy forward, dual-read, verify
+ * counts, cut over, delete. Tracked in plan §A19q. Until then every identifier,
+ * type, route, label and file name in this feature says "giveaway", and this
+ * one string is the only place the old vocabulary survives — where no user,
+ * regulator or reviewer ever sees it.
+ */
+export const GIVEAWAY_ENTRIES_COLLECTION = "lotteryEntries";
+export const GIVEAWAY_ENTRY_INDEXED_FIELDS = [
+    "sourceType",
+    "eventId",
+    "productId",
+    "userId",
+    "status",
+    "submittedAt",
+    "userGiveawayNumber",
+];
+/** Canonical field name constants for giveawayEntries collection — use instead of hardcoded strings. */
+export const GIVEAWAY_ENTRY_FIELDS = {
+    SOURCE_TYPE: "sourceType",
+    EVENT_ID: "eventId",
+    PRODUCT_ID: "productId",
+    USER_ID: "userId",
+    STATUS: "status",
+    TRANSACTION_ID: "transactionId",
+    SUBMITTED_AT: "submittedAt",
+    USER_GIVEAWAY_NUMBER: "userGiveawayNumber",
+    IS_FLAGGED: "isFlagged",
+};

package/dist/features/giveaway/schemas/zod.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Zod schemas for giveaway entry submission and validation.
+ */
+import { z } from "zod";
+export declare const giveawayEntrySubmitSchema: z.ZodObject<{
+    transactionId: z.ZodString;
+    paymentTime: z.ZodString;
+    purchasedItemNumber: z.ZodNumber;
+    userPhone: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    transactionId: string;
+    paymentTime: string;
+    purchasedItemNumber: number;
+    userPhone: string;
+}, {
+    transactionId: string;
+    paymentTime: string;
+    purchasedItemNumber: number;
+    userPhone: string;
+}>;
+export type GiveawayEntrySubmitInput = z.infer<typeof giveawayEntrySubmitSchema>;
+/** Schema for flag action */
+export declare const flagGiveawayEntrySchema: z.ZodObject<{
+    entryId: z.ZodString;
+    flagNote: z.ZodString;
+    flaggedByUserId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    entryId: string;
+    flagNote: string;
+    flaggedByUserId: string;
+}, {
+    entryId: string;
+    flagNote: string;
+    flaggedByUserId: string;
+}>;
+export type FlagGiveawayEntryInput = z.infer<typeof flagGiveawayEntrySchema>;
+/** Schema for reopen-slot action */
+export declare const reopenGiveawaySlotSchema: z.ZodObject<{
+    sourceType: z.ZodEnum<["event", "product"]>;
+    sourceId: z.ZodString;
+    slotNumber: z.ZodNumber;
+    adminUserId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    slotNumber: number;
+    sourceType: "product" | "event";
+    sourceId: string;
+    adminUserId: string;
+}, {
+    slotNumber: number;
+    sourceType: "product" | "event";
+    sourceId: string;
+    adminUserId: string;
+}>;
+export type ReopenGiveawaySlotInput = z.infer<typeof reopenGiveawaySlotSchema>;
+/** Schema for submit giveaway pull (full, server-side) */
+export declare const submitGiveawayPullSchema: z.ZodEffects<z.ZodObject<{
+    sourceType: z.ZodEnum<["event", "product"]>;
+    eventId: z.ZodOptional<z.ZodString>;
+    productId: z.ZodOptional<z.ZodString>;
+    userId: z.ZodString;
+    userDisplayName: z.ZodOptional<z.ZodString>;
+    userEmail: z.ZodOptional<z.ZodString>;
+} & {
+    transactionId: z.ZodString;
+    paymentTime: z.ZodString;
+    purchasedItemNumber: z.ZodNumber;
+    userPhone: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    userId: string;
+    transactionId: string;
+    sourceType: "product" | "event";
+    paymentTime: string;
+    purchasedItemNumber: number;
+    userPhone: string;
+    productId?: string | undefined;
+    userEmail?: string | undefined;
+    eventId?: string | undefined;
+    userDisplayName?: string | undefined;
+}, {
+    userId: string;
+    transactionId: string;
+    sourceType: "product" | "event";
+    paymentTime: string;
+    purchasedItemNumber: number;
+    userPhone: string;
+    productId?: string | undefined;
+    userEmail?: string | undefined;
+    eventId?: string | undefined;
+    userDisplayName?: string | undefined;
+}>, {
+    userId: string;
+    transactionId: string;
+    sourceType: "product" | "event";
+    paymentTime: string;
+    purchasedItemNumber: number;
+    userPhone: string;
+    productId?: string | undefined;
+    userEmail?: string | undefined;
+    eventId?: string | undefined;
+    userDisplayName?: string | undefined;
+}, {
+    userId: string;
+    transactionId: string;
+    sourceType: "product" | "event";
+    paymentTime: string;
+    purchasedItemNumber: number;
+    userPhone: string;
+    productId?: string | undefined;
+    userEmail?: string | undefined;
+    eventId?: string | undefined;
+    userDisplayName?: string | undefined;
+}>;
+export type SubmitGiveawayPullInput = z.infer<typeof submitGiveawayPullSchema>;

package/dist/features/giveaway/schemas/zod.js

@@ -0,0 +1,39 @@
+/**
+ * Zod schemas for giveaway entry submission and validation.
+ */
+import { z } from "zod";
+export const giveawayEntrySubmitSchema = z.object({
+    transactionId: z.string().min(4, "Transaction ID must be at least 4 characters"),
+    paymentTime: z.string().datetime({ message: "Payment time must be a valid ISO datetime" }),
+    purchasedItemNumber: z.number().int().min(1, "Item number must be at least 1"),
+    userPhone: z
+        .string()
+        .min(10, "Phone number must be at least 10 digits")
+        .regex(/^\+?[\d\s\-()]{10,}$/, "Enter a valid phone number"),
+});
+/** Schema for flag action */
+export const flagGiveawayEntrySchema = z.object({
+    entryId: z.string().min(1),
+    flagNote: z.string().min(1, "Flag note is required"),
+    flaggedByUserId: z.string().min(1),
+});
+/** Schema for reopen-slot action */
+export const reopenGiveawaySlotSchema = z.object({
+    sourceType: z.enum(["event", "product"]),
+    sourceId: z.string().min(1),
+    slotNumber: z.number().int().min(1),
+    adminUserId: z.string().min(1),
+});
+/** Schema for submit giveaway pull (full, server-side) */
+export const submitGiveawayPullSchema = z
+    .object({
+    sourceType: z.enum(["event", "product"]),
+    eventId: z.string().optional(),
+    productId: z.string().optional(),
+    userId: z.string().min(1),
+    userDisplayName: z.string().optional(),
+    userEmail: z.string().email().optional(),
+})
+    .merge(giveawayEntrySubmitSchema)
+    .refine((data) => (data.sourceType === "event" && !!data.eventId) ||
+    (data.sourceType === "product" && !!data.productId), { message: "eventId or productId must be provided matching sourceType" });

package/dist/features/giveaway/types/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Giveaway feature shared types
+ *
+ * Used by both event-type giveaway and prize-draw-mode giveaway.
+ * Weight + price fields are server-only — never sent to client consumers.
+ */
+export interface GiveawaySlot {
+    slotNumber: number;
+    name: string;
+    /** Prize photo. Public — rendered in the prize collage on the giveaway detail page. */
+    image?: string;
+    price: number;
+    weight: number;
+    isBooked: boolean;
+    bookedByUserGiveawayNumber?: number;
+    bookedByUserId?: string;
+    bookedByDisplayName?: string;
+}
+/** Slot shape safe to expose to clients — price and weight stripped by adapter. */
+export interface ClientGiveawaySlot {
+    slotNumber: number;
+    name: string;
+    image?: string;
+    isBooked: boolean;
+    bookedByUserGiveawayNumber?: number;
+    bookedByDisplayName?: string;
+}
+export type GiveawayPricingMode = "uniform" | "variable";
+export interface GiveawayConfig {
+    slots: GiveawaySlot[];
+    totalSlots: number;
+    pricingMode: GiveawayPricingMode;
+    uniformPrice?: number;
+    drawWindowDurationMinutes: number;
+    maxPullsPerTransaction: number;
+    maxPullsPerUser: number;
+}
+/** Client-safe config shape — slots have price/weight stripped. */
+export interface ClientGiveawayConfig {
+    slots: ClientGiveawaySlot[];
+    totalSlots: number;
+    pricingMode: GiveawayPricingMode;
+    drawWindowDurationMinutes: number;
+    maxPullsPerTransaction: number;
+    maxPullsPerUser: number;
+}
+export type GiveawayEntryStatus = "pending" | "drawn" | "won" | "flagged" | "cancelled";
+/** Error codes thrown by giveaway actions */
+export type GiveawayErrorCode = "GIVEAWAY_FULL" | "GIVEAWAY_WINDOW_CLOSED" | "USER_LIMIT_REACHED" | "TX_ALREADY_USED" | "SLOT_NOT_FOUND" | "ENTRY_NOT_FLAGGED";
+export declare class GiveawayError extends Error {
+    readonly code: GiveawayErrorCode;
+    constructor(code: GiveawayErrorCode, message: string);
+}
+/**
+ * Compute the weight for a slot given its price.
+ * Lower price → higher weight → more likely to be selected.
+ * Weight is always at least 1 (never 0).
+ * For uniform pricing: all slots get weight 50.
+ */
+export declare function computeWeight(price: number, maxPrice: number): number;
+/**
+ * Pick a slot using weighted random selection. Uses the Web Crypto API, not
+ * `Math.random()`, so the fairness claim shown to users (PrizeRevealModal's
+ * "provably fair" copy) is actually true for this path too.
+ * @throws {GiveawayError} GIVEAWAY_FULL when unclaimed is empty.
+ */
+export declare function pickWeightedSlot(unclaimed: GiveawaySlot[]): GiveawaySlot;
+/**
+ * Assign weights to slots based on pricing mode.
+ * Returns a new array with weight populated on every slot.
+ */
+export declare function assignSlotWeights(config: GiveawayConfig): GiveawaySlot[];