@devx-retailos/employee

Generic Employee module for Medusa v2: an Employee entity with CRUD service and admin API routes, plus an identity resolver that maps authenticated Medusa users to employee subjects for RBAC.

Part of retailOS, a Medusa v2 SDK for offline-store POS systems. Packages are installed independently and composed in a brand's Medusa backend; this module pairs with @devx-retailos/rbac to give store staff role-based permissions.

Installation

npm install @devx-retailos/employee

Requires a Medusa v2 project (peer dependencies: @medusajs/framework and @medusajs/medusa ^2.15.0). Depends on @devx-retailos/core and @devx-retailos/rbac (installed automatically).

Setup

Register it alongside the RBAC module — on boot a loader syncs this module's permission keys into the RBAC permission table:

// medusa-config.ts
export default defineConfig({
  // ...
  plugins: [
    {
      resolve: "@devx-retailos/rbac",
      options: {},
    },
    {
      resolve: "@devx-retailos/employee",
      options: {},
    },
  ],
})

Then run migrations (npx medusa db:migrate) to create the retailos_employee table.

Data model

Employee (retailos_employee): organization_id, optional store_id, optional medusa_user_id (link to a Medusa admin user), unique employee_code, first_name, last_name, unique email, phone_number, is_active, metadata. Module links connect employees to the RBAC Organization and Store entities.

Usage

Resolve the service with the EMPLOYEE_MODULE key ("employee"):

import { EMPLOYEE_MODULE, type EmployeeModuleService } from "@devx-retailos/employee"

const employees: EmployeeModuleService = req.scope.resolve(EMPLOYEE_MODULE)

const [created] = await employees.createEmployees([
  {
    organization_id: "org_01",
    employee_code: "EMP-001",
    first_name: "Asha",
    last_name: "Rao",
    email: "[email protected]",
  },
])

await employees.linkToMedusaUser(created.id, "user_123")

On top of the standard Medusa-generated CRUD (createEmployees, listEmployees, …):

• findByEmail(email) / findByEmployeeCode(code) / findByMedusaUserId(id)
• linkToMedusaUser(employee_id, medusa_user_id | null) — link or unlink an admin user.
• deactivate(employee_id) — soft-deactivate (is_active: false).

Identity resolver

employeeIdentityResolver turns the authenticated Medusa admin user into an employee subject (SUBJECT_TYPE_EMPLOYEE = "employee"), so roles are assigned to employees rather than raw Medusa users. It looks up the employee by medusa_user_id, returns null if no active linked employee exists, and scopes the check to the employee's own organization_id / store_id (overridable via the x-retailos-organization-id / x-retailos-store-id headers).

// src/api/middlewares.ts
import { defineMiddlewares } from "@medusajs/framework/http"
import { requirePermission } from "@devx-retailos/rbac/middlewares"
import { employeeIdentityResolver } from "@devx-retailos/employee/identity"

export default defineMiddlewares({
  routes: [
    {
      matcher: "/admin/retailos/employees*",
      middlewares: [
        requirePermission("employee.read", {
          identityResolver: employeeIdentityResolver,
        }),
      ],
    },
  ],
})

Permissions

Exported as EMPLOYEE_PERMISSIONS (also via @devx-retailos/employee/permissions) and auto-synced into RBAC at boot:

| Key | Description | | --- | --- | | employee.read | View employees | | employee.create | Create or invite employees | | employee.update | Edit employee profile | | employee.delete | Deactivate employees | | employee.link_user | Link or unlink an Employee with a Medusa admin user |

API routes

Mounted under the Medusa admin API (admin authentication applies). Permission enforcement is left to the consumer — guard them with requirePermission using the keys above.

| Method | Path | Description | | --- | --- | --- | | GET | /admin/retailos/employees | List employees (filterable). | | POST | /admin/retailos/employees | Create an employee. | | GET | /admin/retailos/employees/:id | Retrieve an employee. | | POST | /admin/retailos/employees/:id | Update an employee. | | DELETE | /admin/retailos/employees/:id | Deactivate an employee (soft delete). | | POST | /admin/retailos/employees/:id/link-user | Link/unlink a Medusa user ({ medusa_user_id: string \| null }). |

Related packages

• @devx-retailos/core — shared Subject, IdentityResolver, errors, registries.
• @devx-retailos/rbac — roles, permissions, and the requirePermission middleware this module plugs into.
• @devx-retailos/sdk-client — frontend hooks over the same permission keys.

License

MIT