@explorins/pers-shared 2.1.36 → 2.1.37

package/dist/esm/shared-patterns/orchestrators/base-orchestrator.d.ts

@@ -0,0 +1,90 @@
+import { Logger } from '@nestjs/common';
+import { OrchestrationError } from '../../shared-lib/errors';
+import { CommandBus, QueryBus } from '@nestjs/cqrs';
+/**
+ * BaseOrchestrator - Centralized Application Layer Orchestration Pattern
+ *
+ * @description Foundation for all domain orchestrators following PERS DDD principles:
+ * - Application layer orchestrates cross-domain operations via CQRS
+ * - Domain services contain pure business logic only
+ * - Microservice boundary preparation through clean abstractions
+ * - Consistent patterns across all domains (transaction, user, wallet, token, etc.)
+ * - Smart error handling that preserves business context
+ *
+ * @usage Extend this class in domain-specific orchestrators:
+ * ```typescript
+ * @Injectable()
+ * export class UserOrchestrator extends BaseOrchestrator {
+ *   constructor(commandBus: CommandBus, queryBus: QueryBus) {
+ *     super(commandBus, queryBus, UserOrchestrator.name);
+ *   }
+ * }
+ * ```
+ *
+ * @library @explorins/pers-shared
+ * @version 2.0.0
+ * @since August 2025
+ */
+export declare abstract class BaseOrchestrator {
+    protected readonly commandBus: CommandBus;
+    protected readonly queryBus: QueryBus;
+    protected readonly logger: Logger;
+    protected constructor(commandBus: CommandBus, queryBus: QueryBus, loggerContext: string);
+    /**
+     * Enhanced error handling that preserves business errors while wrapping technical errors
+     * Business errors (with category: DOMAIN_RULE) are passed through unchanged
+     * Technical errors are wrapped in OrchestrationError for consistent handling
+     */
+    protected executeWithErrorHandling<T>(operation: () => Promise<T>, operationName: string, context?: Record<string, any>): Promise<T>;
+    /**
+     * Execute CQRS command with consistent error handling and logging
+     * Standardizes command execution across all orchestrators
+     */
+    protected executeCommand<T>(command: any, operationName?: string): Promise<T>;
+    /**
+     * Execute CQRS query with consistent error handling and logging
+     * Standardizes query execution across all orchestrators
+     */
+    protected executeQuery<T>(query: any, operationName?: string): Promise<T>;
+    /**
+     * Execute multiple operations in parallel with error handling
+     * Useful for batch operations across domains
+     */
+    protected executeParallel<T>(operations: (() => Promise<T>)[], operationName: string): Promise<T[]>;
+}
+/**
+ * Result pattern for orchestrator operations (optional - for complex flows)
+ * Provides type-safe error handling without exceptions
+ */
+export type OrchestrationResult<T> = {
+    success: true;
+    data: T;
+    operation?: string;
+} | {
+    success: false;
+    error: OrchestrationError;
+    operation?: string;
+};
+/**
+ * Helper function to create success result
+ */
+export declare function createSuccessResult<T>(data: T, operation?: string): OrchestrationResult<T>;
+/**
+ * Helper function to create error result
+ */
+export declare function createErrorResult<T>(error: OrchestrationError, operation?: string): OrchestrationResult<T>;
+/**
+ * Utility function to check if result is successful
+ * Provides type guard for TypeScript
+ */
+export declare function isSuccessResult<T>(result: OrchestrationResult<T>): result is {
+    success: true;
+    data: T;
+    operation?: string;
+};
+/**
+ * Utility function to extract data from result or throw error
+ * Useful for converting result pattern back to exception-based flow
+ */
+export declare function unwrapResult<T>(result: OrchestrationResult<T>): T;
+//# sourceMappingURL=base-orchestrator.d.ts.map

package/dist/esm/shared-patterns/orchestrators/base-orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-orchestrator.d.ts","sourceRoot":"","sources":["../../../../src/shared-patterns/orchestrators/base-orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAiB,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAiB,MAAM,yBAAyB,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAY,QAAQ,EAAU,MAAM,cAAc,CAAC;AACtE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,8BAAsB,gBAAgB;IAIlC,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,UAAU;IACzC,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ;IAJvC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAElC,SAAS,aACY,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,QAAQ,EACrC,aAAa,EAAE,MAAM;IAKvB;;;;OAIG;cACa,wBAAwB,CAAC,CAAC,EACxC,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC;IAwBb;;;OAGG;cACa,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IASnF;;;OAGG;cACa,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAS/E;;;OAGG;cACa,eAAe,CAAC,CAAC,EAC/B,UAAU,EAAE,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,EAChC,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,CAAC,EAAE,CAAC;CAOhB;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI;IACnC,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,CAAC,CAAC;IACR,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG;IACF,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,kBAAkB,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAE1F;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,kBAAkB,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAE1G;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAE3H;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,CAAC,CAKjE"}

package/dist/esm/shared-patterns/orchestrators/base-orchestrator.js

@@ -0,0 +1,116 @@
+import { Logger, HttpException } from '@nestjs/common';
+import { OrchestrationError, ErrorCategory } from '../../shared-lib/errors';
+/**
+ * BaseOrchestrator - Centralized Application Layer Orchestration Pattern
+ *
+ * @description Foundation for all domain orchestrators following PERS DDD principles:
+ * - Application layer orchestrates cross-domain operations via CQRS
+ * - Domain services contain pure business logic only
+ * - Microservice boundary preparation through clean abstractions
+ * - Consistent patterns across all domains (transaction, user, wallet, token, etc.)
+ * - Smart error handling that preserves business context
+ *
+ * @usage Extend this class in domain-specific orchestrators:
+ * ```typescript
+ * @Injectable()
+ * export class UserOrchestrator extends BaseOrchestrator {
+ *   constructor(commandBus: CommandBus, queryBus: QueryBus) {
+ *     super(commandBus, queryBus, UserOrchestrator.name);
+ *   }
+ * }
+ * ```
+ *
+ * @library @explorins/pers-shared
+ * @version 2.0.0
+ * @since August 2025
+ */
+export class BaseOrchestrator {
+    commandBus;
+    queryBus;
+    logger;
+    constructor(commandBus, queryBus, loggerContext) {
+        this.commandBus = commandBus;
+        this.queryBus = queryBus;
+        this.logger = new Logger(loggerContext);
+    }
+    /**
+     * Enhanced error handling that preserves business errors while wrapping technical errors
+     * Business errors (with category: DOMAIN_RULE) are passed through unchanged
+     * Technical errors are wrapped in OrchestrationError for consistent handling
+     */
+    async executeWithErrorHandling(operation, operationName, context) {
+        try {
+            this.logger.debug(`🚀 Starting ${operationName}`, context);
+            const result = await operation();
+            this.logger.debug(`✅ Completed ${operationName}`, context);
+            return result;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            // Preserve business errors - don't wrap them
+            if (error instanceof HttpException) {
+                const response = error.getResponse();
+                if (typeof response === 'object' && response?.category === ErrorCategory.DOMAIN_RULE) {
+                    this.logger.warn(`⚠️ Business logic error in ${operationName}: ${errorMessage}`, { ...context, error });
+                    throw error; // Pass through unchanged
+                }
+            }
+            // Wrap technical errors
+            this.logger.error(`❌ Failed ${operationName}: ${errorMessage}`, { ...context, error });
+            throw new OrchestrationError(operationName, error instanceof Error ? error : new Error(errorMessage));
+        }
+    }
+    /**
+     * Execute CQRS command with consistent error handling and logging
+     * Standardizes command execution across all orchestrators
+     */
+    async executeCommand(command, operationName) {
+        const operation = operationName || `Command: ${command.constructor.name}`;
+        return this.executeWithErrorHandling(() => this.commandBus.execute(command), operation, { commandType: command.constructor.name });
+    }
+    /**
+     * Execute CQRS query with consistent error handling and logging
+     * Standardizes query execution across all orchestrators
+     */
+    async executeQuery(query, operationName) {
+        const operation = operationName || `Query: ${query.constructor.name}`;
+        return this.executeWithErrorHandling(() => this.queryBus.execute(query), operation, { queryType: query.constructor.name });
+    }
+    /**
+     * Execute multiple operations in parallel with error handling
+     * Useful for batch operations across domains
+     */
+    async executeParallel(operations, operationName) {
+        return this.executeWithErrorHandling(() => Promise.all(operations.map(op => op())), `Parallel: ${operationName}`, { operationCount: operations.length });
+    }
+}
+/**
+ * Helper function to create success result
+ */
+export function createSuccessResult(data, operation) {
+    return { success: true, data, operation };
+}
+/**
+ * Helper function to create error result
+ */
+export function createErrorResult(error, operation) {
+    return { success: false, error, operation };
+}
+/**
+ * Utility function to check if result is successful
+ * Provides type guard for TypeScript
+ */
+export function isSuccessResult(result) {
+    return result.success === true;
+}
+/**
+ * Utility function to extract data from result or throw error
+ * Useful for converting result pattern back to exception-based flow
+ */
+export function unwrapResult(result) {
+    if (isSuccessResult(result)) {
+        return result.data;
+    }
+    throw result.error;
+}
+//# sourceMappingURL=base-orchestrator.js.map

package/dist/esm/shared-patterns/orchestrators/base-orchestrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-orchestrator.js","sourceRoot":"","sources":["../../../../src/shared-patterns/orchestrators/base-orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAgB,gBAAgB;IAIf;IACA;IAJF,MAAM,CAAS;IAElC,YACqB,UAAsB,EACtB,QAAkB,EACrC,aAAqB;QAFF,eAAU,GAAV,UAAU,CAAY;QACtB,aAAQ,GAAR,QAAQ,CAAU;QAGrC,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC,aAAa,CAAC,CAAC;IAC1C,CAAC;IAED;;;;OAIG;IACO,KAAK,CAAC,wBAAwB,CACtC,SAA2B,EAC3B,aAAqB,EACrB,OAA6B;QAE7B,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,aAAa,EAAE,EAAE,OAAO,CAAC,CAAC;YAC3D,MAAM,MAAM,GAAG,MAAM,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,aAAa,EAAE,EAAE,OAAO,CAAC,CAAC;YAC3D,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAE5E,6CAA6C;YAC7C,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;gBACnC,MAAM,QAAQ,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;gBACrC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAK,QAAgB,EAAE,QAAQ,KAAK,aAAa,CAAC,WAAW,EAAE,CAAC;oBAC9F,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,8BAA8B,aAAa,KAAK,YAAY,EAAE,EAAE,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;oBACxG,MAAM,KAAK,CAAC,CAAC,yBAAyB;gBACxC,CAAC;YACH,CAAC;YAED,wBAAwB;YACxB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,aAAa,KAAK,YAAY,EAAE,EAAE,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;YACvF,MAAM,IAAI,kBAAkB,CAAC,aAAa,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC;QACxG,CAAC;IACH,CAAC;IAED;;;OAGG;IACO,KAAK,CAAC,cAAc,CAAI,OAAY,EAAE,aAAsB;QACpE,MAAM,SAAS,GAAG,aAAa,IAAI,YAAY,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;QAC1E,OAAO,IAAI,CAAC,wBAAwB,CAClC,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,EACtC,SAAS,EACT,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,CAC1C,CAAC;IACJ,CAAC;IAED;;;OAGG;IACO,KAAK,CAAC,YAAY,CAAI,KAAU,EAAE,aAAsB;QAChE,MAAM,SAAS,GAAG,aAAa,IAAI,UAAU,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;QACtE,OAAO,IAAI,CAAC,wBAAwB,CAClC,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,EAClC,SAAS,EACT,EAAE,SAAS,EAAE,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,CACtC,CAAC;IACJ,CAAC;IAED;;;OAGG;IACO,KAAK,CAAC,eAAe,CAC7B,UAAgC,EAChC,aAAqB;QAErB,OAAO,IAAI,CAAC,wBAAwB,CAClC,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAC7C,aAAa,aAAa,EAAE,EAC5B,EAAE,cAAc,EAAE,UAAU,CAAC,MAAM,EAAE,CACtC,CAAC;IACJ,CAAC;CACF;AAgBD;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAI,IAAO,EAAE,SAAkB;IAChE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAC5C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAI,KAAyB,EAAE,SAAkB;IAChF,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAI,MAA8B;IAC/D,OAAO,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAI,MAA8B;IAC5D,IAAI,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5B,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;IACD,MAAM,MAAM,CAAC,KAAK,CAAC;AACrB,CAAC"}

package/dist/esm/shared-patterns/orchestrators/base-workflow.d.ts

@@ -0,0 +1,50 @@
+import { Logger } from '@nestjs/common';
+/**
+ * BaseWorkflow - Business Process Coordination Pattern
+ *
+ * @description Foundation for business workflow coordination in PERS domains.
+ * Distinct from BaseOrchestrator which handles technical CQRS coordination.
+ *
+ * ARCHITECTURAL DISTINCTION:
+ * - BaseOrchestrator: Technical coordination (CQRS, queries, commands)
+ * - BaseWorkflow: Business process coordination (orchestrator choreography)
+ *
+ * @usage Extend this class for domain-specific business workflows:
+ * ```typescript
+ * @Injectable()
+ * export class ServerTransactionWorkflow extends BaseWorkflow {
+ *   constructor(
+ *     private readonly walletOrchestrator: WalletResolutionOrchestrator,
+ *     private readonly tokenOrchestrator: TokenResolutionOrchestrator
+ *   ) {
+ *     super(ServerTransactionWorkflow.name);
+ *   }
+ *
+ *   async executeTransactionFlow(dto: TransactionRequestDTO): Promise<TransactionDTO> {
+ *     return this.executeWorkflowStep(async () => {
+ *       const token = await this.tokenOrchestrator.resolveToken(dto.token);
+ *       const addresses = await this.walletOrchestrator.resolveAddresses(dto, token.chainId);
+ *       return this.createTransaction(token, addresses, dto);
+ *     }, 'Transaction Creation Flow');
+ *   }
+ * }
+ * ```
+ *
+ * @library @explorins/pers-shared-patterns
+ * @version 1.0.0
+ * @since September 2025
+ */
+export declare abstract class BaseWorkflow {
+    protected readonly logger: Logger;
+    protected constructor(loggerContext: string);
+    /**
+     * Execute a workflow step with standardized logging and error handling
+     *
+     * @param step - Function to execute as workflow step
+     * @param stepName - Human-readable name for the step
+     * @param context - Optional context for logging
+     * @returns Promise resolving to step result
+     */
+    protected executeWorkflowStep<T>(step: () => Promise<T>, stepName: string, context?: Record<string, any>): Promise<T>;
+}
+//# sourceMappingURL=base-workflow.d.ts.map

package/dist/esm/shared-patterns/orchestrators/base-workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-workflow.d.ts","sourceRoot":"","sources":["../../../../src/shared-patterns/orchestrators/base-workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,8BAAsB,YAAY;IAChC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAElC,SAAS,aAAa,aAAa,EAAE,MAAM;IAI3C;;;;;;;OAOG;cACa,mBAAmB,CAAC,CAAC,EACnC,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC;CAYd"}

package/dist/esm/shared-patterns/orchestrators/base-workflow.js

@@ -0,0 +1,64 @@
+import { Logger } from '@nestjs/common';
+/**
+ * BaseWorkflow - Business Process Coordination Pattern
+ *
+ * @description Foundation for business workflow coordination in PERS domains.
+ * Distinct from BaseOrchestrator which handles technical CQRS coordination.
+ *
+ * ARCHITECTURAL DISTINCTION:
+ * - BaseOrchestrator: Technical coordination (CQRS, queries, commands)
+ * - BaseWorkflow: Business process coordination (orchestrator choreography)
+ *
+ * @usage Extend this class for domain-specific business workflows:
+ * ```typescript
+ * @Injectable()
+ * export class ServerTransactionWorkflow extends BaseWorkflow {
+ *   constructor(
+ *     private readonly walletOrchestrator: WalletResolutionOrchestrator,
+ *     private readonly tokenOrchestrator: TokenResolutionOrchestrator
+ *   ) {
+ *     super(ServerTransactionWorkflow.name);
+ *   }
+ *
+ *   async executeTransactionFlow(dto: TransactionRequestDTO): Promise<TransactionDTO> {
+ *     return this.executeWorkflowStep(async () => {
+ *       const token = await this.tokenOrchestrator.resolveToken(dto.token);
+ *       const addresses = await this.walletOrchestrator.resolveAddresses(dto, token.chainId);
+ *       return this.createTransaction(token, addresses, dto);
+ *     }, 'Transaction Creation Flow');
+ *   }
+ * }
+ * ```
+ *
+ * @library @explorins/pers-shared-patterns
+ * @version 1.0.0
+ * @since September 2025
+ */
+export class BaseWorkflow {
+    logger;
+    constructor(loggerContext) {
+        this.logger = new Logger(loggerContext);
+    }
+    /**
+     * Execute a workflow step with standardized logging and error handling
+     *
+     * @param step - Function to execute as workflow step
+     * @param stepName - Human-readable name for the step
+     * @param context - Optional context for logging
+     * @returns Promise resolving to step result
+     */
+    async executeWorkflowStep(step, stepName, context) {
+        try {
+            this.logger.debug(`🎯 Starting workflow step: ${stepName}`, context);
+            const result = await step();
+            this.logger.debug(`✅ Completed workflow step: ${stepName}`, context);
+            return result;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger.error(`❌ Failed workflow step: ${stepName}: ${errorMessage}`, { ...context, error });
+            throw error; // Let business errors flow through unchanged
+        }
+    }
+}
+//# sourceMappingURL=base-workflow.js.map

package/dist/esm/shared-patterns/orchestrators/base-workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-workflow.js","sourceRoot":"","sources":["../../../../src/shared-patterns/orchestrators/base-workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,OAAgB,YAAY;IACb,MAAM,CAAS;IAElC,YAAsB,aAAqB;QACzC,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC,aAAa,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;;;OAOG;IACO,KAAK,CAAC,mBAAmB,CACjC,IAAsB,EACtB,QAAgB,EAChB,OAA6B;QAE7B,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,8BAA8B,QAAQ,EAAE,EAAE,OAAO,CAAC,CAAC;YACrE,MAAM,MAAM,GAAG,MAAM,IAAI,EAAE,CAAC;YAC5B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,8BAA8B,QAAQ,EAAE,EAAE,OAAO,CAAC,CAAC;YACrE,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC5E,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,2BAA2B,QAAQ,KAAK,YAAY,EAAE,EAAE,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;YACjG,MAAM,KAAK,CAAC,CAAC,6CAA6C;QAC5D,CAAC;IACH,CAAC;CACF"}

package/dist/esm/shared-patterns/orchestrators/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * PERS Orchestrators - Application Layer Patterns
+ *
+ * @description Centralized orchestration utilities for DDD-compliant applications
+ * - BaseOrchestrator: Foundation for all domain orchestrators (technical coordination)
+ * - BaseWorkflow: Foundation for business process workflows (business coordination)
+ * - OrchestrationError: Standard error handling
+ * - OrchestrationResult: Type-safe result pattern
+ * - Utility functions for error handling and result processing
+ *
+ * @usage Import directly from shared library:
+ * ```typescript
+ * import { BaseOrchestrator, BaseWorkflow, OrchestrationError } from '@explorins/pers-shared-patterns';
+ * ```
+ *
+ * ARCHITECTURAL DISTINCTION:
+ * - BaseOrchestrator: Technical coordination (CQRS, queries, commands)
+ * - BaseWorkflow: Business process coordination (orchestrator choreography)
+ *
+ * @library @explorins/pers-shared-patterns
+ * @version 2.0.0
+ * @since August 2025
+ */
+export * from './base-orchestrator';
+export * from './base-workflow';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/shared-patterns/orchestrators/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/shared-patterns/orchestrators/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC"}

package/dist/esm/shared-patterns/orchestrators/index.js

@@ -0,0 +1,30 @@
+/**
+ * PERS Orchestrators - Application Layer Patterns
+ *
+ * @description Centralized orchestration utilities for DDD-compliant applications
+ * - BaseOrchestrator: Foundation for all domain orchestrators (technical coordination)
+ * - BaseWorkflow: Foundation for business process workflows (business coordination)
+ * - OrchestrationError: Standard error handling
+ * - OrchestrationResult: Type-safe result pattern
+ * - Utility functions for error handling and result processing
+ *
+ * @usage Import directly from shared library:
+ * ```typescript
+ * import { BaseOrchestrator, BaseWorkflow, OrchestrationError } from '@explorins/pers-shared-patterns';
+ * ```
+ *
+ * ARCHITECTURAL DISTINCTION:
+ * - BaseOrchestrator: Technical coordination (CQRS, queries, commands)
+ * - BaseWorkflow: Business process coordination (orchestrator choreography)
+ *
+ * @library @explorins/pers-shared-patterns
+ * @version 2.0.0
+ * @since August 2025
+ */
+export * from './base-orchestrator';
+export * from './base-workflow';
+// Future orchestration utilities can be added here:
+// export * from './validation-orchestrator';
+// export * from './audit-orchestrator';
+// export * from './notification-orchestrator';
+//# sourceMappingURL=index.js.map

package/dist/esm/shared-patterns/orchestrators/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/shared-patterns/orchestrators/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAEhC,oDAAoD;AACpD,6CAA6C;AAC7C,wCAAwC;AACxC,+CAA+C"}

package/dist/esm/shared-patterns/utils/error-message.utils.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Standardized error message generators for consistent error handling across applications
+ *
+ * This utility provides reusable message generation functions for common error scenarios:
+ * - Authentication context errors
+ * - Resource not found errors
+ * - Access denied errors
+ * - Validation errors
+ * - Business rule violations
+ * - Database operation errors
+ *
+ * @example
+ * import { generateAuthRequiredMessage, generateNotFoundMessage } from '@explorins/pers-shared-patterns';
+ *
+ * const message = generateAuthRequiredMessage(['user', 'admin']);
+ * // "User or admin authentication required"
+ *
+ * const notFound = generateNotFoundMessage('transaction', 'tx-123');
+ * // "Transaction with identifier 'tx-123' not found"
+ */
+/**
+ * Authentication context types supported across applications
+ */
+export type AuthenticationContext = 'user' | 'business' | 'admin' | 'tenant';
+/**
+ * Resource types commonly used in error messages
+ */
+export type ResourceType = 'user' | 'business' | 'admin' | 'campaign' | 'transaction' | 'redemption' | 'wallet' | 'contract' | 'tenant' | 'token' | 'signing-account';
+/**
+ * Database operation types for error reporting
+ */
+export type DatabaseOperation = 'save' | 'find' | 'delete' | 'update' | 'query';
+/**
+ * Generate standardized authentication required error message
+ * @param requiredContexts - Array of required authentication contexts
+ * @param action - Optional action description (e.g., 'for redemption processing')
+ * @returns Standardized error message
+ */
+export declare function generateAuthRequiredMessage(requiredContexts: AuthenticationContext[], action?: string): string;
+/**
+ * Generate standardized "not found" error message
+ * @param resourceType - Type of resource that was not found
+ * @param identifier - Optional identifier (ID, email, etc.)
+ * @returns Standardized not found message
+ */
+export declare function generateNotFoundMessage(resourceType: ResourceType, identifier?: string): string;
+/**
+ * Generate standardized "access denied" error message
+ * @param action - The action being attempted
+ * @param resource - Optional resource context
+ * @returns Standardized access denied message
+ */
+export declare function generateAccessDeniedMessage(action: string, resource?: string): string;
+/**
+ * Generate standardized validation error message
+ * @param field - Field that failed validation
+ * @param constraint - The validation constraint
+ * @returns Standardized validation message
+ */
+export declare function generateValidationMessage(field: string, constraint: string): string;
+/**
+ * Generate standardized business rule violation message
+ * @param rule - The business rule that was violated
+ * @param context - Optional context information
+ * @returns Standardized business rule message
+ */
+export declare function generateBusinessRuleMessage(rule: string, context?: string): string;
+/**
+ * Generate standardized database error message
+ * @param operation - The database operation that failed
+ * @param resourceType - Type of resource involved
+ * @param details - Optional error details
+ * @returns Standardized database error message
+ */
+export declare function generateDatabaseErrorMessage(operation: DatabaseOperation, resourceType: ResourceType, details?: string): string;
+/**
+ * Generate standardized input validation error message
+ * @param parameter - The parameter that failed validation
+ * @param requirement - What the parameter should meet
+ * @returns Standardized input validation message
+ */
+export declare function generateInputValidationMessage(parameter: string, requirement: string): string;
+/**
+ * Generate standardized operation error message
+ * @param operation - The operation that was attempted
+ * @param reason - Why it failed
+ * @returns Standardized operation error message
+ */
+export declare function generateOperationErrorMessage(operation: string, reason: string): string;
+/**
+ * Common error message constants for quick access
+ */
+export declare const ERROR_MESSAGE_TEMPLATES: {
+    readonly AUTH: {
+        readonly USER_ONLY: () => string;
+        readonly BUSINESS_ONLY: () => string;
+        readonly ADMIN_ONLY: () => string;
+        readonly USER_OR_BUSINESS: () => string;
+        readonly USER_OR_ADMIN: () => string;
+        readonly BUSINESS_OR_ADMIN: () => string;
+        readonly USER_BUSINESS_OR_ADMIN: () => string;
+        readonly ANY_AUTH: () => string;
+        readonly FOR_REDEMPTION: () => string;
+        readonly FOR_TRANSACTION: () => string;
+        readonly FOR_ADMIN_ACTION: () => string;
+    };
+    readonly NOT_FOUND: {
+        readonly USER: (id?: string) => string;
+        readonly BUSINESS: (id?: string) => string;
+        readonly ADMIN: (id?: string) => string;
+        readonly CAMPAIGN: (id?: string) => string;
+        readonly TRANSACTION: (id?: string) => string;
+        readonly REDEMPTION: (id?: string) => string;
+        readonly WALLET: (id?: string) => string;
+        readonly CONTRACT: (address?: string) => string;
+        readonly TENANT: (id?: string) => string;
+        readonly TOKEN: (id?: string) => string;
+        readonly SIGNING_ACCOUNT: (id?: string) => string;
+    };
+    readonly ACCESS_DENIED: {
+        readonly VIEW_RESOURCE: (resource: string) => string;
+        readonly MODIFY_RESOURCE: (resource: string) => string;
+        readonly DELETE_RESOURCE: (resource: string) => string;
+        readonly EXECUTE_ACTION: (action: string) => string;
+    };
+    readonly VALIDATION: {
+        readonly REQUIRED_FIELD: (field: string) => string;
+        readonly INVALID_FORMAT: (field: string, format: string) => string;
+        readonly OUT_OF_RANGE: (field: string, min?: number, max?: number) => string;
+    };
+    readonly BUSINESS_RULES: {
+        readonly REDEMPTION_LIMIT_REACHED: () => string;
+        readonly INSUFFICIENT_BALANCE: (required?: string) => string;
+        readonly GEOGRAPHIC_RESTRICTION: (location: string) => string;
+        readonly STATUS_NOT_ALLOWED: (status: string, action: string) => string;
+    };
+    readonly DATABASE: {
+        readonly SAVE_FAILED: (resourceType: ResourceType, details?: string) => string;
+        readonly FIND_FAILED: (resourceType: ResourceType, details?: string) => string;
+        readonly DELETE_FAILED: (resourceType: ResourceType, details?: string) => string;
+        readonly UPDATE_FAILED: (resourceType: ResourceType, details?: string) => string;
+        readonly QUERY_FAILED: (resourceType: ResourceType, details?: string) => string;
+    };
+    readonly INPUT_VALIDATION: {
+        readonly REQUIRED: (param: string) => string;
+        readonly EMPTY: (param: string) => string;
+        readonly INVALID_FORMAT: (param: string, format: string) => string;
+        readonly OUT_OF_RANGE: (param: string, range: string) => string;
+        readonly INVALID_COMBINATION: (params: string) => string;
+        readonly MISSING_FIELD: (param: string) => string;
+    };
+    readonly OPERATIONS: {
+        readonly TRANSACTION_FAILED: (reason: string) => string;
+        readonly SIGNATURE_FAILED: (reason: string) => string;
+        readonly WALLET_OPERATION_FAILED: (reason: string) => string;
+        readonly CONTRACT_INTERACTION_FAILED: (reason: string) => string;
+        readonly DATA_PROCESSING_FAILED: (reason: string) => string;
+    };
+};
+/**
+ * Database operation error helper function
+ * Creates appropriate errors for database operations using the centralized ErrorFactory
+ */
+export declare function DatabaseOperationError(operation: DatabaseOperation, resourceType: ResourceType, details?: string): void;
+/**
+ * Input validation error helper function
+ * Creates appropriate validation errors using the centralized ErrorFactory
+ */
+export declare function InputValidationError(field: string, requirement: string, providedValue?: any): void;
+/**
+ * Operation failure error helper function
+ * Creates appropriate operation errors using the centralized ErrorFactory
+ */
+export declare function OperationFailureError(operation: string, reason: string, retryable?: boolean): void;
+//# sourceMappingURL=error-message.utils.d.ts.map

package/dist/esm/shared-patterns/utils/error-message.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-message.utils.d.ts","sourceRoot":"","sources":["../../../../src/shared-patterns/utils/error-message.utils.ts"],"names":[],"mappings":"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"}