@mohasinac/appkit 3.0.4 → 3.1.0

package/dist/features/history/repository/__tests__/user-history.repository.test.js

@@ -0,0 +1,180 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { makeMockDb, makeSnap } from "../../../../../tests/helpers/mock-firestore";
+const { db, mockDocRef, mockTxn } = makeMockDb();
+vi.mock("../../../../providers/db-firebase", () => ({
+    getAdminDb: () => db,
+}));
+vi.mock("../../../../monitoring", () => ({
+    serverLogger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+import { UserHistoryRepository } from "../user-history.repository";
+import { HISTORY_MAX } from "../../../../constants/limits";
+const repo = new UserHistoryRepository();
+function makeHistoryItems(count, baseDate = new Date("2026-01-01")) {
+    return Array.from({ length: count }, (_, i) => ({
+        productId: `product-${i}`,
+        productType: "product",
+        viewedAt: new Date(baseDate.getTime() - i * 1000),
+    }));
+}
+beforeEach(() => {
+    vi.clearAllMocks();
+    db.runTransaction.mockImplementation(async (fn) => fn(mockTxn));
+    mockDocRef.get.mockResolvedValue(makeSnap(null));
+    mockTxn.get.mockResolvedValue(makeSnap(null));
+    mockTxn.set.mockReturnValue(undefined);
+});
+describe("UserHistoryRepository.track", () => {
+    it("empty history → items has 1 entry, returns 1", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap({ userId: "u", items: [], updatedAt: new Date() }));
+        const count = await repo.track("u", { productId: "product-x", productType: "product" });
+        expect(count).toBe(1);
+        expect(mockTxn.set).toHaveBeenCalledOnce();
+    });
+    it("49 items + new productId → 50 items, new at position 0", async () => {
+        const items = makeHistoryItems(49);
+        mockTxn.get.mockResolvedValue(makeSnap({ userId: "u", items, updatedAt: new Date() }));
+        const count = await repo.track("u", { productId: "product-new", productType: "product" });
+        expect(count).toBe(50);
+        const setCall = mockTxn.set.mock.calls[0][1];
+        expect(setCall.items[0].productId).toBe("product-new");
+    });
+    it("50 items + new productId → evicts last item, stays at 50 (FIFO)", async () => {
+        const items = makeHistoryItems(HISTORY_MAX);
+        mockTxn.get.mockResolvedValue(makeSnap({ userId: "u", items, updatedAt: new Date() }));
+        const count = await repo.track("u", { productId: "product-new", productType: "product" });
+        expect(count).toBe(HISTORY_MAX);
+        const setCall = mockTxn.set.mock.calls[0][1];
+        expect(setCall.items).toHaveLength(HISTORY_MAX);
+        expect(setCall.items[0].productId).toBe("product-new");
+        // Last item from original list is evicted
+        expect(setCall.items[HISTORY_MAX - 1].productId).not.toBe(`product-${HISTORY_MAX - 1}`);
+    });
+    it("revisit existing productId → removes old, inserts at position 0, length unchanged", async () => {
+        const items = [
+            { productId: "product-A", productType: "product", viewedAt: new Date("2026-01-03") },
+            { productId: "product-B", productType: "product", viewedAt: new Date("2026-01-02") },
+            { productId: "product-C", productType: "product", viewedAt: new Date("2026-01-01") },
+        ];
+        mockTxn.get.mockResolvedValue(makeSnap({ userId: "u", items, updatedAt: new Date() }));
+        const count = await repo.track("u", { productId: "product-C", productType: "product" });
+        expect(count).toBe(3);
+        const setCall = mockTxn.set.mock.calls[0][1];
+        expect(setCall.items[0].productId).toBe("product-C");
+        expect(setCall.items.filter((i) => i.productId === "product-C")).toHaveLength(1);
+    });
+    it("uses db.runTransaction", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap({ userId: "u", items: [], updatedAt: new Date() }));
+        await repo.track("u", { productId: "product-x", productType: "product" });
+        expect(db.runTransaction).toHaveBeenCalledOnce();
+    });
+    it("stores viewedAt as current timestamp when not provided", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap({ userId: "u", items: [], updatedAt: new Date() }));
+        const before = Date.now();
+        await repo.track("u", { productId: "product-x", productType: "product" });
+        const after = Date.now();
+        const setCall = mockTxn.set.mock.calls[0][1];
+        const ts = setCall.items[0].viewedAt.getTime();
+        expect(ts).toBeGreaterThanOrEqual(before);
+        expect(ts).toBeLessThanOrEqual(after);
+    });
+});
+describe("UserHistoryRepository.merge", () => {
+    it("guest items merged into empty history → all items present", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap({ userId: "u", items: [], updatedAt: new Date() }));
+        const incoming = [
+            { productId: "product-A", productType: "product" },
+            { productId: "product-B", productType: "product" },
+        ];
+        const count = await repo.merge("u", incoming);
+        expect(count).toBe(2);
+    });
+    it("duplicate productId: keeps newer viewedAt, discards older", async () => {
+        const older = new Date("2026-01-01");
+        const newer = new Date("2026-01-10");
+        const existingItems = [{ productId: "product-A", productType: "product", viewedAt: older }];
+        mockTxn.get.mockResolvedValue(makeSnap({ userId: "u", items: existingItems, updatedAt: new Date() }));
+        await repo.merge("u", [{ productId: "product-A", productType: "product", viewedAt: newer }]);
+        const setCall = mockTxn.set.mock.calls[0][1];
+        expect(setCall.items).toHaveLength(1);
+        expect(setCall.items[0].viewedAt.getTime()).toBe(newer.getTime());
+    });
+    it("result trimmed to HISTORY_MAX (50 items)", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap({ userId: "u", items: [], updatedAt: new Date() }));
+        const incoming = Array.from({ length: 60 }, (_, i) => ({
+            productId: `product-${i}`,
+            productType: "product",
+            viewedAt: new Date(Date.now() - i * 1000),
+        }));
+        const count = await repo.merge("u", incoming);
+        expect(count).toBe(HISTORY_MAX);
+    });
+    it("items sorted descending by viewedAt after merge", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap({ userId: "u", items: [], updatedAt: new Date() }));
+        const incoming = [
+            { productId: "product-old", productType: "product", viewedAt: new Date("2026-01-01") },
+            { productId: "product-new", productType: "product", viewedAt: new Date("2026-01-10") },
+        ];
+        await repo.merge("u", incoming);
+        const setCall = mockTxn.set.mock.calls[0][1];
+        expect(setCall.items[0].productId).toBe("product-new");
+        expect(setCall.items[1].productId).toBe("product-old");
+    });
+    it("uses db.runTransaction", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap({ userId: "u", items: [], updatedAt: new Date() }));
+        await repo.merge("u", []);
+        expect(db.runTransaction).toHaveBeenCalledOnce();
+    });
+});
+describe("UserHistoryRepository.removeOne", () => {
+    it("removes specified productId from items", async () => {
+        const items = [
+            { productId: "product-A", productType: "product", viewedAt: new Date() },
+            { productId: "product-B", productType: "product", viewedAt: new Date() },
+        ];
+        mockTxn.get.mockResolvedValue(makeSnap({ userId: "u", items, updatedAt: new Date() }));
+        await repo.removeOne("u", "product-A");
+        const setCall = mockTxn.set.mock.calls[0][1];
+        expect(setCall.items).toHaveLength(1);
+        expect(setCall.items[0].productId).toBe("product-B");
+    });
+    it("non-existent productId → no-op, set not called", async () => {
+        const items = [{ productId: "product-A", productType: "product", viewedAt: new Date() }];
+        mockTxn.get.mockResolvedValue(makeSnap({ userId: "u", items, updatedAt: new Date() }));
+        await repo.removeOne("u", "product-xxx");
+        expect(mockTxn.set).not.toHaveBeenCalled();
+    });
+});
+describe("UserHistoryRepository.clearForUser", () => {
+    it("sets items: [] without deleting the document", async () => {
+        await repo.clearForUser("u");
+        expect(mockDocRef.set).toHaveBeenCalledWith(expect.objectContaining({ items: [] }));
+    });
+});
+describe("UserHistoryRepository.getHistory", () => {
+    it("returns items array", async () => {
+        const items = [{ productId: "product-A", productType: "product", viewedAt: new Date() }];
+        mockDocRef.get.mockResolvedValue(makeSnap({ userId: "u", items, updatedAt: new Date() }));
+        const result = await repo.getHistory("u");
+        expect(result).toHaveLength(1);
+        expect(result[0].productId).toBe("product-A");
+    });
+    it("returns empty array for user with no history document", async () => {
+        mockDocRef.get.mockResolvedValue(makeSnap(null));
+        const result = await repo.getHistory("u");
+        expect(result).toEqual([]);
+    });
+});
+describe("UserHistoryRepository.countByUser", () => {
+    it("returns items.length", async () => {
+        const items = makeHistoryItems(5);
+        mockDocRef.get.mockResolvedValue(makeSnap({ userId: "u", items, updatedAt: new Date() }));
+        const count = await repo.countByUser("u");
+        expect(count).toBe(5);
+    });
+    it("returns 0 for missing document", async () => {
+        mockDocRef.get.mockResolvedValue(makeSnap(null));
+        const count = await repo.countByUser("u");
+        expect(count).toBe(0);
+    });
+});

package/dist/features/homepage/api/[id]/route.d.ts

@@ -15,9 +15,9 @@ export declare function GET(_request: Request, context: {
     }>;
 }): Promise<NextResponse>;
 export { GET as homepageSectionItemGET };
-export declare const homepageSectionItemPATCH: (request: Request, context: {
+export declare const homepageSectionItemPATCH: (request: Request, context?: {
     params: Promise<Record<string, string>>;
-}) => Promise<Response>;
-export declare const homepageSectionItemDELETE: (request: Request, context: {
+} | undefined) => Promise<Response>;
+export declare const homepageSectionItemDELETE: (request: Request, context?: {
     params: Promise<Record<string, string>>;
-}) => Promise<Response>;
+} | undefined) => Promise<Response>;

package/dist/features/homepage/api/carousel/[id]/route.d.ts

@@ -15,9 +15,9 @@ export declare function GET(_request: Request, context: {
     }>;
 }): Promise<NextResponse>;
 export { GET as carouselItemGET };
-export declare const carouselItemPATCH: (request: Request, context: {
+export declare const carouselItemPATCH: (request: Request, context?: {
     params: Promise<Record<string, string>>;
-}) => Promise<Response>;
-export declare const carouselItemDELETE: (request: Request, context: {
+} | undefined) => Promise<Response>;
+export declare const carouselItemDELETE: (request: Request, context?: {
     params: Promise<Record<string, string>>;
-}) => Promise<Response>;
+} | undefined) => Promise<Response>;

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

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

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/homepage/schemas/firestore.d.ts

@@ -2,6 +2,7 @@
  * Homepage Feature Firestore Document Types & Constants
  * Covers: carousel slides, homepage sections
  */
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 /** Unified background for a slide or card — supports image, video, solid color, or gradient. */
 export interface CarouselBackground {
     type: "image" | "video" | "color" | "gradient";
@@ -63,14 +64,11 @@ export interface CarouselCard {
 }
 export type GridCardCreateInput = Omit<CarouselCard, "id">;
 /** A named carousel that holds up to MAX_SLIDES_PER_CAROUSEL slide references. */
-export interface CarouselDocument {
-    id: string;
+export interface CarouselDocument extends BaseDocument {
     name: string;
     status: "active" | "draft";
     /** Ordered slide IDs (max MAX_SLIDES_PER_CAROUSEL). */
     slideIds: string[];
-    createdAt: Date;
-    updatedAt: Date;
     createdBy: string;
 }
 export type CarouselCreateInput = Omit<CarouselDocument, "id" | "createdAt" | "updatedAt">;
@@ -78,8 +76,7 @@ export type CarouselUpdateInput = Partial<Pick<CarouselDocument, "name" | "statu
 export declare class TooManySlidesError extends Error {
     constructor();
 }
-export interface CarouselSlideDocument {
-    id: string;
+export interface CarouselSlideDocument extends BaseDocument {
     /**
      * Reference to a named CarouselDocument (EX2).
      * null = default hero carousel (backward-compat with pre-EX2 slides).
@@ -131,8 +128,6 @@ export interface CarouselSlideDocument {
         views: number;
         lastViewed?: Date;
     };
-    createdAt: Date;
-    updatedAt: Date;
     createdBy: string;
 }
 export declare const CAROUSEL_SLIDES_COLLECTION: "carouselSlides";
@@ -552,14 +547,11 @@ export interface GoogleReviewsSectionConfig {
 }
 export type SectionType = "welcome" | "carousel" | "stats" | "trust-indicators" | "categories" | "brands" | "products" | "pre-orders" | "auctions" | "banner" | "features" | "reviews" | "whatsapp-community" | "faq" | "blog-articles" | "newsletter" | "stores" | "events" | "social-feed" | "custom-cards" | "google-reviews" | "featured-bundles" | "prize-draws" | "event-raffles" | "collection-cards";
 export type SectionConfig = CarouselSectionConfig | WelcomeSectionConfig | StatsSectionConfig | TrustIndicatorsSectionConfig | CategoriesSectionConfig | BrandsSectionConfig | ProductsSectionConfig | PreOrdersSectionConfig | AuctionsSectionConfig | BannerSectionConfig | FeaturesSectionConfig | ReviewsSectionConfig | WhatsAppCommunitySectionConfig | FAQSectionConfig | BlogArticlesSectionConfig | NewsletterSectionConfig | StoresSectionConfig | EventsSectionConfig | SocialFeedSectionConfig | CustomCardsSectionConfig | GoogleReviewsSectionConfig | FeaturedBundlesSectionConfig | PrizeDrawsSectionConfig | EventRafflesSectionConfig | CollectionCardsSectionConfig;
-export interface HomepageSectionDocument {
-    id: string;
+export interface HomepageSectionDocument extends BaseDocument {
     type: SectionType;
     order: number;
     enabled: boolean;
     config: SectionConfig;
-    createdAt: Date;
-    updatedAt: Date;
 }
 export declare const HOMEPAGE_SECTIONS_COLLECTION: "homepageSections";
 export declare const HOMEPAGE_SECTIONS_INDEXED_FIELDS: readonly ["enabled", "order", "type"];