@mohasinac/appkit 2.3.0 → 2.3.1

package/dist/features/admin/repository/chat.repository.js

@@ -0,0 +1,216 @@
+/**
+ * Chat Repository
+ *
+ * Manages Firestore chat room metadata documents.
+ * Actual messages are stored in Realtime Database for live streaming.
+ * This repository provides the persistent record of rooms and participants.
+ *
+ * Deletion semantics
+ * ------------------
+ * 1-1 rooms:
+ *   - `softDeleteForUser(chatId, uid)` adds the uid to `deletedBy`.
+ *   - When BOTH participants are in `deletedBy` the room is permanently deleted
+ *     (Firestore doc + RTDB subtree) by the same method.
+ *   - Until then the room is invisible only to the deleting user.
+ *
+ * Group rooms (admin-created):
+ *   - Only an admin may delete via `adminHardDelete(chatId)`.
+ *   - Sets `adminDeleted: true` and deletes the RTDB subtree.
+ *   - All participants lose access on next token refresh.
+ */
+import { getAdminRealtimeDb } from "../../../providers/db-firebase";
+import { BaseRepository } from "../../../providers/db-firebase";
+import { prepareForFirestore } from "../../../providers/db-firebase";
+import { DatabaseError } from "../../../errors";
+import { CHAT_ROOM_COLLECTION } from "../schemas";
+import { encryptPiiFields, decryptPiiFields, CHAT_PII_FIELDS, } from "../../../security";
+export { CHAT_ROOM_COLLECTION } from "../schemas";
+class ChatRepository extends BaseRepository {
+    constructor() {
+        super(CHAT_ROOM_COLLECTION);
+    }
+    /** Override mapDoc to auto-decrypt PII on every chat room read */
+    mapDoc(snap) {
+        const raw = super.mapDoc(snap);
+        return decryptPiiFields(raw, [
+            ...CHAT_PII_FIELDS,
+        ]);
+    }
+    /**
+     * Create a new chat room (buyer ↔ seller for an order)
+     */
+    async create(input) {
+        const id = input.isGroup
+            ? `chat_group_${Date.now()}`
+            : `chat_${input.buyerId}_${input.sellerId}_${input.orderId}`;
+        const doc = {
+            ...input,
+            deletedBy: [],
+            adminDeleted: false,
+            createdAt: new Date(),
+            updatedAt: new Date(),
+        };
+        const encrypted = encryptPiiFields({ ...doc }, [...CHAT_PII_FIELDS]);
+        await this.db
+            .collection(this.collection)
+            .doc(id)
+            .set(prepareForFirestore(encrypted));
+        return { id, ...doc }; // return plaintext to caller
+    }
+    /**
+     * Find existing room by buyerId + sellerId + orderId (idempotent create)
+     */
+    async findRoom(buyerId, sellerId, orderId) {
+        const id = `chat_${buyerId}_${sellerId}_${orderId}`;
+        return this.findById(id);
+    }
+    /**
+     * Get all chat room IDs that the user can currently access.
+     * Excludes rooms where the user has soft-deleted or where adminDeleted=true.
+     */
+    async getChatIdsForUser(userId) {
+        try {
+            const [asBuyer, asSeller] = await Promise.all([
+                this.getCollection()
+                    .where("buyerId", "==", userId)
+                    .where("adminDeleted", "==", false)
+                    .get(),
+                this.getCollection()
+                    .where("sellerId", "==", userId)
+                    .where("adminDeleted", "==", false)
+                    .get(),
+            ]);
+            const ids = new Set();
+            [...asBuyer.docs, ...asSeller.docs].forEach((d) => {
+                const deletedBy = d.data().deletedBy ?? [];
+                if (!deletedBy.includes(userId)) {
+                    ids.add(d.id);
+                }
+            });
+            return Array.from(ids);
+        }
+        catch (error) {
+            throw new DatabaseError(`Failed to get chatIds for user: ${userId}`, error);
+        }
+    }
+    /**
+     * List all visible rooms for a user (most recent first).
+     * Excludes rooms the user has deleted and admin-deleted group rooms.
+     */
+    async listForUser(userId) {
+        try {
+            const [asBuyer, asSeller] = await Promise.all([
+                this.getCollection()
+                    .where("buyerId", "==", userId)
+                    .where("adminDeleted", "==", false)
+                    .orderBy("updatedAt", "desc")
+                    .get(),
+                this.getCollection()
+                    .where("sellerId", "==", userId)
+                    .where("adminDeleted", "==", false)
+                    .orderBy("updatedAt", "desc")
+                    .get(),
+            ]);
+            const seen = new Set();
+            const rooms = [];
+            [...asBuyer.docs, ...asSeller.docs].forEach((d) => {
+                if (!seen.has(d.id)) {
+                    seen.add(d.id);
+                    const data = d.data();
+                    const deletedBy = data.deletedBy ?? [];
+                    // Only include rooms the user hasn't personally deleted
+                    if (!deletedBy.includes(userId)) {
+                        rooms.push(decryptPiiFields({ id: d.id, ...data }, [...CHAT_PII_FIELDS]));
+                    }
+                }
+            });
+            rooms.sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
+            return rooms;
+        }
+        catch (error) {
+            throw new DatabaseError(`Failed to list rooms for user: ${userId}`, error);
+        }
+    }
+    /**
+     * Update last message preview (called after a new message is sent)
+     */
+    async updateLastMessage(chatId, message) {
+        try {
+            await this.db
+                .collection(this.collection)
+                .doc(chatId)
+                .update(prepareForFirestore({
+                lastMessage: message.slice(0, 80),
+                lastMessageAt: new Date(),
+                updatedAt: new Date(),
+            }));
+        }
+        catch (error) {
+            throw new DatabaseError(`Failed to update last message for room: ${chatId}`, error);
+        }
+    }
+    /**
+     * Soft-delete a 1-1 chat room for a single user.
+     *
+     * - Adds `uid` to `deletedBy`.
+     * - If both participants have now deleted → permanently deletes the
+     *   Firestore document and the RTDB subtree.
+     *
+     * @returns `"hidden"` if the room was only hidden for this user,
+     *          `"deleted"` if it was permanently purged.
+     */
+    async softDeleteForUser(chatId, uid) {
+        try {
+            const docRef = this.db.collection(this.collection).doc(chatId);
+            const snap = await docRef.get();
+            if (!snap.exists)
+                return "deleted";
+            const data = snap.data();
+            const deletedBy = Array.from(new Set([...(data.deletedBy ?? []), uid]));
+            const bothDeleted = !data.isGroup &&
+                deletedBy.includes(data.buyerId) &&
+                deletedBy.includes(data.sellerId);
+            if (bothDeleted) {
+                // Permanently remove Firestore doc + RTDB messages
+                await docRef.delete();
+                try {
+                    await getAdminRealtimeDb().ref(`/chat/${chatId}`).remove();
+                }
+                catch {
+                    // Non-fatal — RTDB subtree cleanup is best-effort
+                }
+                return "deleted";
+            }
+            // Otherwise just record this user's deletion
+            await docRef.update(prepareForFirestore({ deletedBy, updatedAt: new Date() }));
+            return "hidden";
+        }
+        catch (error) {
+            throw new DatabaseError(`Failed to soft-delete room ${chatId} for user ${uid}`, error);
+        }
+    }
+    /**
+     * Admin hard-delete for group chats.
+     *
+     * Sets `adminDeleted: true` in Firestore (revokes all access) and
+     * removes the RTDB subtree.
+     */
+    async adminHardDelete(chatId) {
+        try {
+            await this.db
+                .collection(this.collection)
+                .doc(chatId)
+                .update(prepareForFirestore({ adminDeleted: true, updatedAt: new Date() }));
+            try {
+                await getAdminRealtimeDb().ref(`/chat/${chatId}`).remove();
+            }
+            catch {
+                // Non-fatal
+            }
+        }
+        catch (error) {
+            throw new DatabaseError(`Failed to admin-delete group room ${chatId}`, error);
+        }
+    }
+}
+export const chatRepository = new ChatRepository();

package/dist/features/admin/repository/notification.repository.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Notification Repository
+ *
+ * Handles all Firestore operations for the notifications collection.
+ * Used exclusively by server-side API routes (Firebase Admin SDK).
+ */
+import type { DocumentReference, WriteBatch } from "firebase-admin/firestore";
+import { BaseRepository } from "../../../providers/db-firebase";
+import { NotificationDocument, NotificationCreateInput } from "../schemas";
+import type { SieveModel, FirebaseSieveFields, FirebaseSieveResult } from "../../../providers/db-firebase";
+export declare class NotificationRepository extends BaseRepository<NotificationDocument> {
+    constructor();
+    /**
+     * Sieve field definitions for admin/user paginated listing
+     */
+    static readonly SIEVE_FIELDS: FirebaseSieveFields;
+    /**
+     * Admin-level paginated notification list (all users).
+     */
+    list(model: SieveModel): Promise<FirebaseSieveResult<NotificationDocument>>;
+    /**
+     * User-scoped paginated notification list.
+     */
+    listForUser(userId: string, model: SieveModel): Promise<FirebaseSieveResult<NotificationDocument>>;
+    /**
+     * Find all notifications for a user, newest first.
+     */
+    findByUser(userId: string, limit?: number): Promise<NotificationDocument[]>;
+    /**
+     * Get unread notification count for a user.
+     */
+    getUnreadCount(userId: string): Promise<number>;
+    /**
+     * Mark a single notification as read.
+     */
+    markAsRead(id: string): Promise<NotificationDocument | null>;
+    /**
+     * Mark all unread notifications for a user as read.
+     */
+    markAllAsRead(userId: string): Promise<number>;
+    /**
+     * Create a new notification.
+     */
+    create(input: NotificationCreateInput): Promise<NotificationDocument>;
+    /**
+     * Delete a notification by ID.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Delete all notifications for a user.
+     */
+    deleteAllForUser(userId: string): Promise<number>;
+    /**
+     * Cloud Functions: return refs of old read notifications for TTL-based cleanup.
+     */
+    getOldReadRefs(ttlDays?: number): Promise<DocumentReference[]>;
+    /**
+     * Cloud Functions: stage notification creation into a caller-owned WriteBatch.
+     * Returns the new DocumentReference synchronously for chaining.
+     */
+    createInBatch(batch: WriteBatch, input: NotificationCreateInput): DocumentReference;
+}
+export declare const notificationRepository: NotificationRepository;

package/dist/features/admin/repository/notification.repository.js

@@ -0,0 +1,227 @@
+/**
+ * Notification Repository
+ *
+ * Handles all Firestore operations for the notifications collection.
+ * Used exclusively by server-side API routes (Firebase Admin SDK).
+ */
+import { BaseRepository, getFirestoreCount, prepareForFirestore, } from "../../../providers/db-firebase";
+import { NOTIFICATIONS_COLLECTION, NOTIFICATION_FIELDS, } from "../schemas";
+import { serverLogger } from "../../../monitoring";
+import { serverTimestamp } from "../../../contracts/field-ops";
+export class NotificationRepository extends BaseRepository {
+    constructor() {
+        super(NOTIFICATIONS_COLLECTION);
+    }
+    /**
+     * Admin-level paginated notification list (all users).
+     */
+    async list(model) {
+        return this.sieveQuery(model, NotificationRepository.SIEVE_FIELDS);
+    }
+    /**
+     * User-scoped paginated notification list.
+     */
+    async listForUser(userId, model) {
+        return this.sieveQuery(model, NotificationRepository.SIEVE_FIELDS, {
+            baseQuery: this.getCollection().where(NOTIFICATION_FIELDS.USER_ID, "==", userId),
+        });
+    }
+    /**
+     * Find all notifications for a user, newest first.
+     */
+    async findByUser(userId, limit = 20) {
+        try {
+            const snap = await this.getCollection()
+                .where(NOTIFICATION_FIELDS.USER_ID, "==", userId)
+                .orderBy(NOTIFICATION_FIELDS.CREATED_AT, "desc")
+                .limit(limit)
+                .get();
+            return snap.docs.map((doc) => this.mapDoc(doc));
+        }
+        catch (error) {
+            serverLogger.error("Failed to fetch user notifications", {
+                userId,
+                error,
+            });
+            throw error;
+        }
+    }
+    /**
+     * Get unread notification count for a user.
+     */
+    async getUnreadCount(userId) {
+        try {
+            return await getFirestoreCount(this.getCollection()
+                .where(NOTIFICATION_FIELDS.USER_ID, "==", userId)
+                .where(NOTIFICATION_FIELDS.IS_READ, "==", false));
+        }
+        catch (error) {
+            serverLogger.error("Failed to count unread notifications", {
+                userId,
+                error,
+            });
+            return 0;
+        }
+    }
+    /**
+     * Mark a single notification as read.
+     */
+    async markAsRead(id) {
+        try {
+            const now = new Date();
+            await this.getCollection()
+                .doc(id)
+                .update(prepareForFirestore({
+                [NOTIFICATION_FIELDS.IS_READ]: true,
+                [NOTIFICATION_FIELDS.READ_AT]: now,
+                [NOTIFICATION_FIELDS.UPDATED_AT]: now,
+            }));
+            return this.findById(id);
+        }
+        catch (error) {
+            serverLogger.error("Failed to mark notification as read", { id, error });
+            throw error;
+        }
+    }
+    /**
+     * Mark all unread notifications for a user as read.
+     */
+    async markAllAsRead(userId) {
+        try {
+            const snap = await this.getCollection()
+                .where(NOTIFICATION_FIELDS.USER_ID, "==", userId)
+                .where(NOTIFICATION_FIELDS.IS_READ, "==", false)
+                .get();
+            if (snap.empty)
+                return 0;
+            const now = new Date();
+            const batch = this.db.batch();
+            snap.docs.forEach((doc) => {
+                batch.update(doc.ref, prepareForFirestore({
+                    [NOTIFICATION_FIELDS.IS_READ]: true,
+                    [NOTIFICATION_FIELDS.READ_AT]: now,
+                    [NOTIFICATION_FIELDS.UPDATED_AT]: now,
+                }));
+            });
+            await batch.commit();
+            serverLogger.info("Marked all notifications as read", {
+                userId,
+                count: snap.size,
+            });
+            return snap.size;
+        }
+        catch (error) {
+            serverLogger.error("Failed to mark all notifications as read", {
+                userId,
+                error,
+            });
+            throw error;
+        }
+    }
+    /**
+     * Create a new notification.
+     */
+    async create(input) {
+        try {
+            const now = new Date();
+            const data = prepareForFirestore({
+                ...input,
+                isRead: false,
+                createdAt: now,
+                updatedAt: now,
+            });
+            const ref = this.getCollection().doc();
+            await ref.set(data);
+            serverLogger.info("Notification created", {
+                id: ref.id,
+                userId: input.userId,
+                type: input.type,
+            });
+            return { id: ref.id, ...data };
+        }
+        catch (error) {
+            serverLogger.error("Failed to create notification", { error });
+            throw error;
+        }
+    }
+    /**
+     * Delete a notification by ID.
+     */
+    async delete(id) {
+        try {
+            await this.getCollection().doc(id).delete();
+            serverLogger.info("Notification deleted", { id });
+        }
+        catch (error) {
+            serverLogger.error("Failed to delete notification", { id, error });
+            throw error;
+        }
+    }
+    /**
+     * Delete all notifications for a user.
+     */
+    async deleteAllForUser(userId) {
+        try {
+            const snap = await this.getCollection()
+                .where(NOTIFICATION_FIELDS.USER_ID, "==", userId)
+                .get();
+            if (snap.empty)
+                return 0;
+            const batch = this.db.batch();
+            snap.docs.forEach((doc) => batch.delete(doc.ref));
+            await batch.commit();
+            serverLogger.info("Deleted all user notifications", {
+                userId,
+                count: snap.size,
+            });
+            return snap.size;
+        }
+        catch (error) {
+            serverLogger.error("Failed to delete all user notifications", {
+                userId,
+                error,
+            });
+            throw error;
+        }
+    }
+    /**
+     * Cloud Functions: return refs of old read notifications for TTL-based cleanup.
+     */
+    async getOldReadRefs(ttlDays = 30) {
+        const cutoff = new Date();
+        cutoff.setDate(cutoff.getDate() - ttlDays);
+        const snap = await this.getCollection()
+            .where(NOTIFICATION_FIELDS.IS_READ, "==", true)
+            .where(NOTIFICATION_FIELDS.CREATED_AT, "<", cutoff)
+            .limit(500)
+            .get();
+        return snap.docs.map((d) => d.ref);
+    }
+    /**
+     * Cloud Functions: stage notification creation into a caller-owned WriteBatch.
+     * Returns the new DocumentReference synchronously for chaining.
+     */
+    createInBatch(batch, input) {
+        const ref = this.getCollection().doc();
+        batch.create(ref, prepareForFirestore({
+            id: ref.id,
+            ...input,
+            isRead: false,
+            createdAt: serverTimestamp(),
+            updatedAt: serverTimestamp(),
+        }));
+        return ref;
+    }
+}
+/**
+ * Sieve field definitions for admin/user paginated listing
+ */
+NotificationRepository.SIEVE_FIELDS = {
+    userId: { canFilter: true, canSort: false },
+    type: { canFilter: true, canSort: false },
+    priority: { canFilter: true, canSort: true },
+    isRead: { canFilter: true, canSort: false },
+    relatedType: { canFilter: true, canSort: false },
+    createdAt: { canFilter: true, canSort: true },
+};
+export const notificationRepository = new NotificationRepository();

package/dist/features/admin/repository/site-settings.repository.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Site Settings Repository
+ *
+ * Manages site-wide configuration settings (singleton document)
+ */
+import { BaseRepository } from "../../../providers/db-firebase";
+import { SiteSettingsDocument, SiteSettingsCredentialsMasked, SiteSettingsUpdateInput } from "../schemas";
+/**
+ * Repository for site settings management
+ *
+ * Note: Site settings is a singleton document with ID "global"
+ */
+export declare class SiteSettingsRepository extends BaseRepository<SiteSettingsDocument> {
+    /**
+     * Singleton document ID
+     */
+    private readonly SINGLETON_ID;
+    private static readonly CACHE_TTL_MS;
+    constructor();
+    private cacheKey;
+    /**
+     * Get the global site settings
+     * Creates default settings if not exists
+     *
+     * @returns Promise<SiteSettingsDocument>
+     */
+    getSingleton(): Promise<SiteSettingsDocument>;
+    /**
+     * Update the global site settings
+     *
+     * Credentials are encrypted before being written to Firestore.
+     * Pass an empty string for a credential field to leave it unchanged.
+     *
+     * @param updates - Partial updates to apply
+     * @returns Promise<SiteSettingsDocument>
+     */
+    updateSingleton(updates: SiteSettingsUpdateInput): Promise<SiteSettingsDocument>;
+    /**
+     * Decrypt all stored provider credentials.
+     * FOR INTERNAL BACKEND USE ONLY — never return plaintext to the client.
+     *
+     * Falls back gracefully: returns an empty string for any field that
+     * cannot be decrypted (wrong key, missing value, etc.).
+     */
+    getDecryptedCredentials(): Promise<Record<string, string>>;
+    /**
+     * Return masked credential values for the admin UI (e.g. "rzp_li…key4").
+     * Safe to include in API responses for authenticated admins.
+     */
+    getCredentialsMasked(): Promise<SiteSettingsCredentialsMasked>;
+    /**
+     * Get FAQ variables for interpolation
+     *
+     * @returns Promise<Record<string, string | number>>
+     */
+    getFAQVariables(): Promise<Record<string, string | number>>;
+    /**
+     * Update FAQ variables
+     *
+     * @param variables - New FAQ variable values
+     * @returns Promise<void>
+     */
+    updateFAQVariables(variables: {
+        shippingDays: number;
+        minOrderValue: number;
+        returnWindow: number;
+        supportEmail: string;
+        supportPhone: string;
+        codDeposit: number;
+    }): Promise<void>;
+    /**
+     * Get site features
+     *
+     * @returns Promise<Array<{id, icon, title, description}>>
+     */
+    getFeatures(): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        icon: string;
+        enabled: boolean;
+    }[]>;
+    /**
+     * Update site features
+     *
+     * @param features - New features array
+     * @returns Promise<void>
+     */
+    updateFeatures(features: Array<{
+        id: string;
+        name: string;
+        description: string;
+        icon: string;
+        enabled: boolean;
+    }>): Promise<void>;
+    /**
+     * Get email settings for transactional emails
+     *
+     * @returns Promise<{fromName, fromEmail, replyTo}>
+     */
+    getEmailSettings(): Promise<{
+        fromName: string;
+        fromEmail: string;
+        replyTo: string;
+    }>;
+    /**
+     * Check if site settings exist
+     *
+     * @returns Promise<boolean>
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Reset site settings to defaults
+     * WARNING: This will overwrite all custom settings
+     *
+     * @returns Promise<SiteSettingsDocument>
+     */
+    resetToDefaults(): Promise<SiteSettingsDocument>;
+}
+export declare const siteSettingsRepository: SiteSettingsRepository;