@wildo-ai/saas-backend-lib 1.0.1

package/dist/esm/errors/services/__tests__/mock-error-builder.service.d.ts

@@ -0,0 +1,339 @@
+/**
+ * Vitest-oriented mock error builder for integration tests (`vi.fn` on methods).
+ *
+ * **Naming**: `mock-*.service.ts` — canonical mock module, not a test suite.
+ * Plain `.ts` keeps it barrel-compilable, and Vitest also excludes these files
+ * explicitly as a defensive guard.
+ */
+import 'reflect-metadata';
+import { ErrorType, ErrorCustomMessageReference, ErrorSeverity, ErrorActionBackend } from '@wildo-ai/saas-models';
+type MockErrorBuilderOptions = {
+    customMessageReference?: ErrorCustomMessageReference;
+    context?: Record<string, unknown>;
+    stack?: string;
+};
+type MockBuiltErrorRecord = {
+    type: ErrorType;
+    customMessageReference?: ErrorCustomMessageReference;
+    context?: Record<string, unknown>;
+    executionContext?: unknown;
+};
+export declare class MockErrorBuilderService {
+    /**
+     * Matches {@link ErrorBuilderBackendService.buildError} (errorType, executionContext?, options?).
+     */
+    buildError: import("vitest").Mock<[errorType: ErrorType, _executionContext?: unknown, options?: {
+        customMessageReference?: ErrorCustomMessageReference;
+        context?: Record<string, unknown>;
+        stack?: string;
+    }], {
+        type: ErrorType;
+        severity: ErrorSeverity;
+        timestamp: Date;
+        backendActions: ErrorActionBackend[];
+        customMessageReference: ErrorCustomMessageReference;
+        statusCode: number;
+        operationPathKey?: string;
+        context?: Record<string, any>;
+        ipAddress?: string;
+        errorHandlingStrategy?: import("@wildo-ai/saas-models").ErrorHandling_Strategy;
+        retryPolicy?: import("@wildo-ai/saas-models").RetryPolicy_BackoffType;
+        maxRetries?: number;
+        initialDelay?: number;
+        baseDelay?: number;
+        retryCount?: number;
+        lastRetryTime?: Date;
+        stack?: string;
+        requestUUID?: string;
+        initiatorIds?: {
+            organizationId?: string;
+            userId?: string;
+            applicationId?: string;
+            organizationApiKeyId?: string;
+            applicationApiKeyId?: string;
+            consumableTokenId?: string;
+            webhookProviderId?: string;
+            anonymousUserId?: string;
+        };
+        executionType?: import("@wildo-ai/saas-models").ExecutionContext_ExecutionType;
+        userGuidance?: {
+            guidanceKey?: string;
+            explanation?: string;
+            resolution?: string;
+            completedSteps?: string[];
+            nextAction?: {
+                label: string;
+                ref: string;
+                type: import("@wildo-ai/saas-models").NotificationNextStepType;
+            };
+            retryAfterSeconds?: number;
+            missingConfiguration?: string[];
+        };
+    }>;
+    buildValidationError: import("vitest").Mock<[message: string, details?: any], {
+        type: ErrorType;
+        severity: ErrorSeverity;
+        timestamp: Date;
+        backendActions: ErrorActionBackend[];
+        customMessageReference: ErrorCustomMessageReference;
+        statusCode: number;
+        operationPathKey?: string;
+        context?: Record<string, any>;
+        ipAddress?: string;
+        errorHandlingStrategy?: import("@wildo-ai/saas-models").ErrorHandling_Strategy;
+        retryPolicy?: import("@wildo-ai/saas-models").RetryPolicy_BackoffType;
+        maxRetries?: number;
+        initialDelay?: number;
+        baseDelay?: number;
+        retryCount?: number;
+        lastRetryTime?: Date;
+        stack?: string;
+        requestUUID?: string;
+        initiatorIds?: {
+            organizationId?: string;
+            userId?: string;
+            applicationId?: string;
+            organizationApiKeyId?: string;
+            applicationApiKeyId?: string;
+            consumableTokenId?: string;
+            webhookProviderId?: string;
+            anonymousUserId?: string;
+        };
+        executionType?: import("@wildo-ai/saas-models").ExecutionContext_ExecutionType;
+        userGuidance?: {
+            guidanceKey?: string;
+            explanation?: string;
+            resolution?: string;
+            completedSteps?: string[];
+            nextAction?: {
+                label: string;
+                ref: string;
+                type: import("@wildo-ai/saas-models").NotificationNextStepType;
+            };
+            retryAfterSeconds?: number;
+            missingConfiguration?: string[];
+        };
+    }>;
+    buildNotFoundError: import("vitest").Mock<[resourceType: string, id: string], {
+        type: ErrorType;
+        severity: ErrorSeverity;
+        timestamp: Date;
+        backendActions: ErrorActionBackend[];
+        customMessageReference: ErrorCustomMessageReference;
+        statusCode: number;
+        operationPathKey?: string;
+        context?: Record<string, any>;
+        ipAddress?: string;
+        errorHandlingStrategy?: import("@wildo-ai/saas-models").ErrorHandling_Strategy;
+        retryPolicy?: import("@wildo-ai/saas-models").RetryPolicy_BackoffType;
+        maxRetries?: number;
+        initialDelay?: number;
+        baseDelay?: number;
+        retryCount?: number;
+        lastRetryTime?: Date;
+        stack?: string;
+        requestUUID?: string;
+        initiatorIds?: {
+            organizationId?: string;
+            userId?: string;
+            applicationId?: string;
+            organizationApiKeyId?: string;
+            applicationApiKeyId?: string;
+            consumableTokenId?: string;
+            webhookProviderId?: string;
+            anonymousUserId?: string;
+        };
+        executionType?: import("@wildo-ai/saas-models").ExecutionContext_ExecutionType;
+        userGuidance?: {
+            guidanceKey?: string;
+            explanation?: string;
+            resolution?: string;
+            completedSteps?: string[];
+            nextAction?: {
+                label: string;
+                ref: string;
+                type: import("@wildo-ai/saas-models").NotificationNextStepType;
+            };
+            retryAfterSeconds?: number;
+            missingConfiguration?: string[];
+        };
+    }>;
+    buildConfigurationError: import("vitest").Mock<[message: string, details?: any], {
+        type: ErrorType;
+        severity: ErrorSeverity;
+        timestamp: Date;
+        backendActions: ErrorActionBackend[];
+        customMessageReference: ErrorCustomMessageReference;
+        statusCode: number;
+        operationPathKey?: string;
+        context?: Record<string, any>;
+        ipAddress?: string;
+        errorHandlingStrategy?: import("@wildo-ai/saas-models").ErrorHandling_Strategy;
+        retryPolicy?: import("@wildo-ai/saas-models").RetryPolicy_BackoffType;
+        maxRetries?: number;
+        initialDelay?: number;
+        baseDelay?: number;
+        retryCount?: number;
+        lastRetryTime?: Date;
+        stack?: string;
+        requestUUID?: string;
+        initiatorIds?: {
+            organizationId?: string;
+            userId?: string;
+            applicationId?: string;
+            organizationApiKeyId?: string;
+            applicationApiKeyId?: string;
+            consumableTokenId?: string;
+            webhookProviderId?: string;
+            anonymousUserId?: string;
+        };
+        executionType?: import("@wildo-ai/saas-models").ExecutionContext_ExecutionType;
+        userGuidance?: {
+            guidanceKey?: string;
+            explanation?: string;
+            resolution?: string;
+            completedSteps?: string[];
+            nextAction?: {
+                label: string;
+                ref: string;
+                type: import("@wildo-ai/saas-models").NotificationNextStepType;
+            };
+            retryAfterSeconds?: number;
+            missingConfiguration?: string[];
+        };
+    }>;
+    buildInternalError: import("vitest").Mock<[message: string, details?: any], {
+        type: ErrorType;
+        severity: ErrorSeverity;
+        timestamp: Date;
+        backendActions: ErrorActionBackend[];
+        customMessageReference: ErrorCustomMessageReference;
+        statusCode: number;
+        operationPathKey?: string;
+        context?: Record<string, any>;
+        ipAddress?: string;
+        errorHandlingStrategy?: import("@wildo-ai/saas-models").ErrorHandling_Strategy;
+        retryPolicy?: import("@wildo-ai/saas-models").RetryPolicy_BackoffType;
+        maxRetries?: number;
+        initialDelay?: number;
+        baseDelay?: number;
+        retryCount?: number;
+        lastRetryTime?: Date;
+        stack?: string;
+        requestUUID?: string;
+        initiatorIds?: {
+            organizationId?: string;
+            userId?: string;
+            applicationId?: string;
+            organizationApiKeyId?: string;
+            applicationApiKeyId?: string;
+            consumableTokenId?: string;
+            webhookProviderId?: string;
+            anonymousUserId?: string;
+        };
+        executionType?: import("@wildo-ai/saas-models").ExecutionContext_ExecutionType;
+        userGuidance?: {
+            guidanceKey?: string;
+            explanation?: string;
+            resolution?: string;
+            completedSteps?: string[];
+            nextAction?: {
+                label: string;
+                ref: string;
+                type: import("@wildo-ai/saas-models").NotificationNextStepType;
+            };
+            retryAfterSeconds?: number;
+            missingConfiguration?: string[];
+        };
+    }>;
+    buildFromReference: import("vitest").Mock<[ref: ErrorCustomMessageReference, context?: Record<string, unknown>, httpStatus?: number], {
+        type: ErrorType;
+        severity: ErrorSeverity;
+        timestamp: Date;
+        backendActions: ErrorActionBackend[];
+        customMessageReference: ErrorCustomMessageReference;
+        statusCode: number;
+        operationPathKey?: string;
+        context?: Record<string, any>;
+        ipAddress?: string;
+        errorHandlingStrategy?: import("@wildo-ai/saas-models").ErrorHandling_Strategy;
+        retryPolicy?: import("@wildo-ai/saas-models").RetryPolicy_BackoffType;
+        maxRetries?: number;
+        initialDelay?: number;
+        baseDelay?: number;
+        retryCount?: number;
+        lastRetryTime?: Date;
+        stack?: string;
+        requestUUID?: string;
+        initiatorIds?: {
+            organizationId?: string;
+            userId?: string;
+            applicationId?: string;
+            organizationApiKeyId?: string;
+            applicationApiKeyId?: string;
+            consumableTokenId?: string;
+            webhookProviderId?: string;
+            anonymousUserId?: string;
+        };
+        executionType?: import("@wildo-ai/saas-models").ExecutionContext_ExecutionType;
+        userGuidance?: {
+            guidanceKey?: string;
+            explanation?: string;
+            resolution?: string;
+            completedSteps?: string[];
+            nextAction?: {
+                label: string;
+                ref: string;
+                type: import("@wildo-ai/saas-models").NotificationNextStepType;
+            };
+            retryAfterSeconds?: number;
+            missingConfiguration?: string[];
+        };
+    }>;
+    reset(): void;
+}
+/**
+ * Shared helper for tests where production code does `throw this.errorBuilder.buildError(...)`.
+ * The helper returns a real `Error` instance with useful attached metadata while leaving the
+ * actual throw site in the service under test.
+ */
+export declare class MockReturningErrorBuilderService {
+    private lastError;
+    protected buildMockError(errorType: ErrorType, executionContext?: unknown, options?: MockErrorBuilderOptions, fallbackMessage?: string): Error;
+    buildError: import("vitest").Mock<[errorType: ErrorType, executionContext?: unknown, options?: MockErrorBuilderOptions], Error>;
+    getLastError(): MockBuiltErrorRecord | null;
+    reset(): void;
+}
+type MockErrorBuilderPayload = Record<string, unknown>;
+/**
+ * Shared helper for tests that expect a real `Error` instance and also assert on
+ * payload fields copied directly onto the thrown error (`error.context`,
+ * `error.customMessageReference`, etc.).
+ */
+export declare class MockPayloadAssigningErrorBuilderService {
+    private readonly options;
+    constructor(options?: {
+        preferPayloadContextMessage?: boolean;
+    });
+    buildError: import("vitest").Mock<[errorType: ErrorType, _executionContext?: unknown, payload?: MockErrorBuilderPayload], Error>;
+    reset(): void;
+}
+/**
+ * Shared helper for tests that expect the builder to return a real `Error` while
+ * wrapping the original builder payload under `error.payload` and exposing the
+ * `error.type` discriminator separately.
+ */
+export declare class MockPayloadWrappingErrorBuilderService {
+    buildError: import("vitest").Mock<[errorType: ErrorType, _executionContext?: unknown, payload?: MockErrorBuilderPayload], Error>;
+    reset(): void;
+}
+/**
+ * Shared helper for tests where the builder itself is expected to throw immediately.
+ * This keeps validation-style tests concise while preserving last-error inspection.
+ */
+export declare class MockThrowingErrorBuilderService extends MockReturningErrorBuilderService {
+    buildError: import("vitest").Mock<[errorType: ErrorType, executionContext?: unknown, options?: MockErrorBuilderOptions], never>;
+    reset(): void;
+}
+export {};
+//# sourceMappingURL=mock-error-builder.service.d.ts.map

package/dist/esm/errors/services/__tests__/mock-error-builder.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-error-builder.service.d.ts","sourceRoot":"","sources":["../../../../../src/errors/services/__tests__/mock-error-builder.service.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,kBAAkB,CAAC;AAE1B,OAAO,EAAE,SAAS,EAAsB,2BAA2B,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAGtI,KAAK,uBAAuB,GAAG;IAC7B,sBAAsB,CAAC,EAAE,2BAA2B,CAAC;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,KAAK,oBAAoB,GAAG;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,sBAAsB,CAAC,EAAE,2BAA2B,CAAC;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAgCF,qBACa,uBAAuB;IAClC;;OAEG;IACH,UAAU;iCAKqB,2BAA2B;kBAC1C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBACzB,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAYlB;IAEF,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAQhB;IAEJ,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAQd;IAEJ,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAQnB;IAEJ,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAQd;IAEJ,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAYd;IAEJ,KAAK;CAQN;AAED;;;;GAIG;AACH,qBACa,gCAAgC;IAC3C,OAAO,CAAC,SAAS,CAAqC;IAEtD,SAAS,CAAC,cAAc,CACtB,SAAS,EAAE,SAAS,EACpB,gBAAgB,CAAC,EAAE,OAAO,EAC1B,OAAO,CAAC,EAAE,uBAAuB,EACjC,eAAe,CAAC,EAAE,MAAM,GACvB,KAAK;IAMR,UAAU,sHAMR;IAEF,YAAY,IAAI,oBAAoB,GAAG,IAAI;IAI3C,KAAK;CAIN;AAED,KAAK,uBAAuB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAiBvD;;;;GAIG;AACH,qBACa,uCAAuC;IAEhD,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,GAAE;QACxB,2BAA2B,CAAC,EAAE,OAAO,CAAC;KAClC;IAGR,UAAU,uHAoBR;IAEF,KAAK,IAAI,IAAI;CAGd;AAED;;;;GAIG;AACH,qBACa,sCAAsC;IACjD,UAAU,uHAaR;IAEF,KAAK,IAAI,IAAI;CAGd;AAED;;;GAGG;AACH,qBACa,+BAAgC,SAAQ,gCAAgC;IAC1E,UAAU,sHAQjB;IAEO,KAAK;CAIf"}

package/dist/esm/errors/services/__tests__/mock-error-builder.service.js

@@ -0,0 +1,209 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+/**
+ * Vitest-oriented mock error builder for integration tests (`vi.fn` on methods).
+ *
+ * **Naming**: `mock-*.service.ts` — canonical mock module, not a test suite.
+ * Plain `.ts` keeps it barrel-compilable, and Vitest also excludes these files
+ * explicitly as a defensive guard.
+ */
+import 'reflect-metadata';
+import { injectable } from 'inversify';
+import { ErrorType, ErrorCustomMessageReference, ErrorSeverity, ErrorActionBackend } from '@wildo-ai/saas-models';
+import { vi } from 'vitest';
+function buildMockBuiltErrorRecord(errorType, executionContext, options) {
+    return {
+        type: errorType,
+        customMessageReference: options?.customMessageReference,
+        context: options?.context,
+        executionContext,
+    };
+}
+function buildMockErrorInstance(errorType, record, options, fallbackMessage) {
+    const message = typeof options?.context?.message === 'string'
+        ? options.context.message
+        : fallbackMessage ?? String(errorType);
+    const error = new Error(message);
+    error.wildoError = record;
+    error.errorType = errorType;
+    error.details = options;
+    return error;
+}
+let MockErrorBuilderService = class MockErrorBuilderService {
+    /**
+     * Matches {@link ErrorBuilderBackendService.buildError} (errorType, executionContext?, options?).
+     */
+    buildError = vi.fn((errorType, _executionContext, options) => ({
+        type: errorType,
+        severity: ErrorSeverity.HIGH,
+        timestamp: new Date(),
+        backendActions: [ErrorActionBackend.LOG],
+        customMessageReference: options?.customMessageReference ?? ErrorCustomMessageReference.DEFAULT,
+        statusCode: 500,
+        context: options?.context,
+    }));
+    buildValidationError = vi.fn((message, details) => ({
+        type: ErrorType.VALIDATION,
+        severity: ErrorSeverity.LOW,
+        timestamp: new Date(),
+        backendActions: [ErrorActionBackend.LOG],
+        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+        statusCode: 400,
+        context: details,
+    }));
+    buildNotFoundError = vi.fn((resourceType, id) => ({
+        type: ErrorType.NOT_FOUND,
+        severity: ErrorSeverity.LOW,
+        timestamp: new Date(),
+        backendActions: [ErrorActionBackend.LOG],
+        customMessageReference: ErrorCustomMessageReference.NOT_FOUND,
+        statusCode: 404,
+        context: { resourceType, id },
+    }));
+    buildConfigurationError = vi.fn((message, details) => ({
+        type: ErrorType.CONFIGURATION,
+        severity: ErrorSeverity.HIGH,
+        timestamp: new Date(),
+        backendActions: [ErrorActionBackend.LOG, ErrorActionBackend.RECORD_METRICS, ErrorActionBackend.ALERT],
+        customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+        statusCode: 500,
+        context: details,
+    }));
+    buildInternalError = vi.fn((message, details) => ({
+        type: ErrorType.INTERNAL,
+        severity: ErrorSeverity.CRITICAL,
+        timestamp: new Date(),
+        backendActions: [ErrorActionBackend.LOG, ErrorActionBackend.RECORD_METRICS, ErrorActionBackend.ALERT, ErrorActionBackend.TRACE],
+        customMessageReference: ErrorCustomMessageReference.INTERNAL,
+        statusCode: 500,
+        context: details,
+    }));
+    buildFromReference = vi.fn((ref, context, httpStatus = 500) => ({
+        type: ErrorType.INTERNAL,
+        severity: ErrorSeverity.HIGH,
+        timestamp: new Date(),
+        backendActions: [ErrorActionBackend.LOG],
+        customMessageReference: ref,
+        statusCode: httpStatus,
+        context,
+    }));
+    reset() {
+        this.buildError.mockClear();
+        this.buildValidationError.mockClear();
+        this.buildNotFoundError.mockClear();
+        this.buildConfigurationError.mockClear();
+        this.buildInternalError.mockClear();
+        this.buildFromReference.mockClear();
+    }
+};
+MockErrorBuilderService = __decorate([
+    injectable()
+], MockErrorBuilderService);
+export { MockErrorBuilderService };
+/**
+ * Shared helper for tests where production code does `throw this.errorBuilder.buildError(...)`.
+ * The helper returns a real `Error` instance with useful attached metadata while leaving the
+ * actual throw site in the service under test.
+ */
+let MockReturningErrorBuilderService = class MockReturningErrorBuilderService {
+    lastError = null;
+    buildMockError(errorType, executionContext, options, fallbackMessage) {
+        const record = buildMockBuiltErrorRecord(errorType, executionContext, options);
+        this.lastError = record;
+        return buildMockErrorInstance(errorType, record, options, fallbackMessage);
+    }
+    buildError = vi.fn((errorType, executionContext, options) => this.buildMockError(errorType, executionContext, options, String(errorType)));
+    getLastError() {
+        return this.lastError;
+    }
+    reset() {
+        this.lastError = null;
+        this.buildError.mockClear();
+    }
+};
+MockReturningErrorBuilderService = __decorate([
+    injectable()
+], MockReturningErrorBuilderService);
+export { MockReturningErrorBuilderService };
+function resolveMockPayloadErrorMessage(errorType, payload, preferPayloadContextMessage = true) {
+    if (preferPayloadContextMessage && typeof payload?.context === 'object' && payload.context !== null) {
+        const contextMessage = payload.context.message;
+        if (typeof contextMessage === 'string') {
+            return contextMessage;
+        }
+    }
+    return String(errorType);
+}
+/**
+ * Shared helper for tests that expect a real `Error` instance and also assert on
+ * payload fields copied directly onto the thrown error (`error.context`,
+ * `error.customMessageReference`, etc.).
+ */
+let MockPayloadAssigningErrorBuilderService = class MockPayloadAssigningErrorBuilderService {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    buildError = vi.fn((errorType, _executionContext, payload) => {
+        const error = new Error(resolveMockPayloadErrorMessage(errorType, payload, this.options.preferPayloadContextMessage ?? true));
+        if (payload) {
+            Object.assign(error, payload);
+        }
+        return error;
+    });
+    reset() {
+        this.buildError.mockClear();
+    }
+};
+MockPayloadAssigningErrorBuilderService = __decorate([
+    injectable(),
+    __metadata("design:paramtypes", [Object])
+], MockPayloadAssigningErrorBuilderService);
+export { MockPayloadAssigningErrorBuilderService };
+/**
+ * Shared helper for tests that expect the builder to return a real `Error` while
+ * wrapping the original builder payload under `error.payload` and exposing the
+ * `error.type` discriminator separately.
+ */
+let MockPayloadWrappingErrorBuilderService = class MockPayloadWrappingErrorBuilderService {
+    buildError = vi.fn((errorType, _executionContext, payload) => {
+        const error = new Error(resolveMockPayloadErrorMessage(errorType, payload, true));
+        Object.assign(error, {
+            type: errorType,
+            payload,
+        });
+        return error;
+    });
+    reset() {
+        this.buildError.mockClear();
+    }
+};
+MockPayloadWrappingErrorBuilderService = __decorate([
+    injectable()
+], MockPayloadWrappingErrorBuilderService);
+export { MockPayloadWrappingErrorBuilderService };
+/**
+ * Shared helper for tests where the builder itself is expected to throw immediately.
+ * This keeps validation-style tests concise while preserving last-error inspection.
+ */
+let MockThrowingErrorBuilderService = class MockThrowingErrorBuilderService extends MockReturningErrorBuilderService {
+    buildError = vi.fn((errorType, executionContext, options) => {
+        throw this.buildMockError(errorType, executionContext, options, 'Validation failed');
+    });
+    reset() {
+        super.reset();
+        this.buildError.mockClear();
+    }
+};
+MockThrowingErrorBuilderService = __decorate([
+    injectable()
+], MockThrowingErrorBuilderService);
+export { MockThrowingErrorBuilderService };
+//# sourceMappingURL=mock-error-builder.service.js.map

package/dist/esm/errors/services/__tests__/mock-error-builder.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-error-builder.service.js","sourceRoot":"","sources":["../../../../../src/errors/services/__tests__/mock-error-builder.service.ts"],"names":[],"mappings":"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"}

package/dist/esm/errors/services/error-builder.backend.service.d.ts

@@ -0,0 +1,95 @@
+import { ErrorType, WildoError_Backend, ErrorCustomMessageReference, ErrorUserGuidance } from '@wildo-ai/saas-models';
+import { ExecutionContext } from '../../runtime/models/execution-context.backend.schemas.js';
+import { LoggerService } from '../../monitoring/logger/services/logger.service.js';
+/**
+ * Backend Error Builder Service
+ * Creates unified WildoError_Backend instances with ExecutionContext integration
+ */
+export declare class ErrorBuilderBackendService {
+    private logger;
+    protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+    constructor(logger: LoggerService);
+    /**
+     * Build a WildoError_Backend with ExecutionContext integration
+     */
+    buildError(errorType: ErrorType, executionContext?: ExecutionContext<any>, options?: {
+        customMessageReference?: ErrorCustomMessageReference;
+        context?: Record<string, any>;
+        stack?: string;
+    }): WildoError_Backend;
+    buildFromStandardError(error: unknown, executionContext?: ExecutionContext<any>, options?: {
+        customMessageReference?: ErrorCustomMessageReference;
+        context?: Record<string, any>;
+    }): WildoError_Backend;
+    /**
+     * Build an error with contextual user guidance (Phase 1b).
+     *
+     * The guidance is attached to the error and will be included in the
+     * `ErrorResponse.error.userGuidance` field for the frontend to render.
+     *
+     * @example
+     * ```
+     * throw this.errorBuilder.buildErrorWithGuidance(
+     *   ErrorType.CONFIGURATION,
+     *   executionContext,
+     *   {
+     *     explanation: 'SMTP is not configured for this organization.',
+     *     resolution: 'Go to Settings → Email and configure your SMTP provider.',
+     *     nextAction: { label: 'Go to Settings', ref: '/settings/email', type: 'url' },
+     *     missingConfiguration: ['smtp_host', 'smtp_port'],
+     *   },
+     *   { customMessageReference: ErrorCustomMessageReference.GENERIC_DETAIL }
+     * );
+     * ```
+     */
+    buildErrorWithGuidance(errorType: ErrorType, executionContext: ExecutionContext<any> | undefined, guidance: ErrorUserGuidance, options?: {
+        customMessageReference?: ErrorCustomMessageReference;
+        context?: Record<string, any>;
+        stack?: string;
+    }): WildoError_Backend;
+    /**
+     * Build an error with a guidance key (i18n reference).
+     *
+     * Shorthand for `buildErrorWithGuidance` that sets the `guidanceKey` on the guidance object,
+     * enabling i18n label resolution under `errors_guidance.{guidanceKey}.{field}`.
+     *
+     * @param errorType - The error type
+     * @param executionContext - Current execution context
+     * @param guidanceKey - i18n lookup key (resolves labels under `errors_guidance.{guidanceKey}.*`)
+     * @param guidance - Guidance fields (explanation, resolution, etc.) — used as raw fallbacks
+     * @param options - Additional error options
+     */
+    buildErrorWithGuidanceKey(errorType: ErrorType, executionContext: ExecutionContext<any> | undefined, guidanceKey: string, guidance?: Omit<ErrorUserGuidance, 'guidanceKey'>, options?: {
+        customMessageReference?: ErrorCustomMessageReference;
+        context?: Record<string, any>;
+        stack?: string;
+    }): WildoError_Backend;
+    wildoErrorToSimpleString(wildoError: any): string;
+    /**
+     * Sanitize an error for client-facing HTTP responses.
+     * Called at the serialization boundary (ErrorHandlerService), NOT at build time,
+     * so backend logging retains full context for diagnostics.
+     *
+     * - VALIDATION, CONFLICT, RATE_LIMIT: allowlist of frontend-useful context keys
+     * - AUTHENTICATION: allows `authResponse` through (retry/lockout UI data)
+     * - Everything else (AUTHZ, INTERNAL, DATABASE, etc.): strips context entirely
+     */
+    sanitizeErrorForClient(wildoError: WildoError_Backend): WildoError_Backend;
+    private executeBackendActions;
+    /**
+     * Log error with appropriate severity
+     */
+    private logError;
+    private getCustomMessage;
+    private formatWildoErrorForConsole;
+    /**
+     * Send alert for critical errors
+     */
+    private sendAlert;
+    /**
+     * Centralized error type determination based on error characteristics
+     * This method provides consistent error type classification across all services
+     */
+    determineErrorType(error: Error): ErrorType;
+}
+//# sourceMappingURL=error-builder.backend.service.d.ts.map

package/dist/esm/errors/services/error-builder.backend.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-builder.backend.service.d.ts","sourceRoot":"","sources":["../../../../src/errors/services/error-builder.backend.service.ts"],"names":[],"mappings":"AACA,OAAO,EACL,SAAS,EAIT,kBAAkB,EAClB,2BAA2B,EAM3B,iBAAiB,EAClB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,qEAAqE,CAAC;AAEvG,OAAO,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAI7F;;;GAGG;AACH,qBACa,0BAA0B;IAKA,OAAO,CAAC,MAAM;IAJnD,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;gBAIpC,MAAM,EAAE,aAAa;IAMlE;;OAEG;IACI,UAAU,CACf,SAAS,EAAE,SAAS,EACpB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC,GAAG,CAAC,EACxC,OAAO,GAAE;QACP,sBAAsB,CAAC,EAAE,2BAA2B,CAAC;QACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;QAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;KACX,GACL,kBAAkB;IAsCd,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,gBAAgB,CAAC,EAAE,gBAAgB,CAAC,GAAG,CAAC,EAAE,OAAO,GAAE;QAC/F,sBAAsB,CAAC,EAAE,2BAA2B,CAAC;QACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KACzB,GAAG,kBAAkB;IAW3B;;;;;;;;;;;;;;;;;;;;OAoBG;IACI,sBAAsB,CAC3B,SAAS,EAAE,SAAS,EACpB,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,GAAG,SAAS,EACnD,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,GAAE;QACP,sBAAsB,CAAC,EAAE,2BAA2B,CAAC;QACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;KACX,GACL,kBAAkB;IAMrB;;;;;;;;;;;OAWG;IACI,yBAAyB,CAC9B,SAAS,EAAE,SAAS,EACpB,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,GAAG,SAAS,EACnD,WAAW,EAAE,MAAM,EACnB,QAAQ,GAAE,IAAI,CAAC,iBAAiB,EAAE,aAAa,CAAM,EACrD,OAAO,GAAE;QACP,sBAAsB,CAAC,EAAE,2BAA2B,CAAC;QACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;KACX,GACL,kBAAkB;IAId,wBAAwB,CAAC,UAAU,EAAE,GAAG,GAAG,MAAM;IAcxD;;;;;;;;OAQG;IACI,sBAAsB,CAAC,UAAU,EAAE,kBAAkB,GAAG,kBAAkB;YAiDnE,qBAAqB;IAkCnC;;OAEG;YACW,QAAQ;YAqBR,gBAAgB;IAM9B,OAAO,CAAC,0BAA0B;IA+BlC;;OAEG;IACH,OAAO,CAAC,SAAS;IAIjB;;;OAGG;IACI,kBAAkB,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS;CA6DnD"}