@devx-retailos/cms 0.0.1 → 0.0.2

package/README.md

@@ -126,8 +126,21 @@ const logs = await cmsService.getShiftLogs({
   to: new Date("2024-01-31"),
   limit: 50,
 })
+
+// Daily cash reconciliation report
+const report = await cmsService.getReconciliationReport({
+  store_id: "store_01",
+  date: "2026-06-23",       // YYYY-MM-DD (UTC)
+  net_cash_sales: 28450,    // optional — cash collected from orders (default 0)
+})
+// report.expected_closing_balance = opening + net_cash_sales
+//   + petty_cash_in - petty_cash_out + total_handovers_in - total_handovers_out
+// report.variance      = closing_balance - expected (null until day_end runs)
+// report.is_balanced   = variance === 0
 ```
 
+> **`net_cash_sales`** comes from your order module. Pass it from the brand's order query or via `sdk-client`. When omitted the report uses 0 and computes everything from CMS data only.
+
 ---
 
 ## Permissions
@@ -140,6 +153,109 @@ const logs = await cmsService.getShiftLogs({
 | `cms.petty_cash.read` | View petty cash balance and transactions |
 | `cms.petty_cash.operate` | Add petty cash or record expenses |
 | `cms.accumulation.read` | View current cash accumulation for a store |
+| `cms.reconciliation.read` | View daily cash reconciliation report with variance analysis |
+
+---
+
+## HTTP API
+
+All routes are mounted under `/admin/retailos/cms` and require a valid Medusa admin session.
+
+### Handovers
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/admin/retailos/cms/handovers` | List handovers with filtering, pagination, and linked employee/store data |
+| `POST` | `/admin/retailos/cms/handovers` | Create a cash handover |
+| `GET` | `/admin/retailos/cms/handovers/:id` | Retrieve a single handover by ID |
+
+**GET /admin/retailos/cms/handovers** query params:
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `store_id` | string | Filter by store |
+| `employee_id` | string | Filter by employee |
+| `type` | `CR` \| `DB` | Filter by direction |
+| `handover_id` | string | Exact match on handover_id |
+| `q` | string | Full-text search on handover_id (`ILIKE`) |
+| `created_at` | string / object | Date range filter |
+| `limit` | number | Max 500, default 20 |
+| `offset` | number | Default 0 |
+| `order` | string | Field name; prefix `-` for DESC (e.g. `-created_at`) |
+
+Response includes `handovers[]` and `count`. Each handover carries an embedded `employee` (`id`, `first_name`, `last_name`) and `store` (`id`, `name`, `store_code`) when module links resolve.
+
+**POST /admin/retailos/cms/handovers** body (Zod-validated):
+
+```json
+{
+  "store_id": "store_01",
+  "employee_id": "emp_01",
+  "handover_amount": 2000,
+  "type": "CR",
+  "remark": "shift change",
+  "handover_id": null,
+  "image_url": null,
+  "metadata": null
+}
+```
+
+---
+
+### Petty cash
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/admin/retailos/cms/petty-cash` | List petty cash transactions with employee enrichment |
+
+Query params: `store_id`, `limit` (max 500, default 100), `offset`.
+
+Each transaction includes an embedded `employee` object when the `employee` module is available.
+
+---
+
+### Reconciliation
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/admin/retailos/cms/reconciliation` | Daily cash reconciliation report |
+
+Required params: `store_id`, `date` (YYYY-MM-DD). Optional: `net_cash_sales` (number).
+
+---
+
+### Export
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/admin/retailos/cms/export` | Download all handovers as a CSV file |
+
+Query params: `store_id` (optional). Returns `text/csv` with `Content-Disposition: attachment`.
+
+---
+
+## sdk-client
+
+The `cms` namespace on `RetailOSClient` exposes typed wrappers for all routes above. Key methods:
+
+```ts
+// Reconciliation report
+const report = await client.cms.getReconciliationReport({
+  store_id: "store_01",
+  date: "2026-06-26",
+  net_cash_sales: 28450,
+})
+
+// List handovers (paginated)
+const { handovers, count } = await client.cms.listHandovers({
+  store_id: "store_01",
+  limit: 20,
+  offset: 0,
+})
+
+// Export CSV (returns raw text)
+const csv = await client.cms.exportHandovers({ store_id: "store_01" })
+```
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devx-retailos/cms",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Cash Management System for retailOS: shift ops, handovers, petty cash, accumulation.",
   "license": "MIT",
   "main": "./.medusa/server/src/modules/cms/index.js",

package/src/api/admin/retailos/cms/export/__tests__/route.test.ts

@@ -3,7 +3,7 @@ import { GET } from "../route"
 
 function makeService() {
   return {
-    listAndCountCmsHandovers: vi.fn().mockResolvedValue([[], 0]),
+    listAndCountRetailosCmsHandovers: vi.fn().mockResolvedValue([[], 0]),
   }
 }
 
@@ -34,7 +34,7 @@ function makeRes() {
 describe("GET /export", () => {
   it("returns CSV with correct headers row", async () => {
     const service = makeService()
-    service.listAndCountCmsHandovers.mockResolvedValue([[], 0])
+    service.listAndCountRetailosCmsHandovers.mockResolvedValue([[], 0])
     const req = makeReq({}, service)
     const res = makeRes()
 
@@ -55,7 +55,7 @@ describe("GET /export", () => {
     const handovers = [
       { id: "cmsh_1", store_id: "s1", employee_id: "e1", handover_id: null, handover_amount: 500, total_cash: null, type: "CR", remark: null, created_at: "2026-06-22T00:00:00Z" },
     ]
-    service.listAndCountCmsHandovers.mockResolvedValue([handovers, 1])
+    service.listAndCountRetailosCmsHandovers.mockResolvedValue([handovers, 1])
     const req = makeReq({}, service)
     const res = makeRes()
 
@@ -74,7 +74,7 @@ describe("GET /export", () => {
     const handovers = [
       { id: "cmsh_2", store_id: "s1", employee_id: "e1", handover_id: null, handover_amount: 100, total_cash: null, type: "DB", remark: 'cash, "extra"', created_at: "2026-06-22T00:00:00Z" },
     ]
-    service.listAndCountCmsHandovers.mockResolvedValue([handovers, 1])
+    service.listAndCountRetailosCmsHandovers.mockResolvedValue([handovers, 1])
     const req = makeReq({}, service)
     const res = makeRes()
 
@@ -86,13 +86,13 @@ describe("GET /export", () => {
 
   it("filters by store_id when provided in query", async () => {
     const service = makeService()
-    service.listAndCountCmsHandovers.mockResolvedValue([[], 0])
+    service.listAndCountRetailosCmsHandovers.mockResolvedValue([[], 0])
     const req = makeReq({ store_id: "s1" }, service)
     const res = makeRes()
 
     await GET(req as any, res as any)
 
-    expect(service.listAndCountCmsHandovers).toHaveBeenCalledWith(
+    expect(service.listAndCountRetailosCmsHandovers).toHaveBeenCalledWith(
       expect.objectContaining({ store_id: ["s1"] }),
       expect.any(Object)
     )
@@ -100,13 +100,13 @@ describe("GET /export", () => {
 
   it("does not filter by store_id when not in query", async () => {
     const service = makeService()
-    service.listAndCountCmsHandovers.mockResolvedValue([[], 0])
+    service.listAndCountRetailosCmsHandovers.mockResolvedValue([[], 0])
     const req = makeReq({}, service)
     const res = makeRes()
 
     await GET(req as any, res as any)
 
-    expect(service.listAndCountCmsHandovers).toHaveBeenCalledWith(
+    expect(service.listAndCountRetailosCmsHandovers).toHaveBeenCalledWith(
       expect.not.objectContaining({ store_id: expect.anything() }),
       expect.any(Object)
     )
@@ -114,7 +114,7 @@ describe("GET /export", () => {
 
   it("returns 500 when service throws", async () => {
     const service = makeService()
-    service.listAndCountCmsHandovers.mockRejectedValue(new Error("db error"))
+    service.listAndCountRetailosCmsHandovers.mockRejectedValue(new Error("db error"))
     const req = makeReq({}, service)
     const res = makeRes()
 

package/src/api/admin/retailos/cms/export/route.ts

@@ -35,7 +35,7 @@ export const GET = async (req: AuthenticatedMedusaRequest, res: MedusaResponse)
     const filters: Record<string, unknown> = {}
     if (store_id) filters.store_id = [store_id]
 
-    const [handovers] = await service.listAndCountCmsHandovers(filters, {
+    const [handovers] = await service.listAndCountRetailosCmsHandovers(filters, {
       take: 10000,
       order: { created_at: "DESC" },
     })

package/src/api/admin/retailos/cms/handovers/[id]/__tests__/route.test.ts

@@ -3,7 +3,7 @@ import { GET } from "../route"
 
 function makeService() {
   return {
-    retrieveCmsHandover: vi.fn(),
+    retrieveRetailosCmsHandover: vi.fn(),
   }
 }
 
@@ -31,20 +31,20 @@ describe("GET /handovers/[id]", () => {
   it("returns handover when found", async () => {
     const service = makeService()
     const handover = { id: "cmsh_1", store_id: "s1", handover_amount: 500 }
-    service.retrieveCmsHandover.mockResolvedValue(handover)
+    service.retrieveRetailosCmsHandover.mockResolvedValue(handover)
     const req = makeReq({ id: "cmsh_1" }, service)
     const res = makeRes()
 
     await GET(req as any, res as any)
 
-    expect(service.retrieveCmsHandover).toHaveBeenCalledWith("cmsh_1")
+    expect(service.retrieveRetailosCmsHandover).toHaveBeenCalledWith("cmsh_1")
     expect(res.status).toHaveBeenCalledWith(200)
     expect(res.json).toHaveBeenCalledWith({ handover })
   })
 
   it("returns 404 when handover is null", async () => {
     const service = makeService()
-    service.retrieveCmsHandover.mockResolvedValue(null)
+    service.retrieveRetailosCmsHandover.mockResolvedValue(null)
     const req = makeReq({ id: "cmsh_missing" }, service)
     const res = makeRes()
 
@@ -56,7 +56,7 @@ describe("GET /handovers/[id]", () => {
 
   it("returns 500 when service throws", async () => {
     const service = makeService()
-    service.retrieveCmsHandover.mockRejectedValue(new Error("db error"))
+    service.retrieveRetailosCmsHandover.mockRejectedValue(new Error("db error"))
     const req = makeReq({ id: "cmsh_1" }, service)
     const res = makeRes()
 

package/src/api/admin/retailos/cms/handovers/[id]/route.ts

@@ -21,7 +21,7 @@ export const GET = async (req: AuthenticatedMedusaRequest, res: MedusaResponse)
   const { id } = req.params
   try {
     const service = getService(req)
-    const handover = await service.retrieveCmsHandover(id)
+    const handover = await service.retrieveRetailosCmsHandover(id)
     if (!handover) {
       return res.status(404).json({ code: "NOT_FOUND", message: "Handover not found" })
     }

package/src/api/admin/retailos/cms/handovers/__tests__/route.test.ts

@@ -3,18 +3,24 @@ import { GET, POST } from "../route"
 
 function makeService() {
   return {
-    listAndCountCmsHandovers: vi.fn().mockResolvedValue([[], 0]),
     handover: vi.fn().mockResolvedValue({ id: "cmsh_1", store_id: "s1", handover_amount: 100 }),
   }
 }
 
-function makeReq(overrides: Record<string, unknown> = {}, service = makeService()) {
+function makeQueryModule(data: unknown[] = [], count = 0) {
+  return {
+    graph: vi.fn().mockResolvedValue({ data, metadata: { count } }),
+  }
+}
+
+function makeReq(overrides: Record<string, unknown> = {}, service = makeService(), queryModule = makeQueryModule()) {
   return {
     body: {},
-    filterableFields: {},
+    query: {},
     scope: {
       resolve: vi.fn().mockImplementation((key: string) => {
         if (key === "cms") return service
+        if (key === "query") return queryModule
         throw new Error("not found")
       }),
     },
@@ -32,22 +38,27 @@ function makeRes() {
 
 describe("GET /handovers", () => {
   it("returns handover list with count", async () => {
+    const data = [{ id: "cmsh_1" }, { id: "cmsh_2" }]
+    const queryModule = makeQueryModule(data, 2)
     const service = makeService()
-    const handovers = [{ id: "cmsh_1" }, { id: "cmsh_2" }]
-    service.listAndCountCmsHandovers.mockResolvedValue([handovers, 2])
-    const req = makeReq({}, service)
+    const req = makeReq({}, service, queryModule)
     const res = makeRes()
 
     await GET(req as any, res as any)
 
     expect(res.status).toHaveBeenCalledWith(200)
-    expect(res.json).toHaveBeenCalledWith({ handovers, count: 2 })
+    expect(res.json).toHaveBeenCalledWith({
+      handovers: [
+        { id: "cmsh_1", employee: null, store: null },
+        { id: "cmsh_2", employee: null, store: null },
+      ],
+      count: 2,
+    })
   })
 
-  it("returns 500 when service throws", async () => {
-    const service = makeService()
-    service.listAndCountCmsHandovers.mockRejectedValue(new Error("db error"))
-    const req = makeReq({}, service)
+  it("returns 500 when query.graph throws", async () => {
+    const queryModule = { graph: vi.fn().mockRejectedValue(new Error("db error")) }
+    const req = makeReq({}, makeService(), queryModule)
     const res = makeRes()
 
     await GET(req as any, res as any)

package/src/api/admin/retailos/cms/handovers/route.ts

@@ -2,6 +2,7 @@ import type {
   AuthenticatedMedusaRequest,
   MedusaResponse,
 } from "@medusajs/framework"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
 import { z } from "zod"
 import { CMS_MODULE } from "../../../../../modules/cms/constants"
 import type CmsModuleService from "../../../../../modules/cms/services/cms-module-service"
@@ -32,13 +33,84 @@ function getLogger(req: AuthenticatedMedusaRequest) {
 
 export const GET = async (req: AuthenticatedMedusaRequest, res: MedusaResponse) => {
   try {
-    const service = getService(req)
-    const filters = (req.filterableFields ?? {}) as Record<string, unknown>
-    const [data, count] = await service.listAndCountCmsHandovers(filters, {
-      take: 100,
-      order: { created_at: "DESC" },
+    const query = (req as any).scope.resolve(ContainerRegistrationKeys.QUERY)
+    const q = req.query as Record<string, any>
+
+    const filters: Record<string, unknown> = {}
+
+    // Direct equality filters from query params
+    const DIRECT = ["store_id", "employee_id", "type"] as const
+    for (const key of DIRECT) {
+      if (q[key] !== undefined && q[key] !== "") filters[key] = q[key]
+    }
+    if (q.handover_id) filters.handover_id = q.handover_id
+
+    // q: full-text search on handover_id
+    if (q.q) {
+      filters.handover_id = { $ilike: `%${q.q}%` }
+    }
+
+    // Date range filters
+    if (q.created_at) {
+      filters.created_at = typeof q.created_at === "object" ? q.created_at : { $gte: new Date(q.created_at as string) }
+    }
+    if (q.updated_at) {
+      filters.updated_at = typeof q.updated_at === "object" ? q.updated_at : { $gte: new Date(q.updated_at as string) }
+    }
+
+    // Pagination
+    const limit = q.limit ? Math.min(parseInt(q.limit as string, 10), 500) : 20
+    const offset = q.offset ? parseInt(q.offset as string, 10) : 0
+
+    // Ordering: "field" = ASC, "-field" = DESC
+    let order: Record<string, "ASC" | "DESC"> = { created_at: "DESC" }
+    if (q.order) {
+      const raw = q.order as string
+      const isDesc = raw.startsWith("-")
+      const field = isDesc ? raw.slice(1) : raw
+      const SORTABLE = ["created_at", "updated_at", "handover_amount", "total_cash"]
+      if (SORTABLE.includes(field)) {
+        order = { [field]: isDesc ? "DESC" : "ASC" }
+      }
+    }
+
+    const { data, metadata } = await query.graph({
+      entity: "retailos_cms_handover",
+      fields: [
+        "*",
+        "retailos_employee.id",
+        "retailos_employee.first_name",
+        "retailos_employee.last_name",
+        "retailos_employee.email",
+        "retailos_store.id",
+        "retailos_store.name",
+        "retailos_store.store_code",
+      ],
+      filters: filters as any,
+      pagination: { skip: offset, take: limit },
+      // @ts-ignore
+      order,
     })
-    return res.status(200).json({ handovers: data, count })
+
+    const handovers = (data as any[]).map((h: any) => ({
+      ...h,
+      employee: h.retailos_employee
+        ? {
+            id: h.retailos_employee.id,
+            first_name: h.retailos_employee.first_name,
+            last_name: h.retailos_employee.last_name,
+          }
+        : null,
+      store: h.retailos_store
+        ? {
+            id: h.retailos_store.id,
+            name: h.retailos_store.name,
+            store_code: h.retailos_store.store_code,
+          }
+        : null,
+    }))
+
+    return res.status(200).json({ handovers, count: (metadata as any)?.count ?? handovers.length })
   } catch (err) {
     getLogger(req).error("[retailos/cms] list handovers failed", {
       error: err instanceof Error ? err.message : String(err),

package/src/api/admin/retailos/cms/petty-cash/__tests__/route.test.ts

@@ -3,13 +3,13 @@ import { GET } from "../route"
 
 function makeService() {
   return {
-    listAndCountPettyCashTransactions: vi.fn().mockResolvedValue([[], 0]),
+    listAndCountRetailosPettyCashTransactions: vi.fn().mockResolvedValue([[], 0]),
   }
 }
 
-function makeReq(filterableFields: Record<string, unknown> = {}, service = makeService()) {
+function makeReq(query: Record<string, unknown> = {}, service = makeService()) {
   return {
-    filterableFields,
+    query,
     scope: {
       resolve: vi.fn().mockImplementation((key: string) => {
         if (key === "cms") return service
@@ -28,32 +28,38 @@ function makeRes() {
 }
 
 describe("GET /petty-cash", () => {
-  it("returns transactions and count", async () => {
+  it("returns petty cash transactions and count", async () => {
     const service = makeService()
     const transactions = [{ id: "pct_1" }, { id: "pct_2" }]
-    service.listAndCountPettyCashTransactions.mockResolvedValue([transactions, 2])
+    service.listAndCountRetailosPettyCashTransactions.mockResolvedValue([transactions, 2])
     const req = makeReq({}, service)
     const res = makeRes()
 
     await GET(req as any, res as any)
 
-    expect(service.listAndCountPettyCashTransactions).toHaveBeenCalledWith(
+    expect(service.listAndCountRetailosPettyCashTransactions).toHaveBeenCalledWith(
       expect.objectContaining({ transaction_type: ["open", "close", "petty_cash"] }),
       expect.objectContaining({ take: 100 })
     )
     expect(res.status).toHaveBeenCalledWith(200)
-    expect(res.json).toHaveBeenCalledWith({ transactions, count: 2 })
+    expect(res.json).toHaveBeenCalledWith({
+      petty_cash: [
+        { id: "pct_1", employee: null },
+        { id: "pct_2", employee: null },
+      ],
+      count: 2,
+    })
   })
 
-  it("merges filterableFields with transaction_type filter", async () => {
+  it("includes store_id in filter when provided", async () => {
     const service = makeService()
-    service.listAndCountPettyCashTransactions.mockResolvedValue([[], 0])
-    const req = makeReq({ store_id: ["s1"] }, service)
+    service.listAndCountRetailosPettyCashTransactions.mockResolvedValue([[], 0])
+    const req = makeReq({ store_id: "s1" }, service)
     const res = makeRes()
 
     await GET(req as any, res as any)
 
-    expect(service.listAndCountPettyCashTransactions).toHaveBeenCalledWith(
+    expect(service.listAndCountRetailosPettyCashTransactions).toHaveBeenCalledWith(
       expect.objectContaining({ store_id: ["s1"], transaction_type: ["open", "close", "petty_cash"] }),
       expect.any(Object)
     )
@@ -61,7 +67,7 @@ describe("GET /petty-cash", () => {
 
   it("returns 500 when service throws", async () => {
     const service = makeService()
-    service.listAndCountPettyCashTransactions.mockRejectedValue(new Error("db error"))
+    service.listAndCountRetailosPettyCashTransactions.mockRejectedValue(new Error("db error"))
     const req = makeReq({}, service)
     const res = makeRes()
 

package/src/api/admin/retailos/cms/petty-cash/route.ts

@@ -5,6 +5,8 @@ import type {
 import { CMS_MODULE } from "../../../../../modules/cms/constants"
 import type CmsModuleService from "../../../../../modules/cms/services/cms-module-service"
 
+const EMPLOYEE_MODULE = "employee"
+
 function getService(req: AuthenticatedMedusaRequest): CmsModuleService {
   return (req as any).scope.resolve(CMS_MODULE)
 }
@@ -20,12 +22,52 @@ function getLogger(req: AuthenticatedMedusaRequest) {
 export const GET = async (req: AuthenticatedMedusaRequest, res: MedusaResponse) => {
   try {
     const service = getService(req)
-    const filters = (req.filterableFields ?? {}) as Record<string, unknown>
-    const [transactions, count] = await service.listAndCountPettyCashTransactions(
+    const q = req.query as Record<string, any>
+
+    const filters: Record<string, unknown> = {}
+    if (q.store_id) filters.store_id = [q.store_id]
+
+    const limit = q.limit ? Math.min(parseInt(q.limit as string, 10), 500) : 100
+    const offset = q.offset ? parseInt(q.offset as string, 10) : 0
+
+    const [transactions, count] = await service.listAndCountRetailosPettyCashTransactions(
       { ...filters, transaction_type: ["open", "close", "petty_cash"] },
-      { take: 100, order: { created_at: "DESC" } }
+      { take: limit, skip: offset, order: { created_at: "DESC" } } as any
     )
-    return res.status(200).json({ transactions, count })
+
+    // Enrich with employee data via bulk lookup
+    const employeeIds = [...new Set(
+      transactions.map((t: any) => t.employee_id).filter(Boolean)
+    )] as string[]
+
+    let employeeMap = new Map<string, { id: string; first_name: string; last_name: string }>()
+    if (employeeIds.length) {
+      try {
+        const employeeService = (req as any).scope.resolve(EMPLOYEE_MODULE)
+        const employees = await employeeService.listEmployees(
+          { id: employeeIds },
+          { select: ["id", "first_name", "last_name"] }
+        )
+        employeeMap = new Map(employees.map((e: any) => [e.id, e]))
+      } catch {
+        // employee module unavailable — return without enrichment
+      }
+    }
+
+    const petty_cash = transactions.map((t: any) => ({
+      ...t,
+      employee: t.employee_id
+        ? (employeeMap.get(t.employee_id)
+            ? {
+                id: employeeMap.get(t.employee_id)!.id,
+                first_name: employeeMap.get(t.employee_id)!.first_name,
+                last_name: employeeMap.get(t.employee_id)!.last_name,
+              }
+            : null)
+        : null,
+    }))
+
+    return res.status(200).json({ petty_cash, count })
   } catch (err) {
     getLogger(req).error("[retailos/cms] list petty cash failed", {
       error: err instanceof Error ? err.message : String(err),