@mohasinac/appkit 3.0.4 → 3.1.0

package/dist/features/homepage/schemas/index.d.ts

@@ -713,8 +713,8 @@ export declare const carouselSlideFirestoreSchema: z.ZodObject<{
     createdAt: string | Date | z.objectOutputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
-    id: string;
     title: string;
+    id: string;
     updatedAt: string | Date | z.objectOutputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
@@ -822,8 +822,8 @@ export declare const carouselSlideFirestoreSchema: z.ZodObject<{
     createdAt: string | Date | z.objectInputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
-    id: string;
     title: string;
+    id: string;
     updatedAt: string | Date | z.objectInputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;

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",
+};

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

@@ -0,0 +1,113 @@
+/**
+ * Zod schemas for lottery entry submission and validation.
+ */
+import { z } from "zod";
+export declare const lotteryEntrySubmitSchema: z.ZodObject<{
+    transactionId: z.ZodString;
+    paymentTime: z.ZodString;
+    purchasedItemNumber: z.ZodNumber;
+    userPhone: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    transactionId: string;
+    userPhone: string;
+    paymentTime: string;
+    purchasedItemNumber: number;
+}, {
+    transactionId: string;
+    userPhone: string;
+    paymentTime: string;
+    purchasedItemNumber: number;
+}>;
+export type LotteryEntrySubmitInput = z.infer<typeof lotteryEntrySubmitSchema>;
+/** Schema for flag action */
+export declare const flagLotteryEntrySchema: z.ZodObject<{
+    entryId: z.ZodString;
+    flagNote: z.ZodString;
+    flaggedByUserId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    flagNote: string;
+    entryId: string;
+    flaggedByUserId: string;
+}, {
+    flagNote: string;
+    entryId: string;
+    flaggedByUserId: string;
+}>;
+export type FlagLotteryEntryInput = z.infer<typeof flagLotteryEntrySchema>;
+/** Schema for reopen-slot action */
+export declare const reopenLotterySlotSchema: 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 ReopenLotterySlotInput = z.infer<typeof reopenLotterySlotSchema>;
+/** Schema for submit lottery pull (full, server-side) */
+export declare const submitLotteryPullSchema: 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;
+    userPhone: string;
+    sourceType: "product" | "event";
+    paymentTime: string;
+    purchasedItemNumber: number;
+    productId?: string | undefined;
+    userEmail?: string | undefined;
+    userDisplayName?: string | undefined;
+    eventId?: string | undefined;
+}, {
+    userId: string;
+    transactionId: string;
+    userPhone: string;
+    sourceType: "product" | "event";
+    paymentTime: string;
+    purchasedItemNumber: number;
+    productId?: string | undefined;
+    userEmail?: string | undefined;
+    userDisplayName?: string | undefined;
+    eventId?: string | undefined;
+}>, {
+    userId: string;
+    transactionId: string;
+    userPhone: string;
+    sourceType: "product" | "event";
+    paymentTime: string;
+    purchasedItemNumber: number;
+    productId?: string | undefined;
+    userEmail?: string | undefined;
+    userDisplayName?: string | undefined;
+    eventId?: string | undefined;
+}, {
+    userId: string;
+    transactionId: string;
+    userPhone: string;
+    sourceType: "product" | "event";
+    paymentTime: string;
+    purchasedItemNumber: number;
+    productId?: string | undefined;
+    userEmail?: string | undefined;
+    userDisplayName?: string | undefined;
+    eventId?: string | undefined;
+}>;
+export type SubmitLotteryPullInput = z.infer<typeof submitLotteryPullSchema>;

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

@@ -0,0 +1,39 @@
+/**
+ * Zod schemas for lottery entry submission and validation.
+ */
+import { z } from "zod";
+export const lotteryEntrySubmitSchema = 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 flagLotteryEntrySchema = 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 reopenLotterySlotSchema = 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 lottery pull (full, server-side) */
+export const submitLotteryPullSchema = 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(lotteryEntrySubmitSchema)
+    .refine((data) => (data.sourceType === "event" && !!data.eventId) ||
+    (data.sourceType === "product" && !!data.productId), { message: "eventId or productId must be provided matching sourceType" });

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

@@ -0,0 +1,67 @@
+/**
+ * Lottery feature shared types
+ *
+ * Used by both event-type lottery and prize-draw-mode lottery.
+ * Weight + price fields are server-only — never sent to client consumers.
+ */
+export interface LotterySlot {
+    slotNumber: number;
+    name: string;
+    priceInPaise: number;
+    weight: number;
+    isBooked: boolean;
+    bookedByUserLotteryNumber?: number;
+    bookedByUserId?: string;
+    bookedByDisplayName?: string;
+}
+/** Slot shape safe to expose to clients — price and weight stripped by adapter. */
+export interface ClientLotterySlot {
+    slotNumber: number;
+    name: string;
+    isBooked: boolean;
+    bookedByUserLotteryNumber?: number;
+    bookedByDisplayName?: string;
+}
+export type LotteryPricingMode = "uniform" | "variable";
+export interface LotteryConfig {
+    slots: LotterySlot[];
+    totalSlots: number;
+    pricingMode: LotteryPricingMode;
+    uniformPriceInPaise?: number;
+    drawWindowDurationMinutes: number;
+    maxPullsPerTransaction: number;
+    maxPullsPerUser: number;
+}
+/** Client-safe config shape — slots have price/weight stripped. */
+export interface ClientLotteryConfig {
+    slots: ClientLotterySlot[];
+    totalSlots: number;
+    pricingMode: LotteryPricingMode;
+    drawWindowDurationMinutes: number;
+    maxPullsPerTransaction: number;
+    maxPullsPerUser: number;
+}
+export type LotteryEntryStatus = "pending" | "drawn" | "won" | "flagged" | "cancelled";
+/** Error codes thrown by lottery actions */
+export type LotteryErrorCode = "LOTTERY_FULL" | "LOTTERY_WINDOW_CLOSED" | "USER_LIMIT_REACHED" | "TX_ALREADY_USED" | "SLOT_NOT_FOUND" | "ENTRY_NOT_FLAGGED";
+export declare class LotteryError extends Error {
+    readonly code: LotteryErrorCode;
+    constructor(code: LotteryErrorCode, 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(priceInPaise: number, maxPriceInPaise: number): number;
+/**
+ * Pick a slot using weighted random selection.
+ * @throws {LotteryError} LOTTERY_FULL when unclaimed is empty.
+ */
+export declare function pickWeightedSlot(unclaimed: LotterySlot[]): LotterySlot;
+/**
+ * Assign weights to slots based on pricing mode.
+ * Returns a new array with weight populated on every slot.
+ */
+export declare function assignSlotWeights(config: LotteryConfig): LotterySlot[];

package/dist/features/lottery/types/index.js

@@ -0,0 +1,55 @@
+/**
+ * Lottery feature shared types
+ *
+ * Used by both event-type lottery and prize-draw-mode lottery.
+ * Weight + price fields are server-only — never sent to client consumers.
+ */
+export class LotteryError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "LotteryError";
+    }
+}
+/**
+ * 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 function computeWeight(priceInPaise, maxPriceInPaise) {
+    if (maxPriceInPaise === 0)
+        return 50;
+    return Math.max(1, Math.round((1 - priceInPaise / maxPriceInPaise) * 99) + 1);
+}
+/**
+ * Pick a slot using weighted random selection.
+ * @throws {LotteryError} LOTTERY_FULL when unclaimed is empty.
+ */
+export function pickWeightedSlot(unclaimed) {
+    if (unclaimed.length === 0) {
+        throw new LotteryError("LOTTERY_FULL", "No unclaimed slots remain.");
+    }
+    const total = unclaimed.reduce((s, sl) => s + sl.weight, 0);
+    let r = Math.random() * total;
+    for (const sl of unclaimed) {
+        r -= sl.weight;
+        if (r <= 0)
+            return sl;
+    }
+    return unclaimed[unclaimed.length - 1];
+}
+/**
+ * Assign weights to slots based on pricing mode.
+ * Returns a new array with weight populated on every slot.
+ */
+export function assignSlotWeights(config) {
+    if (config.pricingMode === "uniform") {
+        return config.slots.map((sl) => ({ ...sl, weight: 50 }));
+    }
+    const maxPrice = Math.max(...config.slots.map((sl) => sl.priceInPaise), 0);
+    return config.slots.map((sl) => ({
+        ...sl,
+        weight: computeWeight(sl.priceInPaise, maxPrice),
+    }));
+}

package/dist/features/messages/repository/__tests__/conversations.repository.test.d.ts

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