@devx-retailos/store-config

@devx-retailos/store-config

Typed, org/store-scoped configuration entries and atomic sequence counters for POS backends. Store-level values override org-level values; secret values are masked at the API boundary; sequences increment in a single SQL statement so concurrent requests never produce duplicate numbers.

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/store-config

Requires a Medusa v2 project (@medusajs/framework / @medusajs/medusa ^2.15.0 and React as peers). @devx-retailos/core and @devx-retailos/rbac are installed automatically as dependencies — API routes enforce permissions through the RBAC module, and config entries are linked to RBAC organizations and stores.

Setup

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

Then run migrations to create the retailos_config_entry and retailos_config_sequence tables:

npx medusa db:migrate

Usage

import {
  STORE_CONFIG_MODULE,
  type StoreConfigModuleService,
} from "@devx-retailos/store-config"

const config: StoreConfigModuleService = container.resolve(STORE_CONFIG_MODULE)

Typed config entries

Values are stored as strings with a value_type of "string" | "number" | "boolean" | "json" | "secret". Reads resolve the store-level entry first, then fall back to the org-level entry (store_id: null).

const scope = { organization_id: "org_1", store_id: "store_1" }

// Write (validates the value parses as the declared type)
await config.set("invoice.tax_rate", "18", scope, { value_type: "number" })

// Read the raw entry, or the parsed value
const entry = await config.get("invoice.tax_rate", scope)
const rate = await config.getTyped<number>("invoice.tax_rate", scope) // 18

// Optionally register known keys at boot so `set` infers their type
config.registerConfigKey({
  key: "invoice.tax_rate",
  value_type: "number",
  scope: "both",
  description: "GST rate applied at billing",
})

A failed parse throws StoreConfigTypeError (code RETAILOS_STORE_CONFIG_TYPE_MISMATCH). All error classes extend RetailOSError and are importable from @devx-retailos/store-config/errors.

Sequence counters

Sequences are rows in retailos_config_sequence with a prefix, padding, and current_value. Create one with the generated CRUD, then advance it atomically:

await config.createConfigSequences([
  { organization_id: "org_1", store_id: "store_1", key: "invoice_number", prefix: "INV-", padding: 5 },
])

const next = await config.nextSequence("invoice_number", scope) // "INV-00001"
await config.resetSequence("invoice_number", scope, { value: 0 })

nextSequence / resetSequence throw StoreConfigSequenceNotFoundError (code RETAILOS_STORE_CONFIG_SEQUENCE_NOT_FOUND) if no sequence matches the key and scope.

Permissions

Exported as STORE_CONFIG_PERMISSIONS (also from @devx-retailos/store-config/permissions):

Key	Description
cms.config.read	List and retrieve configuration entries (secrets excluded)
cms.config.update	Create or update configuration entries
cms.config.read_secret	Read the plaintext value of secret-typed configuration entries
cms.sequence.read	List sequence counters and advance to the next value
cms.sequence.reset	Reset a sequence counter to a given value

API routes

Routes resolve scope from organization_id / store_id query params (or body for POSTs) or the x-retailos-organization-id / x-retailos-store-id headers, and check permissions via RBAC. Entries with value_type: "secret" are returned with value: null unless the caller holds cms.config.read_secret.

Method	Path	Description	Permission
GET	/admin/retailos/config	List config entries for a scope	cms.config.read
POST	/admin/retailos/config	Create or update a config entry	cms.config.update
GET	/admin/retailos/config/:key	Get one entry (store-level wins over org-level)	cms.config.read
DELETE	/admin/retailos/config/:key	Delete an entry	cms.config.update
GET	/admin/retailos/config/sequences	List sequence counters for a scope	cms.sequence.read
POST	/admin/retailos/config/sequences/:key/next	Atomically advance and return the formatted value	cms.sequence.read
POST	/admin/retailos/config/sequences/:key/reset	Reset a sequence to a value (default 0)	cms.sequence.reset

Admin UI

Ships a config-editor widget injected into the store.details.after zone of Medusa Admin, with type-aware inputs (checkbox for booleans, number input, JSON textarea) for editing entries.

Related packages

• @devx-retailos/core — shared types, Logger, RetailOSError, permission registry.
• @devx-retailos/rbac — organizations, stores, roles, permissions; enforces this module's permission keys.
• @devx-retailos/store-details — extended store metadata (address, contact, tax info).
• @devx-retailos/footfall — time-series visitor footfall per store.

License

MIT