@devx-retailos/store-details

Extended store metadata for POS backends: address, contact, tax info, opening hours, and a JSON metadata escape hatch — stored 1:1 against a retailos_store.

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-details

Requires a Medusa v2 project (@medusajs/framework / @medusajs/medusa ^2.15.0 as peers, plus @medusajs/admin-sdk, @medusajs/ui, and React for the bundled admin page). @devx-retailos/core and @devx-retailos/rbac are installed automatically as dependencies — the module links each details record to the RBAC retailos_store entity.

Setup

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

Then run migrations to create the retailos_store_details table:

npx medusa db:migrate

Usage

Resolve the service from the Medusa container using the exported module key:

import {
  STORE_DETAILS_MODULE,
  type StoreDetailsModuleService,
  type UpsertStoreDetailsInput,
} from "@devx-retailos/store-details"

const storeDetails: StoreDetailsModuleService =
  container.resolve(STORE_DETAILS_MODULE)

// Create-or-update the single details record for a store
await storeDetails.upsertForStore({
  store_id: "store_123",
  email: "[email protected]",
  phone_number: "+91 9876543210",
  address_line_1: "12 Market Road",
  city: "Bengaluru",
  state: "Karnataka",
  pin_code: "560001",
  country: "India",
  gst_number: "29ABCDE1234F1Z5",
  store_timings: "10:00-21:00",
  metadata: { floor: "G" },
} satisfies UpsertStoreDetailsInput)

// Fetch by store id (returns null if none exists)
const details = await storeDetails.findByStoreId("store_123")

The service extends Medusa's MedusaService, so the generated CRUD methods (listStoreDetails, retrieveStoreDetails, createStoreDetails, updateStoreDetails, ...) are also available.

Fields: email, phone_number, address_line_1/2, pin_code, city, state, state_code, country, store_timings, gst_number, gst_owner_name, billing_address (JSON), metadata (JSON). All nullable.

Permissions

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

| Key | Description | | --- | --- | | store_details.read | View store details | | store_details.update | Update store details |

API routes

All routes live under the authenticated Medusa admin scope:

| Method | Path | Description | | --- | --- | --- | | GET | /admin/retailos/stores | List all store-details records (newest first) | | GET | /admin/retailos/stores/:id/details | Get details for a store by store id (404 if none) | | POST | /admin/retailos/stores/:id/details | Upsert details for a store (Zod-validated body) |

Admin UI

Ships a "Stores" page in Medusa Admin (sidebar route) that lists store-details records and provides a form to create and edit a store's address, contact, GST, and timing fields.

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-config — typed org/store-scoped configuration entries and sequence counters.
• @devx-retailos/footfall — time-series visitor footfall per store.

License

MIT