@mohasinac/appkit 4.70.0 → 4.71.2

package/dist/_internal/server/features/forms/field-visibility.d.ts

@@ -0,0 +1,35 @@
+import type { CustomFieldDef, FormStep } from "../../../../features/shell/field-ui-meta";
+export interface SurfaceFieldConfig {
+    fields: Record<string, boolean>;
+    fieldOrder: string[];
+    customFields: CustomFieldDef[];
+    steps: FormStep[];
+}
+/**
+ * The wide read — everything an admin has customized on this surface.
+ * Cached and degraded the same way `getFieldVisibility` is; a read failure
+ * here must fall back to "nothing customized", never block the surface.
+ */
+export declare const getSurfaceFieldConfig: (surfaceId: string) => Promise<SurfaceFieldConfig>;
+/**
+ * Cached on `surfaceId` alone — the narrowest shared argument, same
+ * reasoning as `getPageRegion`. Degrades to `{}` (= "show everything") on
+ * a missing doc or any read failure, so a field-visibility outage never
+ * blocks a form or a display page from rendering.
+ *
+ * Unchanged signature/return type — see this file's header. Built on
+ * `getSurfaceFieldConfig` rather than reading Firestore a second time.
+ */
+export declare const getFieldVisibility: (surfaceId: string) => Promise<Record<string, boolean>>;
+/**
+ * Whole-map replace per key the caller actually passes — `fields` alone
+ * (the pre-existing shape) leaves `fieldOrder`/`customFields` untouched via
+ * `merge: true`, so the original single-param call shape still works
+ * byte-for-byte; the new keys are additive, never required.
+ */
+export declare function setFieldVisibility(surfaceId: string, patch: {
+    fields?: Record<string, boolean>;
+    fieldOrder?: string[];
+    customFields?: CustomFieldDef[];
+    steps?: FormStep[];
+}): Promise<void>;

package/dist/_internal/server/features/forms/field-visibility.js

@@ -0,0 +1,89 @@
+/*
+ * WHY: Mirrors `_internal/server/features/dashboard/page-regions.ts`'s
+ *      `getPageRegion`/`setPageRegion` shape exactly — same cache-wrapped
+ *      safeRead-degrading read, same plain async write, same "surfaceId is
+ *      a hand-chosen stable string the caller passes" identity rule. A
+ *      field-visibility surface and a page region are a different
+ *      collection holding a different document shape, not a different
+ *      mechanism, so there is nothing to generalize between the two yet
+ *      (Rule of Three — this is the second occurrence of the pattern, not
+ *      the third).
+ *
+ * WHAT: `getFieldVisibility(surfaceId)` / `setFieldVisibility(surfaceId,
+ *       fields)` over the `fieldVisibility` collection — widened 2026-11-03
+ *       (3B item 1b, Universal Template System pilot) to also carry
+ *       `fieldOrder`/`customFields` on the SAME document. This is
+ *       deliberately NOT a second mechanism or a second store: the plan's
+ *       own words are "`hiddenFields` IS `fieldVisibility/{surfaceId}`'s
+ *       existing `fields` map, same storage… `fieldOrder`/`customFields`
+ *       are new, additive fields on the SAME document shape, not a
+ *       parallel store." `getFieldVisibility`'s own signature and return
+ *       type are UNCHANGED — every existing caller (`SectionVisibilityGate`,
+ *       7 PDP views) keeps reading a bare `Record<string, boolean>` and
+ *       never has to learn about the wider doc. `getSurfaceFieldConfig` is
+ *       the new, wider reader for the one caller that needs fieldOrder and
+ *       customFields too (the field-visibility API route, for
+ *       `useFieldVisibility`).
+ *
+ * EXPORTS: getFieldVisibility, getSurfaceFieldConfig, setFieldVisibility
+ *
+ * @tag domain:forms
+ * @tag layer:server
+ * @tag pattern:none
+ * @tag access:server-only
+ * @tag consumers:field-visibility-route,SectionForm-callers
+ * @tag sideEffects:firestore-read,firestore-write
+ */
+import { cache } from "react";
+import { getAdminDb } from "../../../../providers/db-firebase/index.js";
+import { safeRead } from "../../../../errors/safe-read.js";
+const FIELD_VISIBILITY_COLLECTION = "fieldVisibility";
+const EMPTY_SURFACE_CONFIG = { fields: {}, fieldOrder: [], customFields: [], steps: [] };
+/**
+ * The wide read — everything an admin has customized on this surface.
+ * Cached and degraded the same way `getFieldVisibility` is; a read failure
+ * here must fall back to "nothing customized", never block the surface.
+ */
+export const getSurfaceFieldConfig = cache(async (surfaceId) => {
+    return safeRead(async () => {
+        const snap = await getAdminDb().collection(FIELD_VISIBILITY_COLLECTION).doc(surfaceId).get();
+        if (!snap.exists)
+            return EMPTY_SURFACE_CONFIG;
+        const data = snap.data();
+        return {
+            fields: data.fields && typeof data.fields === "object" ? data.fields : {},
+            fieldOrder: Array.isArray(data.fieldOrder) ? data.fieldOrder : [],
+            customFields: Array.isArray(data.customFields) ? data.customFields : [],
+            steps: Array.isArray(data.steps) ? data.steps : [],
+        };
+    }, {
+        route: "field-visibility",
+        key: `surface-field-config:${surfaceId}`,
+        fallback: EMPTY_SURFACE_CONFIG,
+    });
+});
+/**
+ * Cached on `surfaceId` alone — the narrowest shared argument, same
+ * reasoning as `getPageRegion`. Degrades to `{}` (= "show everything") on
+ * a missing doc or any read failure, so a field-visibility outage never
+ * blocks a form or a display page from rendering.
+ *
+ * Unchanged signature/return type — see this file's header. Built on
+ * `getSurfaceFieldConfig` rather than reading Firestore a second time.
+ */
+export const getFieldVisibility = cache(async (surfaceId) => {
+    const config = await getSurfaceFieldConfig(surfaceId);
+    return config.fields;
+});
+/**
+ * Whole-map replace per key the caller actually passes — `fields` alone
+ * (the pre-existing shape) leaves `fieldOrder`/`customFields` untouched via
+ * `merge: true`, so the original single-param call shape still works
+ * byte-for-byte; the new keys are additive, never required.
+ */
+export async function setFieldVisibility(surfaceId, patch) {
+    await getAdminDb()
+        .collection(FIELD_VISIBILITY_COLLECTION)
+        .doc(surfaceId)
+        .set({ surfaceId, ...patch, updatedAt: new Date() }, { merge: true });
+}

package/dist/_internal/server/features/giveaway/actions.d.ts

@@ -0,0 +1,43 @@
+import { type ActionResult } from "../../../shared/types/action-result";
+import type { GiveawayConfig } from "../../../../features/giveaway/types";
+import type { GiveawayEntryDocument } from "../../../../features/giveaway/schemas/firestore";
+/**
+ * User-initiated giveaway pull.
+ * Atomically:
+ * 1. Validates inputs + limits
+ * 2. Runs weighted slot selection on unclaimed slots
+ * 3. Marks the slot as booked
+ * 4. Creates the GiveawayEntryDocument with assignedPrizeSlotNumber set
+ *
+ * Returns the assigned slot number so the user sees their prize immediately.
+ */
+export declare function submitGiveawayPullAction(input: unknown): Promise<ActionResult<{
+    userGiveawayNumber: number;
+    assignedPrizeSlotNumber: number;
+    slotName: string;
+}>>;
+/**
+ * Admin — flag a giveaway entry as fraudulent.
+ * Slot stays booked; use reopenGiveawaySlotAction to free it.
+ */
+export declare function flagGiveawayEntryAction(input: unknown): Promise<ActionResult<GiveawayEntryDocument>>;
+/**
+ * Admin — reopen a slot from a flagged entry.
+ * Clears isBooked on the slot so it can be claimed in a future pull.
+ */
+export declare function reopenGiveawaySlotAction(input: unknown): Promise<ActionResult<void>>;
+/**
+ * Admin — create a new giveaway event.
+ * Weights computed server-side; never returned to client.
+ */
+export declare function createGiveawayEventAction(data: unknown): Promise<ActionResult<unknown>>;
+/**
+ * Admin — update a giveaway event.
+ * Recomputes slot weights after update.
+ */
+export declare function updateGiveawayEventAction(id: string, data: unknown): Promise<ActionResult<unknown>>;
+/**
+ * Store owner or Admin — switch a clearance product into giveaway mode.
+ * Store owners provide prizeSlotPrice but weight is NEVER returned to them.
+ */
+export declare function setProductGiveawayModeAction(productId: string, giveawayConfig: GiveawayConfig): Promise<ActionResult<void>>;

package/dist/_internal/server/features/giveaway/actions.js

@@ -0,0 +1,369 @@
+"use server";
+/*
+ * 🛑 From the DEFINING module, never "@mohasinac/appkit/server".
+ *
+ * appkit importing its own public server barrel is a self-reference that drags
+ * the whole server surface in behind it — `dist/server.js` reaches next/og,
+ * next/navigation, next/headers and driver.js. Twenty `actions.ts` files did
+ * this for two symbols, and because `obligationSweep` reaches one of them, the
+ * Firebase Functions tsup bundle (noExternal: appkit) had to resolve Next:
+ * it failed on two `react-server-dom-webpack/*` requires and two @vercel/og
+ * .wasm files, naming none of the responsible files. Root Cause #18.
+ */
+import { wrapAction } from "../../../shared/types/action-result.js";
+import { getAdminDb } from "../../../../providers/db-firebase/index.js";
+import { eventRepository, productRepository, orderRepository } from "../../../../repositories/index.js";
+import { normalizeEventType } from "../../../../features/events/types/index.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+import { giveawayEntryRepository } from "../../../../features/giveaway/repository/giveaway-entry.repository.js";
+import { requireRoleUser } from "../../../../providers/auth-firebase/helpers.js";
+import { ValidationError } from "../../../shared/errors/index.js";
+import { submitGiveawayPullSchema, flagGiveawayEntrySchema, reopenGiveawaySlotSchema, } from "../../../../features/giveaway/schemas/zod.js";
+import { GiveawayError, assignSlotWeights, pickWeightedSlot, } from "../../../../features/giveaway/types/index.js";
+import { GIVEAWAY_ENTRIES_COLLECTION } from "../../../../features/giveaway/schemas/firestore.js";
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function isDrawWindowOpen(config) {
+    // Draw window is implicitly open when there are unclaimed slots.
+    // A real implementation would also check if the event status is "active".
+    return config.slots.some((s) => !s.isBooked);
+}
+// ── Public actions ────────────────────────────────────────────────────────────
+/**
+ * User-initiated giveaway pull.
+ * Atomically:
+ * 1. Validates inputs + limits
+ * 2. Runs weighted slot selection on unclaimed slots
+ * 3. Marks the slot as booked
+ * 4. Creates the GiveawayEntryDocument with assignedPrizeSlotNumber set
+ *
+ * Returns the assigned slot number so the user sees their prize immediately.
+ */
+export async function submitGiveawayPullAction(input) {
+    return wrapAction(async () => {
+        // Auth — must be logged in
+        const user = await requireRoleUser(["user", "buyer", "seller", "admin", "moderator", "employee"]);
+        const parsed = submitGiveawayPullSchema.safeParse(input);
+        if (!parsed.success) {
+            throw new ValidationError(parsed.error.issues[0]?.message ?? "Invalid giveaway pull input");
+        }
+        const data = parsed.data;
+        const sourceId = data.sourceType === "event" ? data.eventId : data.productId;
+        const sourceField = data.sourceType === "event" ? "eventId" : "productId";
+        // Load the event/product to get the giveawayConfig
+        let giveawayConfig;
+        if (data.sourceType === "event") {
+            const event = await eventRepository.findById(sourceId);
+            // 🛑 `normalizeEventType`, not `===`: documents written before the
+            // 2026-10-31 rename still hold `type: "giveaway"`, and a bare equality
+            // would reject every one of them as "not found".
+            if (!event || normalizeEventType(event.type) !== "random-draw") {
+                throw new GiveawayError("GIVEAWAY_WINDOW_CLOSED", "Random draw event not found or not of type random-draw.");
+            }
+            if (event.status !== "active") {
+                throw new GiveawayError("GIVEAWAY_WINDOW_CLOSED", "This giveaway is not currently active.");
+            }
+            if (!event.giveawayConfig) {
+                throw new GiveawayError("GIVEAWAY_WINDOW_CLOSED", "Giveaway config not found on event.");
+            }
+            giveawayConfig = event.giveawayConfig;
+        }
+        else {
+            const product = await productRepository.findById(sourceId);
+            if (!product || product.listingType !== "clearance") {
+                throw new GiveawayError("GIVEAWAY_WINDOW_CLOSED", "Clearance product not found.");
+            }
+            if (product.status !== "published") {
+                throw new GiveawayError("GIVEAWAY_WINDOW_CLOSED", "This clearance draw is not currently active.");
+            }
+            if (product.prizeDrawMode !== "giveaway" || !product.giveawayConfig) {
+                throw new GiveawayError("GIVEAWAY_WINDOW_CLOSED", "Giveaway config not found on product.");
+            }
+            giveawayConfig = product.giveawayConfig;
+        }
+        // Check draw window
+        if (!isDrawWindowOpen(giveawayConfig)) {
+            throw new GiveawayError("GIVEAWAY_FULL", "All slots have been claimed.");
+        }
+        // Enforce maxPullsPerUser
+        const existingUserPulls = await giveawayEntryRepository.countByUser(sourceId, sourceField, user.uid);
+        if (existingUserPulls >= giveawayConfig.maxPullsPerUser) {
+            throw new GiveawayError("USER_LIMIT_REACHED", "You have reached the maximum number of pulls for this giveaway.");
+        }
+        /*
+         * ── D52: THE TRANSACTION MUST BE A REAL, PAID, CALLER-OWNED ORDER ──────
+         *
+         * 🛑 Before this, `data.transactionId` was a user-supplied STRING
+         * (`z.string().min(4)`) and the only thing checked was a COUNT of prior
+         * entries carrying the same string. Nothing verified that the transaction
+         * existed, that it was paid, or that it belonged to the caller — and
+         * `paymentTime` was user-supplied too.
+         *
+         * So **anyone could claim a giveaway slot for free** by typing any
+         * four-character string, up to `maxPullsPerUser`, and then another
+         * `maxPullsPerUser` under the next string. On a giveaway whose slots carry
+         * real prices and real prizes.
+         *
+         * The code knew: `// FUTURE_FINANCIAL_DB: external_tx_id →
+         * giveaway_transactions.external_tx_id`, pointing at a collection that does
+         * not exist. The gap was marked and left open.
+         *
+         * It does not need that collection: a clearance entry is bought through
+         * the ordinary cart, so a paid ORDER is the payment record we already
+         * have. `maxPullsPerTransaction` then does what its name says — it bounds
+         * pulls per PAYMENT rather than per guessed string.
+         *
+         * 🛑 THE TWO SOURCES HAVE DIFFERENT PAYMENT REALITIES, and pretending
+         * otherwise would either leave the hole open or break a working feature.
+         *
+         * · A PRODUCT-sourced giveaway is a `clearance` listing bought through the
+         *   ordinary cart, so a paid ORDER exists and is verifiable. Required.
+         *
+         * · An EVENT-sourced giveaway carries real slot prices (the seed has both
+         *   `uniform` and `variable` events) and has **no cart or checkout path at
+         *   all** — an event is not a product and cannot be added to a cart. So
+         *   the typed `transactionId` was the ENTIRE payment record: an
+         *   honour-system reference with nothing behind it.
+         *
+         *   Requiring an order here would break every event giveaway. Accepting the
+         *   string silently is the hole. So the entry is accepted and marked
+         *   `isFlagged` for admin review BEFORE the draw — `flagGiveawayEntry`
+         *   already exists for exactly this, and an admin can clear or void it.
+         *   That makes the unverified state VISIBLE instead of indistinguishable
+         *   from a paid one.
+         *
+         * 🛑 This is a stopgap, not a fix, and it is the honest one available
+         * without building a checkout path for events. The real fix is to make an
+         * event giveaway purchasable (or free), which is a product decision.
+         */
+        let paymentUnverified = false;
+        if (data.sourceType === "product") {
+            const payingOrder = await orderRepository.findById(data.transactionId);
+            /*
+             * "Not found" and "not yours" share one message DELIBERATELY.
+             * Distinguishing them confirms that an order id exists and belongs to
+             * someone else, which is an enumeration oracle over order ids.
+             */
+            if (!payingOrder || payingOrder.userId !== user.uid) {
+                throw new GiveawayError("TX_ALREADY_USED", "That order could not be found. Enter the order ID from your confirmation email.");
+            }
+            if (payingOrder.paymentStatus !== "paid") {
+                throw new GiveawayError("TX_ALREADY_USED", "That order has not been paid yet. Once the payment is confirmed you can claim your slot.");
+            }
+            /*
+             * The order must contain THIS clearance draw, or one paid order could be
+             * spent across every open giveaway on the site.
+             *
+             * Both shapes are checked: `items[]` is the fan-out form, and the flat
+             * `productId` is the PRIMARY field on an order — CLAUDE.md's own
+             * correction records that `items` is OPTIONAL and the flat fields are
+             * not legacy residue, so checking only one misses real orders.
+             */
+            const orderCoversSource = payingOrder.productId === sourceId ||
+                (payingOrder.items ?? []).some((i) => i.productId === sourceId);
+            if (!orderCoversSource) {
+                throw new GiveawayError("TX_ALREADY_USED", "That order does not include this clearance draw. Check the order ID.");
+            }
+        }
+        else {
+            paymentUnverified = true;
+            serverLogger.warn("[giveaway] event pull accepted with an UNVERIFIED payment reference — flagged for admin review", { eventId: sourceId, uid: user.uid, transactionId: data.transactionId });
+        }
+        // Enforce maxPullsPerTransaction — now per PAYMENT, not per guessed string.
+        const existingTxPulls = await giveawayEntryRepository.countByTransactionId(sourceId, sourceField, data.transactionId);
+        if (existingTxPulls >= giveawayConfig.maxPullsPerTransaction) {
+            throw new GiveawayError("TX_ALREADY_USED", "This order has already been used for the maximum number of pulls.");
+        }
+        // Atomically: pick slot + create entry + mark slot booked
+        const db = getAdminDb();
+        const sourceCollectionName = data.sourceType === "event" ? "events" : "products";
+        const sourceDocRef = db.collection(sourceCollectionName).doc(sourceId);
+        const { assignedSlot, userGiveawayNumber } = await db.runTransaction(async (tx) => {
+            // Re-read giveawayConfig inside transaction for freshness
+            const sourceSnap = await tx.get(sourceDocRef);
+            if (!sourceSnap.exists)
+                throw new GiveawayError("GIVEAWAY_WINDOW_CLOSED", "Giveaway source not found.");
+            const freshConfig = sourceSnap.data().giveawayConfig;
+            if (!freshConfig)
+                throw new GiveawayError("GIVEAWAY_WINDOW_CLOSED", "Giveaway config missing.");
+            const freshWeighted = assignSlotWeights(freshConfig);
+            const unclaimed = freshWeighted.filter((s) => !s.isBooked);
+            if (unclaimed.length === 0)
+                throw new GiveawayError("GIVEAWAY_FULL", "All slots have been claimed.");
+            // Weighted pick
+            const chosen = pickWeightedSlot(unclaimed);
+            // Compute next userGiveawayNumber (count + 1 inside tx via collection size)
+            const countSnap = await db
+                .collection(GIVEAWAY_ENTRIES_COLLECTION)
+                .where(sourceField, "==", sourceId)
+                .get();
+            const nextNumber = countSnap.size + 1;
+            // Mark slot booked in the source document
+            const updatedSlots = freshConfig.slots.map((s) => s.slotNumber === chosen.slotNumber
+                ? {
+                    ...s,
+                    isBooked: true,
+                    bookedByUserId: user.uid,
+                    bookedByDisplayName: user.displayName ?? user.name ?? undefined,
+                    bookedByUserGiveawayNumber: nextNumber,
+                }
+                : s);
+            tx.update(sourceDocRef, {
+                "giveawayConfig.slots": updatedSlots,
+            });
+            return { assignedSlot: chosen, userGiveawayNumber: nextNumber };
+        });
+        /*
+         * Create the entry document outside the transaction (acceptable — slot is
+         * already booked).
+         *
+         * Typed `GiveawayEntryPlain`: this is PLAINTEXT from the session and the
+         * request body, and `createEntry` encrypts it. The document type now says
+         * `Encrypted<string>`, so annotating this `GiveawayEntryDocument` is a
+         * compile error — correctly, because the values here are not ciphertext.
+         */
+        const entryData = {
+            sourceType: data.sourceType,
+            ...(data.sourceType === "event" ? { eventId: sourceId } : { productId: sourceId }),
+            userId: user.uid,
+            userDisplayName: user.displayName ?? user.name ?? undefined,
+            userEmail: user.email ?? undefined,
+            userPhone: data.userPhone,
+            transactionId: data.transactionId,
+            paymentTime: new Date(data.paymentTime),
+            purchasedItemNumber: data.purchasedItemNumber,
+            userGiveawayNumber,
+            assignedPrizeSlotNumber: assignedSlot.slotNumber,
+            status: "drawn",
+            /*
+             * D52 — an EVENT pull carries no verifiable payment (events have no
+             * cart path), so it is flagged on creation rather than recorded as if it
+             * were paid. A product pull reached here only after its order was
+             * verified paid, caller-owned and covering this draw, so it is not
+             * flagged.
+             *
+             * This is what makes the unverified state visible to an admin before the
+             * draw instead of indistinguishable from a paid one.
+             */
+            isFlagged: paymentUnverified,
+            ...(paymentUnverified
+                ? {
+                    flagNote: "Payment reference not verified — event giveaways have no checkout path, so this reference was typed by the entrant. Confirm the payment before the draw.",
+                }
+                : {}),
+            submittedAt: new Date(),
+            drawnAt: new Date(),
+        };
+        await giveawayEntryRepository.createEntry(entryData);
+        return {
+            userGiveawayNumber,
+            assignedPrizeSlotNumber: assignedSlot.slotNumber,
+            slotName: assignedSlot.name,
+        };
+    });
+}
+/**
+ * Admin — flag a giveaway entry as fraudulent.
+ * Slot stays booked; use reopenGiveawaySlotAction to free it.
+ */
+export async function flagGiveawayEntryAction(input) {
+    return wrapAction(async () => {
+        await requireRoleUser(["admin", "moderator"]);
+        const parsed = flagGiveawayEntrySchema.safeParse(input);
+        if (!parsed.success) {
+            throw new ValidationError(parsed.error.issues[0]?.message ?? "Invalid flag input");
+        }
+        return giveawayEntryRepository.flagEntry(parsed.data.entryId, parsed.data.flagNote, parsed.data.flaggedByUserId);
+    });
+}
+/**
+ * Admin — reopen a slot from a flagged entry.
+ * Clears isBooked on the slot so it can be claimed in a future pull.
+ */
+export async function reopenGiveawaySlotAction(input) {
+    return wrapAction(async () => {
+        await requireRoleUser(["admin"]);
+        const parsed = reopenGiveawaySlotSchema.safeParse(input);
+        if (!parsed.success) {
+            throw new ValidationError(parsed.error.issues[0]?.message ?? "Invalid reopen input");
+        }
+        const { sourceType, sourceId, slotNumber } = parsed.data;
+        const db = getAdminDb();
+        const collectionName = sourceType === "event" ? "events" : "products";
+        const docRef = db.collection(collectionName).doc(sourceId);
+        await db.runTransaction(async (tx) => {
+            const snap = await tx.get(docRef);
+            if (!snap.exists)
+                throw new ValidationError("Source document not found.");
+            const config = snap.data().giveawayConfig;
+            if (!config?.slots)
+                throw new ValidationError("Giveaway config not found.");
+            const updatedSlots = config.slots.map((s) => s.slotNumber === slotNumber
+                ? {
+                    ...s,
+                    isBooked: false,
+                    bookedByUserId: null,
+                    bookedByDisplayName: null,
+                    bookedByUserGiveawayNumber: null,
+                }
+                : s);
+            tx.update(docRef, { "giveawayConfig.slots": updatedSlots });
+        });
+    });
+}
+/**
+ * Admin — create a new giveaway event.
+ * Weights computed server-side; never returned to client.
+ */
+export async function createGiveawayEventAction(data) {
+    return wrapAction(async () => {
+        const user = await requireRoleUser(["admin", "moderator"]);
+        const rawData = data;
+        const giveawayConfig = rawData.giveawayConfig;
+        if (!giveawayConfig)
+            throw new ValidationError("giveawayConfig is required for giveaway events.");
+        // Compute weights server-side
+        const withWeights = assignSlotWeights(giveawayConfig);
+        return eventRepository.createEvent({
+            ...rawData,
+            type: "random-draw",
+            giveawayConfig: { ...giveawayConfig, slots: withWeights },
+            createdBy: user.uid,
+            status: rawData.status ?? "draft",
+            stats: { totalEntries: 0, approvedEntries: 0, flaggedEntries: 0 },
+        });
+    });
+}
+/**
+ * Admin — update a giveaway event.
+ * Recomputes slot weights after update.
+ */
+export async function updateGiveawayEventAction(id, data) {
+    return wrapAction(async () => {
+        await requireRoleUser(["admin", "moderator"]);
+        const rawData = data;
+        const giveawayConfig = rawData.giveawayConfig;
+        if (giveawayConfig) {
+            const withWeights = assignSlotWeights(giveawayConfig);
+            return eventRepository.updateEvent(id, {
+                ...rawData,
+                giveawayConfig: { ...giveawayConfig, slots: withWeights },
+            });
+        }
+        return eventRepository.updateEvent(id, rawData);
+    });
+}
+/**
+ * Store owner or Admin — switch a clearance product into giveaway mode.
+ * Store owners provide prizeSlotPrice but weight is NEVER returned to them.
+ */
+export async function setProductGiveawayModeAction(productId, giveawayConfig) {
+    return wrapAction(async () => {
+        await requireRoleUser(["admin", "moderator", "seller"]);
+        const withWeights = assignSlotWeights(giveawayConfig);
+        const db = getAdminDb();
+        await db.collection("products").doc(productId).update({
+            prizeDrawMode: "giveaway",
+            giveawayConfig: { ...giveawayConfig, slots: withWeights },
+        });
+    });
+}

package/dist/_internal/server/features/giveaway/adapters.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Giveaway adapters — strips server-only fields (price, weight)
+ * before any slot/config data leaves the server.
+ */
+import type { GiveawayConfig, GiveawaySlot, ClientGiveawayConfig, ClientGiveawaySlot } from "../../../../features/giveaway/types";
+/**
+ * Strip price and weight from a single slot for client consumption.
+ *
+ * Takes the loose shape rather than `GiveawaySlot` so it can be applied to a
+ * value already TYPED as projected but not actually projected — which is the
+ * state `EventItem.giveawayConfig` is in when it comes off the repository.
+ */
+export declare function toClientGiveawaySlot(slot: GiveawaySlot | ClientGiveawaySlot): ClientGiveawaySlot;
+/** Strip price/weight from the entire config for client consumption. */
+export declare function toClientGiveawayConfig(config: GiveawayConfig | ClientGiveawayConfig): ClientGiveawayConfig;

package/dist/_internal/server/features/giveaway/adapters.js

@@ -0,0 +1,31 @@
+/**
+ * Strip price and weight from a single slot for client consumption.
+ *
+ * Takes the loose shape rather than `GiveawaySlot` so it can be applied to a
+ * value already TYPED as projected but not actually projected — which is the
+ * state `EventItem.giveawayConfig` is in when it comes off the repository.
+ */
+export function toClientGiveawaySlot(slot) {
+    // Allow-list, not a spread: every field named here is a deliberate public
+    // exposure with a known reader (§ Public Data Projections). `image` is read
+    // by the prize collage on the giveaway detail page.
+    return {
+        slotNumber: slot.slotNumber,
+        name: slot.name,
+        image: slot.image,
+        isBooked: slot.isBooked,
+        bookedByUserGiveawayNumber: slot.bookedByUserGiveawayNumber,
+        bookedByDisplayName: slot.bookedByDisplayName,
+    };
+}
+/** Strip price/weight from the entire config for client consumption. */
+export function toClientGiveawayConfig(config) {
+    return {
+        slots: config.slots.map(toClientGiveawaySlot),
+        totalSlots: config.totalSlots,
+        pricingMode: config.pricingMode,
+        drawWindowDurationMinutes: config.drawWindowDurationMinutes,
+        maxPullsPerTransaction: config.maxPullsPerTransaction,
+        maxPullsPerUser: config.maxPullsPerUser,
+    };
+}

package/dist/_internal/server/features/giveaway/data.d.ts

@@ -0,0 +1,19 @@
+import type { SieveModel } from "../../../../providers/db-firebase";
+import type { EventDocument } from "../../../../features/events/schemas/firestore";
+import type { ClientGiveawayConfig } from "../../../../features/giveaway/types";
+/** Event shape with giveaway config stripped of price/weight. */
+export type GiveawayEventClient = Omit<EventDocument, "giveawayConfig"> & {
+    giveawayConfig?: ClientGiveawayConfig;
+};
+/** Fetch a random-draw event with price/weight stripped for client use. */
+export declare const getGiveawayEventCached: (id: string) => Promise<GiveawayEventClient | null>;
+/** List all random-draw events with price/weight stripped. */
+export declare const listGiveawayEvents: (opts?: {
+    status?: string;
+    page?: number;
+    pageSize?: number;
+}) => Promise<GiveawayEventClient[]>;
+/** Fetch giveaway entries for admin view (includes phone + txId via PII decrypt). */
+export declare function getGiveawayEntriesForAdmin(sourceType: "event" | "product", sourceId: string, model: SieveModel): Promise<import("../../../..").FirebaseSieveResult<import("../../../..").GiveawayEntryDocument>>;
+/** Fetch giveaway entries for a specific user (own entries only). */
+export declare function getGiveawayEntriesForUser(userId: string, model: SieveModel): Promise<import("../../../..").FirebaseSieveResult<import("../../../..").GiveawayEntryDocument>>;

package/dist/_internal/server/features/giveaway/data.js

@@ -0,0 +1,56 @@
+import { cache } from "react";
+import { eventRepository } from "../../../../repositories/index.js";
+import { normalizeEventType } from "../../../../features/events/types/index.js";
+import { giveawayEntryRepository } from "../../../../features/giveaway/repository/giveaway-entry.repository.js";
+import { toClientGiveawayConfig } from "./adapters.js";
+/** Fetch a random-draw event with price/weight stripped for client use. */
+export const getGiveawayEventCached = cache(async (id) => {
+    const event = await eventRepository.findById(id);
+    // 🛑 `normalizeEventType`, not `===`: pre-2026-10-31 documents still hold
+    // `type: "giveaway"`, and a bare equality returns null for every one.
+    if (!event || normalizeEventType(event.type) !== "random-draw")
+        return null;
+    return {
+        ...event,
+        giveawayConfig: event.giveawayConfig ? toClientGiveawayConfig(event.giveawayConfig) : undefined,
+    };
+});
+/** List all random-draw events with price/weight stripped. */
+export const listGiveawayEvents = cache(async (opts) => {
+    // Build Sieve filter: type==random-draw (or the legacy `giveaway`),
+    // optionally also status.
+    //
+    // 🛑 A RAW filter string, so `tsc` cannot see this value at all — it was
+    // `"type==giveaway"` and the rename would have silently emptied /giveaway
+    // while still answering 200 (Root Cause #33/#99).
+    //
+    // 🛑 PIPE-joined, never comma-joined. Sieve parses `type==a|b` as one
+    // OR-group and the Firebase adapter upgrades a same-field OR-group of
+    // equalities into a single Firestore `in`. A comma is an AND, so
+    // `type==random-draw,type==giveaway` is two equalities on one field that no
+    // document can satisfy (Root Cause #59). The legacy arm can be dropped
+    // once the rename migration has run everywhere.
+    let filters = "type==random-draw|giveaway";
+    if (opts?.status)
+        filters += `,status==${opts.status}`;
+    const result = await eventRepository.list({
+        filters,
+        sorts: "-startsAt",
+        page: opts?.page ?? 1,
+        pageSize: opts?.pageSize ?? 50,
+    });
+    const items = result.items ?? [];
+    return items.map((event) => ({
+        ...event,
+        giveawayConfig: event.giveawayConfig ? toClientGiveawayConfig(event.giveawayConfig) : undefined,
+    }));
+});
+/** Fetch giveaway entries for admin view (includes phone + txId via PII decrypt). */
+export async function getGiveawayEntriesForAdmin(sourceType, sourceId, model) {
+    const field = sourceType === "event" ? "eventId" : "productId";
+    return giveawayEntryRepository.listForSource(sourceId, field, model);
+}
+/** Fetch giveaway entries for a specific user (own entries only). */
+export async function getGiveawayEntriesForUser(userId, model) {
+    return giveawayEntryRepository.listForUser(userId, model);
+}