@rytass/wms-module-graphql 0.5.0 → 0.6.1

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

@@ -55,6 +55,65 @@ exports.LoaderService = class LoaderService {
         const fields = ___default.default(Object.keys(__from)).sort();
         return `${__hash}_${fields.map((field) => data[field]).join('_')}`;
     }
+    /**
+     * resolve a `__from` property name to the physical column it is stored in.
+     *
+     * TypeORM's `FindOptionsWhere` only accepts real column properties. A
+     * `@RelationId()` property — e.g. `LocationEntityClass.parentId`, which mirrors
+     * the `parent` tree relation — is virtual and is rejected with
+     * `EntityPropertyNotFoundError`, even though it is backed by the relation's
+     * join column. Map those back to their join column so they stay batchable.
+     * @param EntityMetadata
+     * @param string
+     * @returns string | null
+     */
+    resolveColumnName(metadata, propertyName) {
+        const column = metadata.findColumnWithPropertyName(propertyName);
+        if (column)
+            return column.databaseName;
+        const relationId = metadata.relationIds.find((candidate) => candidate.propertyName === propertyName);
+        const joinColumns = relationId?.relation.joinColumns ?? [];
+        return joinColumns.length === 1 ? joinColumns[0].databaseName : null;
+    }
+    /**
+     * build the where clause for `__from` keys that TypeORM's find options cannot
+     * express (see {@link resolveColumnName}), by addressing the columns directly.
+     * @param SelectQueryBuilder
+     * @param EntityMetadata
+     * @param LoaderOptions[]
+     * @param (keyof T)[]
+     */
+    applyColumnWhere(qb, metadata, options, primaryKeys) {
+        const columns = primaryKeys.map((primaryKey) => {
+            const columnName = this.resolveColumnName(metadata, String(primaryKey));
+            if (!columnName)
+                throw new Error(`Loader cannot resolve property "${String(primaryKey)}" to a column of "${metadata.name}".`);
+            return {
+                primaryKey,
+                column: `entity.${this.dataSource.driver.escape(columnName)}`,
+            };
+        });
+        if (columns.length === 1) {
+            const [{ primaryKey, column }] = columns;
+            qb.andWhere(`${column} IN (:...wmsLoaderValues)`, {
+                wmsLoaderValues: options.map(({ __from }) => __from[primaryKey]),
+            });
+            return;
+        }
+        qb.andWhere(new typeorm.Brackets((where) => {
+            options.forEach(({ __from }, optionIndex) => {
+                const parameters = {};
+                const predicate = columns
+                    .map(({ primaryKey, column }, columnIndex) => {
+                    const parameter = `wmsLoaderValue_${optionIndex}_${columnIndex}`;
+                    parameters[parameter] = __from[primaryKey];
+                    return `${column} = :${parameter}`;
+                })
+                    .join(' AND ');
+                where.orWhere(`(${predicate})`, parameters);
+            });
+        }));
+    }
     /**
      * query data by collecting primary keys from options with same `__entity`
      * @param LoaderOptions[]
@@ -65,7 +124,10 @@ exports.LoaderService = class LoaderService {
         const repo = this.dataSource.getRepository(__entity);
         let qb = repo.createQueryBuilder('entity');
         const primaryKeys = Object.keys(__from);
-        if (primaryKeys.length > 1)
+        const hasVirtualKey = primaryKeys.some((primaryKey) => !repo.metadata.findColumnWithPropertyName(String(primaryKey)));
+        if (hasVirtualKey)
+            this.applyColumnWhere(qb, repo.metadata, options, primaryKeys);
+        else if (primaryKeys.length > 1)
             qb.setFindOptions({ where: options.map(({ __from }) => __from) });
         else {
             const [primaryKey] = primaryKeys;
@@ -330,9 +392,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 +417,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 +432,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 +445,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);
 
 /**
@@ -3593,8 +3673,21 @@ let LocationResolver = class LocationResolver {
             __from: { id: parentId },
         });
     }
-    children({ children }) {
-        return children;
+    /**
+     * `children` must never be read off the parent entity: only
+     * `LocationQuery.location` and `LocationService.findMany` eager-load the tree
+     * relation. Every other producer of a `LocationDto` (stock/loader/change-log/
+     * transfer/ship/receive/warehouse-map resolvers, the `parent` field above and
+     * the create/update mutations) hands back an entity whose `children` is
+     * `undefined`, which breaks the non-nullable list. Always resolve through the
+     * request-scoped loader instead.
+     */
+    children({ id }, { loaders }) {
+        return loaders.batchMany.load({
+            __entity: wmsModuleCore.LocationEntityClass,
+            __from: { parentId: id },
+            __conditions: (qb) => qb.orderBy('entity."key"', 'ASC'),
+        });
     }
 };
 tslib.__decorate([
@@ -3616,9 +3709,10 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.ResolveField(() => [LocationDto]),
     tslib.__param(0, graphql.Parent()),
+    tslib.__param(1, graphql.Context()),
     tslib.__metadata("design:type", Function),
-    tslib.__metadata("design:paramtypes", [wmsModuleCore.LocationEntityClass]),
-    tslib.__metadata("design:returntype", void 0)
+    tslib.__metadata("design:paramtypes", [wmsModuleCore.LocationEntityClass, Object]),
+    tslib.__metadata("design:returntype", Promise)
 ], LocationResolver.prototype, "children", null);
 LocationResolver = tslib.__decorate([
     graphql.Resolver(() => LocationDto)
@@ -6521,15 +6615,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/lib/helpers/loader.service.d.ts

@@ -33,6 +33,28 @@ export declare class LoaderService {
      * @returns Map<string, data>
      */
     private useIndex;
+    /**
+     * resolve a `__from` property name to the physical column it is stored in.
+     *
+     * TypeORM's `FindOptionsWhere` only accepts real column properties. A
+     * `@RelationId()` property — e.g. `LocationEntityClass.parentId`, which mirrors
+     * the `parent` tree relation — is virtual and is rejected with
+     * `EntityPropertyNotFoundError`, even though it is backed by the relation's
+     * join column. Map those back to their join column so they stay batchable.
+     * @param EntityMetadata
+     * @param string
+     * @returns string | null
+     */
+    private resolveColumnName;
+    /**
+     * build the where clause for `__from` keys that TypeORM's find options cannot
+     * express (see {@link resolveColumnName}), by addressing the columns directly.
+     * @param SelectQueryBuilder
+     * @param EntityMetadata
+     * @param LoaderOptions[]
+     * @param (keyof T)[]
+     */
+    private applyColumnWhere;
     /**
      * query data by collecting primary keys from options with same `__entity`
      * @param LoaderOptions[]