@medusajs/customer 2.22.0-snapshot-20261020204851 → 2.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/AGENTS.md +73 -0
  2. package/README.md +69 -5
  3. package/package.json +8 -4
package/AGENTS.md ADDED
@@ -0,0 +1,73 @@
1
+ # @medusajs/customer
2
+
3
+ Customer Module (`Modules.CUSTOMER`, container key `"customer"`). Stores customers (guest and registered), their addresses, and customer groups. Authentication is not here: registered customers are tied to an Auth Module identity via `app_metadata.customer_id`.
4
+
5
+ ## Using this package
6
+
7
+ - Registered by default via `defineConfig` as `@medusajs/medusa/customer`. No module options.
8
+ - Resolve: `container.resolve(Modules.CUSTOMER)` (`ICustomerModuleService`).
9
+ - Prefer core-flows workflows (`@medusajs/medusa/core-flows`) such as `createCustomersWorkflow` and `createCustomerAccountWorkflow` (creates the customer and sets `customer_id` on the auth identity). They also handle default-address flipping and emit the public events.
10
+
11
+ ```ts
12
+ const customerModule = container.resolve(Modules.CUSTOMER)
13
+
14
+ const customer = await customerModule.createCustomers({
15
+ email: "jane@example.com",
16
+ addresses: [{ address_1: "1 Main St", is_default_shipping: true }],
17
+ })
18
+
19
+ await customerModule.updateCustomers(customer.id, { first_name: "Jane" })
20
+ await customerModule.addCustomerToGroup({
21
+ customer_id: customer.id,
22
+ customer_group_id: groupId,
23
+ })
24
+ ```
25
+
26
+ ### Data models (`src/models`)
27
+
28
+ - `Customer` (`cus_`): `email`, `first_name`, `last_name`, `company_name`, `phone`, `has_account`, `created_by`, `metadata`; `addresses` (cascade delete), `groups` (many-to-many via `CustomerGroupCustomer`). Unique on (`email`, `has_account`) among non-deleted rows.
29
+ - `CustomerAddress` (`cuaddr_`): address fields plus `is_default_shipping` / `is_default_billing`. Partial unique indexes allow one default of each per customer.
30
+ - `CustomerGroup` (`cusgroup_`): `name` (unique among non-deleted, translatable), `metadata`, `created_by`.
31
+ - `CustomerGroupCustomer` (`cusgc_`): pivot with `created_by`, `metadata`.
32
+
33
+ ### Custom service methods (`src/services/customer-module.ts`)
34
+
35
+ - `createCustomers(data | data[])`: also creates nested `addresses`.
36
+ - `updateCustomers(id | ids[] | selector, data)`, `updateCustomerGroups(...)`, `updateCustomerAddresses(...)`: same `(idOrIdsOrSelector, data)` shape.
37
+ - `addCustomerToGroup(pair | pairs)`, `removeCustomerFromGroup(pair | pairs)` with `{ customer_id, customer_group_id }`.
38
+ - `createCustomerGroups`, `createCustomerAddresses`; everything else is generated by `MedusaService`.
39
+
40
+ ### Events
41
+
42
+ - `customer.created`, `customer.updated`, `customer.deleted` (`CustomerWorkflowEvents`) are emitted by core-flows workflows, not by the module.
43
+ - The module emits internal mutation events like `customer.customer.created`, `customer.customer-address.updated`.
44
+
45
+ ### Module links
46
+
47
+ - Stored: `Customer` <-> payment `AccountHolder` (`customer.account_holders`, `link-modules/src/definitions/customer-account-holder.ts`).
48
+ - Read-only: `cart.customer` / `customer.carts`, `order.customer` / `customer.orders` (joined on `customer_id`).
49
+
50
+ ### Docs
51
+
52
+ - https://docs.medusajs.com/resources/commerce-modules/customer.md
53
+ - https://docs.medusajs.com/resources/commerce-modules/customer/customer-accounts.md
54
+ - https://docs.medusajs.com/resources/commerce-modules/customer/links-to-other-modules.md
55
+ - https://docs.medusajs.com/resources/commerce-modules/customer/extend.md
56
+ - https://docs.medusajs.com/resources/commerce-modules/customer/workflows.md
57
+
58
+ ## Development
59
+
60
+ ```bash
61
+ yarn build
62
+ yarn test # src unit tests (none currently)
63
+ yarn test:integration # integration-tests/__tests__/services/customer-module/index.spec.ts (Postgres)
64
+ yarn test:integration -t "<test name>"
65
+ yarn migration:create # after any change to src/models; never hand-write migrations
66
+ ```
67
+
68
+ ## Gotchas
69
+
70
+ - `updateCustomers` takes `(ids, data)`, not an array of `{ id, ...data }` objects. An array is always treated as a list of IDs, so `updateCustomers([{ id, first_name }])` does not do a batch update.
71
+ - The same email can exist twice: once as a guest (`has_account: false`) and once registered (`has_account: true`).
72
+ - Setting a second default shipping/billing address for a customer violates a unique index. The module does not unset the previous default; the core-flows steps `maybe-unset-default-*-addresses` do.
73
+ - Deleting a customer cascades to its addresses and detaches group memberships; deleting a group only detaches customers.
package/README.md CHANGED
@@ -1,8 +1,72 @@
1
- # Customer Module
1
+ <p align="center">
2
+ <a href="https://www.medusajs.com">
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
5
+ <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
6
+ <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
7
+ </picture>
8
+ </a>
9
+ </p>
10
+ <h1 align="center">
11
+ @medusajs/customer
12
+ </h1>
2
13
 
3
- Customers represent entities who can make purchases in a store.
14
+ <h4 align="center">
15
+ <a href="https://docs.medusajs.com">Documentation</a> |
16
+ <a href="https://www.medusajs.com">Website</a>
17
+ </h4>
4
18
 
5
- ### Features
19
+ <p align="center">
20
+ Building blocks for digital commerce
21
+ </p>
22
+ <p align="center">
23
+ <a href="https://github.com/medusajs/medusa/blob/develop/LICENSE">
24
+ <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Medusa is released under the MIT license." />
25
+ </a>
26
+ <a href="https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md">
27
+ <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
28
+ </a>
29
+ <a href="https://discord.gg/xpCwq3Kfn8">
30
+ <img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
31
+ </a>
32
+ <a href="https://twitter.com/intent/follow?screen_name=medusajs">
33
+ <img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
34
+ </a>
35
+ </p>
6
36
 
7
- - The customer module enables you to store your customers’s contact details.
8
- - The customer module enables you to group your customers.
37
+ Customer Module for Medusa: manages customers, customer addresses, and customer groups. Use it to store customer contact details and segment customers into groups. It ships with `@medusajs/medusa` and is registered by default, so you normally use it through the Medusa application rather than installing it directly.
38
+
39
+ ## At a glance
40
+
41
+ | | |
42
+ | --- | --- |
43
+ | Package | `@medusajs/customer` |
44
+ | Type | Commerce Module |
45
+ | Module key | `Modules.CUSTOMER` (`"customer"`) |
46
+ | Registered by default | Yes |
47
+ | Import from | `@medusajs/medusa/customer` |
48
+
49
+ ## Features
50
+
51
+ - Store customer contact details and multiple addresses per customer.
52
+ - Group customers into customer groups.
53
+
54
+ ## Installation
55
+
56
+ No installation needed. The module ships with `@medusajs/medusa` and is registered by default.
57
+
58
+ ## Usage
59
+
60
+ Resolve the module's service from the container, for example in a workflow step:
61
+
62
+ ```ts
63
+ import { Modules } from "@medusajs/framework/utils"
64
+
65
+ const customerModuleService = container.resolve(Modules.CUSTOMER)
66
+ ```
67
+
68
+ ## Resources
69
+
70
+ - [Customer Module](https://docs.medusajs.com/resources/commerce-modules/customer)
71
+ - [Customer accounts](https://docs.medusajs.com/resources/commerce-modules/customer/customer-accounts)
72
+ - [Commerce Modules](https://docs.medusajs.com/learn/fundamentals/modules/commerce-modules)
package/package.json CHANGED
@@ -1,15 +1,19 @@
1
1
  {
2
2
  "name": "@medusajs/customer",
3
- "version": "2.22.0-snapshot-20261020204851",
3
+ "version": "2.22.0",
4
4
  "description": "Medusa Customer module",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
7
7
  "files": [
8
8
  "dist",
9
+ "AGENTS.md",
9
10
  "!dist/**/__tests__",
10
11
  "!dist/**/__mocks__",
11
12
  "!dist/**/__fixtures__"
12
13
  ],
14
+ "llms": "https://docs.medusajs.com/llms.txt",
15
+ "llmsFull": "https://docs.medusajs.com/llms-full.txt",
16
+ "mcpServer": "https://docs.medusajs.com/mcp",
13
17
  "engines": {
14
18
  "node": ">=22.22.0"
15
19
  },
@@ -40,10 +44,10 @@
40
44
  "orm:cache:clear": "MIKRO_ORM_CLI_CONFIG=./mikro-orm.config.dev.ts MIKRO_ORM_ALLOW_GLOBAL_CLI=true medusa-mikro-orm cache:clear"
41
45
  },
42
46
  "devDependencies": {
43
- "@medusajs/framework": "2.22.0-snapshot-20261020204851",
44
- "@medusajs/test-utils": "2.22.0-snapshot-20261020204851"
47
+ "@medusajs/framework": "2.22.0",
48
+ "@medusajs/test-utils": "2.22.0"
45
49
  },
46
50
  "peerDependencies": {
47
- "@medusajs/framework": "2.22.0-snapshot-20261020204851"
51
+ "@medusajs/framework": "2.22.0"
48
52
  }
49
53
  }