@mohasinac/appkit 3.0.6 → 3.1.1

package/dist/features/homepage/api/route.d.ts

@@ -9,6 +9,6 @@
  */
 import { NextResponse } from "next/server.js";
 export declare function GET(request: Request): Promise<NextResponse>;
-export declare const POST: (request: Request, context: {
+export declare const POST: (request: Request, context?: {
     params: Promise<Record<string, string>>;
-}) => Promise<Response>;
+} | undefined) => Promise<Response>;

package/dist/features/homepage/repository/__tests__/carousel.repository.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/features/homepage/repository/__tests__/carousel.repository.test.js

@@ -0,0 +1,182 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { makeMockDb, makeSnap, makeQuerySnap } from "../../../../../tests/helpers/mock-firestore";
+import { DatabaseError } from "../../../../errors";
+const { db, mockDocRef, mockCollection, mockQuery, mockBatch } = makeMockDb();
+const { mockGetFirestoreCount } = vi.hoisted(() => ({
+    mockGetFirestoreCount: vi.fn().mockResolvedValue(0),
+}));
+vi.mock("../../../../providers/db-firebase/admin", () => ({
+    getAdminDb: () => db,
+}));
+vi.mock("../../../../providers/db-firebase", async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        prepareForFirestore: (d) => d,
+        getFirestoreCount: mockGetFirestoreCount,
+    };
+});
+vi.mock("../../../../errors/normalize", () => ({
+    normalizeError: vi.fn(),
+}));
+import { CarouselRepository } from "../carousel.repository";
+import { MAX_ACTIVE_SLIDES } from "../../schemas";
+const repo = new CarouselRepository();
+function makeSlideDoc(overrides = {}) {
+    return {
+        id: "slide-hero",
+        title: "Hero Slide",
+        active: true,
+        order: 0,
+        cards: [],
+        background: { type: "image", url: "https://example.com/img.jpg" },
+        createdBy: "admin-1",
+        createdAt: new Date(),
+        updatedAt: new Date(),
+        ...overrides,
+    };
+}
+function makeActiveSlides(count) {
+    return Array.from({ length: count }, (_, i) => ({
+        id: `slide-${i}`,
+        data: makeSlideDoc({ id: `slide-${i}`, active: true, order: i }),
+    }));
+}
+beforeEach(() => {
+    vi.clearAllMocks();
+    db.collection.mockReturnValue(mockCollection);
+    mockCollection.doc.mockReturnValue(mockDocRef);
+    mockCollection.where.mockReturnValue(mockQuery);
+    mockQuery.where.mockReturnValue(mockQuery);
+    mockQuery.orderBy.mockReturnValue(mockQuery);
+    mockQuery.limit.mockReturnValue(mockQuery);
+    mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+    mockDocRef.get.mockResolvedValue(makeSnap(null));
+    mockDocRef.set.mockResolvedValue(undefined);
+    mockDocRef.update.mockResolvedValue(undefined);
+    db.batch.mockReturnValue(mockBatch);
+    mockGetFirestoreCount.mockResolvedValue(0);
+});
+// ---------------------------------------------------------------------------
+// activateSlide
+// ---------------------------------------------------------------------------
+describe("CarouselRepository.activateSlide", () => {
+    it("activates when active count < MAX_ACTIVE_SLIDES", async () => {
+        // getActiveSlides returns fewer than max
+        mockQuery.get.mockResolvedValue(makeQuerySnap(makeActiveSlides(MAX_ACTIVE_SLIDES - 1)));
+        const slide = makeSlideDoc({ active: true });
+        mockDocRef.get.mockResolvedValue(makeSnap(slide, "slide-hero"));
+        await repo.activateSlide("slide-hero");
+        expect(mockDocRef.update).toHaveBeenCalledWith(expect.objectContaining({ active: true }));
+    });
+    it("throws DatabaseError when active count = MAX_ACTIVE_SLIDES", async () => {
+        mockQuery.get.mockResolvedValue(makeQuerySnap(makeActiveSlides(MAX_ACTIVE_SLIDES)));
+        await expect(repo.activateSlide("slide-7")).rejects.toThrow(DatabaseError);
+    });
+    it("throws DatabaseError when active count > MAX_ACTIVE_SLIDES (defensive)", async () => {
+        mockQuery.get.mockResolvedValue(makeQuerySnap(makeActiveSlides(MAX_ACTIVE_SLIDES + 1)));
+        await expect(repo.activateSlide("slide-7")).rejects.toThrow(DatabaseError);
+    });
+});
+// ---------------------------------------------------------------------------
+// deactivateSlide
+// ---------------------------------------------------------------------------
+describe("CarouselRepository.deactivateSlide", () => {
+    it("sets active: false on the slide", async () => {
+        const slide = makeSlideDoc({ active: false });
+        mockDocRef.get.mockResolvedValue(makeSnap(slide, "slide-hero"));
+        await repo.deactivateSlide("slide-hero");
+        expect(mockDocRef.update).toHaveBeenCalledWith(expect.objectContaining({ active: false }));
+    });
+    it("sets updatedAt timestamp", async () => {
+        const slide = makeSlideDoc();
+        mockDocRef.get.mockResolvedValue(makeSnap(slide, "slide-hero"));
+        await repo.deactivateSlide("slide-hero");
+        expect(mockDocRef.update).toHaveBeenCalledWith(expect.objectContaining({ updatedAt: expect.any(Date) }));
+    });
+});
+// ---------------------------------------------------------------------------
+// canActivateMore
+// ---------------------------------------------------------------------------
+describe("CarouselRepository.canActivateMore", () => {
+    it("returns true when active count < MAX_ACTIVE_SLIDES", async () => {
+        mockGetFirestoreCount.mockResolvedValue(MAX_ACTIVE_SLIDES - 1);
+        const result = await repo.canActivateMore();
+        expect(result).toBe(true);
+    });
+    it("returns false when active count = MAX_ACTIVE_SLIDES", async () => {
+        mockGetFirestoreCount.mockResolvedValue(MAX_ACTIVE_SLIDES);
+        const result = await repo.canActivateMore();
+        expect(result).toBe(false);
+    });
+    it("returns false when active count > MAX_ACTIVE_SLIDES", async () => {
+        mockGetFirestoreCount.mockResolvedValue(MAX_ACTIVE_SLIDES + 2);
+        const result = await repo.canActivateMore();
+        expect(result).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------------
+// reorderSlides
+// ---------------------------------------------------------------------------
+describe("CarouselRepository.reorderSlides", () => {
+    it("batch-updates order field on each slide", async () => {
+        await repo.reorderSlides([
+            { id: "slide-1", order: 0 },
+            { id: "slide-2", order: 1 },
+            { id: "slide-3", order: 2 },
+        ]);
+        expect(mockBatch.update).toHaveBeenCalledTimes(3);
+    });
+    it("commits the batch", async () => {
+        await repo.reorderSlides([{ id: "slide-1", order: 0 }]);
+        expect(mockBatch.commit).toHaveBeenCalledOnce();
+    });
+    it("each update carries the correct order value", async () => {
+        await repo.reorderSlides([
+            { id: "slide-a", order: 2 },
+            { id: "slide-b", order: 5 },
+        ]);
+        const updateCalls = mockBatch.update.mock.calls;
+        const orders = updateCalls.map((c) => c[1].order);
+        expect(orders).toContain(2);
+        expect(orders).toContain(5);
+    });
+    it("empty list → no batch update called, commits empty batch", async () => {
+        await repo.reorderSlides([]);
+        expect(mockBatch.update).not.toHaveBeenCalled();
+        expect(mockBatch.commit).toHaveBeenCalledOnce();
+    });
+});
+// ---------------------------------------------------------------------------
+// incrementViews
+// ---------------------------------------------------------------------------
+describe("CarouselRepository.incrementViews", () => {
+    it("increments stats.views by 1", async () => {
+        await repo.incrementViews("slide-hero");
+        expect(mockDocRef.update).toHaveBeenCalledWith(expect.objectContaining({ "stats.views": expect.anything() }));
+    });
+    it("updates stats.lastViewed timestamp", async () => {
+        await repo.incrementViews("slide-hero");
+        expect(mockDocRef.update).toHaveBeenCalledWith(expect.objectContaining({ "stats.lastViewed": expect.any(Date) }));
+    });
+    it("swallows errors — analytics must not break callers", async () => {
+        mockDocRef.update.mockRejectedValue(new Error("Firestore error"));
+        await expect(repo.incrementViews("slide-hero")).resolves.toBeUndefined();
+    });
+});
+// ---------------------------------------------------------------------------
+// getActiveSlides
+// ---------------------------------------------------------------------------
+describe("CarouselRepository.getActiveSlides", () => {
+    it("queries active=true, ordered by order ascending", async () => {
+        mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+        await repo.getActiveSlides();
+        expect(mockCollection.where).toHaveBeenCalledWith("active", "==", true);
+        expect(mockQuery.orderBy).toHaveBeenCalledWith("order", "asc");
+    });
+    it("limits results to MAX_ACTIVE_SLIDES", async () => {
+        mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+        await repo.getActiveSlides();
+        expect(mockQuery.limit).toHaveBeenCalledWith(MAX_ACTIVE_SLIDES);
+    });
+});

package/dist/features/homepage/repository/__tests__/homepage-sections.repository.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/features/homepage/repository/__tests__/homepage-sections.repository.test.js

@@ -0,0 +1,185 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { makeMockDb, makeSnap, makeQuerySnap } from "../../../../../tests/helpers/mock-firestore";
+const { db, mockDocRef, mockCollection, mockQuery, mockBatch } = makeMockDb();
+vi.mock("../../../../providers/db-firebase/admin", () => ({
+    getAdminDb: () => db,
+}));
+vi.mock("../../../../providers/db-firebase", async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        prepareForFirestore: (d) => d,
+    };
+});
+vi.mock("../../../../errors/normalize", () => ({
+    normalizeError: vi.fn(),
+}));
+import { HomepageSectionsRepository } from "../homepage-sections.repository";
+const repo = new HomepageSectionsRepository();
+function makeSectionDoc(overrides = {}) {
+    return {
+        id: "section-featured-products",
+        type: "featured-products",
+        enabled: true,
+        order: 0,
+        config: {},
+        createdAt: new Date(),
+        updatedAt: new Date(),
+        ...overrides,
+    };
+}
+beforeEach(() => {
+    vi.clearAllMocks();
+    db.collection.mockReturnValue(mockCollection);
+    mockCollection.doc.mockReturnValue(mockDocRef);
+    mockCollection.where.mockReturnValue(mockQuery);
+    mockQuery.where.mockReturnValue(mockQuery);
+    mockQuery.orderBy.mockReturnValue(mockQuery);
+    mockQuery.limit.mockReturnValue(mockQuery);
+    mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+    mockDocRef.get.mockResolvedValue(makeSnap(null));
+    mockDocRef.set.mockResolvedValue(undefined);
+    mockDocRef.update.mockResolvedValue(undefined);
+    db.batch.mockReturnValue(mockBatch);
+});
+// ---------------------------------------------------------------------------
+// getEnabledSections
+// ---------------------------------------------------------------------------
+describe("HomepageSectionsRepository.getEnabledSections", () => {
+    it("queries where enabled=true, ordered by order ascending", async () => {
+        mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+        await repo.getEnabledSections();
+        expect(mockCollection.where).toHaveBeenCalledWith("enabled", "==", true);
+        expect(mockQuery.orderBy).toHaveBeenCalledWith("order", "asc");
+    });
+    it("returns only enabled sections", async () => {
+        const section = makeSectionDoc({ enabled: true });
+        mockQuery.get.mockResolvedValue(makeQuerySnap([{ id: section.id, data: section }]));
+        const results = await repo.getEnabledSections();
+        expect(results).toHaveLength(1);
+    });
+    it("returns empty array when no enabled sections", async () => {
+        mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+        const results = await repo.getEnabledSections();
+        expect(results).toHaveLength(0);
+    });
+});
+// ---------------------------------------------------------------------------
+// enableSection
+// ---------------------------------------------------------------------------
+describe("HomepageSectionsRepository.enableSection", () => {
+    it("sets enabled: true on the section", async () => {
+        const section = makeSectionDoc({ enabled: false });
+        mockDocRef.get.mockResolvedValue(makeSnap(section, "section-1"));
+        await repo.enableSection("section-1");
+        expect(mockDocRef.update).toHaveBeenCalledWith(expect.objectContaining({ enabled: true }));
+    });
+    it("sets updatedAt timestamp", async () => {
+        const section = makeSectionDoc();
+        mockDocRef.get.mockResolvedValue(makeSnap(section, "section-1"));
+        await repo.enableSection("section-1");
+        expect(mockDocRef.update).toHaveBeenCalledWith(expect.objectContaining({ updatedAt: expect.any(Date) }));
+    });
+});
+// ---------------------------------------------------------------------------
+// disableSection
+// ---------------------------------------------------------------------------
+describe("HomepageSectionsRepository.disableSection", () => {
+    it("sets enabled: false on the section", async () => {
+        const section = makeSectionDoc({ enabled: true });
+        mockDocRef.get.mockResolvedValue(makeSnap(section, "section-1"));
+        await repo.disableSection("section-1");
+        expect(mockDocRef.update).toHaveBeenCalledWith(expect.objectContaining({ enabled: false }));
+    });
+});
+// ---------------------------------------------------------------------------
+// toggleSection
+// ---------------------------------------------------------------------------
+describe("HomepageSectionsRepository.toggleSection", () => {
+    it("enabled:true → sets enabled:false", async () => {
+        const section = makeSectionDoc({ enabled: true });
+        mockDocRef.get.mockResolvedValue(makeSnap(section, "section-1"));
+        await repo.toggleSection("section-1");
+        expect(mockDocRef.update).toHaveBeenCalledWith(expect.objectContaining({ enabled: false }));
+    });
+    it("enabled:false → sets enabled:true", async () => {
+        const section = makeSectionDoc({ enabled: false });
+        mockDocRef.get.mockResolvedValue(makeSnap(section, "section-1"));
+        await repo.toggleSection("section-1");
+        expect(mockDocRef.update).toHaveBeenCalledWith(expect.objectContaining({ enabled: true }));
+    });
+});
+// ---------------------------------------------------------------------------
+// reorderSections
+// ---------------------------------------------------------------------------
+describe("HomepageSectionsRepository.reorderSections", () => {
+    it("batch-updates order field for each section", async () => {
+        await repo.reorderSections([
+            { id: "section-1", order: 0 },
+            { id: "section-2", order: 1 },
+            { id: "section-3", order: 2 },
+        ]);
+        expect(mockBatch.update).toHaveBeenCalledTimes(3);
+        expect(mockBatch.commit).toHaveBeenCalledOnce();
+    });
+    it("each update sets the correct order value", async () => {
+        await repo.reorderSections([
+            { id: "section-a", order: 5 },
+            { id: "section-b", order: 10 },
+        ]);
+        const calls = mockBatch.update.mock.calls;
+        expect(calls.some((c) => c[1].order === 5)).toBe(true);
+        expect(calls.some((c) => c[1].order === 10)).toBe(true);
+    });
+    it("empty list → no batch update, commits empty batch", async () => {
+        await repo.reorderSections([]);
+        expect(mockBatch.update).not.toHaveBeenCalled();
+        expect(mockBatch.commit).toHaveBeenCalledOnce();
+    });
+});
+// ---------------------------------------------------------------------------
+// batchToggleSections
+// ---------------------------------------------------------------------------
+describe("HomepageSectionsRepository.batchToggleSections", () => {
+    it("sets enabled:true on all provided sections in one batch", async () => {
+        await repo.batchToggleSections(["section-1", "section-2", "section-3"], true);
+        expect(mockBatch.update).toHaveBeenCalledTimes(3);
+        const calls = mockBatch.update.mock.calls;
+        expect(calls.every((c) => c[1].enabled === true)).toBe(true);
+        expect(mockBatch.commit).toHaveBeenCalledOnce();
+    });
+    it("sets enabled:false on all provided sections", async () => {
+        await repo.batchToggleSections(["section-x", "section-y"], false);
+        const calls = mockBatch.update.mock.calls;
+        expect(calls.every((c) => c[1].enabled === false)).toBe(true);
+    });
+    it("empty list → no updates, commits empty batch", async () => {
+        await repo.batchToggleSections([], true);
+        expect(mockBatch.update).not.toHaveBeenCalled();
+        expect(mockBatch.commit).toHaveBeenCalledOnce();
+    });
+});
+// ---------------------------------------------------------------------------
+// resetSectionToDefault
+// ---------------------------------------------------------------------------
+describe("HomepageSectionsRepository.resetSectionToDefault", () => {
+    it("overwrites config with the provided default config", async () => {
+        const section = makeSectionDoc({ config: { customKey: "old-value" } });
+        mockDocRef.get.mockResolvedValue(makeSnap(section, "section-1"));
+        const defaultCfg = { title: "Default Title", itemCount: 6 };
+        await repo.resetSectionToDefault("section-1", defaultCfg);
+        expect(mockDocRef.update).toHaveBeenCalledWith(expect.objectContaining({ config: defaultCfg }));
+    });
+    it("does NOT delete the section document", async () => {
+        const section = makeSectionDoc();
+        mockDocRef.get.mockResolvedValue(makeSnap(section, "section-1"));
+        await repo.resetSectionToDefault("section-1", {});
+        expect(mockDocRef.delete).not.toHaveBeenCalled();
+    });
+    it("sets updatedAt timestamp on reset", async () => {
+        const section = makeSectionDoc();
+        mockDocRef.get.mockResolvedValue(makeSnap(section, "section-1"));
+        await repo.resetSectionToDefault("section-1", {});
+        expect(mockDocRef.update).toHaveBeenCalledWith(expect.objectContaining({ updatedAt: expect.any(Date) }));
+    });
+});

package/dist/features/lottery/repository/lottery-entry.repository.d.ts

@@ -0,0 +1,33 @@
+import type { FirebaseSieveFields, FirebaseSieveResult, SieveModel } from "../../../providers/db-firebase";
+import { BaseRepository } from "../../../providers/db-firebase";
+import { type LotteryEntryDocument } from "../schemas/firestore";
+declare class LotteryEntryRepository extends BaseRepository<LotteryEntryDocument> {
+    static readonly SIEVE_FIELDS: FirebaseSieveFields;
+    constructor();
+    protected mapDoc<D = LotteryEntryDocument>(snap: import("../../../providers/db-firebase").DocumentSnapshot): D;
+    /**
+     * Get the next sequential userLotteryNumber for a source atomically.
+     * Returns current count + 1.
+     */
+    nextUserLotteryNumber(sourceId: string, field: "eventId" | "productId"): Promise<number>;
+    /**
+     * Count entries for a given source and transaction ID.
+     * Used to enforce maxPullsPerTransaction.
+     */
+    countByTransactionId(sourceId: string, sourceField: "eventId" | "productId", transactionId: string): Promise<number>;
+    /**
+     * Count entries for a given source and user.
+     * Used to enforce maxPullsPerUser.
+     */
+    countByUser(sourceId: string, sourceField: "eventId" | "productId", userId: string): Promise<number>;
+    /** List all entries for an event/product source. Paginated via Sieve. */
+    listForSource(sourceId: string, sourceField: "eventId" | "productId", model: SieveModel): Promise<FirebaseSieveResult<LotteryEntryDocument>>;
+    /** List entries for a specific user across all sources. */
+    listForUser(userId: string, model: SieveModel): Promise<FirebaseSieveResult<LotteryEntryDocument>>;
+    /** Create a lottery entry with PII encryption. */
+    createEntry(data: Omit<LotteryEntryDocument, "id">): Promise<LotteryEntryDocument>;
+    /** Flag a lottery entry as fraudulent. */
+    flagEntry(entryId: string, flagNote: string, flaggedBy: string): Promise<LotteryEntryDocument>;
+}
+export { LotteryEntryRepository };
+export declare const lotteryEntryRepository: LotteryEntryRepository;

package/dist/features/lottery/repository/lottery-entry.repository.js

@@ -0,0 +1,130 @@
+import { normalizeError } from "../../../errors/normalize";
+import { DatabaseError } from "../../../errors";
+import { serverLogger } from "../../../monitoring";
+import { BaseRepository, prepareForFirestore, } from "../../../providers/db-firebase";
+import { decryptPiiFields, encryptPiiFields, LOTTERY_ENTRY_PII_FIELDS, } from "../../../security";
+import { LOTTERY_ENTRIES_COLLECTION, LOTTERY_ENTRY_FIELDS, } from "../schemas/firestore";
+class LotteryEntryRepository extends BaseRepository {
+    constructor() {
+        super(LOTTERY_ENTRIES_COLLECTION);
+    }
+    mapDoc(snap) {
+        const raw = super.mapDoc(snap);
+        return decryptPiiFields(raw, [
+            ...LOTTERY_ENTRY_PII_FIELDS,
+        ]);
+    }
+    /**
+     * Get the next sequential userLotteryNumber for a source atomically.
+     * Returns current count + 1.
+     */
+    async nextUserLotteryNumber(sourceId, field) {
+        try {
+            const snapshot = await this.getCollection()
+                .where(field, "==", sourceId)
+                .get();
+            return snapshot.size + 1;
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError(`Failed to get next lottery number for ${field}=${sourceId}`, error);
+        }
+    }
+    /**
+     * Count entries for a given source and transaction ID.
+     * Used to enforce maxPullsPerTransaction.
+     */
+    async countByTransactionId(sourceId, sourceField, transactionId) {
+        try {
+            const snapshot = await this.getCollection()
+                .where(sourceField, "==", sourceId)
+                .where(LOTTERY_ENTRY_FIELDS.TRANSACTION_ID, "==", transactionId)
+                .get();
+            return snapshot.size;
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError(`Failed to count entries for transactionId=${transactionId}`, error);
+        }
+    }
+    /**
+     * Count entries for a given source and user.
+     * Used to enforce maxPullsPerUser.
+     */
+    async countByUser(sourceId, sourceField, userId) {
+        try {
+            const snapshot = await this.getCollection()
+                .where(sourceField, "==", sourceId)
+                .where(LOTTERY_ENTRY_FIELDS.USER_ID, "==", userId)
+                .where(LOTTERY_ENTRY_FIELDS.STATUS, "!=", "cancelled")
+                .get();
+            return snapshot.size;
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError(`Failed to count entries for userId=${userId}`, error);
+        }
+    }
+    /** List all entries for an event/product source. Paginated via Sieve. */
+    async listForSource(sourceId, sourceField, model) {
+        return this.sieveQuery(model, LotteryEntryRepository.SIEVE_FIELDS, {
+            baseQuery: this.getCollection().where(sourceField, "==", sourceId),
+        });
+    }
+    /** List entries for a specific user across all sources. */
+    async listForUser(userId, model) {
+        return this.sieveQuery(model, LotteryEntryRepository.SIEVE_FIELDS, {
+            baseQuery: this.getCollection().where(LOTTERY_ENTRY_FIELDS.USER_ID, "==", userId),
+        });
+    }
+    /** Create a lottery entry with PII encryption. */
+    async createEntry(data) {
+        try {
+            const encrypted = encryptPiiFields(data, [...LOTTERY_ENTRY_PII_FIELDS]);
+            const prepared = prepareForFirestore({ ...encrypted });
+            const ref = await this.getCollection().add(prepared);
+            const created = await ref.get();
+            serverLogger.info("Lottery entry created", {
+                entryId: ref.id,
+                sourceType: data.sourceType,
+                eventId: data.eventId,
+                productId: data.productId,
+                userId: data.userId,
+                userLotteryNumber: data.userLotteryNumber,
+            });
+            return this.mapDoc(created);
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError("Failed to create lottery entry", error);
+        }
+    }
+    /** Flag a lottery entry as fraudulent. */
+    async flagEntry(entryId, flagNote, flaggedBy) {
+        try {
+            await this.getCollection().doc(entryId).update(prepareForFirestore({
+                isFlagged: true,
+                flagNote,
+                flaggedBy,
+                flaggedAt: new Date(),
+                status: "flagged",
+            }));
+            return this.findByIdOrFail(entryId);
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError(`Failed to flag lottery entry ${entryId}`, error);
+        }
+    }
+}
+LotteryEntryRepository.SIEVE_FIELDS = {
+    sourceType: { canFilter: true, canSort: false },
+    eventId: { canFilter: true, canSort: false },
+    productId: { canFilter: true, canSort: false },
+    userId: { canFilter: true, canSort: false },
+    status: { canFilter: true, canSort: false },
+    submittedAt: { canFilter: true, canSort: true },
+    userLotteryNumber: { canFilter: false, canSort: true },
+};
+export { LotteryEntryRepository };
+export const lotteryEntryRepository = new LotteryEntryRepository();

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

@@ -0,0 +1,49 @@
+/**
+ * LotteryEntry Firestore Document Type & Constants
+ */
+import type { LotteryEntryStatus } from "../types";
+export declare const LOTTERY_ENTRIES_COLLECTION: "lotteryEntries";
+export interface LotteryEntryDocument {
+    id: string;
+    sourceType: "event" | "product";
+    /** Set when sourceType === "event" */
+    eventId?: string;
+    /** Set when sourceType === "product" */
+    productId?: string;
+    userId: string;
+    userDisplayName?: string;
+    /** PII — encrypted at rest */
+    userEmail?: string;
+    /** PII — encrypted at rest; required */
+    userPhone: 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 */
+    userLotteryNumber: number;
+    /** Filled after draw — assigned slot number */
+    assignedPrizeSlotNumber?: number;
+    status: LotteryEntryStatus;
+    isFlagged: boolean;
+    flagNote?: string;
+    flaggedBy?: string;
+    flaggedAt?: Date;
+    submittedAt: Date;
+    drawnAt?: Date;
+}
+export declare const LOTTERY_ENTRY_INDEXED_FIELDS: readonly ["sourceType", "eventId", "productId", "userId", "status", "submittedAt", "userLotteryNumber"];
+/** Canonical field name constants for lotteryEntries collection — use instead of hardcoded strings. */
+export declare const LOTTERY_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_LOTTERY_NUMBER: "userLotteryNumber";
+    readonly IS_FLAGGED: "isFlagged";
+};

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

@@ -0,0 +1,25 @@
+/**
+ * LotteryEntry Firestore Document Type & Constants
+ */
+export const LOTTERY_ENTRIES_COLLECTION = "lotteryEntries";
+export const LOTTERY_ENTRY_INDEXED_FIELDS = [
+    "sourceType",
+    "eventId",
+    "productId",
+    "userId",
+    "status",
+    "submittedAt",
+    "userLotteryNumber",
+];
+/** Canonical field name constants for lotteryEntries collection — use instead of hardcoded strings. */
+export const LOTTERY_ENTRY_FIELDS = {
+    SOURCE_TYPE: "sourceType",
+    EVENT_ID: "eventId",
+    PRODUCT_ID: "productId",
+    USER_ID: "userId",
+    STATUS: "status",
+    TRANSACTION_ID: "transactionId",
+    SUBMITTED_AT: "submittedAt",
+    USER_LOTTERY_NUMBER: "userLotteryNumber",
+    IS_FLAGGED: "isFlagged",
+};