@devx-retailos/cms 0.0.1 → 0.1.0

package/src/modules/cms/__tests__/cms-module-service.test.ts

@@ -4,18 +4,18 @@ import CmsModuleService from "../services/cms-module-service"
 
 // Test subclass that overrides all MedusaService base CRUD methods
 class TestCmsService extends (CmsModuleService as any) {
-  createCmsHandovers = vi.fn()
-  listCmsHandovers = vi.fn()
-  listAndCountCmsHandovers = vi.fn()
-  retrieveCmsHandover = vi.fn()
-  createCmsAccumulations = vi.fn()
-  listCmsAccumulations = vi.fn()
-  updateCmsAccumulations = vi.fn()
-  createPettyCashes = vi.fn()
-  listPettyCashes = vi.fn()
-  updatePettyCashes = vi.fn()
-  createPettyCashTransactions = vi.fn()
-  listPettyCashTransactions = vi.fn()
+  createRetailosCmsHandovers = vi.fn()
+  listRetailosCmsHandovers = vi.fn().mockResolvedValue([])
+  listAndCountRetailosCmsHandovers = vi.fn()
+  retrieveRetailosCmsHandover = vi.fn()
+  createRetailosCmsAccumulations = vi.fn()
+  listRetailosCmsAccumulations = vi.fn()
+  updateRetailosCmsAccumulations = vi.fn()
+  createRetailosPettyCashes = vi.fn()
+  listRetailosPettyCashes = vi.fn().mockResolvedValue([])
+  updateRetailosPettyCashes = vi.fn()
+  createRetailosPettyCashTransactions = vi.fn()
+  listRetailosPettyCashTransactions = vi.fn()
 
   constructor() {
     // Skip super() to avoid MedusaService container requirement
@@ -37,30 +37,30 @@ function makeService(): TestCmsService {
 describe("CmsModuleService.dayStart", () => {
   it("creates accumulation when none exists", async () => {
     const service = makeService()
-    service.listCmsAccumulations.mockResolvedValue([])
-    service.createCmsAccumulations.mockResolvedValue([{ id: "cmsa_1", store_id: "s1", cash_in_store: 500 }])
-    service.createPettyCashTransactions.mockResolvedValue([{ id: "pct_1" }])
+    service.listRetailosCmsAccumulations.mockResolvedValue([])
+    service.createRetailosCmsAccumulations.mockResolvedValue([{ id: "cmsa_1", store_id: "s1", cash_in_store: 500 }])
+    service.createRetailosPettyCashTransactions.mockResolvedValue([{ id: "pct_1" }])
 
     await service.dayStart({ store_id: "s1", employee_id: "emp_1", opening_amount: 500 })
 
-    expect(service.createCmsAccumulations).toHaveBeenCalledWith([
+    expect(service.createRetailosCmsAccumulations).toHaveBeenCalledWith([
       expect.objectContaining({ store_id: "s1", cash_in_store: 500 }),
     ])
-    expect(service.createPettyCashTransactions).toHaveBeenCalledWith([
+    expect(service.createRetailosPettyCashTransactions).toHaveBeenCalledWith([
       expect.objectContaining({ transaction_type: "open", entry_type: "CR", amount: 500 }),
     ])
   })
 
   it("updates accumulation when already exists", async () => {
     const service = makeService()
-    service.listCmsAccumulations.mockResolvedValue([{ id: "cmsa_1", store_id: "s1", cash_in_store: 0 }])
-    service.updateCmsAccumulations.mockResolvedValue([])
-    service.createPettyCashTransactions.mockResolvedValue([{ id: "pct_1" }])
+    service.listRetailosCmsAccumulations.mockResolvedValue([{ id: "cmsa_1", store_id: "s1", cash_in_store: 0 }])
+    service.updateRetailosCmsAccumulations.mockResolvedValue([])
+    service.createRetailosPettyCashTransactions.mockResolvedValue([{ id: "pct_1" }])
 
     await service.dayStart({ store_id: "s1", employee_id: "emp_1", opening_amount: 1000 })
 
-    expect(service.createCmsAccumulations).not.toHaveBeenCalled()
-    expect(service.updateCmsAccumulations).toHaveBeenCalled()
+    expect(service.createRetailosCmsAccumulations).not.toHaveBeenCalled()
+    expect(service.updateRetailosCmsAccumulations).toHaveBeenCalled()
   })
 
   it("throws when opening_amount is negative", async () => {
@@ -74,12 +74,12 @@ describe("CmsModuleService.dayStart", () => {
 describe("CmsModuleService.dayEnd", () => {
   it("records closing transaction with difference", async () => {
     const service = makeService()
-    service.listCmsAccumulations.mockResolvedValue([{ id: "cmsa_1", store_id: "s1", cash_in_store: 1000 }])
-    service.createPettyCashTransactions.mockResolvedValue([{ id: "pct_2" }])
+    service.listRetailosCmsAccumulations.mockResolvedValue([{ id: "cmsa_1", store_id: "s1", cash_in_store: 1000 }])
+    service.createRetailosPettyCashTransactions.mockResolvedValue([{ id: "pct_2" }])
 
     await service.dayEnd({ store_id: "s1", employee_id: "emp_1", closing_amount: 800 })
 
-    expect(service.createPettyCashTransactions).toHaveBeenCalledWith([
+    expect(service.createRetailosPettyCashTransactions).toHaveBeenCalledWith([
       expect.objectContaining({
         transaction_type: "close",
         entry_type: "DB",
@@ -101,9 +101,9 @@ describe("CmsModuleService.dayEnd", () => {
 describe("CmsModuleService.handover", () => {
   it("creates handover and increases accumulation for CR type", async () => {
     const service = makeService()
-    service.createCmsHandovers.mockResolvedValue([{ id: "cmsh_1", store_id: "s1", handover_amount: 200, type: "CR" }])
-    service.listCmsAccumulations.mockResolvedValue([{ id: "cmsa_1", store_id: "s1", cash_in_store: 1000 }])
-    service.updateCmsAccumulations.mockResolvedValue([])
+    service.createRetailosCmsHandovers.mockResolvedValue([{ id: "cmsh_1", store_id: "s1", handover_amount: 200, type: "CR" }])
+    service.listRetailosCmsAccumulations.mockResolvedValue([{ id: "cmsa_1", store_id: "s1", cash_in_store: 1000 }])
+    service.updateRetailosCmsAccumulations.mockResolvedValue([])
 
     const result = await service.handover({
       store_id: "s1",
@@ -113,20 +113,20 @@ describe("CmsModuleService.handover", () => {
     })
 
     expect(result).toMatchObject({ id: "cmsh_1" })
-    expect(service.updateCmsAccumulations).toHaveBeenCalledWith([
+    expect(service.updateRetailosCmsAccumulations).toHaveBeenCalledWith([
       expect.objectContaining({ id: "cmsa_1", cash_in_store: 1200 }),
     ])
   })
 
   it("decreases accumulation for DB type", async () => {
     const service = makeService()
-    service.createCmsHandovers.mockResolvedValue([{ id: "cmsh_2", store_id: "s1", handover_amount: 300, type: "DB" }])
-    service.listCmsAccumulations.mockResolvedValue([{ id: "cmsa_1", store_id: "s1", cash_in_store: 1000 }])
-    service.updateCmsAccumulations.mockResolvedValue([])
+    service.createRetailosCmsHandovers.mockResolvedValue([{ id: "cmsh_2", store_id: "s1", handover_amount: 300, type: "DB" }])
+    service.listRetailosCmsAccumulations.mockResolvedValue([{ id: "cmsa_1", store_id: "s1", cash_in_store: 1000 }])
+    service.updateRetailosCmsAccumulations.mockResolvedValue([])
 
     await service.handover({ store_id: "s1", employee_id: "emp_1", handover_amount: 300, type: "DB" })
 
-    expect(service.updateCmsAccumulations).toHaveBeenCalledWith([
+    expect(service.updateRetailosCmsAccumulations).toHaveBeenCalledWith([
       expect.objectContaining({ id: "cmsa_1", cash_in_store: 700 }),
     ])
   })
@@ -142,16 +142,16 @@ describe("CmsModuleService.handover", () => {
 describe("CmsModuleService.addPettyCash", () => {
   it("creates petty cash record and transaction when none exists", async () => {
     const service = makeService()
-    service.listPettyCashes.mockResolvedValue([])
-    service.createPettyCashes.mockResolvedValue([{ id: "pc_1", store_id: "s1", balance: 500 }])
-    service.createPettyCashTransactions.mockResolvedValue([{ id: "pct_3" }])
+    service.listRetailosPettyCashes.mockResolvedValue([])
+    service.createRetailosPettyCashes.mockResolvedValue([{ id: "pc_1", store_id: "s1", balance: 500 }])
+    service.createRetailosPettyCashTransactions.mockResolvedValue([{ id: "pct_3" }])
 
     await service.addPettyCash({ store_id: "s1", employee_id: "emp_1", amount: 500 })
 
-    expect(service.createPettyCashes).toHaveBeenCalledWith([
+    expect(service.createRetailosPettyCashes).toHaveBeenCalledWith([
       expect.objectContaining({ store_id: "s1", balance: 500 }),
     ])
-    expect(service.createPettyCashTransactions).toHaveBeenCalledWith([
+    expect(service.createRetailosPettyCashTransactions).toHaveBeenCalledWith([
       expect.objectContaining({ entry_type: "CR", amount: 500 }),
     ])
   })
@@ -167,16 +167,16 @@ describe("CmsModuleService.addPettyCash", () => {
 describe("CmsModuleService.addExpense", () => {
   it("debits petty cash and records transaction", async () => {
     const service = makeService()
-    service.listPettyCashes.mockResolvedValue([{ id: "pc_1", store_id: "s1", balance: 500 }])
-    service.updatePettyCashes.mockResolvedValue([])
-    service.createPettyCashTransactions.mockResolvedValue([{ id: "pct_4" }])
+    service.listRetailosPettyCashes.mockResolvedValue([{ id: "pc_1", store_id: "s1", balance: 500 }])
+    service.updateRetailosPettyCashes.mockResolvedValue([])
+    service.createRetailosPettyCashTransactions.mockResolvedValue([{ id: "pct_4" }])
 
     await service.addExpense({ store_id: "s1", employee_id: "emp_1", amount: 100, category: "office" })
 
-    expect(service.updatePettyCashes).toHaveBeenCalledWith([
+    expect(service.updateRetailosPettyCashes).toHaveBeenCalledWith([
       expect.objectContaining({ id: "pc_1", balance: 400 }),
     ])
-    expect(service.createPettyCashTransactions).toHaveBeenCalledWith([
+    expect(service.createRetailosPettyCashTransactions).toHaveBeenCalledWith([
       expect.objectContaining({ entry_type: "DB", expense_amount: 100, category: "office" }),
     ])
   })
@@ -192,7 +192,7 @@ describe("CmsModuleService.addExpense", () => {
 describe("CmsModuleService.getAccumulation", () => {
   it("returns accumulation for store", async () => {
     const service = makeService()
-    service.listCmsAccumulations.mockResolvedValue([{ id: "cmsa_1", store_id: "s1", cash_in_store: 750 }])
+    service.listRetailosCmsAccumulations.mockResolvedValue([{ id: "cmsa_1", store_id: "s1", cash_in_store: 750 }])
 
     const result = await service.getAccumulation("s1")
 
@@ -201,7 +201,7 @@ describe("CmsModuleService.getAccumulation", () => {
 
   it("returns null when no accumulation exists", async () => {
     const service = makeService()
-    service.listCmsAccumulations.mockResolvedValue([])
+    service.listRetailosCmsAccumulations.mockResolvedValue([])
 
     const result = await service.getAccumulation("s1")
 
@@ -216,11 +216,11 @@ describe("CmsModuleService.getShiftLogs", () => {
       { id: "pct_1", transaction_type: "open", store_id: "s1" },
       { id: "pct_2", transaction_type: "close", store_id: "s1" },
     ]
-    service.listPettyCashTransactions.mockResolvedValue(mockLogs)
+    service.listRetailosPettyCashTransactions.mockResolvedValue(mockLogs)
 
     const result = await service.getShiftLogs({ store_id: "s1" })
 
-    expect(service.listPettyCashTransactions).toHaveBeenCalledWith(
+    expect(service.listRetailosPettyCashTransactions).toHaveBeenCalledWith(
       expect.objectContaining({ transaction_type: ["open", "close"], store_id: ["s1"] }),
       expect.any(Object)
     )
@@ -229,23 +229,23 @@ describe("CmsModuleService.getShiftLogs", () => {
 
   it("omits store_id filter when not provided", async () => {
     const service = makeService()
-    service.listPettyCashTransactions.mockResolvedValue([])
+    service.listRetailosPettyCashTransactions.mockResolvedValue([])
 
     await service.getShiftLogs({})
 
-    expect(service.listPettyCashTransactions).toHaveBeenCalledWith(
+    expect(service.listRetailosPettyCashTransactions).toHaveBeenCalledWith(
       expect.not.objectContaining({ store_id: expect.anything() }),
       expect.any(Object)
     )
   })
 
-  it("passes custom limit to listPettyCashTransactions", async () => {
+  it("passes custom limit to listRetailosPettyCashTransactions", async () => {
     const service = makeService()
-    service.listPettyCashTransactions.mockResolvedValue([])
+    service.listRetailosPettyCashTransactions.mockResolvedValue([])
 
     await service.getShiftLogs({ store_id: "s1", limit: 10 })
 
-    expect(service.listPettyCashTransactions).toHaveBeenCalledWith(
+    expect(service.listRetailosPettyCashTransactions).toHaveBeenCalledWith(
       expect.any(Object),
       expect.objectContaining({ take: 10 })
     )
@@ -255,12 +255,12 @@ describe("CmsModuleService.getShiftLogs", () => {
 describe("CmsModuleService.dayEnd - no prior accumulation", () => {
   it("uses zero as current_cash when no accumulation exists", async () => {
     const service = makeService()
-    service.listCmsAccumulations.mockResolvedValue([])
-    service.createPettyCashTransactions.mockResolvedValue([{ id: "pct_x" }])
+    service.listRetailosCmsAccumulations.mockResolvedValue([])
+    service.createRetailosPettyCashTransactions.mockResolvedValue([{ id: "pct_x" }])
 
     await service.dayEnd({ store_id: "s1", employee_id: "emp_1", closing_amount: 300 })
 
-    expect(service.createPettyCashTransactions).toHaveBeenCalledWith([
+    expect(service.createRetailosPettyCashTransactions).toHaveBeenCalledWith([
       expect.objectContaining({
         opening_balance: 0,
         closing_balance: 300,
@@ -271,28 +271,24 @@ describe("CmsModuleService.dayEnd - no prior accumulation", () => {
 })
 
 describe("CmsModuleService.handover - edge cases", () => {
-  it("creates new accumulation when none exists", async () => {
+  it("throws when no Day Start has been run for the store", async () => {
     const service = makeService()
-    service.createCmsHandovers.mockResolvedValue([{ id: "cmsh_3", store_id: "s1", handover_amount: 100, type: "CR" }])
-    service.listCmsAccumulations.mockResolvedValue([])
-    service.createCmsAccumulations.mockResolvedValue([])
+    service.listRetailosCmsAccumulations.mockResolvedValue([])
 
-    await service.handover({ store_id: "s1", employee_id: "emp_1", handover_amount: 100, type: "CR" })
-
-    expect(service.createCmsAccumulations).toHaveBeenCalledWith([
-      expect.objectContaining({ store_id: "s1", cash_in_store: 100 }),
-    ])
+    await expect(
+      service.handover({ store_id: "s1", employee_id: "emp_1", handover_amount: 100, type: "CR" })
+    ).rejects.toThrow("Day Start must be completed before creating a handover")
   })
 
   it("does not change cash when type is null", async () => {
     const service = makeService()
-    service.createCmsHandovers.mockResolvedValue([{ id: "cmsh_4", store_id: "s1", handover_amount: 50, type: null }])
-    service.listCmsAccumulations.mockResolvedValue([{ id: "cmsa_1", store_id: "s1", cash_in_store: 1000 }])
-    service.updateCmsAccumulations.mockResolvedValue([])
+    service.createRetailosCmsHandovers.mockResolvedValue([{ id: "cmsh_4", store_id: "s1", handover_amount: 50, type: null }])
+    service.listRetailosCmsAccumulations.mockResolvedValue([{ id: "cmsa_1", store_id: "s1", cash_in_store: 1000 }])
+    service.updateRetailosCmsAccumulations.mockResolvedValue([])
 
     await service.handover({ store_id: "s1", employee_id: "emp_1", handover_amount: 50, type: null })
 
-    expect(service.updateCmsAccumulations).toHaveBeenCalledWith([
+    expect(service.updateRetailosCmsAccumulations).toHaveBeenCalledWith([
       expect.objectContaining({ cash_in_store: 1000 }),
     ])
   })
@@ -301,17 +297,17 @@ describe("CmsModuleService.handover - edge cases", () => {
 describe("CmsModuleService.addPettyCash - update path", () => {
   it("updates existing petty cash balance", async () => {
     const service = makeService()
-    service.listPettyCashes.mockResolvedValue([{ id: "pc_1", store_id: "s1", balance: 200 }])
-    service.updatePettyCashes.mockResolvedValue([])
-    service.createPettyCashTransactions.mockResolvedValue([{ id: "pct_5" }])
+    service.listRetailosPettyCashes.mockResolvedValue([{ id: "pc_1", store_id: "s1", balance: 200 }])
+    service.updateRetailosPettyCashes.mockResolvedValue([])
+    service.createRetailosPettyCashTransactions.mockResolvedValue([{ id: "pct_5" }])
 
     await service.addPettyCash({ store_id: "s1", employee_id: "emp_1", amount: 300 })
 
-    expect(service.createPettyCashes).not.toHaveBeenCalled()
-    expect(service.updatePettyCashes).toHaveBeenCalledWith([
+    expect(service.createRetailosPettyCashes).not.toHaveBeenCalled()
+    expect(service.updateRetailosPettyCashes).toHaveBeenCalledWith([
       expect.objectContaining({ id: "pc_1", balance: 500 }),
     ])
-    expect(service.createPettyCashTransactions).toHaveBeenCalledWith([
+    expect(service.createRetailosPettyCashTransactions).toHaveBeenCalledWith([
       expect.objectContaining({ opening_balance: 200, closing_balance: 500 }),
     ])
   })
@@ -320,14 +316,159 @@ describe("CmsModuleService.addPettyCash - update path", () => {
 describe("CmsModuleService.addExpense - no existing petty cash", () => {
   it("creates petty cash record when none exists", async () => {
     const service = makeService()
-    service.listPettyCashes.mockResolvedValue([])
-    service.createPettyCashes.mockResolvedValue([{ id: "pc_new", store_id: "s1", balance: -100 }])
-    service.createPettyCashTransactions.mockResolvedValue([{ id: "pct_6" }])
+    service.listRetailosPettyCashes.mockResolvedValue([])
+    service.createRetailosPettyCashes.mockResolvedValue([{ id: "pc_new", store_id: "s1", balance: -100 }])
+    service.createRetailosPettyCashTransactions.mockResolvedValue([{ id: "pct_6" }])
 
     await service.addExpense({ store_id: "s1", employee_id: "emp_1", amount: 100 })
 
-    expect(service.createPettyCashes).toHaveBeenCalledWith([
+    expect(service.createRetailosPettyCashes).toHaveBeenCalledWith([
       expect.objectContaining({ store_id: "s1", balance: -100 }),
     ])
   })
 })
+
+describe("CmsModuleService.getReconciliationReport", () => {
+  it("returns zeros when no transactions exist for the day", async () => {
+    const service = makeService()
+    service.listRetailosPettyCashTransactions.mockResolvedValue([])
+    service.listRetailosCmsHandovers.mockResolvedValue([])
+    service.listRetailosCmsAccumulations.mockResolvedValue([{ id: "cmsa_1", cash_in_store: 5000 }])
+
+    const result = await service.getReconciliationReport({ store_id: "s1", date: "2026-06-23" })
+
+    expect(result).toMatchObject({
+      date: "2026-06-23",
+      store_id: "s1",
+      opening_balance: 0,
+      net_cash_sales: 0,
+      total_handovers_in: 0,
+      total_handovers_out: 0,
+      petty_cash_in: 0,
+      petty_cash_out: 0,
+      expected_closing_balance: 0,
+      closing_balance: null,
+      cms_balance: 5000,
+      variance: null,
+      is_balanced: null,
+    })
+  })
+
+  it("computes expected_closing_balance correctly", async () => {
+    const service = makeService()
+    service.listRetailosPettyCashTransactions.mockResolvedValue([
+      { transaction_type: "open", entry_type: "CR", amount: 8200 },
+      { transaction_type: "petty_cash", entry_type: "CR", amount: 500 },
+      { transaction_type: "petty_cash", entry_type: "DB", amount: 1000 },
+    ])
+    service.listRetailosCmsHandovers.mockResolvedValue([
+      { type: "CR", handover_amount: 2000 },
+      { type: "DB", handover_amount: 5000 },
+    ])
+    service.listRetailosCmsAccumulations.mockResolvedValue([{ id: "cmsa_1", cash_in_store: 12700 }])
+
+    const result = await service.getReconciliationReport({
+      store_id: "s1",
+      date: "2026-06-23",
+      net_cash_sales: 28450,
+    })
+
+    // 8200 + 28450 + 500 - 1000 + 2000 - 5000 = 33150
+    expect(result.expected_closing_balance).toBe(33150)
+    expect(result.opening_balance).toBe(8200)
+    expect(result.petty_cash_in).toBe(500)
+    expect(result.petty_cash_out).toBe(1000)
+    expect(result.total_handovers_in).toBe(2000)
+    expect(result.total_handovers_out).toBe(5000)
+  })
+
+  it("computes variance and is_balanced when day is closed", async () => {
+    const service = makeService()
+    service.listRetailosPettyCashTransactions.mockResolvedValue([
+      { transaction_type: "open", entry_type: "CR", amount: 8200 },
+      { transaction_type: "close", entry_type: "DB", amount: 31650 },
+    ])
+    service.listRetailosCmsHandovers.mockResolvedValue([
+      { type: "DB", handover_amount: 5000 },
+    ])
+    service.listRetailosCmsAccumulations.mockResolvedValue([])
+
+    const result = await service.getReconciliationReport({
+      store_id: "s1",
+      date: "2026-06-23",
+      net_cash_sales: 28450,
+    })
+
+    // expected = 8200 + 28450 - 5000 = 31650; actual = 31650
+    expect(result.expected_closing_balance).toBe(31650)
+    expect(result.closing_balance).toBe(31650)
+    expect(result.variance).toBe(0)
+    expect(result.is_balanced).toBe(true)
+    expect(result.cms_balance).toBeNull()
+  })
+
+  it("detects variance when actual closing differs from expected", async () => {
+    const service = makeService()
+    service.listRetailosPettyCashTransactions.mockResolvedValue([
+      { transaction_type: "open", entry_type: "CR", amount: 8200 },
+      { transaction_type: "close", entry_type: "DB", amount: 16350 },
+    ])
+    service.listRetailosCmsHandovers.mockResolvedValue([
+      { type: "DB", handover_amount: 5000 },
+    ])
+    service.listRetailosCmsAccumulations.mockResolvedValue([{ id: "cmsa_1", cash_in_store: 50500 }])
+
+    const result = await service.getReconciliationReport({
+      store_id: "s1",
+      date: "2026-06-23",
+      net_cash_sales: 28450,
+    })
+
+    // expected = 8200 + 28450 - 5000 = 31650; actual = 16350
+    expect(result.variance).toBe(-15300)
+    expect(result.is_balanced).toBe(false)
+  })
+
+  it("filters transactions by date range using created_at", async () => {
+    const service = makeService()
+    service.listRetailosPettyCashTransactions.mockResolvedValue([])
+    service.listRetailosCmsHandovers.mockResolvedValue([])
+    service.listRetailosCmsAccumulations.mockResolvedValue([])
+
+    await service.getReconciliationReport({ store_id: "s1", date: "2026-06-23" })
+
+    expect(service.listRetailosPettyCashTransactions).toHaveBeenCalledWith(
+      expect.objectContaining({
+        store_id: ["s1"],
+        created_at: expect.objectContaining({ $gte: expect.any(Date), $lte: expect.any(Date) }),
+      }),
+      expect.any(Object)
+    )
+    expect(service.listRetailosCmsHandovers).toHaveBeenCalledWith(
+      expect.objectContaining({
+        store_id: ["s1"],
+        created_at: expect.objectContaining({ $gte: expect.any(Date), $lte: expect.any(Date) }),
+      }),
+      expect.any(Object)
+    )
+  })
+
+  it("separates shift_logs from handovers in the report", async () => {
+    const service = makeService()
+    const openTx = { id: "pct_open", transaction_type: "open", entry_type: "CR", amount: 8200 }
+    const closeTx = { id: "pct_close", transaction_type: "close", entry_type: "DB", amount: 8200 }
+    const pettyCashTx = { id: "pct_pc", transaction_type: "petty_cash", entry_type: "CR", amount: 500 }
+    const handover = { id: "cmsh_1", type: "DB", handover_amount: 1000 }
+
+    service.listRetailosPettyCashTransactions.mockResolvedValue([openTx, pettyCashTx, closeTx])
+    service.listRetailosCmsHandovers.mockResolvedValue([handover])
+    service.listRetailosCmsAccumulations.mockResolvedValue([])
+
+    const result = await service.getReconciliationReport({ store_id: "s1", date: "2026-06-23" })
+
+    expect(result.shift_logs).toHaveLength(2)
+    expect(result.shift_logs).toEqual(expect.arrayContaining([openTx, closeTx]))
+    expect(result.handovers).toHaveLength(1)
+    expect(result.handovers[0]).toMatchObject({ id: "cmsh_1" })
+  })
+})

package/src/modules/cms/__tests__/permissions.test.ts

@@ -9,10 +9,11 @@ describe("CMS_PERMISSIONS", () => {
     "cms.petty_cash.read",
     "cms.petty_cash.operate",
     "cms.accumulation.read",
+    "cms.reconciliation.read",
   ]
 
-  it("exports exactly 6 permission keys", () => {
-    expect(CMS_PERMISSIONS).toHaveLength(6)
+  it("exports exactly 7 permission keys", () => {
+    expect(CMS_PERMISSIONS).toHaveLength(7)
   })
 
   it("contains all required permission keys", () => {

package/src/modules/cms/migrations/Migration20260626000000.ts

@@ -0,0 +1,17 @@
+import { Migration } from "@medusajs/framework/mikro-orm/migrations"
+
+export class Migration20260626000000 extends Migration {
+  override async up(): Promise<void> {
+    this.addSql(
+      `alter table if exists "retailos_cms_handover" add column if not exists "opening_balance" numeric null;`
+    )
+    this.addSql(
+      `alter table if exists "retailos_cms_handover" add column if not exists "closing_balance" numeric null;`
+    )
+  }
+
+  override async down(): Promise<void> {
+    this.addSql(`alter table if exists "retailos_cms_handover" drop column if exists "opening_balance";`)
+    this.addSql(`alter table if exists "retailos_cms_handover" drop column if exists "closing_balance";`)
+  }
+}

package/src/modules/cms/models/cms-handover.ts

@@ -7,6 +7,8 @@ const CmsHandover = model.define("retailos_cms_handover", {
   handover_id: model.text().nullable(), // free-text correlation field: the brand can pass their own ID (e.g. a bank slip number, a vault reference, a POS transaction ID) so they can cross-reference this handover record with their own external system.
   handover_amount: model.number().nullable(),
   total_cash: model.number().nullable(),
+  opening_balance: model.number().nullable(),
+  closing_balance: model.number().nullable(),
   type: model.text().nullable(),
   image_url: model.text().nullable(),
   remark: model.text().nullable(),

package/src/modules/cms/permissions.ts

@@ -31,4 +31,9 @@ export const CMS_PERMISSIONS: PermissionRegistration[] = [
     description: "View current cash accumulation for a store",
     registered_by: "cms",
   },
+  {
+    key: "cms.reconciliation.read",
+    description: "View daily cash reconciliation report with variance analysis",
+    registered_by: "cms",
+  },
 ]