@rytass/wms-module-graphql 0.5.0 → 0.6.0

package/README.md

@@ -96,19 +96,45 @@ Intervene in and get notified about mutations. Every root mutation carries a typ
 - **`afterListeners`** run **after the outermost transaction commits** — never notified about rolled-back changes.
 
 ```ts
+import { memberBaseActorExtractor } from '@rytass/wms-module-graphql/adapters/member-base';
+
 WmsModuleGraphqlModule.forRootAsync({
   ...coreOptions,
+
+  // (v2) populate payload.actor on every event — reads req.payload → { id, domain }
+  actorExtractor: memberBaseActorExtractor,
+
+  // (v2) append materialId/batchId/locationId/loaderId to stock event payloads
+  enrichStockEvents: true,
+
   beforeHooks: {
-    'ship-inventory-order.shipped': async ({ args }) => {
-      if (!allowed(args)) throw new ForbiddenException('blocked');
+    'ship-inventory-order.shipped': async ({ args, actor }) => {
+      if (!allowed(args, actor)) throw new ForbiddenException('blocked');
     },
   },
   afterListeners: {
+    // v2: payload.args carries items[]; payload.actor carries { id, domain }
+    'ship-inventory-order.shipped': async ({ payload }) => {
+      await erp.markShipped(payload.id, payload.result, payload.actor);
+    },
+    // v2 with enrichStockEvents: materialId/batchId/locationId/loaderId also available
     'stock.allocated': async ({ payload }) => { await erp.reserve(payload); },
   },
 });
 ```
 
+**v2 payload enrichment** (upcoming minor — `core@0.3.0` / `graphql@0.6.0`):
+
+- Operation events gain `args` (the GraphQL input that triggered the mutation) and `actor`
+  (`WmsActor | null`). Nine action mutations return `boolean`; their real information is in
+  `args` and the stock events they fan out.
+- Stock events gain opt-in `materialId / batchId / locationId / loaderId` when
+  `enrichStockEvents: true` is set. **Caveat**: split / merge / reclassify order-items have
+  no `materialId` / `batchId` at the item level — only `locationId` / `loaderId` are
+  available for those three domains even with eager enrichment.
+- `WmsOperationResultMap` provides a per-event typed overlay so subscribers receive the
+  concrete DTO (`MaterialDto`, `ShipInventoryOrderDto`, …) instead of `unknown`.
+
 Post-commit delivery is guaranteed by an `AsyncLocalStorage` dispatch scope (events buffer during the request and flush only after commit). Prefer `@OnEvent`? Opt into the optional [`@nestjs/event-emitter`](https://docs.nestjs.com/techniques/events) bridge from `@rytass/wms-module-graphql/adapters/event-emitter` — every event also emits as `wms.<event>`. Nothing configured ⇒ no events, zero overhead.
 
 ➡️ **Full design, the complete 56-event list & limitations: [`docs/events.md`](./docs/events.md)**.
@@ -154,11 +180,11 @@ Full documentation is shipped inside this package under the `docs/` directory (a
 
 GitHub hosted links (always up-to-date):
 
-- [Integration Guide — §4 Backend setup](https://github.com/Rytass/WMS-Module/blob/main/docs/integration-guide.md#4-backend-setup-nestjs--graphql--typeorm)
-- [Integration Guide — §13.1 Existing GraphQLModule co-existence](https://github.com/Rytass/WMS-Module/blob/main/docs/integration-guide.md#13-integrating-into-an-existing-nestjs--nextjs-project)
+- [Integration Guide — §4 Backend setup](https://github.com/Rytass/WMS-Module/blob/main/libs/graphql/docs/integration-guide.md#4-backend-setup-nestjs--graphql--typeorm)
+- [Integration Guide — §13.1 Existing GraphQLModule co-existence](https://github.com/Rytass/WMS-Module/blob/main/libs/graphql/docs/integration-guide.md#13-integrating-into-an-existing-nestjs--nextjs-project)
 - [Authorization — design & recipes](https://github.com/Rytass/WMS-Module/blob/main/libs/graphql/docs/authorization.md)
 - [Events & Hooks — design & event list](https://github.com/Rytass/WMS-Module/blob/main/libs/graphql/docs/events.md)
-- [API Reference — @rytass/wms-module-graphql](https://github.com/Rytass/WMS-Module/blob/main/docs/api-reference.md#rytasswms-module-graphql)
+- [API Reference — @rytass/wms-module-graphql](https://github.com/Rytass/WMS-Module/blob/main/libs/graphql/docs/api-reference.md#rytasswms-module-graphql)
 
 ## License
 

package/adapters/member-base.d.ts

@@ -1,3 +1,4 @@
+import type { WmsActorExtractor } from '@rytass/wms-module-core';
 import type { WmsAuthChecker, WmsOperationRequirement } from '../lib/auth';
 /**
  * A Casbin `[subject, action]` tuple, e.g. `['wms:material', 'read']`.
@@ -33,3 +34,13 @@ export interface MemberBaseWmsAuthCheckerOptions {
  * (Apollo's default).
  */
 export declare const createMemberBaseWmsAuthChecker: (options: MemberBaseWmsAuthCheckerOptions) => WmsAuthChecker;
+/**
+ * A {@link WmsActorExtractor} for `@rytass/member-base-nestjs-module`. Reads the
+ * verified JWT payload that `CasbinGuard` attaches to the request and surfaces it
+ * as the event/hook `actor`. Returns `null` for unauthenticated requests.
+ *
+ * Pass to `WmsModuleGraphqlModule.forRootAsync({ actorExtractor })` so every
+ * operation event and before-hook carries `{ id, domain }`. Imports nothing from
+ * member-base — it only reads the runtime request fields.
+ */
+export declare const memberBaseActorExtractor: WmsActorExtractor;

package/adapters/member-base.js

@@ -43,5 +43,21 @@ const createMemberBaseWmsAuthChecker = (options) => {
         });
     };
 };
+/**
+ * A {@link WmsActorExtractor} for `@rytass/member-base-nestjs-module`. Reads the
+ * verified JWT payload that `CasbinGuard` attaches to the request and surfaces it
+ * as the event/hook `actor`. Returns `null` for unauthenticated requests.
+ *
+ * Pass to `WmsModuleGraphqlModule.forRootAsync({ actorExtractor })` so every
+ * operation event and before-hook carries `{ id, domain }`. Imports nothing from
+ * member-base — it only reads the runtime request fields.
+ */
+const memberBaseActorExtractor = (context) => {
+    const payload = extractRequest(context)?.payload;
+    if (!payload?.id) {
+        return null;
+    }
+    return { id: payload.id, domain: payload.domain, raw: payload };
+};
 
-export { createMemberBaseWmsAuthChecker };
+export { createMemberBaseWmsAuthChecker, memberBaseActorExtractor };

package/docs/api-reference.md

@@ -455,37 +455,57 @@ Opt-in `beforeHooks` (veto) and post-commit `afterListeners` for every mutation.
 
 ### Root exports (`@rytass/wms-module-graphql`, re-exported from `@rytass/wms-module-core`)
 
-| Export | Kind | Signature / shape |
-|---|---|---|
-| `WmsMutationEvent` | decorator | `({ event: WmsOperationEventName, resolveId? }) => MethodDecorator` |
-| `WmsEventModuleOptions` | type | `{ beforeHooks?: WmsBeforeHookMap; afterListeners?: WmsAfterListenerMap }` — part of `forRootAsync` options |
-| `WmsBeforeHookMap` | type | `{ [N in WmsEventName]?: (ctx: WmsBeforeHookContext<N>) => void \| Promise<void> }` |
-| `WmsAfterListenerMap` | type | `{ [N in WmsEventName]?: (ctx: WmsAfterEventContext<N>) => void \| Promise<void> }` |
-| `WmsBeforeHookContext` | type | `{ event; args: Record<string, unknown>; executionContext: ExecutionContext }` |
-| `WmsAfterEventContext` | type | `{ event; payload: WmsEventPayloadMap[event] }` |
-| `WmsDomainEvent` | type | `{ name: WmsEventName; payload }` |
-| `WmsEventName` / `WmsOperationEventName` / `WmsStockEventName` | type | event-name unions (38 operation + 18 stock) |
-| `WmsEventPayloadMap` | type | event name → payload |
-| `WmsOperationEventPayload` | type | `{ id: string \| null; result: unknown }` |
-| `WmsStockEventPayload` | type | `{ orderId; itemId; quantityDelta; changeType: ChangeType \| null; inspectionResult? }` |
+| Export                                                          | Kind      | Signature / shape                                                                                                                |
+|-----------------------------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------|
+| `WmsMutationEvent`                                              | decorator | `({ event: WmsOperationEventName, resolveId? }) => MethodDecorator`                                                              |
+| `WmsEventModuleOptions`                                         | type      | `{ beforeHooks?, afterListeners?, actorExtractor?, enrichStockEvents? }` — part of `forRootAsync` options                        |
+| `WmsBeforeHookMap`                                              | type      | `{ [N in WmsEventName]?: (ctx: WmsBeforeHookContext<N>) => void \| Promise<void> }`                                              |
+| `WmsAfterListenerMap`                                           | type      | `{ [N in WmsEventName]?: (ctx: WmsAfterEventContext<N>) => void \| Promise<void> }`                                              |
+| `WmsBeforeHookContext`                                          | type      | `{ event; args: Record<string, unknown>; executionContext: ExecutionContext; actor: WmsActor \| null }` (v2 adds `actor`)         |
+| `WmsAfterEventContext`                                          | type      | `{ event; payload: WmsEventPayloadMap[event] }`                                                                                  |
+| `WmsDomainEvent`                                                | type      | `{ name: WmsEventName; payload }`                                                                                                |
+| `WmsEventName` / `WmsOperationEventName` / `WmsStockEventName`  | type      | event-name unions (38 operation + 18 stock)                                                                                      |
+| `WmsEventPayloadMap`                                            | type      | event name → payload                                                                                                             |
+| `WmsOperationEventPayload`                                      | type      | v1: `{ id: string \| null; result: unknown }` — v2: `{ id; result; args: Readonly<Record<string, unknown>>; actor: WmsActor \| null }` |
+| `WmsStockEventPayload`                                          | type      | `{ orderId; itemId; quantityDelta; changeType: ChangeType \| null; inspectionResult? }` — v2 adds optional `materialId?`, `batchId?`, `locationId?`, `loaderId?` when `enrichStockEvents: true` |
+| `WmsActor`                                                      | type      | `{ readonly id: string; readonly domain?: string; readonly raw?: unknown }` — actor identity (v2)                                |
+| `WmsActorExtractor`                                             | type      | `(context: ExecutionContext) => WmsActor \| null` — injectable extractor (v2); token `WMS_ACTOR_EXTRACTOR`                       |
+| `WmsOperationResultMap`                                         | type      | Maps each `WmsOperationEventName` to its concrete `result` DTO (e.g. `'material.created' → MaterialDto`); powers typed listeners (v2) |
 
 ### Adapter subpath (`@rytass/wms-module-graphql/adapters/event-emitter`)
 
-| Export | Kind | Purpose |
-|---|---|---|
+| Export                        | Kind       | Purpose                                                                                                                                  |
+|-------------------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------|
 | `wmsEventEmitterBridgeProvider` | `Provider` | Pass to `forRootAsync({ eventEmitterBridge })`; fans every event onto `EventEmitter2` as `wms.<event>` for `@OnEvent`. Requires `@nestjs/event-emitter` (optional peer) + `EventEmitterModule.forRoot()`. |
 
+### Adapter subpath (`@rytass/wms-module-graphql/adapters/member-base`) — event extras (v2)
+
+| Export                      | Kind      | Purpose                                                                                                                             |
+|-----------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------|
+| `memberBaseActorExtractor`  | extractor | `WmsActorExtractor` that reads `GqlExecutionContext.create(ctx).getContext().req?.payload` → `{ id, domain }`. Pass to `forRootAsync({ actorExtractor })`. |
+
 ```ts
+import { memberBaseActorExtractor } from '@rytass/wms-module-graphql/adapters/member-base';
+import { wmsEventEmitterBridgeProvider } from '@rytass/wms-module-graphql/adapters/event-emitter';
+
 WmsModuleGraphqlModule.forRootAsync({
   ...coreOptions,
-  beforeHooks: { 'ship-inventory-order.shipped': async ({ args }) => { if (!ok(args)) throw new ForbiddenException(); } },
-  afterListeners: { 'stock.allocated': async ({ payload }) => { await sync(payload); } },
+  actorExtractor: memberBaseActorExtractor,   // v2: populates payload.actor
+  enrichStockEvents: true,                    // v2: appends ids to stock payloads
+  beforeHooks: {
+    'ship-inventory-order.shipped': async ({ args, actor }) => {
+      if (!ok(args, actor)) throw new ForbiddenException();
+    },
+  },
+  afterListeners: {
+    'stock.allocated': async ({ payload }) => { await sync(payload); },
+  },
   // optional @OnEvent bridge:
   // eventEmitterBridge: wmsEventEmitterBridgeProvider,
 });
 ```
 
-`beforeHooks` / `afterListeners` are **not** part of the GraphQL schema — they are runtime hooks. With none configured the interceptor passes through with zero overhead.
+`beforeHooks` / `afterListeners` are **not** part of the GraphQL schema — they are runtime hooks. With none configured the interceptor passes through with zero overhead. All v2 options (`actorExtractor`, `enrichStockEvents`) are fully optional; omitting them preserves the v1 behaviour exactly.
 
 ---
 

package/docs/events.md

@@ -36,6 +36,23 @@ Two hook points per event:
 Everything is optional. With nothing configured the module behaves exactly as
 before — no events, zero overhead.
 
+### v2 payload enrichment (upcoming minor)
+
+Operation event payloads will gain two new fields — `args` (the GraphQL input
+that triggered the mutation) and `actor` (who performed it, obtained via an
+injectable `actorExtractor`) — turning the shape from `{ id, result }` into
+`{ id, result, args, actor }`. The `result` field will also become **per-event
+typed** via `WmsOperationResultMap` so subscribers receive the concrete DTO
+instead of `unknown`. Nine action mutations (`received`, `deallocated`, …) still
+return `boolean`; their real information comes from `args` and the stock events
+they fan out.
+
+Stock event payloads gain an opt-in `enrichStockEvents: true` flag on
+`forRootAsync` that appends `materialId / batchId / locationId / loaderId` (one
+indexed PK lookup per event, same transaction). Without the flag the lazy shape
+is unchanged. See [§6 Payloads](#6-payloads) for the full shapes and the
+split/merge/reclassify partial-enrichment caveat.
+
 ---
 
 ## 2. Architecture — post-commit guarantee
@@ -82,6 +99,7 @@ is inferred from the key.
 
 ```ts
 import { WmsModuleGraphqlModule } from '@rytass/wms-module-graphql';
+import { memberBaseActorExtractor } from '@rytass/wms-module-graphql/adapters/member-base';
 import { ForbiddenException } from '@nestjs/common';
 
 WmsModuleGraphqlModule.forRootAsync({
@@ -90,6 +108,12 @@ WmsModuleGraphqlModule.forRootAsync({
   defaultLoaderTypeKey: 'DEFAULT',
   defaultLocationKey: 'DEFAULT',
 
+  // (v2) extract the actor from the request; member-base reads req.payload → { id, domain }
+  actorExtractor: memberBaseActorExtractor,
+
+  // (v2) append materialId/batchId/locationId/loaderId to stock event payloads
+  enrichStockEvents: true,
+
   // intervene — runs before any DB work; throw to veto
   beforeHooks: {
     'ship-inventory-order.shipped': async ({ args, executionContext }) => {
@@ -101,10 +125,12 @@ WmsModuleGraphqlModule.forRootAsync({
 
   // notify — runs after commit
   afterListeners: {
+    // v2: payload.args carries the items[] input; payload.actor carries { id, domain }
     'ship-inventory-order.shipped': async ({ payload }) => {
-      await erp.markShipped(payload.id, payload.result);
+      await erp.markShipped(payload.id, payload.result, payload.actor);
     },
     'stock.allocated': async ({ payload }) => {
+      // v2 with enrichStockEvents: materialId/batchId/locationId/loaderId also available
       await erp.reserve(payload.orderId, payload.itemId, payload.quantityDelta);
     },
   },
@@ -117,6 +143,39 @@ WmsModuleGraphqlModule.forRootAsync({
 - An `afterListener` receives `{ event, payload }` — the committed result (see
   [§6](#6-payloads)). It may be async; a thrown error is logged and isolated, it
   never affects the committed mutation or other listeners.
+- **(v2)** `payload.args` carries the full GraphQL input that triggered the mutation
+  — particularly useful for the 9 boolean action events whose `result` is
+  `true`/`false` only.
+- **(v2)** `payload.actor` is `WmsActor | null` — populated when `actorExtractor`
+  is configured, `null` otherwise. Shape: `{ id: string; domain?: string; raw?:
+  unknown }`. The `memberBaseActorExtractor` helper (exported from the
+  `@rytass/wms-module-graphql/adapters/member-base` subpath) reads
+  `req.payload` and returns `{ id, domain }`.
+
+### 3.1 The 9 boolean action events
+
+Nine mutations return `boolean` and cannot carry a rich DTO `result` without a
+breaking GraphQL schema change. For subscribers, the meaningful signal is:
+
+1. **`args`** — the exact items input (see §5 for each event's args shape).
+2. **Stock events** — the operation fans out one `stock.*` event per affected item
+   (see the "Fans out to stock event" column in §5).
+
+The operation event itself only confirms success (`result: true`).
+
+| Event                                    | args key items shape                                         |
+|------------------------------------------|--------------------------------------------------------------|
+| `receive-inventory-order.received`       | `{ itemId, quantity, batchKey?, locationKey?, loaderKey?, inspectionResult? }` |
+| `ship-inventory-order.shipped`           | `{ itemId, quantity }`                                       |
+| `ship-inventory-order.ship-cancelled`    | `{ itemId, quantity? }`                                      |
+| `transfer-order.transferred`             | `{ itemId, quantity }`                                       |
+| `transfer-order.transfer-cancelled`      | `{ itemId, quantity? }`                                      |
+| `hold-inventory-order.released`          | `{ aggregatedKey, quantity, unitId? }`                       |
+| `allocate-inventory-order.deallocated`   | `{ aggregatedKey, quantity, unitId? }`                       |
+| `transfer-customer-order.returned`       | `{ aggregatedKey, quantity, unitId?, locationKey, loaderKey? }` |
+| `transfer-vendor-order.returned`         | `{ aggregatedKey, quantity, unitId?, locationKey, loaderKey? }` |
+
+All are passed as `@Args('items', …) items: T[]`, so `args.items` is the array.
 
 ---
 
@@ -158,52 +217,62 @@ and the bridge can be used together — both fire.
 
 ### Operation events (38) — `<domain>.<past-tense-action>`
 
-| Event | Mutation | Fans out to stock event |
-|---|---|---|
-| `receive-inventory-order.created` | createReceiveInventoryOrder | — |
-| `receive-inventory-order.updated` | updateReceiveInventoryOrder | — |
-| `receive-inventory-order.received` | receive | `stock.received` |
-| `ship-inventory-order.created` | createShipInventoryOrder | — |
-| `ship-inventory-order.updated` | updateShipInventoryOrder | `stock.in-shipment` |
-| `ship-inventory-order.shipped` | ship | `stock.shipped` |
-| `ship-inventory-order.ship-cancelled` | cancelShip | `stock.shipped` (negative) |
-| `transfer-order.created` | createTransferOrder | `stock.in-transfer` |
-| `transfer-order.updated` | updateTransferOrder | `stock.in-transfer` |
-| `transfer-order.transferred` | transfer | `stock.transferred` |
-| `transfer-order.transfer-cancelled` | cancelTransfer | `stock.in-transfer` (reversal) |
-| `hold-inventory-order.created` | createHoldInventoryOrder | `stock.held` |
-| `hold-inventory-order.updated` | updateHoldInventoryOrder | `stock.held` |
-| `hold-inventory-order.released` | release | `stock.released` |
-| `allocate-inventory-order.created` | createAllocateInventoryOrder | `stock.allocated` |
-| `allocate-inventory-order.updated` | updateAllocateInventoryOrder | `stock.allocated` |
-| `allocate-inventory-order.deallocated` | deallocate | `stock.deallocated` |
-| `transfer-vendor-order.created` | createTransferVendorOrder | `stock.vendor-transferred` |
-| `transfer-vendor-order.updated` | updateTransferVendorOrder | `stock.vendor-transferred` |
-| `transfer-vendor-order.returned` | returnTransferVendorOrder | `stock.vendor-returned` |
-| `transfer-customer-order.created` | createTransferCustomerOrder | `stock.customer-held` |
-| `transfer-customer-order.updated` | updateTransferCustomerOrder | `stock.customer-held` |
-| `transfer-customer-order.returned` | returnTransferCustomerOrder | `stock.customer-returned` |
-| `quality-inspection-order.inspected` | inspectMaterials | `stock.inspection-resolved` |
-| `scrape-order.scraped` | scrapeMaterials | `stock.scraped` |
-| `reclassify-inventory-order.reclassified` | reclassifyInventoryOrder | `stock.reclassified` |
-| `batch.merged` | mergeBatch | `stock.merged` |
-| `batch.splitted` | splitBatch | `stock.splitted` |
-| `material.created` | createMaterial | — |
-| `material.updated` | updateMaterial | — |
-| `loader.created` | createLoader | — |
-| `loader.batch-created` | createBatchLoader | — |
-| `loader.updated` | updateLoader | — |
-| `loader.type-created` | createLoaderType | — |
-| `loader.type-updated` | updateLoaderType | — |
-| `location.created` | createLocation | — |
-| `location.updated` | updateLocation | — |
-| `warehouse-map.updated` | updateWarehouseMap | — |
+The **v2 `result` type** column shows the concrete type subscribers receive via
+`WmsOperationResultMap`. Events marked ⚠️ **boolean** are the 9 action mutations
+whose `result` is always `true`/`false`; their real signal is `args` + the stock
+events they fan out (see §3.1).
+
+| Event                                       | Mutation                      | v2 `result` type                  | Fans out to stock event       |
+|---------------------------------------------|-------------------------------|-----------------------------------|-------------------------------|
+| `receive-inventory-order.created`           | createReceiveInventoryOrder   | `ReceiveInventoryOrderDto`        | —                             |
+| `receive-inventory-order.updated`           | updateReceiveInventoryOrder   | `ReceiveInventoryOrderDto`        | —                             |
+| `receive-inventory-order.received`          | receive                       | ⚠️ `boolean`                     | `stock.received`              |
+| `ship-inventory-order.created`              | createShipInventoryOrder      | `ShipInventoryOrderDto`           | —                             |
+| `ship-inventory-order.updated`              | updateShipInventoryOrder      | `ShipInventoryOrderDto`           | `stock.in-shipment`           |
+| `ship-inventory-order.shipped`              | ship                          | ⚠️ `boolean`                     | `stock.shipped`               |
+| `ship-inventory-order.ship-cancelled`       | cancelShip                    | ⚠️ `boolean`                     | `stock.shipped` (negative)    |
+| `transfer-order.created`                    | createTransferOrder           | `TransferOrderDto`                | `stock.in-transfer`           |
+| `transfer-order.updated`                    | updateTransferOrder           | `TransferOrderDto`                | `stock.in-transfer`           |
+| `transfer-order.transferred`                | transfer                      | ⚠️ `boolean`                     | `stock.transferred`           |
+| `transfer-order.transfer-cancelled`         | cancelTransfer                | ⚠️ `boolean`                     | `stock.in-transfer` (reversal)|
+| `hold-inventory-order.created`              | createHoldInventoryOrder      | `HoldInventoryOrderDto`           | `stock.held`                  |
+| `hold-inventory-order.updated`              | updateHoldInventoryOrder      | `HoldInventoryOrderDto`           | `stock.held`                  |
+| `hold-inventory-order.released`             | release                       | ⚠️ `boolean`                     | `stock.released`              |
+| `allocate-inventory-order.created`          | createAllocateInventoryOrder  | `AllocateInventoryOrderDto`       | `stock.allocated`             |
+| `allocate-inventory-order.updated`          | updateAllocateInventoryOrder  | `AllocateInventoryOrderDto`       | `stock.allocated`             |
+| `allocate-inventory-order.deallocated`      | deallocate                    | ⚠️ `boolean`                     | `stock.deallocated`           |
+| `transfer-vendor-order.created`             | createTransferVendorOrder     | `TransferVendorOrderDto`          | `stock.vendor-transferred`    |
+| `transfer-vendor-order.updated`             | updateTransferVendorOrder     | `TransferVendorOrderDto`          | `stock.vendor-transferred`    |
+| `transfer-vendor-order.returned`            | returnTransferVendorOrder     | ⚠️ `boolean`                     | `stock.vendor-returned`       |
+| `transfer-customer-order.created`           | createTransferCustomerOrder   | `TransferCustomerOrderDto`        | `stock.customer-held`         |
+| `transfer-customer-order.updated`           | updateTransferCustomerOrder   | `TransferCustomerOrderDto`        | `stock.customer-held`         |
+| `transfer-customer-order.returned`          | returnTransferCustomerOrder   | ⚠️ `boolean`                     | `stock.customer-returned`     |
+| `quality-inspection-order.inspected`        | inspectMaterials              | `QualityInspectionOrderDto`       | `stock.inspection-resolved`   |
+| `scrape-order.scraped`                      | scrapeMaterials               | `ScrapeOrderDto`                  | `stock.scraped`               |
+| `reclassify-inventory-order.reclassified`   | reclassifyInventoryOrder      | `ReclassifyInventoryOrderDto`     | `stock.reclassified`          |
+| `batch.merged`                              | mergeBatch                    | `MergeBatchOrderDto`              | `stock.merged`                |
+| `batch.splitted`                            | splitBatch                    | `SplitBatchOrderDto`              | `stock.splitted`              |
+| `material.created`                          | createMaterial                | `MaterialDto`                     | —                             |
+| `material.updated`                          | updateMaterial                | `MaterialDto`                     | —                             |
+| `loader.created`                            | createLoader                  | `LoaderDto[]`                     | —                             |
+| `loader.batch-created`                      | createBatchLoader             | `LoaderDto[]`                     | —                             |
+| `loader.updated`                            | updateLoader                  | `LoaderDto`                       | —                             |
+| `loader.type-created`                       | createLoaderType              | `LoaderTypeDto`                   | —                             |
+| `loader.type-updated`                       | updateLoaderType              | `LoaderTypeDto`                   | —                             |
+| `location.created`                          | createLocation                | `LocationDto`                     | —                             |
+| `location.updated`                          | updateLocation                | `LocationDto`                     | —                             |
+| `warehouse-map.updated`                     | updateWarehouseMap            | `MapDataDto`                      | —                             |
 
 > The "Fans out to stock event" column is **indicative**, not a hard binding. A
 > mutation never names a stock event directly — `StockChangeSubscriber` derives
 > it from the `*_order_change` table that was written and the sign of
 > `quantityChanged`. So a mutation emits a stock event only on the code paths
 > that actually write a change row (e.g. an `update*` only when it adds items).
+>
+> The "v2 `result` type" column refers to the typed overlay provided by
+> `WmsOperationResultMap` (exported from `@rytass/wms-module-graphql`). In v1
+> `result` is typed `unknown`; consumer code using the typed maps gets the
+> concrete DTO automatically.
 
 ### Stock domain events (18) — `stock.<change-type>`
 
@@ -227,27 +296,141 @@ with a negative `quantityDelta` (`cancelShip` -> `stock.shipped`,
 
 ## 6. Payloads
 
-**Operation event** — `WmsOperationEventPayload`:
+### Operation event — `WmsOperationEventPayload`
+
+**v1 shape** (currently shipped):
+
+```ts
+{
+  id: string | null;   // primary id of the operation's order/entity
+  result: unknown;     // the mutation's return value (DTO, or boolean for actions)
+}
+```
+
+**v2 shape** (upcoming minor — `core@0.3.0` / `graphql@0.6.0`):
+
+```ts
+{
+  readonly id: string | null;                          // (unchanged) primary id
+  readonly result: TResult;                            // now per-event typed via WmsOperationResultMap
+  readonly args: Readonly<Record<string, unknown>>;    // NEW — the GraphQL input (intent)
+  readonly actor: WmsActor | null;                     // NEW — who performed the mutation
+}
+```
+
+**`WmsActor`** shape:
 
 ```ts
-{ id: string | null;   // primary id of the operation's order/entity
-  result: unknown }     // the mutation's return value (DTO, or boolean for actions)
+interface WmsActor {
+  readonly id: string;       // subject identifier
+  readonly domain?: string;  // optional domain / tenant discriminator
+  readonly raw?: unknown;    // host-specific extras; opaque to the lib
+}
 ```
 
-**Stock event** — `WmsStockEventPayload`:
+`actor` is `null` when no `actorExtractor` is configured. The
+`memberBaseActorExtractor` helper (from
+`@rytass/wms-module-graphql/adapters/member-base`) reads `req.payload` and
+returns `{ id, domain }` — the same fields `CasbinGuard` already puts on the
+JWT payload.
+
+`WmsBeforeHookContext` also gains `actor` (so before-hooks can veto by identity):
 
 ```ts
-{ orderId: string;            // = change.id; correlation id with the operation event
-  itemId: string;             // = change.itemId
-  quantityDelta: number;      // = change.quantityChanged (sign = direction)
-  changeType: ChangeType | null;          // null only for stock.inspection-resolved
-  inspectionResult?: boolean | null }     // present only on stock.inspection-resolved
+interface WmsBeforeHookContext<N extends WmsEventName> {
+  event: N;
+  args: Record<string, unknown>;
+  executionContext: ExecutionContext;
+  actor: WmsActor | null;           // v2 addition
+}
 ```
 
+### Typed result overlay — `WmsOperationResultMap`
+
+The v2 graphql package exports a `WmsOperationResultMap` interface that maps
+every operation event name to its concrete `result` type. Consumers who use the
+typed `beforeHooks` / `afterListeners` maps automatically receive the resolved
+DTO instead of `unknown`:
+
+```ts
+// listener receives ShipInventoryOrderDto, not unknown
+afterListeners: {
+  'ship-inventory-order.updated': async ({ payload }) => {
+    console.log(payload.result.id);    // typed as string
+  },
+  // listener receives boolean
+  'ship-inventory-order.shipped': async ({ payload }) => {
+    console.log(payload.result);       // typed as boolean
+    console.log(payload.args);         // { items: [{ itemId, quantity }, ...] }
+    console.log(payload.actor?.id);    // actor id if actorExtractor is set
+  },
+}
+```
+
+---
+
+### Stock event — `WmsStockEventPayload`
+
+**Lazy shape** (default — unchanged):
+
+```ts
+{
+  readonly orderId: string;                // = change.id; correlation id with the operation event
+  readonly itemId: string;                 // = change.itemId
+  readonly quantityDelta: number;          // = change.quantityChanged (sign = direction)
+  readonly changeType: ChangeType | null;  // null only for stock.inspection-resolved
+  readonly inspectionResult?: boolean | null; // present only on stock.inspection-resolved
+}
+```
+
+**Enriched shape** (opt-in, `enrichStockEvents: true`):
+
+The following fields are appended when the flag is enabled. They are loaded in
+the **same transaction** via a single indexed PK lookup on the change's item row:
+
+```ts
+  readonly materialId?: string | null;
+  readonly batchId?: string | null;
+  readonly locationId?: string | null;
+  readonly loaderId?: string | null;
+```
+
+> All four fields are optional/nullable — a `null` value means the column is
+> nullable in the underlying order-item row and happened to be null at the time
+> of the change. On any lookup error the system degrades to the lazy payload.
+
+**Per-domain enrichment completeness** (`enrichStockEvents: true`):
+
+| Domain (stock event)                              | materialId | batchId | locationId | loaderId |
+|---------------------------------------------------|:----------:|:-------:|:----------:|:--------:|
+| receive (`stock.received`)                        | yes        | yes *   | yes *      | yes *    |
+| ship (`stock.in-shipment` / `stock.shipped`)      | yes        | yes     | yes *      | yes *    |
+| transfer-order (`stock.in-transfer` / `.transferred`) | yes    | yes     | yes        | yes *    |
+| transfer-vendor (`stock.vendor-*`)                | yes        | yes     | yes *      | yes *    |
+| transfer-customer (`stock.customer-*`)            | yes        | yes     | yes *      | yes *    |
+| hold (`stock.held` / `stock.released`)            | yes        | yes     | yes *      | yes *    |
+| allocate (`stock.allocated` / `.deallocated`)     | yes        | yes     | yes *      | yes *    |
+| scrape (`stock.scraped`)                          | yes        | yes     | yes *      | yes *    |
+| quality-inspection (`stock.inspection-resolved`)  | yes        | yes     | yes *      | yes *    |
+| **split (`stock.splitted`)**                      | **no**     | **no**  | yes *      | yes *    |
+| **merge (`stock.merged`)**                        | **no**     | **no**  | yes        | yes *    |
+| **reclassify (`stock.reclassified`)**             | **no**     | **no**  | yes        | yes *    |
+
+`*` = column is nullable; may be `null` even when enrichment is on.
+
+> **Important**: split / merge / reclassify order-items have **no `materialId` /
+> `batchId`** — those domains operate at batch-aggregation level and keep that
+> metadata on the parent order, not the item. With `enrichStockEvents: true`
+> these three event types only receive `locationId` / `loaderId`. If you need
+> `materialId` / `batchId` for these domains, look them up from the parent order
+> by `orderId` inside your after-listener.
+
+---
+
 `orderId` is the same on the operation event (`payload.id`) and the stock events
 it fans out to, so listeners can correlate the two tiers. For richer
-batch/material/location details, look them up by `orderId` / `itemId` inside the
-after-listener — the data is committed by then.
+batch/material/location details when `enrichStockEvents` is off, look them up by
+`orderId` / `itemId` inside the after-listener — the data is committed by then.
 
 ---
 
@@ -279,25 +462,38 @@ after-listener — the data is committed by then.
 From the package root (`@rytass/wms-module-graphql`, re-exported from
 `@rytass/wms-module-core`):
 
-| Export | Kind | Purpose |
-|---|---|---|
-| `WmsMutationEvent({ event })` | decorator | Annotates a mutation (already applied across the library). |
-| `WmsBeforeHookMap` / `WmsAfterListenerMap` | type | The `beforeHooks` / `afterListeners` option shapes. |
-| `WmsEventModuleOptions` | type | `{ beforeHooks?, afterListeners? }` (part of `forRootAsync`). |
-| `WmsBeforeHookContext` / `WmsAfterEventContext` | type | Hook/listener argument shapes. |
-| `WmsDomainEvent` | type | `{ name, payload }`. |
-| `WmsEventName` / `WmsOperationEventName` / `WmsStockEventName` | type | Event-name unions. |
-| `WmsEventPayloadMap` | type | Event name -> payload mapping. |
-| `WmsOperationEventPayload` / `WmsStockEventPayload` | type | Payload shapes. |
+| Export                                                            | Kind      | Purpose                                                                                                      |
+|-------------------------------------------------------------------|-----------|--------------------------------------------------------------------------------------------------------------|
+| `WmsMutationEvent({ event })`                                     | decorator | Annotates a mutation (already applied across the library).                                                    |
+| `WmsBeforeHookMap` / `WmsAfterListenerMap`                        | type      | The `beforeHooks` / `afterListeners` option shapes.                                                           |
+| `WmsEventModuleOptions`                                           | type      | `{ beforeHooks?, afterListeners?, actorExtractor?, enrichStockEvents? }` (part of `forRootAsync`).            |
+| `WmsBeforeHookContext` / `WmsAfterEventContext`                    | type      | Hook/listener argument shapes (v2: `WmsBeforeHookContext` gains `actor`).                                     |
+| `WmsDomainEvent`                                                  | type      | `{ name, payload }`.                                                                                          |
+| `WmsEventName` / `WmsOperationEventName` / `WmsStockEventName`    | type      | Event-name unions.                                                                                            |
+| `WmsEventPayloadMap`                                              | type      | Event name -> payload mapping.                                                                                |
+| `WmsOperationEventPayload`                                        | type      | `{ id, result, args, actor }` (v2); `{ id, result }` in v1.                                                  |
+| `WmsStockEventPayload`                                            | type      | `{ orderId, itemId, quantityDelta, changeType, inspectionResult? }` + optional enrich fields (v2).           |
+| `WmsActor`                                                        | type      | `{ id: string; domain?: string; raw?: unknown }` — actor identity shape (v2).                                |
+| `WmsActorExtractor`                                               | type      | `(context: ExecutionContext) => WmsActor \| null` — injected via `forRootAsync({ actorExtractor })` (v2).    |
+| `WmsOperationResultMap`                                           | type      | Event name → concrete `result` DTO mapping; enables per-event typed listeners (v2, lives in graphql lib).    |
 
 From the adapter subpath (`@rytass/wms-module-graphql/adapters/event-emitter`):
 
-| Export | Kind | Purpose |
-|---|---|---|
-| `wmsEventEmitterBridgeProvider` | provider | Pass to `forRootAsync({ eventEmitterBridge })` to fan events onto `@nestjs/event-emitter`. |
+| Export                        | Kind     | Purpose                                                                                               |
+|-------------------------------|----------|-------------------------------------------------------------------------------------------------------|
+| `wmsEventEmitterBridgeProvider` | provider | Pass to `forRootAsync({ eventEmitterBridge })` to fan events onto `@nestjs/event-emitter`.          |
+
+From the adapter subpath (`@rytass/wms-module-graphql/adapters/member-base`):
+
+| Export                      | Kind      | Purpose                                                                                                   |
+|-----------------------------|-----------|-----------------------------------------------------------------------------------------------------------|
+| `memberBaseActorExtractor`  | extractor | `WmsActorExtractor` that reads `req.payload` → `{ id, domain }` (v2). Pass to `forRootAsync({ actorExtractor })`. |
 
-`forRootAsync` accepts `beforeHooks`, `afterListeners` and `eventEmitterBridge`
-on its single options object — all optional.
+`forRootAsync` accepts `beforeHooks`, `afterListeners`, `eventEmitterBridge`,
+`actorExtractor`, and `enrichStockEvents` on its single options object — all
+optional. Omitting `actorExtractor` leaves `actor: null` on every payload;
+omitting `enrichStockEvents` (or setting it `false`) keeps the lazy stock
+payload shape.
 
 ---
 

package/docs/integration-guide.md

@@ -884,14 +884,23 @@ Every WMS mutation can be **intervened in** and **observed** through two opt-in
 // apps/api/src/app/app.module.ts
 import { ForbiddenException } from '@nestjs/common';
 import { WmsModuleGraphqlModule } from '@rytass/wms-module-graphql';
+import { memberBaseActorExtractor } from '@rytass/wms-module-graphql/adapters/member-base';
 
 WmsModuleGraphqlModule.forRootAsync({
   // ...the same core options as §4.2 (defaultLoaderSerialId, useFactory, etc.)...
 
+  // (v2) extract actor from the request: memberBaseActorExtractor reads
+  //      req.payload → { id, domain } (the same JWT payload CasbinGuard uses)
+  actorExtractor: memberBaseActorExtractor,
+
+  // (v2) append materialId/batchId/locationId/loaderId to stock event payloads
+  //      via a single indexed PK lookup per event, inside the same transaction
+  enrichStockEvents: true,
+
   beforeHooks: {
-    // intent payload = the raw GraphQL args; throw to abort
-    'ship-inventory-order.shipped': async ({ args, executionContext }) => {
-      if (!(await canShip(args, executionContext))) {
+    // intent payload = the raw GraphQL args; v2 also receives actor
+    'ship-inventory-order.shipped': async ({ args, actor, executionContext }) => {
+      if (!(await canShip(args, actor, executionContext))) {
         throw new ForbiddenException('shipment blocked');
       }
     },
@@ -899,10 +908,12 @@ WmsModuleGraphqlModule.forRootAsync({
 
   afterListeners: {
     // operation event — fires once per mutation, with the result
+    // v2: payload also carries args (the items[] input) and actor
     'ship-inventory-order.shipped': async ({ payload }) => {
-      await erp.markShipped(payload.id, payload.result);
+      await erp.markShipped(payload.id, payload.result, payload.actor);
     },
     // stock domain event — fires once per affected item (post-commit)
+    // v2 with enrichStockEvents: materialId/batchId/locationId/loaderId also present
     'stock.allocated': async ({ payload }) => {
       await erp.reserve(payload.orderId, payload.itemId, payload.quantityDelta);
     },
@@ -912,11 +923,26 @@ WmsModuleGraphqlModule.forRootAsync({
 
 Two tiers of events you can listen to:
 
-- **Operation events** — one per mutation: `material.created`, `receive-inventory-order.received`, `ship-inventory-order.shipped`, … (38 total). Payload: `{ id, result }`.
-- **Stock domain events** — driven by the `ChangeType` state machine: `stock.allocated`, `stock.shipped`, `stock.held`, … (18 total). Payload: `{ orderId, itemId, quantityDelta, changeType, inspectionResult? }`. `orderId` matches the operation event's `id`, so you can correlate the two tiers.
+- **Operation events** — one per mutation: `material.created`, `receive-inventory-order.received`, `ship-inventory-order.shipped`, … (38 total). v1 payload: `{ id, result }`. v2 payload: `{ id, result, args, actor }`.
+- **Stock domain events** — driven by the `ChangeType` state machine: `stock.allocated`, `stock.shipped`, `stock.held`, … (18 total). Payload: `{ orderId, itemId, quantityDelta, changeType, inspectionResult? }`. `orderId` matches the operation event's `id`, so you can correlate the two tiers. With `enrichStockEvents: true` the payload also carries `materialId?`, `batchId?`, `locationId?`, `loaderId?`.
 
 Both maps are fully typed — the payload is inferred from the event-name key. With neither configured, the interceptor passes through with **zero overhead** (no behaviour change).
 
+#### v2: The 9 boolean action events
+
+Nine mutations — `received`, `deallocated`, `released`, `shipped`, `ship-cancelled`,
+`transferred`, `transfer-cancelled`, customer/vendor `returned` — return `boolean` and
+cannot carry a richer `result` without a breaking GraphQL schema change. For subscribers,
+the full signal comes from **`payload.args`** (the exact items input) and the **stock events
+they fan out** (one per affected item). The operation event confirms success; `args` carries
+the intent.
+
+> ⚠️ **`enrichStockEvents` partial coverage**: split / merge / reclassify order-items have
+> **no `materialId` / `batchId`** at the item level (these domains keep that metadata on the
+> parent order). With `enrichStockEvents: true`, `stock.splitted`, `stock.merged`, and
+> `stock.reclassified` only receive `locationId` / `loaderId` — look up `materialId` /
+> `batchId` from the parent order by `orderId` if you need them.
+
 #### Optional: `@OnEvent` via `@nestjs/event-emitter`
 
 Prefer decoupled subscribers? Install `@nestjs/event-emitter` (an optional peer dependency) and opt into the bridge — every event is then also emitted as `wms.<event-name>`:
@@ -930,7 +956,9 @@ import { wmsEventEmitterBridgeProvider } from '@rytass/wms-module-graphql/adapte
     EventEmitterModule.forRoot(),
     WmsModuleGraphqlModule.forRootAsync({
       ...coreOptions,
-      eventEmitterBridge: wmsEventEmitterBridgeProvider, // <- enables the bridge
+      actorExtractor: memberBaseActorExtractor,   // v2 — optional
+      enrichStockEvents: true,                    // v2 — optional
+      eventEmitterBridge: wmsEventEmitterBridgeProvider,
     }),
   ],
 })

package/index.cjs.js

@@ -330,9 +330,23 @@ const defaultResolveId = (result, args) => {
 exports.WmsMutationInterceptor = class WmsMutationInterceptor {
     reflector;
     dispatcher;
-    constructor(reflector, dispatcher) {
+    actorExtractor;
+    constructor(reflector, dispatcher, actorExtractor = null) {
         this.reflector = reflector;
         this.dispatcher = dispatcher;
+        this.actorExtractor = actorExtractor;
+    }
+    resolveActor(context) {
+        if (!this.actorExtractor) {
+            return null;
+        }
+        try {
+            return this.actorExtractor(context);
+        }
+        catch {
+            // Fail-open on actor resolution: never break a mutation over audit metadata.
+            return null;
+        }
     }
     async intercept(context, next) {
         const config = this.reflector.get(WMS_MUTATION_EVENT_METADATA, context.getHandler());
@@ -341,11 +355,13 @@ exports.WmsMutationInterceptor = class WmsMutationInterceptor {
         }
         const args = graphql.GqlExecutionContext.create(context).getArgs() ??
             {};
+        const actor = this.resolveActor(context);
         // Before-hook runs before any DB work; a throw vetoes with zero side effects.
         await this.dispatcher.runBeforeHook({
             event: config.event,
             args,
             executionContext: context,
+            actor,
         });
         const { result, events } = await wmsModuleCore.runInDispatchScope(async () => {
             const handlerResult = await rxjs.firstValueFrom(next.handle());
@@ -354,7 +370,7 @@ exports.WmsMutationInterceptor = class WmsMutationInterceptor {
                 : defaultResolveId(handlerResult, args);
             const operationEvent = {
                 name: config.event,
-                payload: { id, result: handlerResult },
+                payload: { id, result: handlerResult, args, actor },
             };
             wmsModuleCore.collectToScope(operationEvent);
             return handlerResult;
@@ -367,8 +383,10 @@ exports.WmsMutationInterceptor = class WmsMutationInterceptor {
 };
 exports.WmsMutationInterceptor = tslib.__decorate([
     common.Injectable(),
+    tslib.__param(2, common.Optional()),
+    tslib.__param(2, common.Inject(wmsModuleCore.WMS_ACTOR_EXTRACTOR)),
     tslib.__metadata("design:paramtypes", [core.Reflector,
-        wmsModuleCore.WmsEventDispatcher])
+        wmsModuleCore.WmsEventDispatcher, Object])
 ], exports.WmsMutationInterceptor);
 
 /**
@@ -6521,15 +6539,23 @@ const exportDependencies = [
 ];
 exports.WmsModuleGraphqlModule = WmsModuleGraphqlModule_1 = class WmsModuleGraphqlModule {
     static forRootAsync(options) {
-        const { authChecker, beforeHooks, afterListeners, eventEmitterBridge, ...coreOptions } = options;
+        const { authChecker, beforeHooks, afterListeners, actorExtractor, eventEmitterBridge, ...coreOptions } = options;
+        // coreOptions still carries `enrichStockEvents`, forwarded to the core module.
         const coreModule = wmsModuleCore.WmsModuleCoreModule.forRootAsync(coreOptions);
         const authOptions = { authChecker };
-        const eventOptions = { beforeHooks, afterListeners };
+        // The typed hook maps are a compile-time refinement of the core maps; at
+        // runtime the dispatched payload IS the concrete result type, so handing the
+        // refined maps to the (looser) core option contract is sound.
+        const eventOptions = {
+            beforeHooks: beforeHooks,
+            afterListeners: afterListeners,
+        };
         const providers = [
             ...exportDependencies,
             exports.WmsAuthGuard,
             { provide: WMS_AUTH_OPTIONS, useValue: authOptions },
             { provide: wmsModuleCore.WMS_EVENT_OPTIONS, useValue: eventOptions },
+            { provide: wmsModuleCore.WMS_ACTOR_EXTRACTOR, useValue: actorExtractor ?? null },
             wmsModuleCore.WmsEventDispatcher,
             exports.WmsMutationInterceptor,
             ...(eventEmitterBridge ? [eventEmitterBridge] : []),

package/index.d.ts

@@ -5,5 +5,5 @@ export type { LoaderType } from './lib/helpers/dataloader.type';
 export { createWmsLoaders, type WmsLoaders, } from './lib/helpers/create-wms-loaders';
 export { HOST_SKIP_METADATA_KEY, WmsAuthGuard, WmsOperation, WMS_AUTH_OPTIONS, WMS_OPERATION_METADATA, type WmsAuthChecker, type WmsAuthModuleOptions, type WmsOperationRequirement, } from './lib/auth';
 export type { WmsModuleGraphqlModuleAsyncOptions } from './lib/graphql.module';
-export { WmsMutationEvent, WmsMutationInterceptor, WMS_MUTATION_EVENT_METADATA, type WmsMutationEventConfig, } from './lib/events';
-export type { WmsAfterEventContext, WmsAfterListener, WmsAfterListenerMap, WmsBeforeHook, WmsBeforeHookContext, WmsBeforeHookMap, WmsDomainEvent, WmsEventModuleOptions, WmsEventName, WmsEventPayloadMap, WmsOperationEventName, WmsOperationEventPayload, WmsStockEventName, WmsStockEventPayload, } from '@rytass/wms-module-core';
+export { WmsMutationEvent, WmsMutationInterceptor, WMS_MUTATION_EVENT_METADATA, type WmsMutationEventConfig, type WmsOperationResultMap, type WmsEventPayloadFor, type WmsTypedAfterEventContext, type WmsTypedAfterListenerMap, type WmsTypedBeforeHookContext, type WmsTypedBeforeHookMap, } from './lib/events';
+export type { WmsActor, WmsActorExtractor, WmsAfterEventContext, WmsAfterListener, WmsAfterListenerMap, WmsBeforeHook, WmsBeforeHookContext, WmsBeforeHookMap, WmsDomainEvent, WmsEventModuleOptions, WmsEventName, WmsEventPayloadMap, WmsOperationEventName, WmsOperationEventPayload, WmsStockEventName, WmsStockEventPayload, } from '@rytass/wms-module-core';

package/lib/events/index.d.ts

@@ -1,3 +1,5 @@
 export { WmsMutationEvent } from './wms-mutation-event.decorator';
 export { WMS_MUTATION_EVENT_METADATA, type WmsMutationEventConfig, } from './wms-mutation-event.constants';
 export { WmsMutationInterceptor } from './wms-mutation.interceptor';
+export type { WmsOperationResultMap } from './operation-result-map';
+export type { WmsEventPayloadFor, WmsTypedAfterEventContext, WmsTypedAfterListenerMap, WmsTypedBeforeHookContext, WmsTypedBeforeHookMap, } from './typed-maps';

package/lib/events/operation-result-map.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @file operation-result-map.ts
+ * Typed overlay that maps every {@link WmsOperationEventName} to the concrete
+ * DTO (or `boolean`) returned by that mutation.  Used by {@link WmsEventPayloadFor}
+ * and the consumer-facing typed hook/listener maps in `typed-maps.ts`.
+ *
+ * `WmsOperationResultMap` extends `Record<WmsOperationEventName, unknown>` so
+ * the compiler rejects any key that is not a valid operation-event name, and
+ * flags missing keys at the interface level — every new mutation must add an
+ * entry here.
+ */
+import type { WmsOperationEventName } from '@rytass/wms-module-core';
+import type { AllocateInventoryOrderDto, HoldInventoryOrderDto, LoaderDto, LoaderTypeDto, MaterialDto, QualityInspectionOrderDto, ReceiveInventoryOrderDto, ScrapeOrderDto, ShipInventoryOrderDto, TransferCustomerOrderDto, TransferOrderDto, TransferVendorOrderDto } from '../dto';
+import type { LocationDto } from '../dto/location.dto';
+import type { MapDataDto } from '../dto/warehouse-map.dto';
+import type { MergeBatchOrderDto } from '../dto/merge-batch-order.dto';
+import type { ReclassifyInventoryOrderDto } from '../dto/reclassify-inventory-order.dto';
+import type { SplitBatchOrderDto } from '../dto/split-batch-order.dto';
+/**
+ * Maps every {@link WmsOperationEventName} to the concrete type returned by
+ * the corresponding mutation resolver.
+ *
+ * - **DTO-returning mutations (29)**: the resolved DTO class.
+ * - **Action mutations (9)**: `boolean` (success flag; real intent is in
+ *   `WmsOperationEventPayload.args` and the accompanying stock events).
+ *
+ * Maintenance: for every new `@Mutation`, add the matching entry here.
+ */
+export interface WmsOperationResultMap extends Record<WmsOperationEventName, unknown> {
+    'material.created': MaterialDto;
+    'material.updated': MaterialDto;
+    'location.created': LocationDto;
+    'location.updated': LocationDto;
+    'warehouse-map.updated': MapDataDto;
+    'loader.created': LoaderDto[];
+    'loader.batch-created': LoaderDto[];
+    'loader.updated': LoaderDto;
+    'loader.type-created': LoaderTypeDto;
+    'loader.type-updated': LoaderTypeDto;
+    'receive-inventory-order.created': ReceiveInventoryOrderDto;
+    'receive-inventory-order.updated': ReceiveInventoryOrderDto;
+    /** Action mutation — result is a success flag; use args + stock.received. */
+    'receive-inventory-order.received': boolean;
+    'allocate-inventory-order.created': AllocateInventoryOrderDto;
+    'allocate-inventory-order.updated': AllocateInventoryOrderDto;
+    /** Action mutation — result is a success flag; use args + stock.deallocated. */
+    'allocate-inventory-order.deallocated': boolean;
+    'hold-inventory-order.created': HoldInventoryOrderDto;
+    'hold-inventory-order.updated': HoldInventoryOrderDto;
+    /** Action mutation — result is a success flag; use args + stock.released. */
+    'hold-inventory-order.released': boolean;
+    'reclassify-inventory-order.reclassified': ReclassifyInventoryOrderDto;
+    'ship-inventory-order.created': ShipInventoryOrderDto;
+    'ship-inventory-order.updated': ShipInventoryOrderDto;
+    /** Action mutation — result is a success flag; use args + stock.shipped. */
+    'ship-inventory-order.shipped': boolean;
+    /** Action mutation — result is a success flag; use args + stock.shipped (negative). */
+    'ship-inventory-order.ship-cancelled': boolean;
+    'batch.merged': MergeBatchOrderDto;
+    'batch.splitted': SplitBatchOrderDto;
+    'scrape-order.scraped': ScrapeOrderDto;
+    'quality-inspection-order.inspected': QualityInspectionOrderDto;
+    'transfer-order.created': TransferOrderDto;
+    'transfer-order.updated': TransferOrderDto;
+    /** Action mutation — result is a success flag; use args + stock.transferred. */
+    'transfer-order.transferred': boolean;
+    /** Action mutation — result is a success flag; use args + stock.in-transfer reversal. */
+    'transfer-order.transfer-cancelled': boolean;
+    'transfer-customer-order.created': TransferCustomerOrderDto;
+    'transfer-customer-order.updated': TransferCustomerOrderDto;
+    /** Action mutation — result is a success flag; use args + stock.customer-returned. */
+    'transfer-customer-order.returned': boolean;
+    'transfer-vendor-order.created': TransferVendorOrderDto;
+    'transfer-vendor-order.updated': TransferVendorOrderDto;
+    /** Action mutation — result is a success flag; use args + stock.vendor-returned. */
+    'transfer-vendor-order.returned': boolean;
+}

package/lib/events/typed-maps.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @file typed-maps.ts
+ * Consumer-facing typed hook/listener maps for the WMS mutation event system.
+ *
+ * These types give consumers per-event type safety when wiring `beforeHooks`
+ * and `afterListeners` in `WmsModuleGraphqlModule.forRootAsync(...)`.  They
+ * layer on top of the runtime-erased core contracts without introducing any
+ * runtime dependency — everything here is `import type` only.
+ *
+ * Key exports
+ * -----------
+ * - {@link WmsEventPayloadFor}      — resolves the payload type for a given event name
+ * - {@link WmsTypedAfterEventContext}   — ctx passed to after-listeners
+ * - {@link WmsTypedBeforeHookContext}   — ctx passed to before-hooks (pre-DB)
+ * - {@link WmsTypedAfterListenerMap}   — `afterListeners` option with typed callbacks
+ * - {@link WmsTypedBeforeHookMap}      — `beforeHooks` option with typed callbacks
+ */
+import type { WmsActor, WmsEventName, WmsOperationEventName, WmsOperationEventPayload, WmsStockEventPayload } from '@rytass/wms-module-core';
+import type { ExecutionContext } from '@nestjs/common';
+import type { WmsOperationResultMap } from './operation-result-map';
+/**
+ * Resolves the full event payload type for a given {@link WmsEventName}.
+ *
+ * - Operation events (`WmsOperationEventName`): `WmsOperationEventPayload`
+ *   parameterised with the concrete result type from {@link WmsOperationResultMap}.
+ * - Stock events (`WmsStockEventName`): `WmsStockEventPayload` (ids-only by
+ *   default; enriched when `enrichStockEvents: true`).
+ */
+export type WmsEventPayloadFor<N extends WmsEventName> = N extends WmsOperationEventName ? WmsOperationEventPayload<WmsOperationResultMap[N]> : WmsStockEventPayload;
+/**
+ * Context passed to an after-listener.  Runs post-commit with the full
+ * typed event payload.
+ */
+export interface WmsTypedAfterEventContext<N extends WmsEventName> {
+    readonly event: N;
+    readonly payload: WmsEventPayloadFor<N>;
+}
+/**
+ * Context passed to a before-hook.  Runs *before* any DB work, so
+ * `payload` / `result` are not yet available — only the raw GraphQL
+ * arguments (`args`) and the resolved actor.  Throwing from a before-hook
+ * vetoes the mutation with zero side effects.
+ */
+export interface WmsTypedBeforeHookContext<N extends WmsEventName> {
+    readonly event: N;
+    /** Raw GraphQL arguments — the mutation intent (per §3.4 of the design doc). */
+    readonly args: Readonly<Record<string, unknown>>;
+    /** The NestJS execution context at the time of the mutation call. */
+    readonly executionContext: ExecutionContext;
+    /** Who performed the mutation; `null` when no `actorExtractor` is configured. */
+    readonly actor: WmsActor | null;
+}
+/**
+ * Typed `afterListeners` map.  Each key is an optional per-event callback
+ * that receives a fully typed {@link WmsTypedAfterEventContext}.
+ *
+ * Pass an instance of this type as `afterListeners` in
+ * `WmsModuleGraphqlModule.forRootAsync(...)` to get per-event type safety.
+ */
+export type WmsTypedAfterListenerMap = {
+    readonly [N in WmsEventName]?: (ctx: WmsTypedAfterEventContext<N>) => void | Promise<void>;
+};
+/**
+ * Typed `beforeHooks` map.  Each key is an optional per-event callback
+ * that receives a fully typed {@link WmsTypedBeforeHookContext}.
+ *
+ * Throwing inside a before-hook vetoes the mutation before any transaction
+ * is opened.  Pass an instance of this type as `beforeHooks` in
+ * `WmsModuleGraphqlModule.forRootAsync(...)`.
+ */
+export type WmsTypedBeforeHookMap = {
+    readonly [N in WmsEventName]?: (ctx: WmsTypedBeforeHookContext<N>) => void | Promise<void>;
+};

package/lib/events/wms-mutation.interceptor.d.ts

@@ -1,6 +1,6 @@
 import { type CallHandler, type ExecutionContext, type NestInterceptor } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
-import { WmsEventDispatcher } from '@rytass/wms-module-core';
+import { WmsEventDispatcher, type WmsActorExtractor } from '@rytass/wms-module-core';
 import { type Observable } from 'rxjs';
 /**
  * Wraps each `@WmsMutationEvent` mutation in a dispatch scope:
@@ -14,6 +14,8 @@ import { type Observable } from 'rxjs';
 export declare class WmsMutationInterceptor implements NestInterceptor {
     private readonly reflector;
     private readonly dispatcher;
-    constructor(reflector: Reflector, dispatcher: WmsEventDispatcher);
+    private readonly actorExtractor;
+    constructor(reflector: Reflector, dispatcher: WmsEventDispatcher, actorExtractor?: WmsActorExtractor | null);
+    private resolveActor;
     intercept(context: ExecutionContext, next: CallHandler): Promise<Observable<unknown>>;
 }

package/lib/events/wms-mutation.interceptor.js

@@ -1,8 +1,8 @@
-import { __decorate, __metadata } from 'tslib';
-import { Injectable } from '@nestjs/common';
+import { __decorate, __param, __metadata } from 'tslib';
+import { Injectable, Optional, Inject } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
 import { GqlExecutionContext } from '@nestjs/graphql';
-import { WmsEventDispatcher, runInDispatchScope, collectToScope } from '@rytass/wms-module-core';
+import { WMS_ACTOR_EXTRACTOR, WmsEventDispatcher, runInDispatchScope, collectToScope } from '@rytass/wms-module-core';
 import { firstValueFrom, of } from 'rxjs';
 import { WMS_MUTATION_EVENT_METADATA } from './wms-mutation-event.constants.js';
 
@@ -28,9 +28,23 @@ const defaultResolveId = (result, args) => {
 let WmsMutationInterceptor = class WmsMutationInterceptor {
     reflector;
     dispatcher;
-    constructor(reflector, dispatcher) {
+    actorExtractor;
+    constructor(reflector, dispatcher, actorExtractor = null) {
         this.reflector = reflector;
         this.dispatcher = dispatcher;
+        this.actorExtractor = actorExtractor;
+    }
+    resolveActor(context) {
+        if (!this.actorExtractor) {
+            return null;
+        }
+        try {
+            return this.actorExtractor(context);
+        }
+        catch {
+            // Fail-open on actor resolution: never break a mutation over audit metadata.
+            return null;
+        }
     }
     async intercept(context, next) {
         const config = this.reflector.get(WMS_MUTATION_EVENT_METADATA, context.getHandler());
@@ -39,11 +53,13 @@ let WmsMutationInterceptor = class WmsMutationInterceptor {
         }
         const args = GqlExecutionContext.create(context).getArgs() ??
             {};
+        const actor = this.resolveActor(context);
         // Before-hook runs before any DB work; a throw vetoes with zero side effects.
         await this.dispatcher.runBeforeHook({
             event: config.event,
             args,
             executionContext: context,
+            actor,
         });
         const { result, events } = await runInDispatchScope(async () => {
             const handlerResult = await firstValueFrom(next.handle());
@@ -52,7 +68,7 @@ let WmsMutationInterceptor = class WmsMutationInterceptor {
                 : defaultResolveId(handlerResult, args);
             const operationEvent = {
                 name: config.event,
-                payload: { id, result: handlerResult },
+                payload: { id, result: handlerResult, args, actor },
             };
             collectToScope(operationEvent);
             return handlerResult;
@@ -65,8 +81,10 @@ let WmsMutationInterceptor = class WmsMutationInterceptor {
 };
 WmsMutationInterceptor = __decorate([
     Injectable(),
+    __param(2, Optional()),
+    __param(2, Inject(WMS_ACTOR_EXTRACTOR)),
     __metadata("design:paramtypes", [Reflector,
-        WmsEventDispatcher])
+        WmsEventDispatcher, Object])
 ], WmsMutationInterceptor);
 
 export { WmsMutationInterceptor };

package/lib/graphql.module.d.ts

@@ -1,12 +1,18 @@
 import { DynamicModule, type Provider } from '@nestjs/common';
-import { type WmsModuleCoreModuleAsyncOptions, type WmsEventModuleOptions } from '@rytass/wms-module-core';
+import { type WmsActorExtractor, type WmsModuleCoreModuleAsyncOptions } from '@rytass/wms-module-core';
 import { type WmsAuthModuleOptions } from './auth';
+import { type WmsTypedAfterListenerMap, type WmsTypedBeforeHookMap } from './events';
 /**
  * Options for `WmsModuleGraphqlModule.forRootAsync`. Extends the core module
  * options with:
  * - {@link WmsAuthModuleOptions.authChecker} — opt-in resolver authorization;
- * - {@link WmsEventModuleOptions} — `beforeHooks` (veto) / `afterListeners`
- *   (post-commit notify) for the mutation event/hook system;
+ * - `beforeHooks` (veto) / `afterListeners` (post-commit notify) — the mutation
+ *   event/hook system, **typed per event** (operation events carry their concrete
+ *   DTO via {@link WmsTypedAfterListenerMap});
+ * - `actorExtractor` — populates `payload.actor` on every event (pass
+ *   `memberBaseActorExtractor` from the member-base adapter, or your own);
+ * - `enrichStockEvents` — when `true`, stock events also carry
+ *   `materialId/batchId/locationId/loaderId` (inherited from the core options);
  * - `eventEmitterBridge` — pass `wmsEventEmitterBridgeProvider` from
  *   `@rytass/wms-module-graphql/adapters/event-emitter` to also fan events out
  *   to `@nestjs/event-emitter` (`@OnEvent('wms.<event>')`).
@@ -14,7 +20,10 @@ import { type WmsAuthModuleOptions } from './auth';
  * Everything is optional; with nothing configured the module behaves exactly as
  * before (no events emitted, fully permissive).
  */
-export type WmsModuleGraphqlModuleAsyncOptions = WmsModuleCoreModuleAsyncOptions & WmsAuthModuleOptions & WmsEventModuleOptions & {
+export type WmsModuleGraphqlModuleAsyncOptions = WmsModuleCoreModuleAsyncOptions & WmsAuthModuleOptions & {
+    readonly beforeHooks?: WmsTypedBeforeHookMap;
+    readonly afterListeners?: WmsTypedAfterListenerMap;
+    readonly actorExtractor?: WmsActorExtractor;
     readonly eventEmitterBridge?: Provider;
 };
 export declare class WmsModuleGraphqlModule {

package/lib/graphql.module.js

@@ -1,6 +1,6 @@
 import { __decorate } from 'tslib';
 import { Module } from '@nestjs/common';
-import { WmsModuleCoreModule, WMS_EVENT_OPTIONS, WmsEventDispatcher } from '@rytass/wms-module-core';
+import { WmsModuleCoreModule, WMS_EVENT_OPTIONS, WMS_ACTOR_EXTRACTOR, WmsEventDispatcher } from '@rytass/wms-module-core';
 import './helpers/loader.service.js';
 import { HelperModule } from './helpers/helper.module.js';
 import './helpers/query-path.js';
@@ -111,15 +111,23 @@ const exportDependencies = [
 ];
 let WmsModuleGraphqlModule = WmsModuleGraphqlModule_1 = class WmsModuleGraphqlModule {
     static forRootAsync(options) {
-        const { authChecker, beforeHooks, afterListeners, eventEmitterBridge, ...coreOptions } = options;
+        const { authChecker, beforeHooks, afterListeners, actorExtractor, eventEmitterBridge, ...coreOptions } = options;
+        // coreOptions still carries `enrichStockEvents`, forwarded to the core module.
         const coreModule = WmsModuleCoreModule.forRootAsync(coreOptions);
         const authOptions = { authChecker };
-        const eventOptions = { beforeHooks, afterListeners };
+        // The typed hook maps are a compile-time refinement of the core maps; at
+        // runtime the dispatched payload IS the concrete result type, so handing the
+        // refined maps to the (looser) core option contract is sound.
+        const eventOptions = {
+            beforeHooks: beforeHooks,
+            afterListeners: afterListeners,
+        };
         const providers = [
             ...exportDependencies,
             WmsAuthGuard,
             { provide: WMS_AUTH_OPTIONS, useValue: authOptions },
             { provide: WMS_EVENT_OPTIONS, useValue: eventOptions },
+            { provide: WMS_ACTOR_EXTRACTOR, useValue: actorExtractor ?? null },
             WmsEventDispatcher,
             WmsMutationInterceptor,
             ...(eventEmitterBridge ? [eventEmitterBridge] : []),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rytass/wms-module-graphql",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Rytass WMS Module — GraphQL schema, resolvers and DTOs for warehouse management",
   "keywords": [
     "rytass",
@@ -57,7 +57,7 @@
     "@nestjs/apollo": ">=13.0.0 <13.2.0",
     "@nestjs/common": "^11.0.0",
     "@nestjs/graphql": "^13.0.0",
-    "@rytass/wms-module-core": "^0.2.0",
+    "@rytass/wms-module-core": "^0.3.0",
     "graphql": "^16.0.0",
     "reflect-metadata": "^0.1.13 || ^0.2.0",
     "rxjs": "^7.8.0",