promptspeak-mcp-server 0.1.0

package/dist/core/config/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../src/core/config/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CASjE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAExE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGjE;AAMD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAUtE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAUrE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,OAAO,CAOzE;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,MAAM,EACX,YAAY,GAAE,MAAM,EAAO,EAC3B,SAAS,GAAE,MAAY,GACtB,MAAM,EAAE,CAMV;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,GAAG,CAAC,CAU7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,SAAS,CAAC,EAAE,EAC3B,YAAY,EAAE,CAAC,GACd,CAAC,CAYH;AAMD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,iDAAiD;IACjD,KAAK,EAAE,OAAO,CAAC;IACf,yCAAyC;IACzC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,+CAA+C;IAC/C,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,mBAAmB,CAa3E;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAG3C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,UAAU,GAAE,aAAa,GAAG,YAAY,GAAG,MAAsB,GAChE,aAAa,GAAG,YAAY,GAAG,MAAM,CAEvC;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;GAEG;AACH,wBAAgB,MAAM,IAAI,OAAO,CAEhC"}

package/dist/core/config/env.js

@@ -0,0 +1,230 @@
+/**
+ * ===============================================================================
+ * ENVIRONMENT VARIABLE UTILITIES
+ * ===============================================================================
+ *
+ * Type-safe utilities for reading environment variables with validation.
+ * Extracted from http/config.ts for reuse across the codebase.
+ *
+ * Usage:
+ *   import { getEnv, getEnvNumber, getEnvBoolean } from '../core/config/env.js';
+ *
+ *   const port = getEnvNumber('PORT', 3000);
+ *   const debug = getEnvBoolean('DEBUG', false);
+ *   const apiKey = getEnv('API_KEY');  // throws if missing
+ *
+ * ===============================================================================
+ */
+// -----------------------------------------------------------------------------
+// BASIC ACCESSORS
+// -----------------------------------------------------------------------------
+/**
+ * Get a required environment variable.
+ * Throws if the variable is not set and no default is provided.
+ *
+ * @param key - Environment variable name
+ * @param defaultValue - Optional default value
+ * @returns The environment variable value
+ * @throws Error if variable is missing and no default provided
+ */
+export function getEnv(key, defaultValue) {
+    const value = process.env[key];
+    if (value === undefined || value === '') {
+        if (defaultValue !== undefined) {
+            return defaultValue;
+        }
+        throw new Error(`Missing required environment variable: ${key}`);
+    }
+    return value;
+}
+/**
+ * Get an optional environment variable with a default value.
+ * Never throws - always returns a value.
+ *
+ * @param key - Environment variable name
+ * @param defaultValue - Default value if not set
+ * @returns The environment variable value or default
+ */
+export function getEnvOptional(key, defaultValue) {
+    return process.env[key] ?? defaultValue;
+}
+/**
+ * Get an optional environment variable, returning undefined if not set.
+ *
+ * @param key - Environment variable name
+ * @returns The environment variable value or undefined
+ */
+export function getEnvOrUndefined(key) {
+    const value = process.env[key];
+    return value === '' ? undefined : value;
+}
+// -----------------------------------------------------------------------------
+// TYPED ACCESSORS
+// -----------------------------------------------------------------------------
+/**
+ * Get an environment variable as a number.
+ *
+ * @param key - Environment variable name
+ * @param defaultValue - Default value if not set
+ * @returns Parsed number value
+ * @throws Error if value is not a valid number
+ */
+export function getEnvNumber(key, defaultValue) {
+    const value = process.env[key];
+    if (value === undefined || value === '') {
+        return defaultValue;
+    }
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed)) {
+        throw new Error(`Invalid number for environment variable ${key}: "${value}"`);
+    }
+    return parsed;
+}
+/**
+ * Get an environment variable as a float.
+ *
+ * @param key - Environment variable name
+ * @param defaultValue - Default value if not set
+ * @returns Parsed float value
+ * @throws Error if value is not a valid number
+ */
+export function getEnvFloat(key, defaultValue) {
+    const value = process.env[key];
+    if (value === undefined || value === '') {
+        return defaultValue;
+    }
+    const parsed = parseFloat(value);
+    if (isNaN(parsed)) {
+        throw new Error(`Invalid float for environment variable ${key}: "${value}"`);
+    }
+    return parsed;
+}
+/**
+ * Get an environment variable as a boolean.
+ * Accepts: 'true', '1', 'yes', 'on' (case-insensitive) as truthy.
+ *
+ * @param key - Environment variable name
+ * @param defaultValue - Default value if not set
+ * @returns Boolean value
+ */
+export function getEnvBoolean(key, defaultValue) {
+    const value = process.env[key];
+    if (value === undefined || value === '') {
+        return defaultValue;
+    }
+    const lower = value.toLowerCase();
+    return lower === 'true' || lower === '1' || lower === 'yes' || lower === 'on';
+}
+/**
+ * Get an environment variable as a comma-separated list.
+ *
+ * @param key - Environment variable name
+ * @param defaultValue - Default array if not set
+ * @param separator - Separator character (default: ',')
+ * @returns Array of trimmed strings
+ */
+export function getEnvList(key, defaultValue = [], separator = ',') {
+    const value = process.env[key];
+    if (value === undefined || value === '') {
+        return defaultValue;
+    }
+    return value.split(separator).map(s => s.trim()).filter(s => s.length > 0);
+}
+/**
+ * Get an environment variable as a JSON object.
+ *
+ * @param key - Environment variable name
+ * @param defaultValue - Default value if not set
+ * @returns Parsed JSON object
+ * @throws Error if value is not valid JSON
+ */
+export function getEnvJson(key, defaultValue) {
+    const value = process.env[key];
+    if (value === undefined || value === '') {
+        return defaultValue;
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch (err) {
+        throw new Error(`Invalid JSON for environment variable ${key}: ${err.message}`);
+    }
+}
+/**
+ * Get an environment variable constrained to specific values (enum-like).
+ *
+ * @param key - Environment variable name
+ * @param allowedValues - Array of allowed values
+ * @param defaultValue - Default value if not set
+ * @returns The environment variable value
+ * @throws Error if value is not in allowed values
+ */
+export function getEnvEnum(key, allowedValues, defaultValue) {
+    const value = process.env[key];
+    if (value === undefined || value === '') {
+        return defaultValue;
+    }
+    if (!allowedValues.includes(value)) {
+        throw new Error(`Invalid value for environment variable ${key}: "${value}". ` +
+            `Allowed values: ${allowedValues.join(', ')}`);
+    }
+    return value;
+}
+/**
+ * Validate that required environment variables are set.
+ *
+ * @param required - Array of required variable names
+ * @returns Validation result
+ */
+export function validateRequiredEnv(required) {
+    const missing = [];
+    for (const key of required) {
+        const value = process.env[key];
+        if (value === undefined || value === '') {
+            missing.push(key);
+        }
+    }
+    return {
+        valid: missing.length === 0,
+        missing,
+        invalid: [],
+    };
+}
+/**
+ * Check if an environment variable is set (non-empty).
+ *
+ * @param key - Environment variable name
+ * @returns true if the variable is set and non-empty
+ */
+export function hasEnv(key) {
+    const value = process.env[key];
+    return value !== undefined && value !== '';
+}
+/**
+ * Get the current Node environment.
+ *
+ * @param defaultEnv - Default environment if NODE_ENV is not set
+ * @returns Current environment name
+ */
+export function getNodeEnv(defaultEnv = 'development') {
+    return getEnvEnum('NODE_ENV', ['development', 'production', 'test'], defaultEnv);
+}
+/**
+ * Check if running in production mode.
+ */
+export function isProduction() {
+    return getNodeEnv() === 'production';
+}
+/**
+ * Check if running in development mode.
+ */
+export function isDevelopment() {
+    return getNodeEnv() === 'development';
+}
+/**
+ * Check if running in test mode.
+ */
+export function isTest() {
+    return getNodeEnv() === 'test';
+}
+//# sourceMappingURL=env.js.map

package/dist/core/config/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../../src/core/config/env.ts"],"names":[],"mappings":"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"}

package/dist/core/config/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ===============================================================================
+ * CONFIGURATION MODULE
+ * ===============================================================================
+ *
+ * Centralized configuration utilities for the PromptSpeak codebase.
+ * Provides type-safe environment variable access and validation.
+ *
+ * Usage:
+ *   import {
+ *     getEnv,
+ *     getEnvNumber,
+ *     getEnvBoolean,
+ *     getEnvList,
+ *     validateRequiredEnv,
+ *     isProduction,
+ *   } from '../core/config/index.js';
+ *
+ * ===============================================================================
+ */
+export { getEnv, getEnvOptional, getEnvOrUndefined, getEnvNumber, getEnvFloat, getEnvBoolean, getEnvList, getEnvJson, getEnvEnum, validateRequiredEnv, hasEnv, getNodeEnv, isProduction, isDevelopment, isTest, } from './env.js';
+export type { EnvValidationResult } from './env.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/config/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAEL,MAAM,EACN,cAAc,EACd,iBAAiB,EAGjB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,UAAU,EACV,UAAU,EACV,UAAU,EAGV,mBAAmB,EACnB,MAAM,EAGN,UAAU,EACV,YAAY,EACZ,aAAa,EACb,MAAM,GACP,MAAM,UAAU,CAAC;AAElB,YAAY,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC"}

package/dist/core/config/index.js

@@ -0,0 +1,31 @@
+/**
+ * ===============================================================================
+ * CONFIGURATION MODULE
+ * ===============================================================================
+ *
+ * Centralized configuration utilities for the PromptSpeak codebase.
+ * Provides type-safe environment variable access and validation.
+ *
+ * Usage:
+ *   import {
+ *     getEnv,
+ *     getEnvNumber,
+ *     getEnvBoolean,
+ *     getEnvList,
+ *     validateRequiredEnv,
+ *     isProduction,
+ *   } from '../core/config/index.js';
+ *
+ * ===============================================================================
+ */
+// Environment variable utilities
+export { 
+// Basic accessors
+getEnv, getEnvOptional, getEnvOrUndefined, 
+// Typed accessors
+getEnvNumber, getEnvFloat, getEnvBoolean, getEnvList, getEnvJson, getEnvEnum, 
+// Validation
+validateRequiredEnv, hasEnv, 
+// Environment helpers
+getNodeEnv, isProduction, isDevelopment, isTest, } from './env.js';
+//# sourceMappingURL=index.js.map

package/dist/core/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/config/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,iCAAiC;AACjC,OAAO;AACL,kBAAkB;AAClB,MAAM,EACN,cAAc,EACd,iBAAiB;AAEjB,kBAAkB;AAClB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,UAAU,EACV,UAAU,EACV,UAAU;AAEV,aAAa;AACb,mBAAmB,EACnB,MAAM;AAEN,sBAAsB;AACtB,UAAU,EACV,YAAY,EACZ,aAAa,EACb,MAAM,GACP,MAAM,UAAU,CAAC"}

package/dist/core/errors/base.d.ts

@@ -0,0 +1,168 @@
+/**
+ * ===============================================================================
+ * BASE ERROR CLASSES - Foundation for PromptSpeak Error Handling
+ * ===============================================================================
+ *
+ * Provides the abstract base class for all PromptSpeak errors.
+ * Ensures consistent error structure across the entire codebase with:
+ *   - Structured error information for logging and debugging
+ *   - JSON serialization for API responses
+ *   - Error chaining for root cause analysis
+ *   - Automatic timestamps
+ *   - HTTP status code mapping
+ *   - Retry guidance
+ *
+ * ===============================================================================
+ */
+import { ErrorCode, ErrorSeverity } from './codes.js';
+/**
+ * Options for constructing a PromptSpeakError.
+ */
+export interface PromptSpeakErrorOptions {
+    /** Additional details about the error */
+    details?: Record<string, unknown>;
+    /** The original error that caused this error */
+    originalError?: Error;
+    /** Override the default retryable status */
+    retryable?: boolean;
+    /** Override the default HTTP status code */
+    statusCode?: number;
+    /** Override the default severity */
+    severity?: ErrorSeverity;
+}
+/**
+ * JSON representation of a PromptSpeakError.
+ * Used for API responses and logging.
+ */
+export interface SerializedError {
+    /** Error name/type */
+    name: string;
+    /** Error message */
+    message: string;
+    /** Error code for programmatic handling */
+    code: ErrorCode;
+    /** Error severity */
+    severity: ErrorSeverity;
+    /** Whether the operation can be retried */
+    retryable: boolean;
+    /** HTTP status code */
+    statusCode: number;
+    /** ISO timestamp when the error occurred */
+    timestamp: string;
+    /** Additional error details */
+    details?: Record<string, unknown>;
+    /** Stack trace (only in development) */
+    stack?: string;
+    /** Original error information */
+    cause?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+}
+/**
+ * Base error class for all PromptSpeak errors.
+ * Provides structured error information for logging and debugging.
+ *
+ * @abstract
+ * @example
+ * ```typescript
+ * class MyCustomError extends PromptSpeakError {
+ *   readonly code = ErrorCode.CUSTOM_ERROR;
+ *   readonly severity = ErrorSeverity.MEDIUM;
+ *
+ *   constructor(message: string, options?: PromptSpeakErrorOptions) {
+ *     super(message, options);
+ *     this.name = 'MyCustomError';
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class PromptSpeakError extends Error {
+    /**
+     * The error code for programmatic handling.
+     */
+    abstract readonly code: ErrorCode;
+    /**
+     * The severity level of the error.
+     */
+    abstract readonly severity: ErrorSeverity;
+    /**
+     * Whether the operation that caused this error can be retried.
+     */
+    readonly retryable: boolean;
+    /**
+     * The HTTP status code associated with this error.
+     */
+    readonly statusCode: number;
+    /**
+     * Additional details about the error.
+     */
+    readonly details?: Record<string, unknown>;
+    /**
+     * The original error that caused this error, if any.
+     */
+    readonly originalError?: Error;
+    /**
+     * ISO timestamp when the error was created.
+     */
+    readonly timestamp: string;
+    /**
+     * Creates a new PromptSpeakError.
+     *
+     * @param message - Human-readable error message
+     * @param options - Additional error options
+     */
+    constructor(message: string, options?: PromptSpeakErrorOptions);
+    /**
+     * Initialize properties that depend on abstract members.
+     * Call this in subclass constructors after setting code and severity.
+     */
+    protected initializeDefaults(options?: PromptSpeakErrorOptions): void;
+    /**
+     * Serializes the error to a JSON-compatible object.
+     * Useful for API responses and structured logging.
+     *
+     * @param includeStack - Whether to include the stack trace (default: false)
+     * @returns Serialized error object
+     */
+    toJSON(includeStack?: boolean): SerializedError;
+    /**
+     * Returns a string representation of the error.
+     */
+    toString(): string;
+    /**
+     * Creates a new error of the same type with additional details.
+     * Useful for adding context as errors propagate up the call stack.
+     *
+     * @param additionalDetails - Additional details to merge
+     * @returns A new error instance with merged details
+     */
+    withDetails(additionalDetails: Record<string, unknown>): this;
+    /**
+     * Wraps an existing error in a PromptSpeakError.
+     * Preserves the original error for debugging.
+     *
+     * @param error - The error to wrap
+     * @param message - Optional override message
+     * @returns A new error instance wrapping the original
+     */
+    static wrap<T extends PromptSpeakError>(this: new (message: string, options?: PromptSpeakErrorOptions) => T, error: Error, message?: string): T;
+}
+/**
+ * Type guard to check if an error is a PromptSpeakError.
+ */
+export declare function isPromptSpeakError(error: unknown): error is PromptSpeakError;
+/**
+ * Type guard to check if an error has a specific error code.
+ */
+export declare function hasErrorCode<T extends ErrorCode>(error: unknown, code: T): error is PromptSpeakError & {
+    code: T;
+};
+/**
+ * Converts any error to a PromptSpeakError.
+ * If already a PromptSpeakError, returns it unchanged.
+ * Otherwise, wraps it in an InternalError.
+ */
+export declare function toPromptSpeakError(error: unknown): PromptSpeakError;
+//# sourceMappingURL=base.d.ts.map

package/dist/core/errors/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/core/errors/base.ts"],"names":[],"mappings":"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"}

package/dist/core/errors/base.js

@@ -0,0 +1,195 @@
+/**
+ * ===============================================================================
+ * BASE ERROR CLASSES - Foundation for PromptSpeak Error Handling
+ * ===============================================================================
+ *
+ * Provides the abstract base class for all PromptSpeak errors.
+ * Ensures consistent error structure across the entire codebase with:
+ *   - Structured error information for logging and debugging
+ *   - JSON serialization for API responses
+ *   - Error chaining for root cause analysis
+ *   - Automatic timestamps
+ *   - HTTP status code mapping
+ *   - Retry guidance
+ *
+ * ===============================================================================
+ */
+import { ERROR_CODE_TO_STATUS, ERROR_CODE_RETRYABLE, } from './codes.js';
+/**
+ * Base error class for all PromptSpeak errors.
+ * Provides structured error information for logging and debugging.
+ *
+ * @abstract
+ * @example
+ * ```typescript
+ * class MyCustomError extends PromptSpeakError {
+ *   readonly code = ErrorCode.CUSTOM_ERROR;
+ *   readonly severity = ErrorSeverity.MEDIUM;
+ *
+ *   constructor(message: string, options?: PromptSpeakErrorOptions) {
+ *     super(message, options);
+ *     this.name = 'MyCustomError';
+ *   }
+ * }
+ * ```
+ */
+export class PromptSpeakError extends Error {
+    /**
+     * Whether the operation that caused this error can be retried.
+     */
+    retryable;
+    /**
+     * The HTTP status code associated with this error.
+     */
+    statusCode;
+    /**
+     * Additional details about the error.
+     */
+    details;
+    /**
+     * The original error that caused this error, if any.
+     */
+    originalError;
+    /**
+     * ISO timestamp when the error was created.
+     */
+    timestamp;
+    /**
+     * Creates a new PromptSpeakError.
+     *
+     * @param message - Human-readable error message
+     * @param options - Additional error options
+     */
+    constructor(message, options) {
+        super(message);
+        // Set the prototype explicitly for proper instanceof checks
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.timestamp = new Date().toISOString();
+        this.details = options?.details;
+        this.originalError = options?.originalError;
+        // These will be set by subclasses via abstract properties,
+        // but we need defaults for the constructor
+        // The actual values will be determined after construction
+        this.retryable = options?.retryable ?? false;
+        this.statusCode = options?.statusCode ?? 500;
+        // Capture stack trace, excluding the constructor
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    /**
+     * Initialize properties that depend on abstract members.
+     * Call this in subclass constructors after setting code and severity.
+     */
+    initializeDefaults(options) {
+        // Use type assertion to allow setting readonly properties during initialization
+        const self = this;
+        self.retryable =
+            options?.retryable ?? ERROR_CODE_RETRYABLE[this.code] ?? false;
+        self.statusCode =
+            options?.statusCode ?? ERROR_CODE_TO_STATUS[this.code] ?? 500;
+    }
+    /**
+     * Serializes the error to a JSON-compatible object.
+     * Useful for API responses and structured logging.
+     *
+     * @param includeStack - Whether to include the stack trace (default: false)
+     * @returns Serialized error object
+     */
+    toJSON(includeStack = false) {
+        const result = {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            severity: this.severity,
+            retryable: this.retryable,
+            statusCode: this.statusCode,
+            timestamp: this.timestamp,
+        };
+        if (this.details && Object.keys(this.details).length > 0) {
+            result.details = this.details;
+        }
+        if (includeStack && this.stack) {
+            result.stack = this.stack;
+        }
+        if (this.originalError) {
+            result.cause = {
+                name: this.originalError.name,
+                message: this.originalError.message,
+            };
+            if (includeStack && this.originalError.stack) {
+                result.cause.stack = this.originalError.stack;
+            }
+        }
+        return result;
+    }
+    /**
+     * Returns a string representation of the error.
+     */
+    toString() {
+        let str = `${this.name} [${this.code}]: ${this.message}`;
+        if (this.originalError) {
+            str += ` (caused by: ${this.originalError.message})`;
+        }
+        return str;
+    }
+    /**
+     * Creates a new error of the same type with additional details.
+     * Useful for adding context as errors propagate up the call stack.
+     *
+     * @param additionalDetails - Additional details to merge
+     * @returns A new error instance with merged details
+     */
+    withDetails(additionalDetails) {
+        const ErrorClass = this.constructor;
+        return new ErrorClass(this.message, {
+            details: { ...this.details, ...additionalDetails },
+            originalError: this.originalError,
+            retryable: this.retryable,
+            statusCode: this.statusCode,
+        });
+    }
+    /**
+     * Wraps an existing error in a PromptSpeakError.
+     * Preserves the original error for debugging.
+     *
+     * @param error - The error to wrap
+     * @param message - Optional override message
+     * @returns A new error instance wrapping the original
+     */
+    static wrap(error, message) {
+        return new this(message ?? error.message, {
+            originalError: error,
+        });
+    }
+}
+/**
+ * Type guard to check if an error is a PromptSpeakError.
+ */
+export function isPromptSpeakError(error) {
+    return error instanceof PromptSpeakError;
+}
+/**
+ * Type guard to check if an error has a specific error code.
+ */
+export function hasErrorCode(error, code) {
+    return isPromptSpeakError(error) && error.code === code;
+}
+/**
+ * Converts any error to a PromptSpeakError.
+ * If already a PromptSpeakError, returns it unchanged.
+ * Otherwise, wraps it in an InternalError.
+ */
+export function toPromptSpeakError(error) {
+    if (isPromptSpeakError(error)) {
+        return error;
+    }
+    if (error instanceof Error) {
+        // Import dynamically to avoid circular dependency
+        const { InternalError } = require('./types.js');
+        return new InternalError(error.message, { originalError: error });
+    }
+    const { InternalError } = require('./types.js');
+    return new InternalError(String(error));
+}
+//# sourceMappingURL=base.js.map

package/dist/core/errors/base.js.map

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