blaizejs 0.4.0 → 0.5.1

package/dist/index.d.ts

@@ -135,6 +135,16 @@ interface ValidationFieldError {
     /** Expected type or format */
     expectedType?: string;
 }
+interface ServiceNotAvailableDetails {
+    /** Service that's unavailable */
+    service?: string;
+    /** Seconds to wait before retry */
+    retryAfter?: number;
+    /** Why service is unavailable */
+    reason?: 'maintenance' | 'overload' | 'circuit_breaker' | 'dependency_down';
+    /** Additional context */
+    [key: string]: unknown;
+}
 /**
  * Validation error details structure
  *
@@ -181,6 +191,8 @@ declare enum ErrorType {
     UNAUTHORIZED = "UNAUTHORIZED",
     /** Access forbidden (403) */
     FORBIDDEN = "FORBIDDEN",
+    /** SSE Not Acceptable (406) */
+    SSE_NOT_ACCEPTABLE = "SSE_NOT_ACCEPTABLE",
     /** Resource conflict (409) */
     CONFLICT = "CONFLICT",
     /** Rate limit exceeded (429) */
@@ -202,7 +214,15 @@ declare enum ErrorType {
     /** Response parsing failure (0) */
     PARSE_ERROR = "PARSE_ERROR",
     /** Generic HTTP error (varies) */
-    HTTP_ERROR = "HTTP_ERROR"
+    HTTP_ERROR = "HTTP_ERROR",
+    /** SSE connection failed (502) */
+    SSE_CONNECTION_ERROR = "SSE_CONNECTION_ERROR",
+    /** SSE buffer overflow (503) */
+    SSE_BUFFER_OVERFLOW = "SSE_BUFFER_OVERFLOW",
+    /** SSE stream closed (410) */
+    SSE_STREAM_CLOSED = "SSE_STREAM_CLOSED",
+    /** Service temporarily unavailable (503) */
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
 }
 /**
  * Error severity levels for logging and monitoring
@@ -357,7 +377,7 @@ interface ForbiddenErrorDetails {
     /** Action being attempted */
     action?: string;
     /** Reason for access denial */
-    reason?: 'insufficient_permissions' | 'account_suspended' | 'resource_locked' | string;
+    reason?: 'insufficient_permissions' | 'account_suspended' | 'resource_locked' | 'origin_not_allowed' | string;
     /** Additional context */
     [key: string]: unknown;
 }
@@ -492,6 +512,115 @@ interface ErrorTransformContext {
     responseSample?: string;
     [key: string]: unknown;
 }
+/**
+ * SSE-specific error detail interfaces for BlaizeJS framework
+ *
+ * These interfaces define the structure of details for SSE errors.
+ * The actual error classes are implemented in blaize-core.
+ */
+/**
+ * Details for SSE connection errors
+ */
+interface SSEConnectionErrorDetails {
+    /** Client identifier if available */
+    clientId?: string;
+    /** Connection attempt number */
+    attemptNumber?: number;
+    /** Maximum retry attempts configured */
+    maxRetries?: number;
+    /** The underlying error that caused connection failure */
+    cause?: string;
+    /** Suggested resolution */
+    suggestion?: string;
+}
+/**
+ * Details for SSE buffer overflow errors
+ */
+interface SSEBufferOverflowErrorDetails {
+    /** Client identifier */
+    clientId?: string;
+    /** Current buffer size when overflow occurred */
+    currentSize: number;
+    /** Maximum buffer size configured */
+    maxSize: number;
+    /** Number of events dropped */
+    eventsDropped?: number;
+    /** Buffer strategy that was applied */
+    strategy: 'drop-oldest' | 'drop-newest' | 'close';
+    /** Event that triggered the overflow */
+    triggeringEvent?: string;
+}
+/**
+ * Details for SSE stream closed errors
+ */
+interface SSEStreamClosedErrorDetails {
+    /** Client identifier */
+    clientId?: string;
+    /** When the stream was closed */
+    closedAt?: string;
+    /** Reason for closure */
+    closeReason?: 'client-disconnect' | 'server-close' | 'timeout' | 'error' | 'buffer-overflow';
+    /** Whether reconnection is possible */
+    canReconnect?: boolean;
+    /** Suggested retry interval in milliseconds */
+    retryAfter?: number;
+}
+/**
+ * Context for SSE connection errors
+ */
+interface SSEConnectionErrorContext {
+    /** The SSE endpoint URL */
+    url: string;
+    /** Correlation ID for tracing */
+    correlationId: string;
+    /** Connection state when error occurred */
+    state: 'connecting' | 'connected' | 'disconnected' | 'closed';
+    /** Number of reconnection attempts made */
+    reconnectAttempts?: number;
+    /** The original error if available */
+    originalError?: Error;
+    /** Additional SSE-specific details */
+    sseDetails?: {
+        /** Whether credentials were included */
+        withCredentials?: boolean;
+        /** Last received event ID */
+        lastEventId?: string;
+        /** EventSource ready state */
+        readyState?: number;
+    };
+}
+/**
+ * Context for SSE stream errors (server-sent errors)
+ */
+interface SSEStreamErrorContext {
+    /** The SSE endpoint URL */
+    url: string;
+    /** Correlation ID from server or client */
+    correlationId: string;
+    /** Error message from server */
+    message: string;
+    /** Error code if provided */
+    code?: string;
+    /** Error name/type from server */
+    name?: string;
+    /** Raw error data from server */
+    rawData?: any;
+}
+/**
+ * Context for SSE heartbeat timeout errors
+ */
+interface SSEHeartbeatErrorContext {
+    /** The SSE endpoint URL */
+    url: string;
+    /** Correlation ID for tracing */
+    correlationId: string;
+    /** Configured heartbeat timeout in ms */
+    heartbeatTimeout: number;
+    /** Time since last event in ms */
+    timeSinceLastEvent?: number;
+    /** Last event ID received */
+    lastEventId?: string;
+}
 
 /**
  * Represents an uploaded file in a multipart/form-data request
@@ -1251,6 +1380,295 @@ type CreateOptionsRoute = <TState extends State = State, TServices extends Servi
  */
 declare function compose(middlewareStack: Middleware[]): MiddlewareFunction;
 
+/**
+ * CORS Types for BlaizeJS Framework
+ *
+ * Comprehensive type definitions for W3C-compliant CORS middleware
+ * with support for string, regex, and async function origin validation.
+ *
+ * @module @blaizejs/types/cors
+ */
+
+/**
+ * Origin configuration type supporting multiple validation methods
+ *
+ * @example
+ * ```typescript
+ * // String origin (exact match)
+ * const origin: CorsOrigin = 'https://example.com';
+ *
+ * // RegExp pattern
+ * const origin: CorsOrigin = /^https:\/\/.*\.example\.com$/;
+ *
+ * // Dynamic validation function
+ * const origin: CorsOrigin = async (origin, ctx) => {
+ *   return await checkOriginAllowed(origin, ctx?.state.user);
+ * };
+ *
+ * // Array of mixed types
+ * const origin: CorsOrigin = [
+ *   'https://localhost:3000',
+ *   /^https:\/\/.*\.example\.com$/,
+ *   (origin) => origin.endsWith('.trusted.com')
+ * ];
+ * ```
+ */
+type CorsOrigin = string | RegExp | ((origin: string, ctx?: Context<any, any>) => boolean | Promise<boolean>) | Array<string | RegExp | ((origin: string, ctx?: Context<any, any>) => boolean | Promise<boolean>)>;
+/**
+ * HTTP methods that can be allowed in CORS
+ * Based on W3C CORS specification
+ */
+type CorsHttpMethod = HttpMethod | 'CONNECT' | 'TRACE';
+/**
+ * Main CORS configuration options
+ *
+ * @example
+ * ```typescript
+ * const corsOptions: CorsOptions = {
+ *   origin: 'https://example.com',
+ *   methods: ['GET', 'POST'],
+ *   credentials: true,
+ *   maxAge: 86400
+ * };
+ * ```
+ */
+interface CorsOptions {
+    /**
+     * Configures the Access-Control-Allow-Origin header
+     *
+     * Possible values:
+     * - `true`: Allow all origins (sets to '*' unless credentials is true, then reflects origin)
+     * - `false`: Disable CORS (no headers set)
+     * - `string`: Specific origin to allow
+     * - `RegExp`: Pattern to match origins
+     * - `function`: Custom validation logic
+     * - `array`: Multiple origin configurations
+     *
+     * @default false
+     */
+    origin?: boolean | CorsOrigin;
+    /**
+     * Configures the Access-Control-Allow-Methods header
+     *
+     * @default ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE']
+     * @example ['GET', 'POST']
+     */
+    methods?: CorsHttpMethod[] | string;
+    /**
+     * Configures the Access-Control-Allow-Headers header
+     *
+     * Pass an array of allowed headers or a comma-delimited string.
+     *
+     * @default Request's Access-Control-Request-Headers header value
+     * @example ['Content-Type', 'Authorization']
+     */
+    allowedHeaders?: string[] | string;
+    /**
+     * Configures the Access-Control-Expose-Headers header
+     *
+     * Headers that the browser is allowed to access.
+     *
+     * @default []
+     * @example ['Content-Range', 'X-Content-Range']
+     */
+    exposedHeaders?: string[] | string;
+    /**
+     * Configures the Access-Control-Allow-Credentials header
+     *
+     * Set to true to allow credentials (cookies, authorization headers, TLS client certificates).
+     * Note: Cannot be used with origin: '*' for security reasons.
+     *
+     * @default false
+     */
+    credentials?: boolean;
+    /**
+     * Configures the Access-Control-Max-Age header in seconds
+     *
+     * Indicates how long browsers can cache preflight response.
+     * Set to -1 to disable caching.
+     *
+     * @default undefined (browser decides)
+     * @example 86400 // 24 hours
+     */
+    maxAge?: number;
+    /**
+     * Whether to pass the CORS preflight response to the next handler
+     *
+     * When false, the preflight response is sent immediately.
+     * When true, control passes to the next middleware/handler.
+     *
+     * @default false
+     */
+    preflightContinue?: boolean;
+    /**
+     * HTTP status code for successful OPTIONS requests
+     *
+     * Some legacy browsers require 200, while 204 is more correct.
+     *
+     * @default 204
+     */
+    optionsSuccessStatus?: number;
+}
+/**
+ * Internal CORS validation result
+ * Used by middleware implementation
+ */
+interface CorsValidationResult {
+    /**
+     * Whether the origin is allowed
+     */
+    allowed: boolean;
+    /**
+     * The origin value to set in the header
+     * Can be '*', specific origin, or 'null'
+     */
+    origin?: string;
+    /**
+     * Whether to add Vary: Origin header
+     */
+    vary?: boolean;
+}
+/**
+ * CORS preflight request information
+ * Extracted from OPTIONS request headers
+ */
+interface CorsPreflightInfo {
+    /**
+     * The origin making the request
+     */
+    origin?: string;
+    /**
+     * The method that will be used in the actual request
+     * From Access-Control-Request-Method header
+     */
+    requestedMethod?: string;
+    /**
+     * The headers that will be sent in the actual request
+     * From Access-Control-Request-Headers header
+     */
+    requestedHeaders?: string[];
+}
+/**
+ * Cache entry for origin validation results
+ * Used for performance optimization
+ */
+interface CorsOriginCacheEntry {
+    /**
+     * Whether the origin is allowed
+     */
+    allowed: boolean;
+    /**
+     * When this cache entry expires (timestamp)
+     */
+    expiresAt: number;
+    /**
+     * Optional user identifier for cache key
+     */
+    userId?: string;
+}
+/**
+ * Configuration for CORS origin validation cache
+ */
+interface CorsOriginCacheConfig {
+    /**
+     * Time-to-live for cache entries in milliseconds
+     * @default 60000 (1 minute)
+     */
+    ttl?: number;
+    /**
+     * Maximum number of entries in the cache
+     * @default 1000
+     */
+    maxSize?: number;
+    /**
+     * Whether to include user ID in cache key
+     * @default true
+     */
+    includeUserId?: boolean;
+}
+/**
+ * Statistics for CORS middleware performance monitoring
+ */
+interface CorsStats {
+    /**
+     * Total number of CORS requests processed
+     */
+    totalRequests: number;
+    /**
+     * Number of preflight requests handled
+     */
+    preflightRequests: number;
+    /**
+     * Number of allowed origins
+     */
+    allowedOrigins: number;
+    /**
+     * Number of denied origins
+     */
+    deniedOrigins: number;
+    /**
+     * Cache hit rate for origin validation
+     */
+    cacheHitRate: number;
+    /**
+     * Average origin validation time in milliseconds
+     */
+    avgValidationTime: number;
+}
+/**
+ * Cache entry type
+ */
+interface CacheEntry {
+    allowed: boolean;
+    expiresAt: number;
+    lastAccessed: number;
+}
+/**
+ * Cache configuration
+ */
+interface CacheConfig {
+    ttl: number;
+    maxSize: number;
+}
+
+/**
+ * Create CORS middleware with the specified options
+ *
+ * @param userOptions - CORS configuration options or boolean
+ * @returns Middleware function that handles CORS
+ *
+ * @example
+ * ```typescript
+ * import { cors } from '@blaize-core/middleware/cors';
+ *
+ * // Development mode - allow all origins
+ * server.use(cors(true));
+ *
+ * // Production - specific origin
+ * server.use(cors({
+ *   origin: 'https://app.example.com',
+ *   credentials: true,
+ *   maxAge: 86400
+ * }));
+ *
+ * // Multiple origins with regex
+ * server.use(cors({
+ *   origin: [
+ *     'https://app.example.com',
+ *     /^https:\/\/.*\.example\.com$/
+ *   ]
+ * }));
+ *
+ * // Dynamic origin validation
+ * server.use(cors({
+ *   origin: async (origin, ctx) => {
+ *     return await checkOriginAllowed(origin, ctx.state.user);
+ *   }
+ * }));
+ * ```
+ */
+declare function cors(userOptions?: CorsOptions | boolean): Middleware;
+
 /**
  * Create a middleware
  */
@@ -1276,6 +1694,438 @@ declare function stateMiddleware<T = {}>(handler: MiddlewareFunction): Middlewar
  */
 declare function serviceMiddleware<T = {}>(handler: MiddlewareFunction): Middleware<{}, T>;
 
+/**
+ * Represents a single Server-Sent Event
+ * @template T - The type of data payload
+ *
+ * @example
+ * ```typescript
+ * const event: SSEEvent<{ message: string }> = {
+ *   id: '123',
+ *   event: 'message',
+ *   data: { message: 'Hello, world!' },
+ *   retry: 5000
+ * };
+ * ```
+ */
+interface SSEEvent<T = unknown> {
+    /** Unique identifier for the event */
+    id: string;
+    /** Event type/name for client-side event listeners */
+    event: string;
+    /** The actual data payload of the event */
+    data: T;
+    /** Optional retry interval in milliseconds for reconnection */
+    retry?: number;
+}
+/**
+ * Backpressure handling strategies for SSE streams
+ *
+ * - `drop-oldest`: Remove oldest events from buffer when full
+ * - `drop-newest`: Reject new events when buffer is full
+ * - `close`: Close the stream when buffer limit is reached
+ */
+type SSEBufferStrategy = 'drop-oldest' | 'drop-newest' | 'close';
+/**
+ * Configuration options for SSE streams
+ *
+ * @example
+ * ```typescript
+ * const options: SSEOptions = {
+ *   autoClose: true,
+ *   maxBufferSize: 100,
+ *   bufferStrategy: 'drop-oldest'
+ * };
+ * ```
+ */
+interface SSEOptions {
+    /** ms between heartbeat pings (0 to disable) */
+    heartbeatInterval?: number;
+    /** Maximum size in bytes for a single event */
+    maxEventSize?: number;
+    /** Automatically close stream when client disconnects */
+    autoClose?: boolean;
+    /** Maximum number of events to buffer before applying strategy */
+    maxBufferSize?: number;
+    /** Strategy to handle buffer overflow conditions */
+    bufferStrategy?: SSEBufferStrategy;
+}
+/**
+ * Connection states for SSE streams
+ */
+type SSEConnectionState = 'connecting' | 'connected' | 'disconnected' | 'closed';
+/**
+ * SSE stream interface for managing server-sent events
+ *
+ * @example
+ * ```typescript
+ * const stream: SSEStream = createSSEStream(response);
+ *
+ * // Send typed event
+ * stream.send('notification', { type: 'info', message: 'Update available' });
+ *
+ * // Send error event
+ * stream.sendError(new Error('Processing failed'));
+ *
+ * // Clean up on close
+ * stream.onClose(() => {
+ *   console.log('Client disconnected');
+ * });
+ *
+ * // Close stream
+ * stream.close();
+ * ```
+ */
+interface SSEStream {
+    /**
+     * Send an event with typed data to the client
+     * @template T - Type of the data payload
+     * @param event - Event name/type
+     * @param data - Event data payload
+     */
+    send<T>(event: string, data: T): void;
+    /**
+     * Send an error event to the client
+     * @param error - Error object to send
+     */
+    sendError(error: Error): void;
+    /**
+     * Close the SSE stream connection
+     */
+    close(): void;
+    /**
+     * Register a callback for stream closure
+     * @param cb - Callback function to execute on close
+     */
+    onClose(cb: () => void): void;
+}
+/**
+ * Extended SSE stream with additional control methods
+ */
+interface SSEStreamExtended extends SSEStream {
+    readonly id: string;
+    [Symbol.asyncIterator](): AsyncGenerator<BufferedEvent, void, unknown>;
+    /** Current connection state */
+    readonly state: SSEConnectionState;
+    /** Number of events in the buffer */
+    readonly bufferSize: number;
+    /** Check if stream is writable */
+    readonly isWritable: boolean;
+    /**
+     * Ping the client to keep connection alive
+     * @param comment - Optional comment to include in ping
+     */
+    ping(comment?: string): void;
+    /**
+     * Set retry interval for client reconnection
+     * @param milliseconds - Retry interval in milliseconds
+     */
+    setRetry(milliseconds: number): void;
+    /**
+     * Flush any buffered events immediately
+     */
+    flush(): void;
+    getMetrics(): StreamMetrics;
+}
+/**
+ * SSE event serialization format
+ */
+interface SSESerializedEvent {
+    /** Event ID field */
+    id?: string;
+    /** Event type field */
+    event?: string;
+    /** Data field (can be multi-line) */
+    data: string;
+    /** Retry field */
+    retry?: number;
+    /** Comment field for keep-alive */
+    comment?: string;
+}
+/**
+ * SSE event handler function type
+ * @template T - Type of the event data
+ */
+type SSEEventHandler<T = unknown> = (event: SSEEvent<T>) => void | Promise<void>;
+/**
+ * SSE event listener registration
+ */
+interface SSEEventListener {
+    /** Event type to listen for (use '*' for all events) */
+    event: string;
+    /** Handler function for the event */
+    handler: SSEEventHandler;
+    /** Optional listener identifier for removal */
+    id?: string;
+}
+/**
+ * SSE metrics for monitoring stream performance
+ */
+interface SSEMetrics {
+    /** Total number of events sent */
+    eventsSent: number;
+    /** Total number of events dropped */
+    eventsDropped: number;
+    /** Current number of connected clients */
+    activeConnections: number;
+    /** Total bytes sent */
+    bytesSent: number;
+    /** Average event send latency in milliseconds */
+    averageLatency: number;
+    /** Connection duration in milliseconds */
+    connectionDuration: number;
+}
+/**
+ * SSE stream manager for handling multiple clients
+ */
+interface SSEStreamManager {
+    /**
+     * Create a new SSE stream for a client
+     * @param clientId - Unique identifier for the client
+     * @param options - Stream configuration options
+     */
+    createStream(clientId: string, options?: SSEOptions): SSEStream;
+    /**
+     * Get an existing stream by client ID
+     * @param clientId - Client identifier
+     */
+    getStream(clientId: string): SSEStream | undefined;
+    /**
+     * Broadcast an event to all connected clients
+     * @template T - Type of the event data
+     * @param event - Event name
+     * @param data - Event data
+     */
+    broadcast<T>(event: string, data: T): void;
+    /**
+     * Broadcast to specific clients
+     * @template T - Type of the event data
+     * @param clientIds - Array of client IDs
+     * @param event - Event name
+     * @param data - Event data
+     */
+    multicast<T>(clientIds: string[], event: string, data: T): void;
+    /**
+     * Close a specific client stream
+     * @param clientId - Client identifier
+     */
+    closeStream(clientId: string): void;
+    /**
+     * Close all active streams
+     */
+    closeAll(): void;
+    /**
+     * Get metrics for all streams
+     */
+    getMetrics(): SSEMetrics;
+}
+/**
+ * Result type for operations that can fail
+ */
+type RegistryResult<T> = {
+    success: true;
+    value: T;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Connection metadata stored in the registry
+ */
+interface ConnectionEntry {
+    stream: SSEStream;
+    connectedAt: number;
+    lastActivity: number;
+    clientIp?: string;
+    userAgent?: string;
+}
+/**
+ * Internal connection registry interface
+ */
+interface ConnectionRegistry {
+    /** Add a new connection to the registry */
+    add: (id: string, stream: SSEStream, metadata?: {
+        clientIp?: string;
+        userAgent?: string;
+    }) => void;
+    /** Remove a connection from the registry */
+    remove: (id: string) => void;
+    /** Get current connection count */
+    count: () => number;
+    /** Clean up inactive or closed connections */
+    cleanup: () => void;
+    /** Get connection by ID (for internal use) */
+    get: (id: string) => SSEStream | undefined;
+    /** Check if a connection exists */
+    has: (id: string) => boolean;
+    /** Get all connection IDs */
+    getIds: () => string[];
+    /** Shutdown the registry and close all connections */
+    shutdown: () => void;
+}
+/**
+ * Extended stream interface for typed events
+ */
+interface TypedSSEStream<TEvents extends Record<string, z.ZodType>> extends SSEStreamExtended {
+    send<K extends keyof TEvents>(event: K & string, data: z.infer<TEvents[K]>): void;
+}
+/**
+ * Schema for SSE route validation with generic type parameters
+ */
+interface SSERouteSchema<P extends z.ZodType = z.ZodType<any>, Q extends z.ZodType = z.ZodType<any>, E = any> {
+    /** Parameter schema for validation */
+    params?: P;
+    /** Query schema for validation */
+    query?: Q;
+    /** Events schema for validation (SSE-specific, replaces response) */
+    events?: E;
+}
+/**
+ * SSE route handler function with stream as first parameter
+ * This is the user-facing API - they write handlers with this signature
+ */
+type SSERouteHandler<TStream extends SSEStreamExtended = SSEStreamExtended, TParams = Record<string, string>, TQuery = Record<string, string | string[] | undefined>, TState extends State = State, TServices extends Services = Services> = (stream: TStream, ctx: Context<TState, TServices, never, TQuery>, // SSE never has body
+params: TParams) => Promise<void> | void;
+/**
+ * SSE route creator with state and services support
+ * Returns a higher-order function to handle generics properly
+ *
+ * The return type matches what the implementation actually returns:
+ * - A route object with a GET property
+ * - The GET property contains the wrapped handler and schemas
+ * - The wrapped handler has the standard (ctx, params) signature expected by the router
+ */
+type CreateSSERoute = <TState extends State = State, TServices extends Services = Services>() => <P = never, Q = never, E = never>(config: {
+    schema?: {
+        params?: P extends never ? never : P;
+        query?: Q extends never ? never : Q;
+        events?: E extends never ? never : E;
+    };
+    handler: SSERouteHandler<E extends Record<string, z.ZodType> ? TypedSSEStream<E> : SSEStreamExtended, P extends z.ZodType ? Infer<P> : Record<string, string>, Q extends z.ZodType ? Infer<Q> : QueryParams, TState, TServices>;
+    middleware?: Middleware[];
+    options?: Record<string, unknown>;
+}) => {
+    GET: {
+        handler: (ctx: any, params: any) => Promise<void>;
+        schema?: {
+            params?: P extends never ? undefined : P;
+            query?: Q extends never ? undefined : Q;
+        };
+        middleware?: Middleware[];
+        options?: Record<string, unknown>;
+    };
+    path: string;
+};
+/**
+ * Buffered event with metadata
+ */
+interface BufferedEvent {
+    id: string;
+    event: string;
+    data: unknown;
+    size: number;
+    timestamp: number;
+    correlationId: string;
+}
+/**
+ * Stream metrics for monitoring
+ */
+interface StreamMetrics {
+    eventsSent: number;
+    eventsDropped: number;
+    bytesWritten: number;
+    bufferHighWatermark: number;
+    lastEventTime: number;
+}
+
+/**
+ * SSE Client Types for BlaizeJS
+ * Location: packages/blaize-client/src/sse/types.ts
+ */
+
+/**
+ * Event handlers map
+ */
+interface EventHandlers {
+    [event: string]: Set<(data: any) => void>;
+}
+/**
+ * SSE connection configuration options
+ */
+interface SSEClientOptions {
+    headers?: Record<string, string>;
+    withCredentials?: boolean;
+    reconnect?: {
+        enabled: boolean;
+        maxAttempts?: number;
+        strategy?: ReconnectStrategy;
+        initialDelay?: number;
+    };
+    bufferMissedEvents?: boolean;
+    maxMissedEvents?: number;
+    heartbeatTimeout?: number;
+    parseJSON?: boolean;
+    /**
+     * Whether to wait for connection before resolving the promise.
+     * If false, returns the client immediately without waiting.
+     * Default: true
+     */
+    waitForConnection?: boolean;
+    /**
+     * Optional timeout for initial connection in milliseconds.
+     * If not set, no timeout is applied (relies on EventSource native timeout).
+     * Only applies if waitForConnection is true.
+     */
+    connectionTimeout?: number;
+}
+/**
+ * Metrics for SSE connection monitoring
+ */
+interface SSEClientMetrics {
+    eventsReceived: number;
+    bytesReceived: number;
+    connectionDuration: number;
+    reconnectAttempts: number;
+    lastEventId?: string;
+}
+/**
+ * Reconnection delay calculation strategy
+ */
+type ReconnectStrategy = (attempt: number) => number;
+/**
+ * SSE Client interface with type-safe event handling
+ */
+interface SSEClient<TEvents extends Record<string, unknown> = Record<string, unknown>> {
+    on<K extends keyof TEvents>(event: K & string, handler: (data: TEvents[K]) => void): void;
+    on(event: 'error', handler: (error: BlaizeError) => void): void;
+    on(event: 'open', handler: () => void): void;
+    on(event: 'close', handler: (event: CloseEvent) => void): void;
+    off<K extends keyof TEvents>(event: K & string, handler?: (data: TEvents[K]) => void): void;
+    off(event: 'error', handler?: (error: BlaizeError) => void): void;
+    off(event: 'open', handler?: () => void): void;
+    off(event: 'close', handler?: (event: CloseEvent) => void): void;
+    once<K extends keyof TEvents>(event: K & string, handler: (data: TEvents[K]) => void): void;
+    once(event: 'error', handler: (error: BlaizeError) => void): void;
+    once(event: 'open', handler: () => void): void;
+    once(event: 'close', handler: (event: CloseEvent) => void): void;
+    close(): void;
+    readonly state: SSEConnectionState;
+    readonly metrics: SSEClientMetrics;
+    readonly lastEventId?: string;
+}
+/**
+ * Close event for SSE connections
+ */
+interface CloseEvent {
+    reconnect: boolean;
+    reason?: string;
+}
+/**
+ * Internal SSE connection factory
+ * Returns a Promise that resolves to an SSEClient instance
+ */
+type SSEConnectionFactory<TEvents extends Record<string, unknown> = Record<string, unknown>> = (options?: SSEClientOptions) => Promise<SSEClient<TEvents>>;
+
 type ExtractMethod<T> = T extends {
     GET: any;
 } ? 'GET' : T extends {
@@ -1331,6 +2181,7 @@ interface ClientConfig {
     baseUrl: string;
     defaultHeaders?: Record<string, string>;
     timeout?: number;
+    sse?: SSEClientOptions;
 }
 interface InternalRequestArgs {
     params?: Record<string, any>;
@@ -1344,6 +2195,77 @@ interface RequestOptions {
     body?: string;
     timeout: number;
 }
+/**
+ * Detect if a route has SSE support
+ * SSE routes have a special 'SSE' method key
+ */
+type HasSSEMethod<TRoute> = TRoute extends {
+    SSE: any;
+} ? true : false;
+/**
+ * Extract SSE event types from route schema
+ */
+type ExtractSSEEvents<TRoute> = TRoute extends {
+    SSE: {
+        events?: infer E;
+    };
+} ? E extends z.ZodType ? z.infer<E> : Record<string, unknown> : Record<string, unknown>;
+/**
+ * Extract SSE query parameters from route
+ */
+type ExtractSSEQuery<TRoute> = TRoute extends {
+    SSE: {
+        schema?: {
+            query?: infer Q;
+        };
+    };
+} ? Q extends z.ZodType ? z.infer<Q> : Record<string, unknown> : never;
+/**
+ * Extract SSE params from route
+ */
+type ExtractSSEParams<TRoute> = TRoute extends {
+    SSE: {
+        schema?: {
+            params?: infer P;
+        };
+    };
+} ? P extends z.ZodType ? z.infer<P> : Record<string, string> : never;
+/**
+ * Build SSE method arguments
+ */
+type BuildSSEArgs<TRoute> = ExtractSSEParams<TRoute> extends never ? ExtractSSEQuery<TRoute> extends never ? {
+    options?: SSEClientOptions;
+} : {
+    query: ExtractSSEQuery<TRoute>;
+    options?: SSEClientOptions;
+} : ExtractSSEQuery<TRoute> extends never ? {
+    params: ExtractSSEParams<TRoute>;
+    options?: SSEClientOptions;
+} : {
+    params: ExtractSSEParams<TRoute>;
+    query: ExtractSSEQuery<TRoute>;
+    options?: SSEClientOptions;
+};
+/**
+ * Create SSE client method
+ */
+type CreateSSEMethod<TRoute> = HasSSEMethod<TRoute> extends true ? BuildSSEArgs<TRoute> extends {
+    options?: SSEClientOptions;
+} ? (args?: BuildSSEArgs<TRoute>) => Promise<SSEClient<ExtractSSEEvents<TRoute>>> : (args: BuildSSEArgs<TRoute>) => Promise<SSEClient<ExtractSSEEvents<TRoute>>> : never;
+/**
+ * Extract SSE routes from registry
+ */
+type ExtractSSERoutes<TRoutes extends Record<string, any>> = {
+    [K in keyof TRoutes as HasSSEMethod<TRoutes[K]> extends true ? K : never]: TRoutes[K];
+};
+/**
+ * Enhanced client with SSE support
+ */
+type CreateEnhancedClient<TRoutes extends Record<string, any>, TRegistry> = TRegistry & {
+    $sse: {
+        [K in keyof ExtractSSERoutes<TRoutes>]: CreateSSEMethod<TRoutes[K]>;
+    };
+};
 
 /**
  * BlaizeJS Server Module - Enhanced with Correlation Configuration
@@ -1411,6 +2333,35 @@ interface ServerOptionsInput {
      * @since 0.4.0
      */
     correlation?: CorrelationOptions;
+    /**
+     * CORS configuration
+     *
+     * - `true`: Enable CORS with development defaults (allow all origins)
+     * - `false`: Disable CORS (no headers set)
+     * - `CorsOptions`: Custom CORS configuration
+     *
+     * @default false (CORS disabled)
+     * @since 0.5.0
+     *
+     * @example
+     * ```typescript
+     * // Enable with dev defaults
+     * const server = createServer({ cors: true });
+     *
+     * // Custom configuration
+     * const server = createServer({
+     *   cors: {
+     *     origin: 'https://example.com',
+     *     credentials: true,
+     *     maxAge: 86400
+     *   }
+     * });
+     *
+     * // Disable CORS
+     * const server = createServer({ cors: false });
+     * ```
+     */
+    cors?: CorsOptions | boolean;
 }
 /**
  * Configuration for a BlaizeJS server
@@ -1440,6 +2391,11 @@ interface ServerOptions {
      * @since 0.4.0
      */
     correlation?: CorrelationOptions;
+    /**
+     * CORS configuration
+     * @since 0.5.0
+     */
+    cors?: CorsOptions | boolean;
 }
 /**
  * BlaizeJS Server instance with generic type accumulation
@@ -1453,6 +2409,8 @@ interface Server<TState, TServices> {
     server: http.Server | http2.Http2Server | undefined;
     /** The port the server is configured to listen on */
     port: number;
+    /** CORS configuration for this server */
+    corsOptions?: CorsOptions | boolean;
     /** The host the server is bound to */
     host: string;
     events: EventEmitter;
@@ -1560,7 +2518,7 @@ interface Plugin<TState = {}, TServices = {}> extends PluginHooks {
 /**
  * Plugin factory function
  */
-type PluginFactory<T = any, TState extends Record<string, unknown> = {}, TServices extends Record<string, unknown> = {}> = (options?: T) => Plugin<TState, TServices>;
+type PluginFactory<TConfig = any, TState = {}, TServices = {}> = (options?: TConfig) => Plugin<TState, TServices>;
 interface PluginLifecycleManager {
     initializePlugins(server: Server<any, any>): Promise<void>;
     terminatePlugins(server: Server<any, any>): Promise<void>;
@@ -1822,7 +2780,7 @@ declare function createPluginArray<T extends ReadonlyArray<Plugin<any, any>>>(..
 /**
  * Create a plugin with the given name, version, and setup function
  */
-declare function create$1<T = any>(name: string, version: string, setup: (app: UnknownServer, options: T) => void | Partial<PluginHooks> | Promise<void> | Promise<Partial<PluginHooks>>, defaultOptions?: Partial<T>): PluginFactory<T>;
+declare function create$1<TConfig = any, TState = {}, TServices = {}>(name: string, version: string, setup: (app: UnknownServer, options: TConfig) => void | Partial<PluginHooks> | Promise<void> | Promise<Partial<PluginHooks>>, defaultOptions?: Partial<TConfig>): PluginFactory<TConfig, TState, TServices>;
 
 /**
  * Create a GET route
@@ -1968,7 +2926,53 @@ declare function createRouteFactory<TState extends State = State, TServices exte
         OPTIONS: RouteMethodOptions<P extends never ? never : P extends zod.ZodType<any, zod.ZodTypeDef, any> ? P : never, Q extends never ? never : Q extends zod.ZodType<any, zod.ZodTypeDef, any> ? Q : never, never, R extends never ? never : R extends zod.ZodType<any, zod.ZodTypeDef, any> ? R : never, zod.ZodType<any, zod.ZodTypeDef, any>>;
         path: string;
     };
+    readonly sse: <P = never, Q = never, E = never>(config: {
+        schema?: {
+            params?: (P extends never ? never : P) | undefined;
+            query?: (Q extends never ? never : Q) | undefined;
+            events?: (E extends never ? never : E) | undefined;
+        } | undefined;
+        handler: SSERouteHandler<E extends Record<string, zod.ZodType<any, zod.ZodTypeDef, any>> ? TypedSSEStream<E> : SSEStreamExtended, P extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<P> : Record<string, string>, Q extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<Q> : QueryParams, TState, TServices>;
+        middleware?: Middleware[];
+        options?: Record<string, unknown>;
+    }) => {
+        GET: {
+            handler: (ctx: any, params: any) => Promise<void>;
+            schema?: {
+                params?: (P extends never ? undefined : P) | undefined;
+                query?: (Q extends never ? undefined : Q) | undefined;
+            } | undefined;
+            middleware?: Middleware[];
+            options?: Record<string, unknown>;
+        };
+        path: string;
+    };
+};
+
+/**
+ * Create a route matcher
+ */
+declare function createMatcher(): Matcher;
+
+/**
+ * Extract parameter values from a URL path
+ */
+declare function extractParams(path: string, pattern: RegExp, paramNames: string[]): Record<string, string>;
+/**
+ * Compile a path pattern with parameters
+ */
+declare function compilePathPattern(path: string): {
+    pattern: RegExp;
+    paramNames: string[];
 };
+/**
+ * Convert parameters object to URL query string
+ */
+declare function paramsToQuery(params: Record<string, string | number | boolean>): string;
+/**
+ * Build a URL with path parameters
+ */
+declare function buildUrl(pathPattern: string, params?: Record<string, string | number | boolean>, query?: Record<string, string | number | boolean>): string;
 
 /**
  * Creates a BlaizeJS server instance
@@ -2315,14 +3319,37 @@ declare class RequestTimeoutError extends BlaizeError {
     constructor(title: string, details?: unknown, correlationId?: string);
 }
 
-declare class UnsupportedMediaTypeError extends BlaizeError {
+declare class UnprocessableEntityError extends BlaizeError {
     constructor(title: string, details?: unknown, correlationId?: string);
 }
 
-declare class UnprocessableEntityError extends BlaizeError {
+declare class UnsupportedMediaTypeError extends BlaizeError {
     constructor(title: string, details?: unknown, correlationId?: string);
 }
 
+/**
+ * Error thrown when a service is temporarily unavailable
+ *
+ * Automatically sets HTTP status to 503 and optionally includes Retry-After.
+ *
+ * @example Basic usage:
+ * ```typescript
+ * throw new ServiceNotAvailableError('Database unavailable');
+ * ```
+ *
+ * @example With retry guidance:
+ * ```typescript
+ * throw new ServiceNotAvailableError('Payment service down', {
+ *   service: 'stripe',
+ *   retryAfter: 30,
+ *   reason: 'circuit_breaker'
+ * });
+ * ```
+ */
+declare class ServiceNotAvailableError extends BlaizeError<ServiceNotAvailableDetails> {
+    constructor(title: string, details?: ServiceNotAvailableDetails | undefined, correlationId?: string | undefined);
+}
+
 declare const VERSION = "0.1.0";
 declare const ServerAPI: {
     createServer: typeof create;
@@ -2337,12 +3364,18 @@ declare const RouterAPI: {
     createPostRoute: CreatePostRoute;
     createPutRoute: CreatePutRoute;
     createRouteFactory: typeof createRouteFactory;
+    createMatcher: typeof createMatcher;
+    extractParams: typeof extractParams;
+    compilePathPattern: typeof compilePathPattern;
+    paramsToQuery: typeof paramsToQuery;
+    buildUrl: typeof buildUrl;
 };
 declare const MiddlewareAPI: {
     createMiddleware: typeof create$2;
     createServiceMiddleware: typeof serviceMiddleware;
     createStateMiddleware: typeof stateMiddleware;
     compose: typeof compose;
+    cors: typeof cors;
 };
 declare const PluginsAPI: {
     createPlugin: typeof create$1;
@@ -2368,12 +3401,18 @@ declare const Blaize: {
         createPostRoute: CreatePostRoute;
         createPutRoute: CreatePutRoute;
         createRouteFactory: typeof createRouteFactory;
+        createMatcher: typeof createMatcher;
+        extractParams: typeof extractParams;
+        compilePathPattern: typeof compilePathPattern;
+        paramsToQuery: typeof paramsToQuery;
+        buildUrl: typeof buildUrl;
     };
     Middleware: {
         createMiddleware: typeof create$2;
         createServiceMiddleware: typeof serviceMiddleware;
         createStateMiddleware: typeof stateMiddleware;
         compose: typeof compose;
+        cors: typeof cors;
     };
     Plugins: {
         createPlugin: typeof create$1;
@@ -2381,4 +3420,4 @@ declare const Blaize: {
     VERSION: string;
 };
 
-export { Blaize, BlaizeError, type BlaizeErrorResponse, type BodyParseError, type BuildRoutesRegistry, type ClientConfig, type ComposeMiddlewareServices, type ComposeMiddlewareStates, type ComposeMiddlewareTypes, type ComposePluginServices, type ComposePluginStates, type ComposePluginTypes, ConflictError, type ConflictErrorDetails, type Context, type ContextOptions, type ContextRequest, type ContextResponse, type CorrelationOptions, type CreateClient, type CreateContextFn, type CreateDeleteRoute, type CreateGetRoute, type CreateHeadRoute, type CreateOptionsRoute, type CreatePatchRoute, type CreatePostRoute, type CreatePutRoute, type ErrorHandlerOptions, ErrorSeverity, type ErrorTransformContext, ErrorType, type ExtractMethod, type ExtractMiddlewareServices, type ExtractMiddlewareState, type ExtractMiddlewareTypes, type ExtractPluginServices, type ExtractPluginState, type ExtractPluginTypes, type FileCache, type FindRouteFilesOptions, ForbiddenError, type ForbiddenErrorDetails, type GetContextFn, type Http2Options, type HttpMethod, type Infer, type InferContext, type InternalRequestArgs, InternalServerError, type InternalServerErrorDetails, type Matcher, type MergeServices, type MergeStates, type Middleware, MiddlewareAPI, type MiddlewareFunction, type MiddlewareOptions, type MultipartData, type MultipartError, type MultipartLimits, type NetworkErrorContext, type NextFunction, NotFoundError, type NotFoundErrorDetails, type ParseErrorContext, type ParseOptions, type ParseResult, type ParsedRoute, type ParserState, PayloadTooLargeError, type PayloadTooLargeErrorDetails, type Plugin, type PluginFactory, type PluginHooks, type PluginLifecycleManager, type PluginLifecycleOptions, type PluginOptions, PluginsAPI, type ProcessResponseOptions, type ProcessingConfig, type QueryParams, RateLimitError, type RateLimitErrorDetails, type ReloadMetrics, type RequestHandler, type RequestOptions, type RequestParams, RequestTimeoutError, type Result, type Route, type RouteDefinition, type RouteEntry, type RouteHandler, type RouteMatch, type RouteMethodOptions, type RouteNode, type RouteOptions, type RouteRegistry, type RouteSchema, type Router, RouterAPI, type RouterOptions, type SafeComposeMiddlewareServices, type SafeComposeMiddlewareStates, type SafeComposePluginServices, type SafeComposePluginStates, type SafeExtractMiddlewareServices, type SafeExtractMiddlewareState, type SafeExtractPluginServices, type SafeExtractPluginState, type Server, ServerAPI, type ServerOptions, type ServerOptionsInput, type Services, type StandardErrorResponse, type StartOptions, type State, type StopOptions, type StreamOptions, type TimeoutErrorContext, UnauthorizedError, type UnauthorizedErrorDetails, type UnifiedRequest, type UnifiedResponse, type UnionToIntersection, type UnknownFunction, type UnknownServer, UnprocessableEntityError, UnsupportedMediaTypeError, type UnsupportedMediaTypeErrorDetails, type UploadProgress, type UploadedFile, VERSION, type ValidationConfig, ValidationError, type ValidationErrorDetails, type ValidationFieldError, type WatchOptions, asMiddlewareArray, asPluginArray, compose, createDeleteRoute, createGetRoute, createHeadRoute, create$2 as createMiddleware, createMiddlewareArray, createOptionsRoute, createPatchRoute, create$1 as createPlugin, createPluginArray, createPostRoute, createPutRoute, createRouteFactory, create as createServer, serviceMiddleware as createServiceMiddleware, stateMiddleware as createStateMiddleware, getCorrelationId, inferContext, isBodyParseError, isMiddleware, isPlugin };
+export { Blaize, BlaizeError, type BlaizeErrorResponse, type BodyParseError, type BufferedEvent, type BuildRoutesRegistry, type BuildSSEArgs, type CacheConfig, type CacheEntry, type ClientConfig, type CloseEvent, type ComposeMiddlewareServices, type ComposeMiddlewareStates, type ComposeMiddlewareTypes, type ComposePluginServices, type ComposePluginStates, type ComposePluginTypes, ConflictError, type ConflictErrorDetails, type ConnectionEntry, type ConnectionRegistry, type Context, type ContextOptions, type ContextRequest, type ContextResponse, type CorrelationOptions, type CorsHttpMethod, type CorsOptions, type CorsOrigin, type CorsOriginCacheConfig, type CorsOriginCacheEntry, type CorsPreflightInfo, type CorsStats, type CorsValidationResult, type CreateClient, type CreateContextFn, type CreateDeleteRoute, type CreateEnhancedClient, type CreateGetRoute, type CreateHeadRoute, type CreateOptionsRoute, type CreatePatchRoute, type CreatePostRoute, type CreatePutRoute, type CreateSSEMethod, type CreateSSERoute, type ErrorHandlerOptions, ErrorSeverity, type ErrorTransformContext, ErrorType, type EventHandlers, type ExtractMethod, type ExtractMiddlewareServices, type ExtractMiddlewareState, type ExtractMiddlewareTypes, type ExtractPluginServices, type ExtractPluginState, type ExtractPluginTypes, type ExtractSSEEvents, type ExtractSSEParams, type ExtractSSEQuery, type ExtractSSERoutes, type FileCache, type FindRouteFilesOptions, ForbiddenError, type ForbiddenErrorDetails, type GetContextFn, type HasSSEMethod, type Http2Options, type HttpMethod, type Infer, type InferContext, type InternalRequestArgs, InternalServerError, type InternalServerErrorDetails, type Matcher, type MergeServices, type MergeStates, type Middleware, MiddlewareAPI, type MiddlewareFunction, type MiddlewareOptions, type MultipartData, type MultipartError, type MultipartLimits, type NetworkErrorContext, type NextFunction, NotFoundError, type NotFoundErrorDetails, type ParseErrorContext, type ParseOptions, type ParseResult, type ParsedRoute, type ParserState, PayloadTooLargeError, type PayloadTooLargeErrorDetails, type Plugin, type PluginFactory, type PluginHooks, type PluginLifecycleManager, type PluginLifecycleOptions, type PluginOptions, PluginsAPI, type ProcessResponseOptions, type ProcessingConfig, type QueryParams, RateLimitError, type RateLimitErrorDetails, type ReconnectStrategy, type RegistryResult, type ReloadMetrics, type RequestHandler, type RequestOptions, type RequestParams, RequestTimeoutError, type Result, type Route, type RouteDefinition, type RouteEntry, type RouteHandler, type RouteMatch, type RouteMethodOptions, type RouteNode, type RouteOptions, type RouteRegistry, type RouteSchema, type Router, RouterAPI, type RouterOptions, type SSEBufferOverflowErrorDetails, type SSEBufferStrategy, type SSEClient, type SSEClientMetrics, type SSEClientOptions, type SSEConnectionErrorContext, type SSEConnectionErrorDetails, type SSEConnectionFactory, type SSEConnectionState, type SSEEvent, type SSEEventHandler, type SSEEventListener, type SSEHeartbeatErrorContext, type SSEMetrics, type SSEOptions, type SSERouteHandler, type SSERouteSchema, type SSESerializedEvent, type SSEStream, type SSEStreamClosedErrorDetails, type SSEStreamErrorContext, type SSEStreamExtended, type SSEStreamManager, type SafeComposeMiddlewareServices, type SafeComposeMiddlewareStates, type SafeComposePluginServices, type SafeComposePluginStates, type SafeExtractMiddlewareServices, type SafeExtractMiddlewareState, type SafeExtractPluginServices, type SafeExtractPluginState, type Server, ServerAPI, type ServerOptions, type ServerOptionsInput, type ServiceNotAvailableDetails, ServiceNotAvailableError, type Services, type StandardErrorResponse, type StartOptions, type State, type StopOptions, type StreamMetrics, type StreamOptions, type TimeoutErrorContext, type TypedSSEStream, UnauthorizedError, type UnauthorizedErrorDetails, type UnifiedRequest, type UnifiedResponse, type UnionToIntersection, type UnknownFunction, type UnknownServer, UnprocessableEntityError, UnsupportedMediaTypeError, type UnsupportedMediaTypeErrorDetails, type UploadProgress, type UploadedFile, VERSION, type ValidationConfig, ValidationError, type ValidationErrorDetails, type ValidationFieldError, type WatchOptions, asMiddlewareArray, asPluginArray, buildUrl, compilePathPattern, compose, cors, createDeleteRoute, createGetRoute, createHeadRoute, createMatcher, create$2 as createMiddleware, createMiddlewareArray, createOptionsRoute, createPatchRoute, create$1 as createPlugin, createPluginArray, createPostRoute, createPutRoute, createRouteFactory, create as createServer, serviceMiddleware as createServiceMiddleware, stateMiddleware as createStateMiddleware, extractParams, getCorrelationId, inferContext, isBodyParseError, isMiddleware, isPlugin, paramsToQuery };