@rytass/wms-module-graphql 0.4.0 → 0.5.0

package/README.md

@@ -88,6 +88,31 @@ The member-base adapter reuses everything `CasbinGuard` already put on the reque
 
 ➡️ **Full design & recipes: [`docs/authorization.md`](./docs/authorization.md)** (the problem, execution order, member-base / custom-JWT / no-guard recipes, the single coupling point, public API, FAQ).
 
+## Events & Hooks
+
+Intervene in and get notified about mutations. Every root mutation carries a typed **operation event** (`material.created`, `ship-inventory-order.shipped`, …) and fans out **stock domain events** (`stock.allocated`, `stock.shipped`, …) driven by the `ChangeType` state machine. Wire two opt-in hook points via `forRootAsync`:
+
+- **`beforeHooks`** run before any DB work — **throw to veto** the mutation (zero side effects).
+- **`afterListeners`** run **after the outermost transaction commits** — never notified about rolled-back changes.
+
+```ts
+WmsModuleGraphqlModule.forRootAsync({
+  ...coreOptions,
+  beforeHooks: {
+    'ship-inventory-order.shipped': async ({ args }) => {
+      if (!allowed(args)) throw new ForbiddenException('blocked');
+    },
+  },
+  afterListeners: {
+    'stock.allocated': async ({ payload }) => { await erp.reserve(payload); },
+  },
+});
+```
+
+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)**.
+
 ## DataLoader context
 
 The module ships a `HelperModule` (auto-registered) that provides a singleton `LoaderService`. To avoid N+1 queries, the WMS resolvers expect a per-request DataLoader trio at `context.loaders`:
@@ -124,6 +149,7 @@ Full documentation is shipped inside this package under the `docs/` directory (a
 |---|---|
 | [`docs/integration-guide.md`](./docs/integration-guide.md) | Step-by-step wiring guide for NestJS + Next.js consumers |
 | [`docs/authorization.md`](./docs/authorization.md) | Complete resolver-authorization design & integration recipes (member-base / custom JWT / no-guard) |
+| [`docs/events.md`](./docs/events.md) | Mutation event/hook system — before-hooks (veto), post-commit after-listeners, complete event list, event-emitter bridge |
 | [`docs/api-reference.md`](./docs/api-reference.md) | Complete export catalog with signatures and usage examples |
 
 GitHub hosted links (always up-to-date):
@@ -131,6 +157,7 @@ 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)
 - [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)
 
 ## License

package/adapters/event-emitter.d.ts

@@ -0,0 +1,29 @@
+import type { Provider } from '@nestjs/common';
+/**
+ * Bridges WMS domain events onto `@nestjs/event-emitter`'s `EventEmitter2`, so
+ * consumers can subscribe with `@OnEvent('wms.<event-name>')` instead of (or in
+ * addition to) the typed `afterListeners`.
+ *
+ * Pass this into `WmsModuleGraphqlModule.forRootAsync({ eventEmitterBridge })`.
+ * Importing this module is the only place `@nestjs/event-emitter` is referenced,
+ * keeping it an entirely optional peer dependency — the core graphql module
+ * never imports it.
+ *
+ * Prerequisite: register `EventEmitterModule.forRoot()` in your app so an
+ * `EventEmitter2` instance is available for injection.
+ *
+ * @example
+ * ```ts
+ * import { wmsEventEmitterBridgeProvider } from '@rytass/wms-module-graphql/adapters/event-emitter';
+ *
+ * WmsModuleGraphqlModule.forRootAsync({
+ *   ...coreOptions,
+ *   eventEmitterBridge: wmsEventEmitterBridgeProvider,
+ * });
+ *
+ * // elsewhere
+ * @OnEvent('wms.stock.allocated')
+ * handle(payload: WmsStockEventPayload) { ... }
+ * ```
+ */
+export declare const wmsEventEmitterBridgeProvider: Provider;

package/adapters/event-emitter.js

@@ -0,0 +1,41 @@
+import { EventEmitter2 } from '@nestjs/event-emitter';
+import { WMS_EVENT_EMITTER_BRIDGE } from '@rytass/wms-module-core';
+
+/**
+ * Bridges WMS domain events onto `@nestjs/event-emitter`'s `EventEmitter2`, so
+ * consumers can subscribe with `@OnEvent('wms.<event-name>')` instead of (or in
+ * addition to) the typed `afterListeners`.
+ *
+ * Pass this into `WmsModuleGraphqlModule.forRootAsync({ eventEmitterBridge })`.
+ * Importing this module is the only place `@nestjs/event-emitter` is referenced,
+ * keeping it an entirely optional peer dependency — the core graphql module
+ * never imports it.
+ *
+ * Prerequisite: register `EventEmitterModule.forRoot()` in your app so an
+ * `EventEmitter2` instance is available for injection.
+ *
+ * @example
+ * ```ts
+ * import { wmsEventEmitterBridgeProvider } from '@rytass/wms-module-graphql/adapters/event-emitter';
+ *
+ * WmsModuleGraphqlModule.forRootAsync({
+ *   ...coreOptions,
+ *   eventEmitterBridge: wmsEventEmitterBridgeProvider,
+ * });
+ *
+ * // elsewhere
+ * @OnEvent('wms.stock.allocated')
+ * handle(payload: WmsStockEventPayload) { ... }
+ * ```
+ */
+const wmsEventEmitterBridgeProvider = {
+    provide: WMS_EVENT_EMITTER_BRIDGE,
+    useFactory: (emitter) => ({
+        forward: (event) => {
+            emitter.emit(`wms.${event.name}`, event.payload);
+        },
+    }),
+    inject: [EventEmitter2],
+};
+
+export { wmsEventEmitterBridgeProvider };

package/docs/README.md

@@ -8,6 +8,7 @@ Reference material for consumers of `@rytass/wms-module-{core,graphql,react}`.
 |------------------------------------------------|---------------------------------------------------------------------------------------------------|
 | [Integration Guide](./integration-guide.md)    | Step-by-step instructions for wiring the three packages into a new consumer project (NestJS + Next.js + PostgreSQL). Includes ready-to-paste `_app.tsx`, `app.module.ts`, `next.config.ts`, the 19 Pages Router shell pattern, AuthGuard stub, seed script template, deployment notes, and known issues. |
 | [Authorization](./authorization.md)            | Complete design of the resolver-level authorization protocol (`@WmsOperation` + `WmsAuthGuard` + `authChecker`). Explains the global deny-by-default guard pitfall, execution order, and integration recipes for member-base / Casbin, custom JWT / RBAC, and no-guard setups. Read this if any WMS query/mutation returns *forbidden*. |
+| [Events & Hooks](./events.md)                  | The mutation event/hook system — `beforeHooks` (veto before any DB work) and `afterListeners` (post-commit notify), the `AsyncLocalStorage` post-commit mechanism, the optional `@nestjs/event-emitter` bridge, and the complete list of 38 operation + 18 stock domain events with payloads. |
 | [API Reference](./api-reference.md)            | Complete export catalog for all three packages — every NestJS module, TypeORM entity, GraphQL resolver, DTO, React component, hook, and utility, organized by role with source paths and usage examples. Mirrors the actual `src/index.ts` barrel exports of `@rytass/wms-module-graphql@0.3.0` and `@rytass/wms-module-{core,react}@0.1.6`. |
 
 ## Quick links
@@ -26,6 +27,8 @@ Reference material for consumers of `@rytass/wms-module-{core,graphql,react}`.
 | Replace the `AuthGuard` stub with real auth             | [Integration Guide section 8.4](./integration-guide.md#84-real-auth-integration) |
 | Authorize WMS resolvers with member-base / Casbin / RBAC | [Authorization](./authorization.md)                                   |
 | Fix "every WMS query/mutation is forbidden"             | [Authorization section 1](./authorization.md#1-the-problem)            |
+| Hook into / get notified about mutations                | [Events & Hooks](./events.md)                                          |
+| See every event the system emits                        | [Events & Hooks section 5](./events.md#5-complete-event-list)          |
 | Decide between PostgreSQL and SQLite                    | [Integration Guide section 9](./integration-guide.md#9-database-support-matrix) |
 | Build a custom UI on top of the lib's GraphQL operations| [Integration Guide section 7.3](./integration-guide.md#73-graphql-operations--typed-hooks) |
 

package/docs/api-reference.md

@@ -449,6 +449,46 @@ The adapter imports nothing from member-base — it reads the `payload` / `enfor
 
 ---
 
+## Events & Hooks
+
+Opt-in `beforeHooks` (veto) and post-commit `afterListeners` for every mutation. Each root mutation carries `@WmsMutationEvent({ event })` (already applied); a per-mutation interceptor runs the before-hook, opens an `AsyncLocalStorage` dispatch scope, and flushes collected events after the transaction commits. Stock domain events are collected centrally by a TypeORM subscriber on `*_order_change` inserts. Full design & the complete event list: [`docs/events.md`](./events.md).
+
+### 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? }` |
+
+### Adapter subpath (`@rytass/wms-module-graphql/adapters/event-emitter`)
+
+| 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()`. |
+
+```ts
+WmsModuleGraphqlModule.forRootAsync({
+  ...coreOptions,
+  beforeHooks: { 'ship-inventory-order.shipped': async ({ args }) => { if (!ok(args)) 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.
+
+---
+
 ## Resolvers（`@Resolver()` decorator class）
 
 以下 Resolver 類別處理 GraphQL `@ResolveField`，解析關聯欄位（防止 N+1）：

package/docs/events.md

@@ -0,0 +1,304 @@
+# Events & Hooks
+
+How a consumer **intervenes in** (vetoes) and **gets notified about** WMS
+mutations, with a host-neutral, opt-in API that mirrors the
+[authorization](./authorization.md) layer's wiring.
+
+- [1. What you get](#1-what-you-get)
+- [2. Architecture — post-commit guarantee](#2-architecture--post-commit-guarantee)
+- [3. Integration](#3-integration)
+- [4. The `@nestjs/event-emitter` bridge](#4-the-nestjsevent-emitter-bridge)
+- [5. Complete event list](#5-complete-event-list)
+- [6. Payloads](#6-payloads)
+- [7. Guarantees & limitations](#7-guarantees--limitations)
+- [8. Public API](#8-public-api)
+
+---
+
+## 1. What you get
+
+Two tiers of events, both opt-in:
+
+- **Operation events** — exactly one per root mutation (`material.created`,
+  `ship-inventory-order.shipped`, …). 38 in total.
+- **Stock domain events** — driven by the `ChangeType` state machine
+  (`stock.allocated`, `stock.shipped`, …), emitted once per stock movement, so a
+  single operation can fan out several. 18 in total.
+
+Two hook points per event:
+
+- **`beforeHooks`** run *before* any DB work. Throwing **vetoes** the whole
+  mutation — nothing is written, no after-listener fires. Use for custom
+  authorization, validation, quota enforcement.
+- **`afterListeners`** run *after the outermost transaction commits*. Use for
+  audit logging, ERP/webhook sync, cache invalidation, notifications.
+
+Everything is optional. With nothing configured the module behaves exactly as
+before — no events, zero overhead.
+
+---
+
+## 2. Architecture — post-commit guarantee
+
+The hard requirement is that an after-listener must **never** be told about a
+change that was rolled back. WMS guarantees this with an `AsyncLocalStorage`
+dispatch scope opened by a per-mutation interceptor:
+
+```
+GraphQL Mutation (@WmsMutationEvent)
+   |
+   v
+WmsMutationInterceptor
+   1. beforeHook(event, args)   --throw--> VETO (no transaction, clean error)
+   2. als.run(scope, async () => {
+        result = await handler()         // services open tx, write *_order_change rows
+      })                                 //   -> StockChangeSubscriber.afterInsert
+   |                                     //      collects stock.* events into the scope
+   |  handler resolved == transaction committed
+   v
+   3. flush(scope.buffer)
+        afterListener(event)  (isolated; one failure never blocks others)
+        emitterBridge.forward(event)  --> EventEmitter2 (optional)
+```
+
+Why it is post-commit: TypeORM's `dataSource.transaction(cb)` resolves only
+*after* `COMMIT`. The interceptor awaits the whole handler before flushing, so
+the buffer is dispatched strictly after commit. If the transaction rolls back
+the handler rejects, the interceptor never flushes, and the buffered events are
+discarded.
+
+Stock events are collected centrally by a single TypeORM subscriber
+(`StockChangeSubscriber`) that listens to every `*_order_change` insert and
+derives the `ChangeType` from the table name and the sign of `quantityChanged`.
+The 12 domain services are untouched, and any future code path that writes a
+change row is covered automatically.
+
+---
+
+## 3. Integration
+
+`beforeHooks` / `afterListeners` are typed maps keyed by event name; the payload
+is inferred from the key.
+
+```ts
+import { WmsModuleGraphqlModule } from '@rytass/wms-module-graphql';
+import { ForbiddenException } from '@nestjs/common';
+
+WmsModuleGraphqlModule.forRootAsync({
+  useFactory: async () => ({}),
+  defaultLoaderSerialId: 'DEFAULT',
+  defaultLoaderTypeKey: 'DEFAULT',
+  defaultLocationKey: 'DEFAULT',
+
+  // intervene — runs before any DB work; throw to veto
+  beforeHooks: {
+    'ship-inventory-order.shipped': async ({ args, executionContext }) => {
+      if (!(await canShip(args, executionContext))) {
+        throw new ForbiddenException('shipment blocked');
+      }
+    },
+  },
+
+  // notify — runs after commit
+  afterListeners: {
+    'ship-inventory-order.shipped': async ({ payload }) => {
+      await erp.markShipped(payload.id, payload.result);
+    },
+    'stock.allocated': async ({ payload }) => {
+      await erp.reserve(payload.orderId, payload.itemId, payload.quantityDelta);
+    },
+  },
+});
+```
+
+- A `beforeHook` receives `{ event, args, executionContext }` — the mutation
+  **intent** (raw GraphQL args), since no result exists yet. Throw (e.g. a
+  `ForbiddenException`) to abort with zero side effects.
+- 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.
+
+---
+
+## 4. The `@nestjs/event-emitter` bridge
+
+Prefer decoupled `@OnEvent` subscribers? Opt into the bridge. It is the only
+thing that imports `@nestjs/event-emitter` (an **optional** peer dependency), so
+the core module never depends on it.
+
+```ts
+import { EventEmitterModule } from '@nestjs/event-emitter';
+import { wmsEventEmitterBridgeProvider } from '@rytass/wms-module-graphql/adapters/event-emitter';
+
+@Module({
+  imports: [
+    EventEmitterModule.forRoot(),
+    WmsModuleGraphqlModule.forRootAsync({
+      ...coreOptions,
+      eventEmitterBridge: wmsEventEmitterBridgeProvider,
+    }),
+  ],
+})
+export class AppModule {}
+
+// anywhere
+@Injectable()
+class StockSync {
+  @OnEvent('wms.stock.allocated')
+  handle(payload: WmsStockEventPayload) { /* ... */ }
+}
+```
+
+Every event is emitted as `wms.<event-name>` with its payload. `afterListeners`
+and the bridge can be used together — both fire.
+
+---
+
+## 5. Complete event list
+
+### 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 "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).
+
+### Stock domain events (18) — `stock.<change-type>`
+
+`stock.received`, `stock.in-shipment`, `stock.shipped`, `stock.in-transfer`,
+`stock.transferred`, `stock.vendor-transferred`, `stock.vendor-returned`,
+`stock.held`, `stock.released`, `stock.customer-held`,
+`stock.customer-returned`, `stock.splitted`, `stock.merged`, `stock.allocated`,
+`stock.deallocated`, `stock.reclassified`, `stock.scraped`,
+`stock.inspection-resolved`.
+
+The first 17 map 1:1 to `ChangeType`. `stock.inspection-resolved` has no
+`ChangeType` (quality inspection only flips the `inspectionResult` flag) and
+carries `changeType: null` plus `inspectionResult`.
+
+A single operation can emit **several** stock events — one per `*_order_change`
+row written, i.e. one per affected item. Cancellations re-use the forward event
+with a negative `quantityDelta` (`cancelShip` -> `stock.shipped`,
+`cancelTransfer` -> `stock.in-transfer`); branch on the sign, not the name only.
+
+---
+
+## 6. Payloads
+
+**Operation event** — `WmsOperationEventPayload`:
+
+```ts
+{ id: string | null;   // primary id of the operation's order/entity
+  result: unknown }     // the mutation's return value (DTO, or boolean for actions)
+```
+
+**Stock event** — `WmsStockEventPayload`:
+
+```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
+```
+
+`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.
+
+---
+
+## 7. Guarantees & limitations
+
+- **Post-commit, in-order.** After-listeners fire strictly after commit, in
+  collection order, with the operation event last.
+- **Veto is side-effect-free.** A throwing before-hook runs before any
+  transaction; nothing is written.
+- **Listener isolation.** A throwing after-listener is logged and skipped; it
+  never rolls back the (already committed) mutation or blocks other listeners.
+- **In-process, not persistent.** If the process crashes after commit but before
+  flush, those events are lost. This is an in-process event bus, not an
+  at-least-once outbox. If you need durable delivery, persist inside your
+  after-listener is *not* enough — use an external CDC/outbox.
+- **"Handler resolve = post-commit" invariant.** Relies on every mutation
+  resolver `await`-ing all its writes (it does today). Never fire-and-forget an
+  un-awaited DB write inside a mutation.
+- **Uneven transaction boundaries.** `receive*` wrap the transaction at the
+  resolver, `ship/transfer/cancel*/reclassify/merge/split` at the service, and
+  the `create/update` series have no explicit transaction (multiple awaits).
+  Events for the no-transaction operations fire after the writes complete, but
+  those operations were never atomic to begin with.
+
+---
+
+## 8. Public API
+
+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. |
+
+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`. |
+
+`forRootAsync` accepts `beforeHooks`, `afterListeners` and `eventEmitterBridge`
+on its single options object — all optional.
+
+---
+
+See also: [Authorization](./authorization.md) · [API Reference](./api-reference.md) · [Integration Guide](./integration-guide.md)

package/docs/integration-guide.md

@@ -16,7 +16,9 @@ Target audience: engineers integrating WMS into a new product who want a working
 5. [Frontend setup (Next.js Pages Router)](#5-frontend-setup-nextjs-pages-router)
 6. [Pages Router shell pattern (the 19 thin shells)](#6-pages-router-shell-pattern-the-19-thin-shells)
 7. [Apollo client wiring](#7-apollo-client-wiring)
-8. [Authentication / authorization](#8-authentication--authorization)
+8. [Authentication, authorization & events](#8-authentication-authorization--events)
+   - [8.5 Backend authorization (resolver-level)](#85-backend-authorization-resolver-level)
+   - [8.6 Mutation events & hooks](#86-mutation-events--hooks)
 9. [Database support matrix](#9-database-support-matrix)
 10. [Seed data for demos](#10-seed-data-for-demos)
 11. [Deployment notes](#11-deployment-notes)
@@ -739,7 +741,7 @@ The full list of generated `Document` constants and their types is in
 
 ---
 
-## 8. Authentication / authorization
+## 8. Authentication, authorization & events
 
 The lib ships **no frontend auth** — the page components assume they render in an authenticated context and call queries on mount without checking session state. On the **backend**, `@rytass/wms-module-graphql` ships an *opt-in, host-neutral authorization protocol* you wire to your own permission system (member-base / Casbin / JWT / anything). See [§8.5 Backend authorization](#85-backend-authorization-resolver-level).
 
@@ -869,6 +871,85 @@ The WMS `resource`/`action` strings are **internal metadata only** — they are
 
 ---
 
+### 8.6 Mutation events & hooks
+
+> 📖 Condensed version. The full design, the complete list of 38 operation + 18 stock domain events, payloads, and limitations live in [**`docs/events.md`**](./events.md).
+
+Every WMS mutation can be **intervened in** and **observed** through two opt-in hook points wired on the same `WmsModuleGraphqlModule.forRootAsync({ ... })` call as everything else:
+
+- **`beforeHooks`** run *before any DB work* — `throw` to **veto** the mutation (zero side effects).
+- **`afterListeners`** run *after the outermost transaction commits* — you are never notified about a rolled-back change.
+
+```ts
+// apps/api/src/app/app.module.ts
+import { ForbiddenException } from '@nestjs/common';
+import { WmsModuleGraphqlModule } from '@rytass/wms-module-graphql';
+
+WmsModuleGraphqlModule.forRootAsync({
+  // ...the same core options as §4.2 (defaultLoaderSerialId, useFactory, etc.)...
+
+  beforeHooks: {
+    // intent payload = the raw GraphQL args; throw to abort
+    'ship-inventory-order.shipped': async ({ args, executionContext }) => {
+      if (!(await canShip(args, executionContext))) {
+        throw new ForbiddenException('shipment blocked');
+      }
+    },
+  },
+
+  afterListeners: {
+    // operation event — fires once per mutation, with the result
+    'ship-inventory-order.shipped': async ({ payload }) => {
+      await erp.markShipped(payload.id, payload.result);
+    },
+    // stock domain event — fires once per affected item (post-commit)
+    'stock.allocated': async ({ payload }) => {
+      await erp.reserve(payload.orderId, payload.itemId, payload.quantityDelta);
+    },
+  },
+});
+```
+
+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.
+
+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).
+
+#### 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>`:
+
+```ts
+import { EventEmitterModule } from '@nestjs/event-emitter';
+import { wmsEventEmitterBridgeProvider } from '@rytass/wms-module-graphql/adapters/event-emitter';
+
+@Module({
+  imports: [
+    EventEmitterModule.forRoot(),
+    WmsModuleGraphqlModule.forRootAsync({
+      ...coreOptions,
+      eventEmitterBridge: wmsEventEmitterBridgeProvider, // <- enables the bridge
+    }),
+  ],
+})
+export class AppModule {}
+
+// elsewhere
+@Injectable()
+class StockSync {
+  @OnEvent('wms.stock.allocated')
+  handle(payload: WmsStockEventPayload) { /* ... */ }
+}
+```
+
+The bridge is the only thing that imports `@nestjs/event-emitter`, so it stays an entirely optional dependency — the core module never requires it. `afterListeners` and the bridge can be used together.
+
+> ⚠️ Delivery is **in-process and post-commit**, not a durable outbox: if the process crashes after commit but before dispatch, those events are lost. See [`docs/events.md` §7](./events.md#7-guarantees--limitations) for the full guarantees.
+
+---
+
 ## 9. Database support matrix
 
 | Database   | Status        | Notes                              |