@procedures/client 0.0.0-stage → 0.2.0

package/src/client/errors/README.md

@@ -0,0 +1,279 @@
+# Universal Error System
+
+Protocol-agnostic error handling with rich metadata and bidirectional HTTP status mapping.
+
+## Zero Magic Strings & Numbers
+
+- **ErrorCode enum** - All error codes use enum values (no string literals)
+- **HTTPStatus enum** - All HTTP status codes use enum values (no magic numbers)
+- **Single source of truth** - `HTTP_STATUS_ERROR_MAP` defines bidirectional mapping
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    ErrorCode Enum                       │
+│  (TIMEOUT, NOT_FOUND, INTERNAL_ERROR, etc.)            │
+└─────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────┐
+│                   ERROR_REGISTRY                        │
+│  Maps ErrorCode → ErrorMetadata (summary, detail, etc.) │
+└─────────────────────────────────────────────────────────┘
+                            │
+                ┌───────────┴───────────┐
+                ▼                       ▼
+┌─────────────────────────┐   ┌──────────────────────────┐
+│  HTTP_STATUS_ERROR_MAP  │   │   HTTPStatus Enum        │
+│  Bidirectional mapping  │   │   (OK=200, NOT_FOUND=404)│
+└─────────────────────────┘   └──────────────────────────┘
+        │           │
+        ▼           ▼
+  httpStatusToErrorCode    errorCodeToHTTPStatus
+  (client-side)            (server-side)
+```
+
+## Quick Start
+
+### Client Side: Handle HTTP responses
+
+```typescript
+import { httpStatusToErrorCode, createError, HTTPStatus } from "@common/client/errors";
+
+// Convert HTTP status to error code
+const code = httpStatusToErrorCode(404); // ErrorCode.NOT_FOUND
+
+// Create rich error with metadata
+const error = createError(code, {
+  requestId: "req-123",
+  transport: "http",
+  method: { service: "users", operation: "get" },
+});
+
+// Access rich metadata
+console.log(error.metadata.summary);      // "Resource not found"
+console.log(error.metadata.userMessage);  // User-friendly message
+console.log(error.metadata.devMessage);   // Developer diagnostic
+console.log(error.metadata.suggestions);  // ["Check URL spelling", ...]
+console.log(error.metadata.retryable);    // false
+```
+
+### Server Side: Return appropriate HTTP status
+
+```typescript
+import { errorCodeToHTTPStatus, ErrorCode, HTTPStatus } from "@common/client/errors";
+
+// Map error code to HTTP status
+function handleError(code: ErrorCode): number {
+  const status = errorCodeToHTTPStatus(code);
+  return status; // Returns HTTPStatus enum value (404, 500, etc.)
+}
+
+// Example
+handleError(ErrorCode.NOT_FOUND);        // HTTPStatus.NOT_FOUND (404)
+handleError(ErrorCode.INTERNAL_ERROR);   // HTTPStatus.INTERNAL_SERVER_ERROR (500)
+handleError(ErrorCode.UNAUTHORIZED);     // HTTPStatus.UNAUTHORIZED (401)
+```
+
+### Create Errors from Exceptions
+
+```typescript
+import { createErrorFromException } from "@common/client/errors";
+
+try {
+  await fetch("https://api.example.com/data");
+} catch (err) {
+  const richError = createErrorFromException(err as Error, {
+    transport: "http",
+    requestId: "req-456",
+  });
+
+  // Automatically categorized based on error message
+  // e.g., "timeout" → ErrorCode.TIMEOUT, "network" → ErrorCode.NETWORK_ERROR
+}
+```
+
+## File Structure
+
+```
+common/src/client/errors/
+├── README.md              ← You are here
+├── index.ts               ← Public API exports
+├── codes.ts               ← ErrorCode enum (70+ codes)
+├── http-status.ts         ← HTTPStatus enum (all HTTP status codes)
+├── types.ts               ← TypeScript interfaces
+├── registry.ts            ← ERROR_REGISTRY with full metadata
+├── http-errors.ts         ← HTTP-specific errors + bidirectional mapping
+└── factory.ts             ← Error creation functions
+```
+
+## Key Features
+
+### 1. Rich Error Metadata
+
+Every error includes:
+- **summary**: Brief one-line description
+- **detail**: Full explanation of what went wrong
+- **category**: Network, Client, Server, Protocol, Auth, etc.
+- **severity**: Info, Warning, Error, Critical
+- **retryable**: Whether the operation can be retried
+- **userMessage**: User-friendly message for end users
+- **devMessage**: Detailed diagnostic for developers
+- **suggestions**: Array of actionable suggestions
+- **httpStatus**: HTTP status code (if applicable)
+
+### 2. Protocol-Agnostic
+
+Works across all transports:
+- HTTP/REST
+- WebSocket
+- gRPC
+- Local/in-memory
+
+### 3. Type-Safe
+
+Full TypeScript support:
+```typescript
+// All enums are type-safe
+const code: ErrorCode = ErrorCode.TIMEOUT;
+const status: HTTPStatus = HTTPStatus.NOT_FOUND;
+
+// Metadata is fully typed
+const metadata: ErrorMetadata = getErrorMetadata(ErrorCode.TIMEOUT);
+```
+
+### 4. Bidirectional HTTP Mapping
+
+Single source of truth for HTTP status ↔ error code mapping:
+
+```typescript
+// Client: HTTP status → Error code
+httpStatusToErrorCode(404) // ErrorCode.NOT_FOUND
+
+// Server: Error code → HTTP status
+errorCodeToHTTPStatus(ErrorCode.NOT_FOUND) // HTTPStatus.NOT_FOUND (404)
+```
+
+## Error Categories
+
+- **NETWORK**: Connection failures, DNS errors
+- **CLIENT**: Bad requests, validation errors (4xx equivalent)
+- **SERVER**: Internal errors, service unavailable (5xx equivalent)
+- **PROTOCOL**: Parsing, serialization errors
+- **AUTH**: Authentication, authorization failures
+- **RATE_LIMIT**: Too many requests
+- **TIMEOUT**: Request timeouts, deadlines exceeded
+- **CANCELLED**: Aborted requests
+- **UNKNOWN**: Uncategorized errors
+
+## Examples
+
+### Check if error is retryable
+
+```typescript
+import { isRetryable } from "@common/client/errors";
+
+if (isRetryable(error)) {
+  // Retry logic
+  await retryRequest();
+}
+```
+
+### Filter errors by category
+
+```typescript
+import { isErrorCategory, ErrorCategory } from "@common/client/errors";
+
+if (isErrorCategory(error, ErrorCategory.NETWORK)) {
+  // Handle network-specific errors
+  showOfflineMessage();
+}
+```
+
+### Format for logging
+
+```typescript
+import { formatError } from "@common/client/errors";
+
+console.error(formatError(error, true)); // include stack trace
+```
+
+## Best Practices
+
+1. **Always use enum values** - Never use string literals or magic numbers
+2. **Use the registry** - Don't create error metadata manually
+3. **Provide context** - Include requestId, transport, method when creating errors
+4. **Check retryable flag** - Respect the metadata when implementing retry logic
+5. **Use suggestions** - Display error.metadata.suggestions to help users resolve issues
+
+## Adding New Errors
+
+1. Add to `ErrorCode` enum in `codes.ts`
+2. Add metadata to `ERROR_REGISTRY` in `registry.ts` or `HTTP_ERROR_REGISTRY` in `http-errors.ts`
+3. If HTTP-related, add to `HTTP_STATUS_ERROR_MAP` in `http-errors.ts`
+
+Example:
+```typescript
+// 1. Add to ErrorCode enum
+export enum ErrorCode {
+  // ... existing codes
+  MY_NEW_ERROR = "MY_NEW_ERROR",
+}
+
+// 2. Add to registry
+export const ERROR_REGISTRY: ErrorRegistry = {
+  // ... existing errors
+  [ErrorCode.MY_NEW_ERROR]: defineError(ErrorCode.MY_NEW_ERROR, {
+    summary: "My new error",
+    detail: "Detailed explanation...",
+    category: ErrorCategory.CLIENT,
+    retryable: false,
+    severity: ErrorSeverity.ERROR,
+    userMessage: "User-friendly message",
+    devMessage: "Developer diagnostic",
+    suggestions: ["Suggestion 1", "Suggestion 2"],
+  }),
+};
+```
+
+## Server Usage
+
+The server can import and use the same error system:
+
+```typescript
+import {
+  ErrorCode,
+  HTTPStatus,
+  errorCodeToHTTPStatus
+} from "@common/server";
+
+// Map internal error to HTTP status
+function setResponseStatus(error: RichError, response: Response): void {
+  const status = errorCodeToHTTPStatus(error.code as ErrorCode);
+  response.status(status);
+}
+```
+
+## Migration from Old System
+
+Before:
+```typescript
+// ❌ Magic strings and numbers
+if (error.code === "NOT_FOUND") {
+  res.status(404).json({ error: "Not found" });
+}
+```
+
+After:
+```typescript
+// ✅ Type-safe enums
+if (error.code === ErrorCode.NOT_FOUND) {
+  const status = errorCodeToHTTPStatus(ErrorCode.NOT_FOUND);
+  res.status(status).json({
+    error: error.metadata.userMessage,
+    code: error.code,
+    retryable: error.metadata.retryable,
+  });
+}
+```

package/src/client/errors/codes.ts

@@ -0,0 +1,88 @@
+/**
+ * Error Code Enums
+ *
+ * Comprehensive enum of ALL error codes.
+ * NO MAGIC STRINGS - use these enums everywhere!
+ */
+
+/**
+ * Universal Error Codes
+ *
+ * Protocol-agnostic error codes that work across all transports.
+ */
+export enum ErrorCode {
+  // Network errors
+  NETWORK_ERROR = "NETWORK_ERROR",
+  CONNECTION_REFUSED = "CONNECTION_REFUSED",
+  DNS_ERROR = "DNS_ERROR",
+
+  // Timeout errors
+  TIMEOUT = "TIMEOUT",
+  CONNECTION_TIMEOUT = "CONNECTION_TIMEOUT",
+  READ_TIMEOUT = "READ_TIMEOUT",
+  DEADLINE_EXCEEDED = "DEADLINE_EXCEEDED",
+
+  // Cancellation
+  ABORTED = "ABORTED",
+
+  // Protocol/parsing errors
+  PARSE_ERROR = "PARSE_ERROR",
+  SERIALIZE_ERROR = "SERIALIZE_ERROR",
+  INVALID_RESPONSE = "INVALID_RESPONSE",
+  PROTOCOL_ERROR = "PROTOCOL_ERROR",
+
+  // Client errors (4xx equivalent)
+  BAD_REQUEST = "BAD_REQUEST",
+  UNAUTHORIZED = "UNAUTHORIZED",
+  FORBIDDEN = "FORBIDDEN",
+  NOT_FOUND = "NOT_FOUND",
+  METHOD_NOT_ALLOWED = "METHOD_NOT_ALLOWED",
+  NOT_ACCEPTABLE = "NOT_ACCEPTABLE",
+  PROXY_AUTHENTICATION_REQUIRED = "PROXY_AUTHENTICATION_REQUIRED",
+  CONFLICT = "CONFLICT",
+  GONE = "GONE",
+  LENGTH_REQUIRED = "LENGTH_REQUIRED",
+  PRECONDITION_FAILED = "PRECONDITION_FAILED",
+  PAYLOAD_TOO_LARGE = "PAYLOAD_TOO_LARGE",
+  URI_TOO_LONG = "URI_TOO_LONG",
+  UNSUPPORTED_MEDIA_TYPE = "UNSUPPORTED_MEDIA_TYPE",
+  RANGE_NOT_SATISFIABLE = "RANGE_NOT_SATISFIABLE",
+  EXPECTATION_FAILED = "EXPECTATION_FAILED",
+  IM_A_TEAPOT = "IM_A_TEAPOT",
+  MISDIRECTED_REQUEST = "MISDIRECTED_REQUEST",
+  UNPROCESSABLE_ENTITY = "UNPROCESSABLE_ENTITY",
+  LOCKED = "LOCKED",
+  FAILED_DEPENDENCY = "FAILED_DEPENDENCY",
+  TOO_EARLY = "TOO_EARLY",
+  UPGRADE_REQUIRED = "UPGRADE_REQUIRED",
+  PRECONDITION_REQUIRED = "PRECONDITION_REQUIRED",
+  TOO_MANY_REQUESTS = "TOO_MANY_REQUESTS",
+  REQUEST_HEADER_FIELDS_TOO_LARGE = "REQUEST_HEADER_FIELDS_TOO_LARGE",
+  UNAVAILABLE_FOR_LEGAL_REASONS = "UNAVAILABLE_FOR_LEGAL_REASONS",
+  CLIENT_CLOSED_REQUEST = "CLIENT_CLOSED_REQUEST",
+
+  // Server errors (5xx equivalent)
+  INTERNAL_ERROR = "INTERNAL_ERROR",
+  NOT_IMPLEMENTED = "NOT_IMPLEMENTED",
+  BAD_GATEWAY = "BAD_GATEWAY",
+  SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE",
+  GATEWAY_TIMEOUT = "GATEWAY_TIMEOUT",
+  HTTP_VERSION_NOT_SUPPORTED = "HTTP_VERSION_NOT_SUPPORTED",
+  VARIANT_ALSO_NEGOTIATES = "VARIANT_ALSO_NEGOTIATES",
+  INSUFFICIENT_STORAGE = "INSUFFICIENT_STORAGE",
+  LOOP_DETECTED = "LOOP_DETECTED",
+  NOT_EXTENDED = "NOT_EXTENDED",
+  NETWORK_AUTHENTICATION_REQUIRED = "NETWORK_AUTHENTICATION_REQUIRED",
+  HTTP_NETWORK_CONNECT_TIMEOUT = "HTTP_NETWORK_CONNECT_TIMEOUT",
+
+  // Configuration errors
+  INVALID_CONFIG = "INVALID_CONFIG",
+  INVALID_URL = "INVALID_URL",
+  INVALID_METHOD = "INVALID_METHOD",
+
+  // HTTP-specific
+  HTTP_ERROR = "HTTP_ERROR",
+
+  // Unknown
+  UNKNOWN = "UNKNOWN",
+}

package/src/client/errors/factory.ts

@@ -0,0 +1,263 @@
+/**
+ * Error Factory Functions
+ *
+ * Create rich errors from error codes with full metadata.
+ * Zero magic strings - everything driven by registry.
+ */
+
+import {
+  type RichError,
+  type ErrorContext,
+  type ErrorMetadata,
+} from "./types.js";
+import { getErrorMetadata } from "./registry.js";
+import { httpStatusToErrorCode } from "./http-errors.js";
+import { ErrorCode } from "./codes.js";
+
+/**
+ * Create a rich error from an error code.
+ *
+ * @param code - Error code from registry
+ * @param context - Runtime context (optional)
+ * @param cause - Underlying error cause (optional)
+ * @returns Rich error with full metadata
+ *
+ * @example
+ * ```typescript
+ * const error = createError("TIMEOUT", {
+ *   requestId: "req-123",
+ *   transport: "http",
+ * });
+ *
+ * console.log(error.metadata.summary); // "Request timed out"
+ * console.log(error.metadata.userMessage); // "The request took too long..."
+ * console.log(error.metadata.suggestions); // ["Try again with longer timeout", ...]
+ * ```
+ */
+export function createError(
+  code: string,
+  context?: Partial<ErrorContext>,
+  cause?: Error
+): RichError {
+  const metadata = getErrorMetadata(code);
+
+  const fullContext: ErrorContext = {
+    timestamp: Date.now(),
+    ...context,
+  };
+
+  return {
+    code,
+    metadata,
+    context: fullContext,
+    ...(cause && { cause }),
+  };
+}
+
+/**
+ * Create error from HTTP status code.
+ *
+ * Uses registry lookup - zero magic strings!
+ *
+ * @param status - HTTP status code
+ * @param context - Runtime context
+ * @returns Rich error with appropriate error code
+ *
+ * @example
+ * ```typescript
+ * const error = createErrorFromHTTPStatus(404, {
+ *   requestId: "req-123",
+ *   method: { service: "users", operation: "get" },
+ * });
+ * ```
+ */
+export function createErrorFromHTTPStatus(
+  status: number,
+  context?: Partial<ErrorContext>
+): RichError {
+  // Use registry - no magic strings!
+  const code = httpStatusToErrorCode(status);
+  return createError(code, context);
+}
+
+export type ErrorPattern = {
+  code: ErrorCode;
+  detect: (name: string, message: string) => boolean;
+}
+
+/**
+ * Error detection patterns.
+ *
+ * Maps error characteristics to error codes.
+ * Uses ErrorCode enum - NO MAGIC STRINGS!
+ */
+const ERROR_PATTERNS : ErrorPattern[] = [
+  {
+    code: ErrorCode.ABORTED,
+    detect: (name: string, message: string) =>
+      name === "aborterror" || message.includes("abort"),
+  },
+  {
+    code: ErrorCode.TIMEOUT,
+    detect: (name: string, message: string) =>
+      name === "timeouterror" ||
+      message.includes("timeout") ||
+      message.includes("timed out"),
+  },
+  {
+    code: ErrorCode.DNS_ERROR,
+    detect: (_name: string, message: string) =>
+      message.includes("dns") ||
+      message.includes("enotfound") ||
+      message.includes("getaddrinfo"),
+  },
+  {
+    code: ErrorCode.CONNECTION_REFUSED,
+    detect: (_name: string, message: string) =>
+      message.includes("econnrefused") ||
+      message.includes("connection refused"),
+  },
+  {
+    code: ErrorCode.NETWORK_ERROR,
+    detect: (_name: string, message: string) =>
+      message.includes("fetch") ||
+      message.includes("network") ||
+      message.includes("connection"),
+  },
+  {
+    code: ErrorCode.PARSE_ERROR,
+    detect: (_name: string, message: string) =>
+      message.includes("parse") ||
+      message.includes("json") ||
+      message.includes("unexpected token"),
+  },
+  {
+    code: ErrorCode.SERIALIZE_ERROR,
+    detect: (_name: string, message: string) =>
+      message.includes("serialize") ||
+      message.includes("stringify") ||
+      message.includes("circular"),
+  },
+] as const satisfies ErrorPattern[];
+
+/**
+ * Create error from native Error exception.
+ *
+ * Uses pattern matching - no scattered magic strings!
+ *
+ * @param error - Native Error object
+ * @param context - Runtime context
+ * @returns Rich error
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await fetch(...);
+ * } catch (err) {
+ *   const richError = createErrorFromException(err as Error, {
+ *     transport: "http",
+ *   });
+ * }
+ * ```
+ */
+export function createErrorFromException(
+  error: Error,
+  context?: Partial<ErrorContext>
+): RichError {
+  const name = error.name?.toLowerCase() ?? "";
+  const message = error.message?.toLowerCase() ?? "";
+
+  // Use pattern matching - declarative, not imperative!
+  const pattern = ERROR_PATTERNS.find((p) => p.detect(name, message));
+  const code = pattern?.code ?? ErrorCode.UNKNOWN;
+
+  return createError(code, context, error);
+}
+
+/**
+ * Convert RichError to Status for universal client.
+ *
+ * @param error - Rich error
+ * @returns Status object
+ */
+export function richErrorToStatus(error: RichError): {
+  type: "error";
+  code: string;
+  message: string;
+  retryable: boolean;
+  metadata: ErrorMetadata;
+} {
+  return {
+    type: "error",
+    code: error.code,
+    message: error.metadata.summary,
+    retryable: error.metadata.retryable,
+    metadata: error.metadata,
+  };
+}
+
+/**
+ * Format error for logging.
+ *
+ * @param error - Rich error
+ * @param includeStack - Include stack trace if cause exists
+ * @returns Formatted error string
+ */
+export function formatError(error: RichError, includeStack = false): string {
+  const lines: string[] = [
+    `[${error.code}] ${error.metadata.summary}`,
+    `  Detail: ${error.metadata.detail}`,
+    `  Category: ${error.metadata.category}`,
+    `  Retryable: ${error.metadata.retryable}`,
+    `  Severity: ${error.metadata.severity}`,
+  ];
+
+  if (error.context.requestId) {
+    lines.push(`  Request ID: ${error.context.requestId}`);
+  }
+
+  if (error.context.transport) {
+    lines.push(`  Transport: ${error.context.transport}`);
+  }
+
+  if (error.context.method) {
+    const m = error.context.method;
+    const methodStr = m.version
+      ? `${m.version}:${m.service}.${m.operation}`
+      : `${m.service}.${m.operation}`;
+    lines.push(`  Method: ${methodStr}`);
+  }
+
+  if (error.metadata.suggestions && error.metadata.suggestions.length > 0) {
+    lines.push(`  Suggestions:`);
+    for (const suggestion of error.metadata.suggestions) {
+      lines.push(`    - ${suggestion}`);
+    }
+  }
+
+  if (error.cause) {
+    lines.push(`  Cause: ${error.cause.message}`);
+    if (includeStack && error.cause.stack) {
+      lines.push(`  Stack: ${error.cause.stack}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Check if error is retryable.
+ */
+export function isRetryable(error: RichError): boolean {
+  return error.metadata.retryable;
+}
+
+/**
+ * Check if error is in a specific category.
+ */
+export function isErrorCategory(
+  error: RichError,
+  category: string
+): boolean {
+  return error.metadata.category === category;
+}