@medusajs/user 2.22.0-snapshot-20261020204851 → 2.22.0

package/AGENTS.md

@@ -0,0 +1,75 @@
+# @medusajs/user
+
+Commerce module for admin users and user invites, including signing and validating JWT invite tokens. Authentication itself lives in the Auth Module. Registered as `Modules.USER` (`"user"`).
+
+## Using this package
+
+- Loaded by default through `defineConfig` (`@medusajs/medusa/user`), which passes the options from `projectConfig.http` (`jwtSecret` or `JWT_SECRET`, `jwtOptions`, `jwtVerifyOptions`, `jwtPublicKey`). Override only to change invite behavior:
+
+```ts
+module.exports = defineConfig({
+  modules: [
+    {
+      resolve: "@medusajs/medusa/user",
+      options: {
+        jwt_secret: process.env.JWT_SECRET,
+        valid_duration: 60 * 60 * 24, // invite TTL in seconds
+      },
+    },
+  ],
+})
+```
+
+- Options read by the service constructor: `jwt_secret` (required, the module throws `INVALID_DATA` without it), `jwt_public_key`, `jwt_options` (jsonwebtoken `SignOptions`), `jwt_verify_options`, `valid_duration` (seconds; falls back to `jwt_options.expiresIn`, then 24 hours).
+- In apps, prefer the core-flows workflows: `createUsersWorkflow`, `updateUsersWorkflow`, `deleteUsersWorkflow`, `createUserAccountWorkflow`, `removeUserAccountWorkflow`, `createInvitesWorkflow`, `acceptInviteWorkflow`, `refreshInviteTokensWorkflow`, `deleteInvitesWorkflow`, and RBAC ones (`assignUserRolesWorkflow`, `removeUserRolesWorkflow`).
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import type { IUserModuleService } from "@medusajs/framework/types"
+
+const userModuleService: IUserModuleService = container.resolve(Modules.USER)
+const invite = await userModuleService.validateInviteToken(token)
+```
+
+### Data models (`src/models`)
+
+- `User` (`user_`): `first_name`, `last_name`, `email` (unique among non-deleted), `avatar_url`, `metadata`.
+- `Invite` (`invite_`): `email` (unique among non-deleted), `accepted`, `token`, `expires_at`, `metadata`.
+
+### Service methods (`src/services/user-module.ts`)
+
+Generated CRUD for both models, plus:
+
+- `validateInviteToken(token)`: verifies the JWT, loads the invite, and checks the token matches the stored one and is not expired.
+- `refreshInviteTokens(inviteIds)`: issues new tokens and `expires_at`.
+- Overridden `createUsers`, `updateUsers`, `createInvites` (generates token and expiry), `updateInvites`.
+
+### Events and links
+
+- Internal CRUD events plus `user.user.invite.token_generated` (`UserEvents.INVITE_TOKEN_GENERATED` from `@medusajs/framework/utils`), emitted by `createInvites`, `updateInvites`, and `refreshInviteTokens`.
+- Workflow events: `user.created|updated|deleted` (`UserWorkflowEvents`) and `invite.created|accepted|deleted|resent` (`InviteWorkflowEvents`).
+- Module links: `user-rbac-role` (`user_rbac_role`) and `invite-rbac-role` (`invite_rbac_role`) to the RBAC Module.
+
+Docs: https://docs.medusajs.com/resources/commerce-modules/user.md, https://docs.medusajs.com/resources/commerce-modules/user/module-options.md, https://docs.medusajs.com/resources/commerce-modules/user/user-creation-flows.md, https://docs.medusajs.com/resources/commerce-modules/user/invite-user-subscriber.md
+
+## Architecture
+
+- Tokens are signed in `generateToken` with `jwt_secret` and `jwt_options` (a random `jwtid` per token unless set). Verification uses `jwt_public_key ?? jwt_secret` and `jwt_verify_options ?? jwt_options`; a single `algorithm` option is converted to `algorithms` for verification.
+- `getExpiresAt` in `src/utils/utils.ts` accepts seconds (number) or a timespan string.
+
+## Development
+
+```bash
+cd packages/modules/user
+yarn build
+yarn test
+yarn test:integration           # integration-tests/__tests__/{user,invite}.spec.ts (needs Postgres, DB_* env vars)
+yarn migration:create           # after any change in src/models
+```
+
+## Gotchas
+
+- The constructor's second parameter is named `moduleDeclaration` but holds the module options; option keys are snake_case.
+- A refreshed (resent) invite invalidates earlier tokens: `validateInviteToken` rejects any token not equal to the stored `invite.token`.
+- `createInvites` throws `INVALID_DATA` when a user with the email already exists.
+- `updateInvites` emits `INVITE_TOKEN_GENERATED` on every update, even when the token didn't change.

package/README.md

@@ -1,3 +1,88 @@
-# User Module
+<p align="center">
+  <a href="https://www.medusajs.com">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
+    <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
+    </picture>
+  </a>
+</p>
+<h1 align="center">
+  @medusajs/user
+</h1>
 
-The User Module is Medusa’s user engine.
+<h4 align="center">
+  <a href="https://docs.medusajs.com">Documentation</a> |
+  <a href="https://www.medusajs.com">Website</a>
+</h4>
+
+<p align="center">
+  Building blocks for digital commerce
+</p>
+<p align="center">
+  <a href="https://github.com/medusajs/medusa/blob/develop/LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Medusa is released under the MIT license." />
+  </a>
+  <a href="https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md">
+    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
+  </a>
+  <a href="https://discord.gg/xpCwq3Kfn8">
+    <img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
+  </a>
+  <a href="https://twitter.com/intent/follow?screen_name=medusajs">
+    <img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
+  </a>
+</p>
+
+User Module for Medusa: manages admin users and invites, including generating and validating invite tokens. It's installed and registered by default with `@medusajs/medusa`, which passes it the JWT settings from your project config, so Medusa applications use it through the `Modules.USER` service rather than installing this package directly.
+
+## At a glance
+
+| | |
+| --- | --- |
+| Package | `@medusajs/user` |
+| Type | Commerce Module |
+| Module key | `Modules.USER` (`"user"`) |
+| Registered by default | Yes |
+| Import from | `@medusajs/medusa/user` |
+
+## Installation
+
+No installation needed. The module ships with `@medusajs/medusa` and is registered by `defineConfig`.
+
+## Usage
+
+To customize the module's options, such as the invite token's validity, register it in `medusa-config.ts`:
+
+```ts
+import { defineConfig } from "@medusajs/framework/utils"
+
+module.exports = defineConfig({
+  // ...
+  modules: [
+    {
+      resolve: "@medusajs/medusa/user",
+      options: {
+        jwt_secret: process.env.JWT_SECRET,
+        valid_duration: 60 * 60 * 24,
+      },
+    },
+  ],
+})
+```
+
+## Configuration
+
+| Option | Type | Description | Default |
+| --- | --- | --- | --- |
+| `jwt_secret` | `string` | Secret used to sign invite tokens (or the private key when using asymmetric signing). Required: the module throws on startup if it's missing. | `projectConfig.http.jwtSecret`, then the `JWT_SECRET` environment variable (set by `defineConfig`) |
+| `jwt_public_key` | `string` | Public key used to verify invite tokens when using asymmetric signing. | `projectConfig.http.jwtPublicKey` (set by `defineConfig`) |
+| `valid_duration` | `number` | How long an invite token is valid, in seconds. | `jwt_options.expiresIn`, then `86400` (24 hours) |
+| `jwt_options` | `object` | [jsonwebtoken](https://github.com/auth0/node-jsonwebtoken) sign options, such as `algorithm`. | `projectConfig.http.jwtOptions` (set by `defineConfig`) |
+| `jwt_verify_options` | `object` | jsonwebtoken verify options, such as `algorithms`. Falls back to `jwt_options` when not set. | `projectConfig.http.jwtVerifyOptions` (set by `defineConfig`) |
+
+## Resources
+
+- [User Module](https://docs.medusajs.com/resources/commerce-modules/user)
+- [Module Options](https://docs.medusajs.com/resources/commerce-modules/user/module-options)
+- [User Creation Flows](https://docs.medusajs.com/resources/commerce-modules/user/user-creation-flows)

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "@medusajs/user",
-  "version": "2.22.0-snapshot-20261020204851",
+  "version": "2.22.0",
   "description": "Medusa Users module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
+    "AGENTS.md",
     "!dist/**/__tests__",
     "!dist/**/__mocks__",
     "!dist/**/__fixtures__"
   ],
+  "llms": "https://docs.medusajs.com/llms.txt",
+  "llmsFull": "https://docs.medusajs.com/llms-full.txt",
+  "mcpServer": "https://docs.medusajs.com/mcp",
   "engines": {
     "node": ">=22.22.0"
   },
@@ -39,13 +43,13 @@
     "orm:cache:clear": "MIKRO_ORM_CLI_CONFIG=./mikro-orm.config.dev.ts MIKRO_ORM_ALLOW_GLOBAL_CLI=true medusa-mikro-orm cache:clear"
   },
   "devDependencies": {
-    "@medusajs/framework": "2.22.0-snapshot-20261020204851",
-    "@medusajs/test-utils": "2.22.0-snapshot-20261020204851"
+    "@medusajs/framework": "2.22.0",
+    "@medusajs/test-utils": "2.22.0"
   },
   "dependencies": {
     "jsonwebtoken": "^9.0.2"
   },
   "peerDependencies": {
-    "@medusajs/framework": "2.22.0-snapshot-20261020204851"
+    "@medusajs/framework": "2.22.0"
   }
 }