@devx-retailos/footfall

Time-series visitor footfall tracking per store: append-only counter events with a timestamp, optional source and recording employee, plus an aggregation helper for totals over a date range.

Part of retailOS, a Medusa v2 SDK for offline-store POS systems. Each @devx-retailos/* package is an independently installable Medusa plugin that you compose in your brand's Medusa backend.

Installation

npm install @devx-retailos/footfall

Requires a Medusa v2 project (@medusajs/framework / @medusajs/medusa ^2.15.0 as peers). @devx-retailos/core and @devx-retailos/rbac are installed automatically as dependencies — each footfall event is linked to the RBAC retailos_store entity.

Setup

// medusa-config.ts
module.exports = defineConfig({
  // ...
  plugins: [
    {
      resolve: "@devx-retailos/rbac",
      options: {},
    },
    {
      resolve: "@devx-retailos/footfall",
      options: {},
    },
  ],
})

Then run migrations to create the retailos_footfall table:

npx medusa db:migrate

Usage

import {
  FOOTFALL_MODULE,
  type FootfallModuleService,
  type RecordFootfallInput,
  type FootfallAggregateFilters,
} from "@devx-retailos/footfall"

const footfall: FootfallModuleService = container.resolve(FOOTFALL_MODULE)

// Record an event (count must be >= 0; recorded_at defaults to now)
await footfall.record({
  organization_id: "org_1",
  store_id: "store_1",
  count: 4,
  source: "manual",
  recorded_by_employee_id: "emp_1",
} satisfies RecordFootfallInput)

// Sum counts for a store within a date range
const total = await footfall.totalForStore({
  organization_id: "org_1",
  store_id: "store_1",
  from: new Date("2026-06-01"),
  to: new Date("2026-06-30"),
} satisfies FootfallAggregateFilters)

The service extends Medusa's MedusaService, so the generated CRUD methods (listFootfalls, listAndCountFootfalls, deleteFootfalls, ...) are also available for raw time-series queries.

Event fields: organization_id, store_id, recorded_at, count, recorded_by_employee_id (nullable), source (nullable), metadata (JSON, nullable).

Permissions

The module exports FOOTFALL_PERMISSIONS (a PermissionRegistration[], also importable from @devx-retailos/footfall/permissions) for registration into the RBAC permission table:

| Key | Description | | --- | --- | | footfall.read | View footfall entries and aggregates | | footfall.create | Record a new footfall entry | | footfall.delete | Delete a footfall entry |

API routes

All routes live under the authenticated Medusa admin scope:

| Method | Path | Description | | --- | --- | --- | | GET | /admin/retailos/footfall | List footfall events (newest first, up to 200) | | POST | /admin/retailos/footfall | Record a footfall event (Zod-validated body) | | GET | /admin/retailos/footfall/total | Total count for organization_id / store_id / from / to query filters |

Related packages

• @devx-retailos/core — shared types, Logger, errors, permission registry.
• @devx-retailos/rbac — organizations, stores, roles, permissions; this module links to its retailos_store.
• @devx-retailos/store-details — extended store metadata (address, contact, tax info).
• @devx-retailos/store-config — typed org/store-scoped configuration entries and sequence counters.

License

MIT