@mohasinac/appkit 3.0.4 → 3.1.0

package/dist/features/admin/repository/__tests__/site-settings.repository.test.js

@@ -0,0 +1,298 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { makeMockDb, makeSnap } from "../../../../../tests/helpers/mock-firestore";
+const { db, mockDocRef, mockCollection } = makeMockDb();
+const { mockCacheManager, mockDecryptSecret } = vi.hoisted(() => ({
+    mockCacheManager: {
+        get: vi.fn().mockReturnValue(null),
+        set: vi.fn(),
+        delete: vi.fn(),
+    },
+    mockDecryptSecret: vi.fn((v) => v.replace("enc:", "")),
+}));
+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("../../../../core", () => ({
+    cacheManager: mockCacheManager,
+}));
+vi.mock("../../../../security", () => ({
+    encryptSecret: (v) => `enc:${v}`,
+    decryptSecret: mockDecryptSecret,
+    maskSecret: (v) => `${v.slice(0, 4)}***`,
+}));
+vi.mock("../../../../errors/normalize", () => ({
+    normalizeError: vi.fn(),
+}));
+vi.mock("../../../../monitoring", () => ({
+    serverLogger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+import { SiteSettingsRepository } from "../site-settings.repository";
+// Create a fresh repo per test to avoid shared state from `siteSettingsRepository` singleton
+function makeRepo() {
+    return new SiteSettingsRepository();
+}
+function makeSettingsDoc(overrides = {}) {
+    return {
+        id: "global",
+        siteName: "LetItRip",
+        credentials: {},
+        featureFlags: { useMockPayment: false, useMockShipping: false },
+        features: [],
+        createdAt: new Date(),
+        updatedAt: new Date(),
+        ...overrides,
+    };
+}
+beforeEach(() => {
+    vi.clearAllMocks();
+    mockCacheManager.get.mockReturnValue(null);
+    mockDecryptSecret.mockImplementation((v) => v.replace("enc:", ""));
+    db.collection.mockReturnValue(mockCollection);
+    mockCollection.doc.mockReturnValue(mockDocRef);
+    const settingsDoc = makeSettingsDoc();
+    mockDocRef.get.mockResolvedValue(makeSnap(settingsDoc, "global"));
+    mockDocRef.set.mockResolvedValue(undefined);
+    mockDocRef.update.mockResolvedValue(undefined);
+});
+// ---------------------------------------------------------------------------
+// getSingleton
+// ---------------------------------------------------------------------------
+describe("SiteSettingsRepository.getSingleton", () => {
+    it("returns cached value without hitting Firestore when cache is warm", async () => {
+        const cached = makeSettingsDoc({ siteName: "Cached LetItRip" });
+        mockCacheManager.get.mockReturnValue(cached);
+        const repo = makeRepo();
+        const result = await repo.getSingleton();
+        expect(result.siteName).toBe("Cached LetItRip");
+        expect(mockDocRef.get).not.toHaveBeenCalled();
+    });
+    it("fetches from Firestore when cache is cold (null)", async () => {
+        mockCacheManager.get.mockReturnValue(null);
+        const repo = makeRepo();
+        await repo.getSingleton();
+        expect(mockDocRef.get).toHaveBeenCalledOnce();
+    });
+    it("populates cache after Firestore fetch", async () => {
+        mockCacheManager.get.mockReturnValue(null);
+        const settingsDoc = makeSettingsDoc();
+        mockDocRef.get.mockResolvedValue(makeSnap(settingsDoc, "global"));
+        const repo = makeRepo();
+        await repo.getSingleton();
+        expect(mockCacheManager.set).toHaveBeenCalledWith(expect.stringContaining("site-settings"), expect.anything(), expect.objectContaining({ ttl: expect.any(Number) }));
+    });
+    it("creates default settings when document does not exist", async () => {
+        mockDocRef.get.mockResolvedValue(makeSnap(null));
+        const repo = makeRepo();
+        await repo.getSingleton();
+        expect(mockDocRef.set).toHaveBeenCalledOnce();
+    });
+    it("returns default settings when document does not exist", async () => {
+        mockDocRef.get.mockResolvedValue(makeSnap(null));
+        const repo = makeRepo();
+        const result = await repo.getSingleton();
+        expect(result.id).toBe("global");
+        expect(result.createdAt).toBeInstanceOf(Date);
+    });
+    it("caches the newly-created default settings", async () => {
+        mockDocRef.get.mockResolvedValue(makeSnap(null));
+        const repo = makeRepo();
+        await repo.getSingleton();
+        expect(mockCacheManager.set).toHaveBeenCalledWith(expect.stringContaining("site-settings"), expect.anything(), expect.objectContaining({ ttl: expect.any(Number) }));
+    });
+});
+// ---------------------------------------------------------------------------
+// updateSingleton
+// ---------------------------------------------------------------------------
+describe("SiteSettingsRepository.updateSingleton", () => {
+    it("clears cache before writing", async () => {
+        const repo = makeRepo();
+        await repo.updateSingleton({ branding: { siteName: "New Name" } });
+        expect(mockCacheManager.delete).toHaveBeenCalledWith(expect.stringContaining("site-settings"));
+        // delete happens before the update
+        const deleteCallOrder = mockCacheManager.delete.mock.invocationCallOrder[0];
+        const updateCallOrder = mockDocRef.update.mock.invocationCallOrder[0];
+        expect(deleteCallOrder).toBeLessThan(updateCallOrder);
+    });
+    it("writes updatedAt timestamp", async () => {
+        const repo = makeRepo();
+        await repo.updateSingleton({ branding: { siteName: "New" } });
+        const updateArg = mockDocRef.update.mock.calls[0][0];
+        expect(updateArg.updatedAt).toBeInstanceOf(Date);
+    });
+    it("encrypts credential values before writing", async () => {
+        const settingsDoc = makeSettingsDoc({ credentials: {} });
+        mockDocRef.get.mockResolvedValue(makeSnap(settingsDoc, "global"));
+        const repo = makeRepo();
+        await repo.updateSingleton({
+            credentials: { razorpayKeyId: "rzp_live_abc123" },
+        });
+        const updateArg = mockDocRef.update.mock.calls[0][0];
+        const creds = updateArg.credentials;
+        expect(creds.razorpayKeyId).toBe("enc:rzp_live_abc123");
+    });
+    it("does not overwrite existing credential with empty string", async () => {
+        const settingsDoc = makeSettingsDoc({
+            credentials: { razorpayKeyId: "enc:existing-key" },
+        });
+        mockDocRef.get.mockResolvedValue(makeSnap(settingsDoc, "global"));
+        const repo = makeRepo();
+        await repo.updateSingleton({
+            credentials: { razorpayKeyId: "" },
+        });
+        const updateArg = mockDocRef.update.mock.calls[0][0];
+        const creds = updateArg.credentials;
+        // Empty string → keep existing
+        expect(creds.razorpayKeyId).toBe("enc:existing-key");
+    });
+    it("re-caches the latest settings after update", async () => {
+        const repo = makeRepo();
+        await repo.updateSingleton({ branding: { siteName: "Updated" } });
+        // getSingleton is called after update to get latest — cacheManager.set re-called
+        expect(mockCacheManager.set).toHaveBeenCalled();
+    });
+});
+// ---------------------------------------------------------------------------
+// getDecryptedCredentials
+// ---------------------------------------------------------------------------
+describe("SiteSettingsRepository.getDecryptedCredentials", () => {
+    it("returns decrypted API key values", async () => {
+        const settingsDoc = makeSettingsDoc({
+            credentials: { razorpayKeyId: "enc:rzp_live_abc123" },
+        });
+        mockDocRef.get.mockResolvedValue(makeSnap(settingsDoc, "global"));
+        const repo = makeRepo();
+        const result = await repo.getDecryptedCredentials();
+        expect(result.razorpayKeyId).toBe("rzp_live_abc123");
+    });
+    it("falls back to empty string when decryption fails", async () => {
+        mockDecryptSecret.mockImplementationOnce(() => {
+            throw new Error("auth-tag mismatch");
+        });
+        const settingsDoc = makeSettingsDoc({
+            credentials: { razorpayKeyId: "corrupt-blob" },
+        });
+        mockDocRef.get.mockResolvedValue(makeSnap(settingsDoc, "global"));
+        const repo = makeRepo();
+        const result = await repo.getDecryptedCredentials();
+        expect(result.razorpayKeyId).toBe("");
+    });
+    it("returns empty object when no credentials stored", async () => {
+        const settingsDoc = makeSettingsDoc({ credentials: {} });
+        mockDocRef.get.mockResolvedValue(makeSnap(settingsDoc, "global"));
+        const repo = makeRepo();
+        const result = await repo.getDecryptedCredentials();
+        expect(Object.keys(result)).toHaveLength(0);
+    });
+});
+// ---------------------------------------------------------------------------
+// getCredentialsMasked
+// ---------------------------------------------------------------------------
+describe("SiteSettingsRepository.getCredentialsMasked", () => {
+    it("replaces credential values with masked versions", async () => {
+        const settingsDoc = makeSettingsDoc({
+            credentials: { razorpayKeyId: "enc:rzp_live_abc123" },
+        });
+        mockDocRef.get.mockResolvedValue(makeSnap(settingsDoc, "global"));
+        const repo = makeRepo();
+        const result = await repo.getCredentialsMasked();
+        // maskSecret("rzp_live_abc123") → "rzp_***" per our mock
+        expect(result.razorpayKeyId).toBe("rzp_***");
+    });
+    it("does not expose raw or encrypted credential values", async () => {
+        const settingsDoc = makeSettingsDoc({
+            credentials: { razorpayKeyId: "enc:secret-key" },
+        });
+        mockDocRef.get.mockResolvedValue(makeSnap(settingsDoc, "global"));
+        const repo = makeRepo();
+        const result = await repo.getCredentialsMasked();
+        expect(result.razorpayKeyId).not.toContain("secret-key");
+        expect(result.razorpayKeyId).not.toContain("enc:");
+    });
+    it("empty/falsy credential value → key omitted from masked output", async () => {
+        // getDecryptedCredentials skips falsy values; getCredentialsMasked
+        // only iterates decrypted keys → empty stored credential does not appear in output
+        const settingsDoc = makeSettingsDoc({ credentials: { razorpayKeyId: "" } });
+        mockDocRef.get.mockResolvedValue(makeSnap(settingsDoc, "global"));
+        const repo = makeRepo();
+        const result = await repo.getCredentialsMasked();
+        expect(result).not.toHaveProperty("razorpayKeyId");
+    });
+});
+// ---------------------------------------------------------------------------
+// getFeatures / updateFeatures
+// ---------------------------------------------------------------------------
+describe("SiteSettingsRepository.getFeatures", () => {
+    it("returns the features array from settings", async () => {
+        const features = [{ id: "f-1", name: "Fast Checkout", description: "Quick buy", icon: "zap", enabled: true }];
+        const settingsDoc = makeSettingsDoc({ features });
+        mockDocRef.get.mockResolvedValue(makeSnap(settingsDoc, "global"));
+        const repo = makeRepo();
+        const result = await repo.getFeatures();
+        expect(result).toHaveLength(1);
+        expect(result[0].name).toBe("Fast Checkout");
+    });
+    it("returns empty array when no features stored", async () => {
+        const settingsDoc = makeSettingsDoc({ features: undefined });
+        mockDocRef.get.mockResolvedValue(makeSnap(settingsDoc, "global"));
+        const repo = makeRepo();
+        const result = await repo.getFeatures();
+        expect(result).toEqual([]);
+    });
+});
+describe("SiteSettingsRepository.updateFeatures", () => {
+    it("writes features array to Firestore", async () => {
+        const repo = makeRepo();
+        const features = [{ id: "f-1", name: "F1", description: "D1", icon: "star", enabled: true }];
+        await repo.updateFeatures(features);
+        expect(mockDocRef.update).toHaveBeenCalled();
+        const updateArg = mockDocRef.update.mock.calls[0][0];
+        expect(updateArg.features).toEqual(features);
+    });
+});
+// ---------------------------------------------------------------------------
+// exists
+// ---------------------------------------------------------------------------
+describe("SiteSettingsRepository.exists", () => {
+    it("returns true when singleton document exists", async () => {
+        mockDocRef.get.mockResolvedValue(makeSnap(makeSettingsDoc(), "global"));
+        const repo = makeRepo();
+        const result = await repo.exists();
+        expect(result).toBe(true);
+    });
+    it("returns false when document does not exist", async () => {
+        mockDocRef.get.mockResolvedValue(makeSnap(null));
+        const repo = makeRepo();
+        const result = await repo.exists();
+        expect(result).toBe(false);
+    });
+    it("returns false when Firestore throws", async () => {
+        mockDocRef.get.mockRejectedValue(new Error("Firestore unavailable"));
+        const repo = makeRepo();
+        const result = await repo.exists();
+        expect(result).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------------
+// resetToDefaults
+// ---------------------------------------------------------------------------
+describe("SiteSettingsRepository.resetToDefaults", () => {
+    it("overwrites the singleton with default settings", async () => {
+        const repo = makeRepo();
+        await repo.resetToDefaults();
+        expect(mockDocRef.set).toHaveBeenCalledOnce();
+        const setArg = mockDocRef.set.mock.calls[0][0];
+        expect(setArg.id).toBe("global");
+    });
+    it("caches the reset defaults", async () => {
+        const repo = makeRepo();
+        await repo.resetToDefaults();
+        expect(mockCacheManager.set).toHaveBeenCalledWith(expect.stringContaining("site-settings"), expect.anything(), expect.objectContaining({ ttl: expect.any(Number) }));
+    });
+});

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

@@ -4,9 +4,9 @@
  */
 export declare const ADMIN_CHECKOUT_BYPASS_FLAG_KEY: "adminCheckoutBypass";
 export type NotificationType = "order_placed" | "order_confirmed" | "order_shipped" | "order_delivered" | "order_cancelled" | "bid_placed" | "bid_outbid" | "bid_won" | "bid_lost" | "review_approved" | "review_replied" | "product_available" | "promotion" | "system" | "welcome" | "account_action" | "offer_received" | "offer_responded" | "offer_expired" | "offer_counter_accepted" | "refund_initiated" | "prize_reveal_ready" | "prize_reveal_expired" | "prize_reveal_reminder";
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 export type NotificationPriority = "low" | "normal" | "high";
-export interface NotificationDocument {
-    id: string;
+export interface NotificationDocument extends BaseDocument {
     userId: string;
     type: NotificationType;
     priority: NotificationPriority;
@@ -19,8 +19,6 @@ export interface NotificationDocument {
     readAt?: Date;
     relatedId?: string;
     relatedType?: "order" | "product" | "bid" | "review" | "blog" | "user" | "offer" | "support_ticket" | "scammer";
-    createdAt: Date;
-    updatedAt: Date;
 }
 export declare const NOTIFICATIONS_COLLECTION: "notifications";
 export declare const NOTIFICATIONS_INDEXED_FIELDS: readonly ["userId", "isRead", "createdAt", "type"];
@@ -81,8 +79,7 @@ export declare const notificationQueryHelpers: {
     readonly unread: (userId: string) => readonly [readonly ["userId", "==", string], readonly ["isRead", "==", false]];
     readonly byType: (type: NotificationType) => readonly ["type", "==", NotificationType];
 };
-export interface ChatRoomDocument {
-    id: string;
+export interface ChatRoomDocument extends BaseDocument {
     buyerId: string;
     ownerId: string;
     orderId: string;
@@ -92,8 +89,6 @@ export interface ChatRoomDocument {
     ownerName: string;
     lastMessage?: string;
     lastMessageAt?: Date;
-    createdAt: Date;
-    updatedAt: Date;
     /** UIDs of participants who soft-deleted this room on their side. */
     deletedBy: string[];
     /** True for admin-created group chats (> 2 participants). */

package/dist/features/auctions/repository/__tests__/bid.repository.test.d.ts

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

package/dist/features/auctions/repository/__tests__/bid.repository.test.js

@@ -0,0 +1,290 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { makeMockDb, makeSnap, makeQuerySnap } from "../../../../../tests/helpers/mock-firestore";
+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(),
+}));
+vi.mock("../../../../security", () => ({
+    encryptPiiFields: (d) => d,
+    decryptPiiFields: (d) => d,
+    BID_PII_FIELDS: [],
+}));
+import { BidRepository } from "../bid.repository";
+const repo = new BidRepository();
+function makeBidDoc(overrides = {}) {
+    return {
+        id: "bid-1",
+        productId: "auction-x",
+        bidderId: "user-1",
+        userId: "user-1",
+        userName: "Ravi",
+        userEmail: "ravi@test.com",
+        bidAmount: 5000,
+        status: "active",
+        isWinning: false,
+        bidDate: new Date(),
+        createdAt: new Date(),
+        updatedAt: new Date(),
+        ...overrides,
+    };
+}
+function makeFakeRef(id = "bid-1") {
+    return { id };
+}
+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);
+    db.batch.mockReturnValue(mockBatch);
+    mockGetFirestoreCount.mockResolvedValue(0);
+});
+// ---------------------------------------------------------------------------
+// markWon / markLost / markOutbid / markWinning (batch helpers)
+// ---------------------------------------------------------------------------
+describe("BidRepository.markWon", () => {
+    it("stages status=won, isWinning=true in caller batch", () => {
+        const ref = makeFakeRef();
+        repo.markWon(mockBatch, ref);
+        expect(mockBatch.update).toHaveBeenCalledWith(ref, expect.objectContaining({ status: "won", isWinning: true }));
+        expect(mockBatch.commit).not.toHaveBeenCalled();
+    });
+});
+describe("BidRepository.markLost", () => {
+    it("stages status=lost, isWinning=false in caller batch", () => {
+        const ref = makeFakeRef();
+        repo.markLost(mockBatch, ref);
+        expect(mockBatch.update).toHaveBeenCalledWith(ref, expect.objectContaining({ status: "lost", isWinning: false }));
+    });
+});
+describe("BidRepository.markOutbid", () => {
+    it("stages status=outbid, isWinning=false in caller batch", () => {
+        const ref = makeFakeRef();
+        repo.markOutbid(mockBatch, ref);
+        expect(mockBatch.update).toHaveBeenCalledWith(ref, expect.objectContaining({ status: "outbid", isWinning: false }));
+    });
+});
+describe("BidRepository.markWinning", () => {
+    it("stages isWinning=true (does not change status) in caller batch", () => {
+        const ref = makeFakeRef();
+        repo.markWinning(mockBatch, ref);
+        expect(mockBatch.update).toHaveBeenCalledWith(ref, expect.objectContaining({ isWinning: true }));
+    });
+});
+// ---------------------------------------------------------------------------
+// getWinningBid
+// ---------------------------------------------------------------------------
+describe("BidRepository.getWinningBid", () => {
+    it("returns {ref, data} for the winning active bid", async () => {
+        const bid = makeBidDoc({ isWinning: true, status: "active" });
+        const snap = makeSnap(bid, bid.id);
+        mockQuery.get.mockResolvedValue({ ...makeQuerySnap([{ id: bid.id, data: bid }]), docs: [snap], empty: false });
+        const result = await repo.getWinningBid("auction-x");
+        expect(result).not.toBeNull();
+        expect(result.data).toBeDefined();
+    });
+    it("returns null when no winning bid", async () => {
+        mockQuery.get.mockResolvedValue({ ...makeQuerySnap([]), empty: true, docs: [] });
+        const result = await repo.getWinningBid("auction-x");
+        expect(result).toBeNull();
+    });
+    it("queries by isWinning=true AND status=active", async () => {
+        mockQuery.get.mockResolvedValue({ docs: [], empty: true });
+        await repo.getWinningBid("auction-x");
+        expect(mockQuery.where).toHaveBeenCalledWith("isWinning", "==", true);
+        expect(mockQuery.where).toHaveBeenCalledWith("status", "==", "active");
+    });
+});
+// ---------------------------------------------------------------------------
+// findWinningBid
+// ---------------------------------------------------------------------------
+describe("BidRepository.findWinningBid", () => {
+    it("returns BidDocument for winning bid", async () => {
+        const bid = makeBidDoc({ isWinning: true });
+        const snap = makeSnap(bid, bid.id);
+        mockQuery.get.mockResolvedValue({ docs: [snap], empty: false });
+        const result = await repo.findWinningBid("auction-x");
+        expect(result).not.toBeNull();
+    });
+    it("returns null when no winning bid", async () => {
+        mockQuery.get.mockResolvedValue({ docs: [], empty: true });
+        const result = await repo.findWinningBid("auction-x");
+        expect(result).toBeNull();
+    });
+    it("queries by isWinning=true (no status filter unlike getWinningBid)", async () => {
+        mockQuery.get.mockResolvedValue({ docs: [], empty: true });
+        await repo.findWinningBid("auction-x");
+        expect(mockQuery.where).toHaveBeenCalledWith("isWinning", "==", true);
+        // findWinningBid does NOT filter by status — that's the distinction from getWinningBid
+        const statusFilterCalls = mockQuery.where.mock.calls.filter((call) => call[0] === "status");
+        expect(statusFilterCalls).toHaveLength(0);
+    });
+});
+// ---------------------------------------------------------------------------
+// findHighestBid
+// ---------------------------------------------------------------------------
+describe("BidRepository.findHighestBid", () => {
+    it("returns highest bidAmount from active bids", async () => {
+        const bid = makeBidDoc({ bidAmount: 8000, status: "active" });
+        const snap = makeSnap(bid, bid.id);
+        mockQuery.get.mockResolvedValue({ docs: [snap], empty: false });
+        const result = await repo.findHighestBid("auction-x");
+        expect(result).toBe(8000);
+    });
+    it("returns 0 when no bids exist", async () => {
+        mockQuery.get.mockResolvedValue({ docs: [], empty: true });
+        const result = await repo.findHighestBid("auction-x");
+        expect(result).toBe(0);
+    });
+    it("queries by status=active, ordered by bidAmount desc", async () => {
+        mockQuery.get.mockResolvedValue({ docs: [], empty: true });
+        await repo.findHighestBid("auction-x");
+        expect(mockQuery.where).toHaveBeenCalledWith("status", "==", "active");
+        expect(mockQuery.orderBy).toHaveBeenCalledWith("bidAmount", "desc");
+    });
+});
+// ---------------------------------------------------------------------------
+// setWinningBid
+// ---------------------------------------------------------------------------
+describe("BidRepository.setWinningBid", () => {
+    it("sets all other bids for product to outbid", async () => {
+        const bid1 = makeBidDoc({ id: "bid-1", isWinning: false });
+        const bid2 = makeBidDoc({ id: "bid-2", isWinning: false });
+        const snap1 = makeSnap(bid1, "bid-1");
+        const snap2 = makeSnap(bid2, "bid-2");
+        mockQuery.get.mockResolvedValue({ docs: [snap1, snap2], empty: false });
+        await repo.setWinningBid("bid-1", "auction-x");
+        expect(mockBatch.update).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ status: "outbid" }));
+    });
+    it("sets the winning bid to status=active, isWinning=true", async () => {
+        const bid = makeBidDoc({ id: "bid-winner" });
+        const snap = makeSnap(bid, "bid-winner");
+        mockQuery.get.mockResolvedValue({ docs: [snap], empty: false });
+        await repo.setWinningBid("bid-winner", "auction-x");
+        // The winning bid ref is updated separately with isWinning=true
+        const updateCalls = mockBatch.update.mock.calls;
+        const winningCall = updateCalls.find((c) => c[1].isWinning === true);
+        expect(winningCall).toBeDefined();
+        expect(winningCall[1].status).toBe("active");
+    });
+    it("commits the batch", async () => {
+        mockQuery.get.mockResolvedValue({ docs: [], empty: true });
+        await repo.setWinningBid("bid-1", "auction-x");
+        expect(mockBatch.commit).toHaveBeenCalledOnce();
+    });
+});
+// ---------------------------------------------------------------------------
+// endAuction
+// ---------------------------------------------------------------------------
+describe("BidRepository.endAuction", () => {
+    it("isWinning bid → status=won", async () => {
+        const winBid = makeBidDoc({ id: "bid-win", isWinning: true });
+        const snap = makeSnap(winBid, "bid-win");
+        mockQuery.get.mockResolvedValue({ docs: [snap], empty: false });
+        await repo.endAuction("auction-x");
+        expect(mockBatch.update).toHaveBeenCalledWith(snap.ref, expect.objectContaining({ status: "won" }));
+    });
+    it("non-winning bids → status=lost", async () => {
+        const loseBid = makeBidDoc({ id: "bid-lose", isWinning: false });
+        const snap = makeSnap(loseBid, "bid-lose");
+        mockQuery.get.mockResolvedValue({ docs: [snap], empty: false });
+        await repo.endAuction("auction-x");
+        expect(mockBatch.update).toHaveBeenCalledWith(snap.ref, expect.objectContaining({ status: "lost" }));
+    });
+    it("commits the batch", async () => {
+        mockQuery.get.mockResolvedValue({ docs: [], empty: true });
+        await repo.endAuction("auction-x");
+        expect(mockBatch.commit).toHaveBeenCalledOnce();
+    });
+});
+// ---------------------------------------------------------------------------
+// cancelProductBids
+// ---------------------------------------------------------------------------
+describe("BidRepository.cancelProductBids", () => {
+    it("sets all bids to status=cancelled", async () => {
+        const bid = makeBidDoc({ id: "bid-1" });
+        const snap = makeSnap(bid, "bid-1");
+        mockQuery.get.mockResolvedValue({ docs: [snap], empty: false });
+        await repo.cancelProductBids("auction-x");
+        expect(mockBatch.update).toHaveBeenCalledWith(snap.ref, expect.objectContaining({ status: "cancelled", isWinning: false }));
+    });
+    it("commits the batch", async () => {
+        mockQuery.get.mockResolvedValue({ docs: [], empty: true });
+        await repo.cancelProductBids("auction-x");
+        expect(mockBatch.commit).toHaveBeenCalledOnce();
+    });
+});
+// ---------------------------------------------------------------------------
+// countByProduct / countByUser
+// ---------------------------------------------------------------------------
+describe("BidRepository.countByProduct", () => {
+    it("returns count from getFirestoreCount", async () => {
+        mockGetFirestoreCount.mockResolvedValue(7);
+        const count = await repo.countByProduct("auction-x");
+        expect(count).toBe(7);
+    });
+    it("queries by productId", async () => {
+        await repo.countByProduct("auction-x");
+        expect(mockCollection.where).toHaveBeenCalledWith("productId", "==", "auction-x");
+    });
+});
+describe("BidRepository.countByUser", () => {
+    it("returns count from getFirestoreCount", async () => {
+        mockGetFirestoreCount.mockResolvedValue(3);
+        const count = await repo.countByUser("user-1");
+        expect(count).toBe(3);
+    });
+    it("queries by userId", async () => {
+        await repo.countByUser("user-1");
+        expect(mockCollection.where).toHaveBeenCalledWith("userId", "==", "user-1");
+    });
+});
+// ---------------------------------------------------------------------------
+// findOneByProductAndUser
+// ---------------------------------------------------------------------------
+describe("BidRepository.findOneByProductAndUser", () => {
+    it("returns matching bid", async () => {
+        const bid = makeBidDoc({ productId: "auction-x", userId: "user-1", status: "active" });
+        const snap = makeSnap(bid, bid.id);
+        mockQuery.get.mockResolvedValue({ docs: [snap], empty: false });
+        const result = await repo.findOneByProductAndUser("auction-x", "user-1");
+        expect(result).not.toBeNull();
+    });
+    it("returns null when not found", async () => {
+        mockQuery.get.mockResolvedValue({ docs: [], empty: true });
+        const result = await repo.findOneByProductAndUser("auction-x", "user-2");
+        expect(result).toBeNull();
+    });
+    it("defaults status to 'active'", async () => {
+        mockQuery.get.mockResolvedValue({ docs: [], empty: true });
+        await repo.findOneByProductAndUser("auction-x", "user-1");
+        expect(mockQuery.where).toHaveBeenCalledWith("status", "==", "active");
+    });
+    it("queries by all three conditions: productId, userId, status", async () => {
+        mockQuery.get.mockResolvedValue({ docs: [], empty: true });
+        await repo.findOneByProductAndUser("auction-x", "user-1", "outbid");
+        expect(mockQuery.where).toHaveBeenCalledWith("productId", "==", "auction-x");
+        expect(mockQuery.where).toHaveBeenCalledWith("userId", "==", "user-1");
+        expect(mockQuery.where).toHaveBeenCalledWith("status", "==", "outbid");
+    });
+});

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

@@ -2,6 +2,7 @@
  * Bids/Auctions Firestore Document Types & Constants
  */
 import { type GenerateBidIdInput } from "../../../utils/id-generators";
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 export type BidStatus = "active" | "outbid" | "won" | "lost" | "cancelled";
 /** Runtime-accessible bid status values — use instead of bare string literals. */
 export declare const BidStatusValues: {
@@ -11,8 +12,7 @@ export declare const BidStatusValues: {
     readonly LOST: "lost";
     readonly CANCELLED: "cancelled";
 };
-export interface BidDocument {
-    id: string;
+export interface BidDocument extends BaseDocument {
     productId: string;
     productTitle: string;
     userId: string;
@@ -25,8 +25,6 @@ export interface BidDocument {
     previousBidAmount?: number;
     bidDate: Date;
     autoMaxBid?: number;
-    createdAt: Date;
-    updatedAt: Date;
 }
 export declare const BID_COLLECTION: "bids";
 export declare const BID_INDEXED_FIELDS: readonly ["productId", "userId", "status", "isWinning", "bidDate", "createdAt"];