@rytass/wms-module-graphql 0.4.0 → 0.6.0

package/index.cjs.js

@@ -10,6 +10,7 @@ var typeorm = require('typeorm');
 var DataLoader = require('dataloader');
 var graphql = require('@nestjs/graphql');
 var core = require('@nestjs/core');
+var rxjs = require('rxjs');
 var wmsBaseNestjsModule = require('@rytass/wms-base-nestjs-module');
 var warehouseMap_entity = require('@rytass/wms-base-nestjs-module/models/warehouse-map.entity');
 
@@ -304,6 +305,105 @@ exports.WmsAuthGuard = tslib.__decorate([
  */
 const WmsOperation = (requirement) => common.applyDecorators(common.SetMetadata(WMS_OPERATION_METADATA, requirement), common.SetMetadata(HOST_SKIP_METADATA_KEY, true), common.UseGuards(exports.WmsAuthGuard));
 
+/** Reflector metadata key carrying the {@link WmsMutationEventConfig}. */
+const WMS_MUTATION_EVENT_METADATA = 'wms:mutation-event';
+
+const defaultResolveId = (result, args) => {
+    if (result &&
+        typeof result === 'object' &&
+        'id' in result &&
+        typeof result.id === 'string') {
+        return result.id;
+    }
+    const argId = args['id'];
+    return typeof argId === 'string' ? argId : null;
+};
+/**
+ * Wraps each `@WmsMutationEvent` mutation in a dispatch scope:
+ * 1. runs the before-hook (throw -> veto, before any transaction);
+ * 2. executes the resolver (services collect stock events into the scope);
+ * 3. emits the operation event after the handler resolves (post-commit);
+ * 4. flushes the whole buffer to after-listeners + emitter bridge.
+ *
+ * When no hook/listener/bridge is configured it passes through untouched.
+ */
+exports.WmsMutationInterceptor = class WmsMutationInterceptor {
+    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());
+        if (!config || !this.dispatcher.isActive()) {
+            return next.handle();
+        }
+        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());
+            const id = config.resolveId
+                ? config.resolveId(handlerResult, args)
+                : defaultResolveId(handlerResult, args);
+            const operationEvent = {
+                name: config.event,
+                payload: { id, result: handlerResult, args, actor },
+            };
+            wmsModuleCore.collectToScope(operationEvent);
+            return handlerResult;
+        });
+        if (events) {
+            await this.dispatcher.flush(events);
+        }
+        return rxjs.of(result);
+    }
+};
+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, Object])
+], exports.WmsMutationInterceptor);
+
+/**
+ * Declares the operation event for a WMS root mutation and wires the
+ * {@link WmsMutationInterceptor} that runs before-hooks (veto) and flushes
+ * collected events post-commit. Apply alongside `@WmsOperation` on each mutation.
+ *
+ * @example
+ * ```ts
+ * @Mutation(() => ShipInventoryOrderDto)
+ * @WmsOperation({ resource: 'ship-inventory-order', action: 'ship' })
+ * @WmsMutationEvent({ event: 'ship-inventory-order.shipped' })
+ * ship(@Args() args: ShipArgs): Promise<boolean> { ... }
+ * ```
+ */
+const WmsMutationEvent = (config) => common.applyDecorators(common.SetMetadata(WMS_MUTATION_EVENT_METADATA, config), common.UseInterceptors(exports.WmsMutationInterceptor));
+
 const IdGenFunction = (input) => {
     const hash = crypto.createHash('sha256');
     hash.update(input);
@@ -1633,6 +1733,7 @@ let LoaderMutation = class LoaderMutation {
 tslib.__decorate([
     graphql.Mutation(() => [LoaderDto]),
     WmsOperation({ resource: 'loader', action: 'create' }),
+    WmsMutationEvent({ event: 'loader.created' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [CreateLoaderArgs]),
@@ -1641,6 +1742,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => [LoaderDto]),
     WmsOperation({ resource: 'loader', action: 'create' }),
+    WmsMutationEvent({ event: 'loader.batch-created' }),
     tslib.__param(0, graphql.Args('items', { type: () => [CreateLoadersArgs] })),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [Array]),
@@ -1649,6 +1751,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => LoaderDto),
     WmsOperation({ resource: 'loader', action: 'update' }),
+    WmsMutationEvent({ event: 'loader.updated' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [UpdateLoaderArgs]),
@@ -1657,6 +1760,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => LoaderTypeDto),
     WmsOperation({ resource: 'loader', action: 'create' }),
+    WmsMutationEvent({ event: 'loader.type-created' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [CreateLoaderTypeArgs]),
@@ -1665,6 +1769,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => LoaderTypeDto),
     WmsOperation({ resource: 'loader', action: 'update' }),
+    WmsMutationEvent({ event: 'loader.type-updated' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [UpdateLoaderTypeArgs]),
@@ -2028,6 +2133,7 @@ let MaterialMutation = class MaterialMutation {
 tslib.__decorate([
     graphql.Mutation(() => MaterialDto),
     WmsOperation({ resource: 'material', action: 'create' }),
+    WmsMutationEvent({ event: 'material.created' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [CreateMaterialArgs]),
@@ -2036,6 +2142,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => MaterialDto),
     WmsOperation({ resource: 'material', action: 'update' }),
+    WmsMutationEvent({ event: 'material.updated' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [UpdateMaterialArgs]),
@@ -2431,6 +2538,7 @@ let ReceiveInventoryOrderMutation = class ReceiveInventoryOrderMutation {
 tslib.__decorate([
     graphql.Mutation(() => ReceiveInventoryOrderDto),
     WmsOperation({ resource: 'receive-inventory-order', action: 'create' }),
+    WmsMutationEvent({ event: 'receive-inventory-order.created' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [CreateReceiveInventoryOrderArgs]),
@@ -2439,6 +2547,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => ReceiveInventoryOrderDto),
     WmsOperation({ resource: 'receive-inventory-order', action: 'update' }),
+    WmsMutationEvent({ event: 'receive-inventory-order.updated' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [UpdateReceiveInventoryOrderArgs]),
@@ -2447,6 +2556,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => Boolean),
     WmsOperation({ resource: 'receive-inventory-order', action: 'receive' }),
+    WmsMutationEvent({ event: 'receive-inventory-order.received' }),
     tslib.__param(0, graphql.Args('items', { type: () => [ReceiveOrderArgs] })),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [Array]),
@@ -2790,6 +2900,7 @@ let ShipInventoryOrderMutation = class ShipInventoryOrderMutation {
 tslib.__decorate([
     graphql.Mutation(() => ShipInventoryOrderDto),
     WmsOperation({ resource: 'ship-inventory-order', action: 'create' }),
+    WmsMutationEvent({ event: 'ship-inventory-order.created' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [CreateShipInventoryOrderArgs]),
@@ -2798,6 +2909,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => ShipInventoryOrderDto),
     WmsOperation({ resource: 'ship-inventory-order', action: 'update' }),
+    WmsMutationEvent({ event: 'ship-inventory-order.updated' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [UpdateShipInventoryOrderArgs]),
@@ -2806,6 +2918,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => Boolean),
     WmsOperation({ resource: 'ship-inventory-order', action: 'ship' }),
+    WmsMutationEvent({ event: 'ship-inventory-order.shipped' }),
     tslib.__param(0, graphql.Args('items', { type: () => [ShipOrderArgs] })),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [Array]),
@@ -2814,6 +2927,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => Boolean),
     WmsOperation({ resource: 'ship-inventory-order', action: 'cancel' }),
+    WmsMutationEvent({ event: 'ship-inventory-order.ship-cancelled' }),
     tslib.__param(0, graphql.Args('items', { type: () => [CancelShipOrderArgs] })),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [Array]),
@@ -3469,6 +3583,7 @@ let WarehouseMapMutation = class WarehouseMapMutation {
 tslib.__decorate([
     graphql.Mutation(() => MapDataDto),
     WmsOperation({ resource: 'warehouse-map', action: 'update' }),
+    WmsMutationEvent({ event: 'warehouse-map.updated' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [UpdateWarehouseMapArgs]),
@@ -3650,6 +3765,7 @@ let LocationMutation = class LocationMutation {
 tslib.__decorate([
     graphql.Mutation(() => LocationDto),
     WmsOperation({ resource: 'location', action: 'create' }),
+    WmsMutationEvent({ event: 'location.created' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [CreateLocationArgs]),
@@ -3658,6 +3774,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => LocationDto),
     WmsOperation({ resource: 'location', action: 'update' }),
+    WmsMutationEvent({ event: 'location.updated' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [UpdateLocationArgs]),
@@ -3961,6 +4078,7 @@ let TransferOrderMutation = class TransferOrderMutation {
 tslib.__decorate([
     graphql.Mutation(() => TransferOrderDto),
     WmsOperation({ resource: 'transfer-order', action: 'create' }),
+    WmsMutationEvent({ event: 'transfer-order.created' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [CreateTransferOrderArgs]),
@@ -3969,6 +4087,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => TransferOrderDto),
     WmsOperation({ resource: 'transfer-order', action: 'update' }),
+    WmsMutationEvent({ event: 'transfer-order.updated' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [UpdateTransferOrderArgs]),
@@ -3977,6 +4096,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => Boolean),
     WmsOperation({ resource: 'transfer-order', action: 'transfer' }),
+    WmsMutationEvent({ event: 'transfer-order.transferred' }),
     tslib.__param(0, graphql.Args('items', { type: () => [TransferOrderArgs] })),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [Array]),
@@ -3985,6 +4105,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => Boolean),
     WmsOperation({ resource: 'transfer-order', action: 'cancel' }),
+    WmsMutationEvent({ event: 'transfer-order.transfer-cancelled' }),
     tslib.__param(0, graphql.Args('items', { type: () => [CancelTransferOrderArgs] })),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [Array]),
@@ -4436,6 +4557,7 @@ let HoldInventoryOrderMutation = class HoldInventoryOrderMutation {
 tslib.__decorate([
     graphql.Mutation(() => HoldInventoryOrderDto),
     WmsOperation({ resource: 'hold-inventory-order', action: 'create' }),
+    WmsMutationEvent({ event: 'hold-inventory-order.created' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [CreateHoldInventoryOrderArgs]),
@@ -4444,6 +4566,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => HoldInventoryOrderDto),
     WmsOperation({ resource: 'hold-inventory-order', action: 'update' }),
+    WmsMutationEvent({ event: 'hold-inventory-order.updated' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [UpdateHoldInventoryOrderArgs]),
@@ -4452,6 +4575,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => Boolean),
     WmsOperation({ resource: 'hold-inventory-order', action: 'release' }),
+    WmsMutationEvent({ event: 'hold-inventory-order.released' }),
     tslib.__param(0, graphql.Args('items', { type: () => [ReleaseOrderArgs] })),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [Array]),
@@ -4970,6 +5094,7 @@ let AllocateInventoryOrderMutation = class AllocateInventoryOrderMutation {
 tslib.__decorate([
     graphql.Mutation(() => AllocateInventoryOrderDto),
     WmsOperation({ resource: 'allocate-inventory-order', action: 'create' }),
+    WmsMutationEvent({ event: 'allocate-inventory-order.created' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [CreateAllocateInventoryOrderArgs]),
@@ -4978,6 +5103,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => AllocateInventoryOrderDto),
     WmsOperation({ resource: 'allocate-inventory-order', action: 'update' }),
+    WmsMutationEvent({ event: 'allocate-inventory-order.updated' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [UpdateAllocateInventoryOrderArgs]),
@@ -4986,6 +5112,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => Boolean),
     WmsOperation({ resource: 'allocate-inventory-order', action: 'deallocate' }),
+    WmsMutationEvent({ event: 'allocate-inventory-order.deallocated' }),
     tslib.__param(0, graphql.Args('items', { type: () => [DeallocateOrderArgs] })),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [Array]),
@@ -5442,6 +5569,7 @@ let SplitBatchMutation = class SplitBatchMutation {
 tslib.__decorate([
     graphql.Mutation(() => SplitBatchOrderDto),
     WmsOperation({ resource: 'batch', action: 'split' }),
+    WmsMutationEvent({ event: 'batch.splitted' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [SplitBatchArgs]),
@@ -5561,6 +5689,7 @@ let MergeBatchMutation = class MergeBatchMutation {
 tslib.__decorate([
     graphql.Mutation(() => MergeBatchOrderDto),
     WmsOperation({ resource: 'batch', action: 'merge' }),
+    WmsMutationEvent({ event: 'batch.merged' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [MergeBatchArgs]),
@@ -5686,6 +5815,7 @@ let ReclassifyInventoryOrderMutation = class ReclassifyInventoryOrderMutation {
 tslib.__decorate([
     graphql.Mutation(() => ReclassifyInventoryOrderDto),
     WmsOperation({ resource: 'reclassify-inventory-order', action: 'reclassify' }),
+    WmsMutationEvent({ event: 'reclassify-inventory-order.reclassified' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [ReclassifyInventoryOrderArgs]),
@@ -5859,6 +5989,7 @@ let TransferCustomerOrderMutation = class TransferCustomerOrderMutation {
 tslib.__decorate([
     graphql.Mutation(() => TransferCustomerOrderDto),
     WmsOperation({ resource: 'transfer-customer-order', action: 'create' }),
+    WmsMutationEvent({ event: 'transfer-customer-order.created' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [CreateTransferCustomerOrderArgs]),
@@ -5867,6 +5998,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => TransferCustomerOrderDto),
     WmsOperation({ resource: 'transfer-customer-order', action: 'update' }),
+    WmsMutationEvent({ event: 'transfer-customer-order.updated' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [UpdateTransferCustomerOrderArgs]),
@@ -5875,6 +6007,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => Boolean),
     WmsOperation({ resource: 'transfer-customer-order', action: 'return' }),
+    WmsMutationEvent({ event: 'transfer-customer-order.returned' }),
     tslib.__param(0, graphql.Args('items', { type: () => [ReturnTransferCustomerOrderArgs] })),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [Array]),
@@ -6067,6 +6200,7 @@ let TransferVendorOrderMutation = class TransferVendorOrderMutation {
 tslib.__decorate([
     graphql.Mutation(() => TransferVendorOrderDto),
     WmsOperation({ resource: 'transfer-vendor-order', action: 'create' }),
+    WmsMutationEvent({ event: 'transfer-vendor-order.created' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [CreateTransferVendorOrderArgs]),
@@ -6075,6 +6209,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => TransferVendorOrderDto),
     WmsOperation({ resource: 'transfer-vendor-order', action: 'update' }),
+    WmsMutationEvent({ event: 'transfer-vendor-order.updated' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [UpdateTransferVendorOrderArgs]),
@@ -6083,6 +6218,7 @@ tslib.__decorate([
 tslib.__decorate([
     graphql.Mutation(() => Boolean),
     WmsOperation({ resource: 'transfer-vendor-order', action: 'return' }),
+    WmsMutationEvent({ event: 'transfer-vendor-order.returned' }),
     tslib.__param(0, graphql.Args('items', { type: () => [ReturnTransferVendorOrderArgs] })),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [Array]),
@@ -6205,6 +6341,7 @@ let ScrapeMutation = class ScrapeMutation {
 tslib.__decorate([
     graphql.Mutation(() => ScrapeOrderDto),
     WmsOperation({ resource: 'scrape-order', action: 'scrape' }),
+    WmsMutationEvent({ event: 'scrape-order.scraped' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [ScrapeOrderArgs]),
@@ -6288,6 +6425,7 @@ let QualityInspectionOrderMutation = class QualityInspectionOrderMutation {
 tslib.__decorate([
     graphql.Mutation(() => QualityInspectionOrderDto),
     WmsOperation({ resource: 'quality-inspection-order', action: 'inspect' }),
+    WmsMutationEvent({ event: 'quality-inspection-order.inspected' }),
     tslib.__param(0, graphql.Args()),
     tslib.__metadata("design:type", Function),
     tslib.__metadata("design:paramtypes", [CreateQualityInspectionOrderArgs]),
@@ -6401,13 +6539,26 @@ const exportDependencies = [
 ];
 exports.WmsModuleGraphqlModule = WmsModuleGraphqlModule_1 = class WmsModuleGraphqlModule {
     static forRootAsync(options) {
-        const { authChecker, ...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 };
+        // 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] : []),
         ];
         return {
             module: WmsModuleGraphqlModule_1,
@@ -6425,6 +6576,8 @@ exports.WmsModuleGraphqlModule = WmsModuleGraphqlModule_1 = tslib.__decorate([
 
 exports.HOST_SKIP_METADATA_KEY = HOST_SKIP_METADATA_KEY;
 exports.WMS_AUTH_OPTIONS = WMS_AUTH_OPTIONS;
+exports.WMS_MUTATION_EVENT_METADATA = WMS_MUTATION_EVENT_METADATA;
 exports.WMS_OPERATION_METADATA = WMS_OPERATION_METADATA;
+exports.WmsMutationEvent = WmsMutationEvent;
 exports.WmsOperation = WmsOperation;
 exports.createWmsLoaders = createWmsLoaders;

package/index.d.ts

@@ -5,3 +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, 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/index.js

@@ -5,3 +5,6 @@ export { HOST_SKIP_METADATA_KEY } from './lib/auth/host-skip.constant.js';
 export { WmsAuthGuard } from './lib/auth/wms-auth.guard.js';
 export { WmsOperation } from './lib/auth/wms-operation.decorator.js';
 export { WMS_AUTH_OPTIONS, WMS_OPERATION_METADATA } from './lib/auth/wms-auth.types.js';
+export { WmsMutationEvent } from './lib/events/wms-mutation-event.decorator.js';
+export { WMS_MUTATION_EVENT_METADATA } from './lib/events/wms-mutation-event.constants.js';
+export { WmsMutationInterceptor } from './lib/events/wms-mutation.interceptor.js';

package/lib/events/index.d.ts

@@ -0,0 +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-event.constants.d.ts

@@ -0,0 +1,12 @@
+import type { WmsOperationEventName } from '@rytass/wms-module-core';
+/** Reflector metadata key carrying the {@link WmsMutationEventConfig}. */
+export declare const WMS_MUTATION_EVENT_METADATA = "wms:mutation-event";
+export interface WmsMutationEventConfig {
+    /** The operation event emitted for this mutation (post-commit). */
+    readonly event: WmsOperationEventName;
+    /**
+     * Optional override for deriving the operation's primary id from the handler
+     * result and/or arguments. Defaults to `result.id ?? args.id ?? null`.
+     */
+    readonly resolveId?: (result: unknown, args: Readonly<Record<string, unknown>>) => string | null;
+}

package/lib/events/wms-mutation-event.constants.js

@@ -0,0 +1,4 @@
+/** Reflector metadata key carrying the {@link WmsMutationEventConfig}. */
+const WMS_MUTATION_EVENT_METADATA = 'wms:mutation-event';
+
+export { WMS_MUTATION_EVENT_METADATA };

package/lib/events/wms-mutation-event.decorator.d.ts

@@ -0,0 +1,15 @@
+import { type WmsMutationEventConfig } from './wms-mutation-event.constants';
+/**
+ * Declares the operation event for a WMS root mutation and wires the
+ * {@link WmsMutationInterceptor} that runs before-hooks (veto) and flushes
+ * collected events post-commit. Apply alongside `@WmsOperation` on each mutation.
+ *
+ * @example
+ * ```ts
+ * @Mutation(() => ShipInventoryOrderDto)
+ * @WmsOperation({ resource: 'ship-inventory-order', action: 'ship' })
+ * @WmsMutationEvent({ event: 'ship-inventory-order.shipped' })
+ * ship(@Args() args: ShipArgs): Promise<boolean> { ... }
+ * ```
+ */
+export declare const WmsMutationEvent: (config: WmsMutationEventConfig) => MethodDecorator;