profclaw 0.0.1-beta.1

package/dist/types/errors.js

@@ -0,0 +1,338 @@
+/**
+ * Structured Error Types for profClaw
+ *
+ * Provides a type-safe error hierarchy for better error handling,
+ * categorization, and retry logic.
+ */
+/**
+ * Error categories for classification and handling
+ */
+export var ErrorCategory;
+(function (ErrorCategory) {
+    /** Configuration or setup issues */
+    ErrorCategory["CONFIGURATION"] = "CONFIGURATION";
+    /** Authentication/authorization failures */
+    ErrorCategory["AUTHENTICATION"] = "AUTHENTICATION";
+    /** Network connectivity issues (retryable) */
+    ErrorCategory["NETWORK"] = "NETWORK";
+    /** External API errors (rate limits, service unavailable) */
+    ErrorCategory["EXTERNAL_API"] = "EXTERNAL_API";
+    /** Data validation errors */
+    ErrorCategory["VALIDATION"] = "VALIDATION";
+    /** Resource not found */
+    ErrorCategory["NOT_FOUND"] = "NOT_FOUND";
+    /** Operation timeout */
+    ErrorCategory["TIMEOUT"] = "TIMEOUT";
+    /** Rate limit exceeded */
+    ErrorCategory["RATE_LIMIT"] = "RATE_LIMIT";
+    /** Task execution failures */
+    ErrorCategory["EXECUTION"] = "EXECUTION";
+    /** Unknown/unexpected errors */
+    ErrorCategory["UNKNOWN"] = "UNKNOWN";
+})(ErrorCategory || (ErrorCategory = {}));
+/**
+ * Error severity levels
+ */
+export var ErrorSeverity;
+(function (ErrorSeverity) {
+    /** Critical - requires immediate attention */
+    ErrorSeverity["CRITICAL"] = "CRITICAL";
+    /** High - should be investigated soon */
+    ErrorSeverity["HIGH"] = "HIGH";
+    /** Medium - can be handled in normal workflow */
+    ErrorSeverity["MEDIUM"] = "MEDIUM";
+    /** Low - informational, may not need action */
+    ErrorSeverity["LOW"] = "LOW";
+})(ErrorSeverity || (ErrorSeverity = {}));
+/**
+ * Base application error with enhanced metadata
+ */
+export class AppError extends Error {
+    category;
+    severity;
+    retryable;
+    statusCode;
+    metadata;
+    timestamp;
+    correlationId;
+    constructor(message, options) {
+        super(message);
+        this.name = this.constructor.name;
+        this.category = options.category;
+        this.severity = options.severity || ErrorSeverity.MEDIUM;
+        this.retryable = options.retryable ?? false;
+        this.statusCode = options.statusCode;
+        this.metadata = options.metadata;
+        this.timestamp = new Date();
+        this.correlationId = options.correlationId;
+        // Maintain proper stack trace
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+        // Store cause if provided
+        if (options.cause) {
+            this.cause = options.cause;
+        }
+    }
+    /**
+     * Convert error to JSON for logging/transmission
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            category: this.category,
+            severity: this.severity,
+            retryable: this.retryable,
+            statusCode: this.statusCode,
+            metadata: this.metadata,
+            timestamp: this.timestamp.toISOString(),
+            correlationId: this.correlationId,
+            stack: this.stack,
+        };
+    }
+}
+/**
+ * Configuration error (non-retryable)
+ */
+export class ConfigurationError extends AppError {
+    constructor(message, metadata) {
+        super(message, {
+            category: ErrorCategory.CONFIGURATION,
+            severity: ErrorSeverity.CRITICAL,
+            retryable: false,
+            statusCode: 500,
+            metadata,
+        });
+    }
+}
+/**
+ * Authentication error (non-retryable)
+ */
+export class AuthenticationError extends AppError {
+    constructor(message, metadata) {
+        super(message, {
+            category: ErrorCategory.AUTHENTICATION,
+            severity: ErrorSeverity.HIGH,
+            retryable: false,
+            statusCode: 401,
+            metadata,
+        });
+    }
+}
+/**
+ * Network error (retryable)
+ */
+export class NetworkError extends AppError {
+    constructor(message, cause, metadata) {
+        super(message, {
+            category: ErrorCategory.NETWORK,
+            severity: ErrorSeverity.MEDIUM,
+            retryable: true,
+            statusCode: 503,
+            metadata,
+            cause,
+        });
+    }
+}
+/**
+ * External API error (conditionally retryable)
+ */
+export class ExternalAPIError extends AppError {
+    constructor(message, statusCode, retryable = false, metadata) {
+        super(message, {
+            category: ErrorCategory.EXTERNAL_API,
+            severity: statusCode >= 500 ? ErrorSeverity.HIGH : ErrorSeverity.MEDIUM,
+            retryable,
+            statusCode,
+            metadata,
+        });
+    }
+}
+/**
+ * Validation error (non-retryable)
+ */
+export class ValidationError extends AppError {
+    constructor(message, metadata) {
+        super(message, {
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.LOW,
+            retryable: false,
+            statusCode: 400,
+            metadata,
+        });
+    }
+}
+/**
+ * Not found error (non-retryable)
+ */
+export class NotFoundError extends AppError {
+    constructor(resource, id, metadata) {
+        super(`${resource} not found: ${id}`, {
+            category: ErrorCategory.NOT_FOUND,
+            severity: ErrorSeverity.LOW,
+            retryable: false,
+            statusCode: 404,
+            metadata: { ...metadata, resource, id },
+        });
+    }
+}
+/**
+ * Timeout error (retryable)
+ */
+export class TimeoutError extends AppError {
+    constructor(operation, timeoutMs, metadata) {
+        super(`Operation timed out after ${timeoutMs}ms: ${operation}`, {
+            category: ErrorCategory.TIMEOUT,
+            severity: ErrorSeverity.MEDIUM,
+            retryable: true,
+            statusCode: 504,
+            metadata: { ...metadata, operation, timeoutMs },
+        });
+    }
+}
+/**
+ * Rate limit error (retryable with backoff)
+ */
+export class RateLimitError extends AppError {
+    retryAfter;
+    constructor(message, retryAfter, metadata) {
+        super(message, {
+            category: ErrorCategory.RATE_LIMIT,
+            severity: ErrorSeverity.MEDIUM,
+            retryable: true,
+            statusCode: 429,
+            metadata: { ...metadata, retryAfter },
+        });
+        this.retryAfter = retryAfter;
+    }
+}
+/**
+ * Task execution error
+ */
+export class TaskExecutionError extends AppError {
+    constructor(taskId, message, retryable = false, metadata) {
+        super(message, {
+            category: ErrorCategory.EXECUTION,
+            severity: ErrorSeverity.HIGH,
+            retryable,
+            statusCode: 500,
+            metadata: { ...metadata, taskId },
+        });
+    }
+}
+/**
+ * Type guard to check if error is an AppError
+ */
+export function isAppError(error) {
+    return error instanceof AppError;
+}
+/**
+ * Type guard to check if error is retryable
+ */
+export function isRetryableError(error) {
+    if (isAppError(error)) {
+        return error.retryable;
+    }
+    // Network errors are generally retryable
+    if (error instanceof Error) {
+        const message = error.message.toLowerCase();
+        return (message.includes('network') ||
+            message.includes('timeout') ||
+            message.includes('econnreset') ||
+            message.includes('enotfound') ||
+            message.includes('etimedout'));
+    }
+    return false;
+}
+/**
+ * Convert unknown error to AppError
+ */
+export function toAppError(error) {
+    if (isAppError(error)) {
+        return error;
+    }
+    if (error instanceof Error) {
+        // Try to infer category from error message
+        const message = error.message.toLowerCase();
+        if (message.includes('timeout') || message.includes('etimedout')) {
+            return new TimeoutError('Operation', 0, { originalError: error.message });
+        }
+        if (message.includes('network') || message.includes('econnreset')) {
+            return new NetworkError(error.message, error);
+        }
+        if (message.includes('unauthorized') || message.includes('forbidden')) {
+            return new AuthenticationError(error.message);
+        }
+        if (message.includes('not found')) {
+            return new AppError(error.message, {
+                category: ErrorCategory.NOT_FOUND,
+                statusCode: 404,
+            });
+        }
+        // Default: unknown error
+        return new AppError(error.message, {
+            category: ErrorCategory.UNKNOWN,
+            severity: ErrorSeverity.MEDIUM,
+            cause: error,
+        });
+    }
+    // Non-Error objects
+    return new AppError(String(error), {
+        category: ErrorCategory.UNKNOWN,
+        severity: ErrorSeverity.MEDIUM,
+        metadata: { originalError: error },
+    });
+}
+/**
+ * Get retry configuration for an error
+ */
+export function getRetryConfig(error) {
+    if (!error.retryable) {
+        return null;
+    }
+    // Rate limit errors - respect retry-after
+    if (error instanceof RateLimitError && error.retryAfter) {
+        return {
+            maxAttempts: 3,
+            initialDelayMs: error.retryAfter * 1000,
+            maxDelayMs: error.retryAfter * 1000,
+            backoffMultiplier: 1,
+        };
+    }
+    // Network errors - aggressive retry
+    if (error.category === ErrorCategory.NETWORK) {
+        return {
+            maxAttempts: 5,
+            initialDelayMs: 1000,
+            maxDelayMs: 30000,
+            backoffMultiplier: 2,
+        };
+    }
+    // Timeout errors - moderate retry
+    if (error.category === ErrorCategory.TIMEOUT) {
+        return {
+            maxAttempts: 3,
+            initialDelayMs: 2000,
+            maxDelayMs: 60000,
+            backoffMultiplier: 2,
+        };
+    }
+    // External API errors - conservative retry
+    if (error.category === ErrorCategory.EXTERNAL_API) {
+        return {
+            maxAttempts: 3,
+            initialDelayMs: 5000,
+            maxDelayMs: 30000,
+            backoffMultiplier: 2,
+        };
+    }
+    // Default retry config
+    return {
+        maxAttempts: 3,
+        initialDelayMs: 2000,
+        maxDelayMs: 30000,
+        backoffMultiplier: 2,
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './task.js';
+export * from './agent.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.js

@@ -0,0 +1,3 @@
+export * from './task.js';
+export * from './agent.js';
+//# sourceMappingURL=index.js.map