@medusajs/inventory 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 +59 -0
  2. package/README.md +69 -0
  3. package/package.json +8 -4
package/AGENTS.md ADDED
@@ -0,0 +1,59 @@
1
+ # @medusajs/inventory
2
+
3
+ Inventory Module (`Modules.INVENTORY`): inventory items, their stock per location (inventory levels), and reservations against that stock.
4
+
5
+ ## Using this package
6
+
7
+ - Registered by default; consumers import it as `@medusajs/medusa/inventory`. No module options.
8
+ - Resolve: `container.resolve(Modules.INVENTORY)` (type `IInventoryService` from `@medusajs/framework/types`). Prefer `@medusajs/core-flows` workflows (e.g. reservation and inventory-level workflows) for mutations.
9
+
10
+ **Data models** (`src/models`):
11
+
12
+ - `InventoryItem` (`iitem_`): `sku` (unique among non-deleted), customs/dimension fields, `requires_shipping`. Computed `stocked_quantity` / `reserved_quantity` are lazy SQL formulas summing its levels (`src/utils/apply-decorators.ts`). Deleting cascades to `location_levels` and `reservation_items`.
13
+ - `InventoryLevel` (`ilev_`): one per `(inventory_item_id, location_id)` (unique), `stocked_quantity`, `reserved_quantity`, `incoming_quantity`; `available_quantity` = stocked - reserved, computed in an `onInit` hook.
14
+ - `ReservationItem` (`resitem_`): `inventory_item_id`, `location_id`, `quantity`, `line_item_id`, `allow_backorder`, `external_id`.
15
+ - `location_id` is a plain string pointing at the Stock Location Module; there is no FK.
16
+
17
+ **Custom service methods** (`src/services/inventory-module.ts`):
18
+
19
+ - `adjustInventory(itemId, locationId, adjustment)` or `adjustInventory([{ inventoryItemId, locationId, adjustment }])`: adds `adjustment` to `stocked_quantity`.
20
+ - `confirmInventory(itemId, locationIds, quantity)`, `retrieveAvailableQuantity`, `retrieveStockedQuantity`, `retrieveReservedQuantity` (summed over `locationIds`; empty array returns 0), `retrieveInventoryLevelByItemAndLocation`.
21
+ - `deleteInventoryLevel(itemId, locationId)`, `deleteInventoryItemLevelByLocationId(locationIds)` (soft delete).
22
+ - `deleteReservationItemByLocationId`, `deleteReservationItemsByLineItem`, `restoreReservationItemsByLineItem`.
23
+ - `create/update/delete/softDelete/restoreReservationItems`, `create/updateInventoryLevels`, `create/updateInventoryItems` are overridden to keep `reserved_quantity` in sync; the rest is generated by `MedusaService`.
24
+
25
+ **Events**: `InventoryEvents` from `@medusajs/framework/utils` (`inventory.inventory-item.*`, `inventory.inventory-level.*`, `inventory.reservation-item.*`), emitted from ORM mutation hooks by `MedusaService` in `@EmitEvents` methods.
26
+
27
+ **Module links** (in `packages/modules/link-modules`):
28
+
29
+ - `product_variant_inventory_item` (`ProductVariant` <-> `InventoryItem`, extra column `required_quantity`, default 1; exposes `variant.inventory_items` and `inventory_item.variants`).
30
+ - Read-only: `InventoryLevel.location_id` -> stock location (`stock_locations`).
31
+
32
+ Docs: https://docs.medusajs.com/resources/commerce-modules/inventory.md, https://docs.medusajs.com/resources/commerce-modules/inventory/concepts.md, https://docs.medusajs.com/resources/commerce-modules/inventory/reservations-lifecycle.md, https://docs.medusajs.com/resources/commerce-modules/inventory/inventory-kit.md
33
+
34
+ ## Architecture
35
+
36
+ - `src/services/inventory-level.ts` (`InventoryLevelService`) wraps `src/repositories/inventory-level.ts`, whose `getAvailableQuantity` / `getStockedQuantity` / `getReservedQuantity` aggregate in SQL. Importing it calls `applyEntityHooks()`, which patches the MikroORM entities with the `onInit` hook and `@Formula` columns.
37
+ - `src/joiner-config.ts`: aliases `inventory_items` / `inventory_item` / `inventory` -> `InventoryItem`, `reservation(s)` / `reservation_item(s)` -> `ReservationItem`.
38
+
39
+ ## Development
40
+
41
+ ```bash
42
+ cd packages/modules/inventory
43
+ yarn build
44
+ yarn test
45
+ yarn test:integration # needs Postgres
46
+ ../../../node_modules/.bin/jest integration-tests/__tests__/inventory-module-service.spec.ts -t "adjustInventory"
47
+ yarn migration:create # after any change in src/models
48
+ ```
49
+
50
+ - Integration tests: `integration-tests/__tests__/inventory-module-service.spec.ts`.
51
+
52
+ ## Gotchas
53
+
54
+ - `reserved_quantity` cannot be set through `createInventoryLevels` / `updateInventoryLevels`; it is stripped from input. It only moves when reservations are created, updated (quantity or location change), deleted, soft-deleted or restored.
55
+ - `location_levels` is stripped from `createInventoryItems` / `updateInventoryItems` input; create levels separately.
56
+ - `createReservationItems` throws `NOT_FOUND` if the item is not stocked at the location and `NOT_ALLOWED` ("Not enough stock available") when `available_quantity < quantity`, unless `allow_backorder` is true.
57
+ - `updateInventoryLevels` addresses levels by `inventory_item_id` + `location_id`, not by `id`.
58
+ - `adjustInventory` with an array runs each adjustment sequentially in its own transaction.
59
+ - Quantities are `bigNumber` columns; use `MathBN` / `BigNumber` from `@medusajs/framework/utils`, not JS arithmetic.
package/README.md ADDED
@@ -0,0 +1,69 @@
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/inventory
12
+ </h1>
13
+
14
+ <h4 align="center">
15
+ <a href="https://docs.medusajs.com">Documentation</a> |
16
+ <a href="https://www.medusajs.com">Website</a>
17
+ </h4>
18
+
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>
36
+
37
+ Inventory Module for Medusa: manages inventory items, their stock levels per location, and reservations. Use it to track stocked quantities, reserve stock for orders and carts, and check availability across locations. It ships with `@medusajs/medusa` and is registered by default; resolve it in your code with `container.resolve(Modules.INVENTORY)`.
38
+
39
+ ## At a glance
40
+
41
+ | | |
42
+ | --- | --- |
43
+ | Package | `@medusajs/inventory` |
44
+ | Type | Commerce Module |
45
+ | Module key | `Modules.INVENTORY` (`"inventory"`) |
46
+ | Registered by default | Yes |
47
+
48
+ ## Installation
49
+
50
+ No installation needed. The module ships with `@medusajs/medusa`.
51
+
52
+ ## Usage
53
+
54
+ ```ts
55
+ import { Modules } from "@medusajs/framework/utils"
56
+
57
+ const inventoryModuleService = container.resolve(Modules.INVENTORY)
58
+
59
+ const [inventoryItems, count] =
60
+ await inventoryModuleService.listAndCountInventoryItems({})
61
+ ```
62
+
63
+ ## Resources
64
+
65
+ - [Inventory Module](https://docs.medusajs.com/resources/commerce-modules/inventory)
66
+ - [Inventory Concepts](https://docs.medusajs.com/resources/commerce-modules/inventory/concepts)
67
+ - [Inventory Kits](https://docs.medusajs.com/resources/commerce-modules/inventory/inventory-kit)
68
+ - [Reservations Lifecycle](https://docs.medusajs.com/resources/commerce-modules/inventory/reservations-lifecycle)
69
+ - [Links to Other Modules](https://docs.medusajs.com/resources/commerce-modules/inventory/links-to-other-modules)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@medusajs/inventory",
3
- "version": "2.22.0-snapshot-20261020204851",
3
+ "version": "2.22.0",
4
4
  "description": "Inventory Module for Medusa",
5
5
  "main": "dist/index.js",
6
6
  "repository": {
@@ -16,21 +16,25 @@
16
16
  },
17
17
  "files": [
18
18
  "dist",
19
+ "AGENTS.md",
19
20
  "!dist/**/__tests__",
20
21
  "!dist/**/__mocks__",
21
22
  "!dist/**/__fixtures__"
22
23
  ],
24
+ "llms": "https://docs.medusajs.com/llms.txt",
25
+ "llmsFull": "https://docs.medusajs.com/llms-full.txt",
26
+ "mcpServer": "https://docs.medusajs.com/mcp",
23
27
  "engines": {
24
28
  "node": ">=22.22.0"
25
29
  },
26
30
  "author": "Medusa",
27
31
  "license": "MIT",
28
32
  "devDependencies": {
29
- "@medusajs/framework": "2.22.0-snapshot-20261020204851",
30
- "@medusajs/test-utils": "2.22.0-snapshot-20261020204851"
33
+ "@medusajs/framework": "2.22.0",
34
+ "@medusajs/test-utils": "2.22.0"
31
35
  },
32
36
  "peerDependencies": {
33
- "@medusajs/framework": "2.22.0-snapshot-20261020204851"
37
+ "@medusajs/framework": "2.22.0"
34
38
  },
35
39
  "scripts": {
36
40
  "watch": "yarn run -T tsc --build --watch",