blaizejs 0.5.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
  *
@@ -210,7 +220,9 @@ declare enum ErrorType {
     /** SSE buffer overflow (503) */
     SSE_BUFFER_OVERFLOW = "SSE_BUFFER_OVERFLOW",
     /** SSE stream closed (410) */
-    SSE_STREAM_CLOSED = "SSE_STREAM_CLOSED"
+    SSE_STREAM_CLOSED = "SSE_STREAM_CLOSED",
+    /** Service temporarily unavailable (503) */
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
 }
 /**
  * Error severity levels for logging and monitoring
@@ -1369,853 +1381,891 @@ type CreateOptionsRoute = <TState extends State = State, TServices extends Servi
 declare function compose(middlewareStack: Middleware[]): MiddlewareFunction;
 
 /**
- * Create a middleware
- */
-declare function create$2<TState = {}, TServices = {}>(handlerOrOptions: MiddlewareFunction | MiddlewareOptions): Middleware<TState, TServices>;
-/**
- * Create a middleware that only contributes state (no services)
- * Convenience helper for state-only middleware
- *
- * @template T - Type of state to contribute
- * @param handler - Middleware function that adds state
- * @returns Middleware that contributes state only
- *
- */
-declare function stateMiddleware<T = {}>(handler: MiddlewareFunction): Middleware<T, {}>;
-/**
- * Create a middleware that only contributes services (no state)
- * Convenience helper for service-only middleware
+ * CORS Types for BlaizeJS Framework
  *
- * @template T - Type of services to contribute
- * @param handler - Middleware function that adds services
- * @returns Middleware that contributes services only
+ * Comprehensive type definitions for W3C-compliant CORS middleware
+ * with support for string, regex, and async function origin validation.
  *
+ * @module @blaizejs/types/cors
  */
-declare function serviceMiddleware<T = {}>(handler: MiddlewareFunction): Middleware<{}, T>;
 
 /**
- * Represents a single Server-Sent Event
- * @template T - The type of data payload
+ * Origin configuration type supporting multiple validation methods
  *
  * @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
+ * // String origin (exact match)
+ * const origin: CorsOrigin = 'https://example.com';
  *
- * - `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
+ * // RegExp pattern
+ * const origin: CorsOrigin = /^https:\/\/.*\.example\.com$/;
  *
- * @example
- * ```typescript
- * const options: SSEOptions = {
- *   autoClose: true,
- *   maxBufferSize: 100,
- *   bufferStrategy: 'drop-oldest'
+ * // 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')
+ * ];
  * ```
  */
-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;
-}
+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>)>;
 /**
- * Connection states for SSE streams
+ * HTTP methods that can be allowed in CORS
+ * Based on W3C CORS specification
  */
-type SSEConnectionState = 'connecting' | 'connected' | 'disconnected' | 'closed';
+type CorsHttpMethod = HttpMethod | 'CONNECT' | 'TRACE';
 /**
- * SSE stream interface for managing server-sent events
+ * Main CORS configuration options
  *
  * @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();
+ * const corsOptions: CorsOptions = {
+ *   origin: 'https://example.com',
+ *   methods: ['GET', 'POST'],
+ *   credentials: true,
+ *   maxAge: 86400
+ * };
  * ```
  */
-interface SSEStream {
+interface CorsOptions {
     /**
-     * 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
+     * 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
      */
-    send<T>(event: string, data: T): void;
+    origin?: boolean | CorsOrigin;
     /**
-     * Send an error event to the client
-     * @param error - Error object to send
+     * Configures the Access-Control-Allow-Methods header
+     *
+     * @default ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE']
+     * @example ['GET', 'POST']
      */
-    sendError(error: Error): void;
+    methods?: CorsHttpMethod[] | string;
     /**
-     * Close the SSE stream connection
+     * 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']
      */
-    close(): void;
+    allowedHeaders?: string[] | string;
     /**
-     * Register a callback for stream closure
-     * @param cb - Callback function to execute on close
+     * Configures the Access-Control-Expose-Headers header
+     *
+     * Headers that the browser is allowed to access.
+     *
+     * @default []
+     * @example ['Content-Range', 'X-Content-Range']
      */
-    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;
+    exposedHeaders?: string[] | string;
     /**
-     * Ping the client to keep connection alive
-     * @param comment - Optional comment to include in ping
+     * 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
      */
-    ping(comment?: string): void;
+    credentials?: boolean;
     /**
-     * Set retry interval for client reconnection
-     * @param milliseconds - Retry interval in milliseconds
+     * 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
      */
-    setRetry(milliseconds: number): void;
+    maxAge?: number;
     /**
-     * Flush any buffered events immediately
+     * 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
      */
-    flush(): void;
-    getMetrics(): StreamMetrics;
+    preflightContinue?: boolean;
+    /**
+     * HTTP status code for successful OPTIONS requests
+     *
+     * Some legacy browsers require 200, while 204 is more correct.
+     *
+     * @default 204
+     */
+    optionsSuccessStatus?: number;
 }
 /**
- * SSE event serialization format
+ * Internal CORS validation result
+ * Used by middleware implementation
  */
-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;
+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;
 }
 /**
- * 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
+ * CORS preflight request information
+ * Extracted from OPTIONS request headers
  */
-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;
+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[];
 }
 /**
- * SSE metrics for monitoring stream performance
+ * Cache entry for origin validation results
+ * Used for performance optimization
  */
-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;
+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;
 }
 /**
- * SSE stream manager for handling multiple clients
+ * Configuration for CORS origin validation cache
  */
-interface SSEStreamManager {
+interface CorsOriginCacheConfig {
     /**
-     * Create a new SSE stream for a client
-     * @param clientId - Unique identifier for the client
-     * @param options - Stream configuration options
+     * Time-to-live for cache entries in milliseconds
+     * @default 60000 (1 minute)
      */
-    createStream(clientId: string, options?: SSEOptions): SSEStream;
+    ttl?: number;
     /**
-     * Get an existing stream by client ID
-     * @param clientId - Client identifier
+     * Maximum number of entries in the cache
+     * @default 1000
      */
-    getStream(clientId: string): SSEStream | undefined;
+    maxSize?: number;
     /**
-     * Broadcast an event to all connected clients
-     * @template T - Type of the event data
-     * @param event - Event name
-     * @param data - Event data
+     * Whether to include user ID in cache key
+     * @default true
      */
-    broadcast<T>(event: string, data: T): void;
+    includeUserId?: boolean;
+}
+/**
+ * Statistics for CORS middleware performance monitoring
+ */
+interface CorsStats {
     /**
-     * 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
+     * Total number of CORS requests processed
      */
-    multicast<T>(clientIds: string[], event: string, data: T): void;
+    totalRequests: number;
     /**
-     * Close a specific client stream
-     * @param clientId - Client identifier
+     * Number of preflight requests handled
      */
-    closeStream(clientId: string): void;
+    preflightRequests: number;
     /**
-     * Close all active streams
+     * Number of allowed origins
      */
-    closeAll(): void;
+    allowedOrigins: number;
     /**
-     * Get metrics for all streams
+     * Number of denied origins
      */
-    getMetrics(): SSEMetrics;
+    deniedOrigins: number;
+    /**
+     * Cache hit rate for origin validation
+     */
+    cacheHitRate: number;
+    /**
+     * Average origin validation time in milliseconds
+     */
+    avgValidationTime: number;
 }
 /**
- * Result type for operations that can fail
- */
-type RegistryResult<T> = {
-    success: true;
-    value: T;
-} | {
-    success: false;
-    error: string;
-};
-/**
- * Connection metadata stored in the registry
+ * Cache entry type
  */
-interface ConnectionEntry {
-    stream: SSEStream;
-    connectedAt: number;
-    lastActivity: number;
-    clientIp?: string;
-    userAgent?: string;
+interface CacheEntry {
+    allowed: boolean;
+    expiresAt: number;
+    lastAccessed: number;
 }
 /**
- * Internal connection registry interface
+ * Cache configuration
  */
-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;
+interface CacheConfig {
+    ttl: number;
+    maxSize: number;
 }
+
 /**
- * Extended stream interface for typed events
+ * 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);
+ *   }
+ * }));
+ * ```
  */
-interface TypedSSEStream<TEvents extends Record<string, z.ZodType>> extends SSEStreamExtended {
-    send<K extends keyof TEvents>(event: K & string, data: z.infer<TEvents[K]>): void;
-}
+declare function cors(userOptions?: CorsOptions | boolean): Middleware;
+
 /**
- * Schema for SSE route validation with generic type parameters
+ * Create a middleware
  */
-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;
-}
+declare function create$2<TState = {}, TServices = {}>(handlerOrOptions: MiddlewareFunction | MiddlewareOptions): Middleware<TState, TServices>;
 /**
- * SSE route handler function with stream as first parameter
- * This is the user-facing API - they write handlers with this signature
+ * Create a middleware that only contributes state (no services)
+ * Convenience helper for state-only middleware
+ *
+ * @template T - Type of state to contribute
+ * @param handler - Middleware function that adds state
+ * @returns Middleware that contributes state only
+ *
  */
-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;
+declare function stateMiddleware<T = {}>(handler: MiddlewareFunction): Middleware<T, {}>;
 /**
- * SSE route creator with state and services support
- * Returns a higher-order function to handle generics properly
+ * Create a middleware that only contributes services (no state)
+ * Convenience helper for service-only middleware
+ *
+ * @template T - Type of services to contribute
+ * @param handler - Middleware function that adds services
+ * @returns Middleware that contributes services only
  *
- * 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;
-};
+declare function serviceMiddleware<T = {}>(handler: MiddlewareFunction): Middleware<{}, T>;
+
 /**
- * Buffered event with metadata
+ * 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 BufferedEvent {
+interface SSEEvent<T = unknown> {
+    /** Unique identifier for the event */
     id: string;
+    /** Event type/name for client-side event listeners */
     event: string;
-    data: unknown;
-    size: number;
-    timestamp: number;
-    correlationId: string;
+    /** The actual data payload of the event */
+    data: T;
+    /** Optional retry interval in milliseconds for reconnection */
+    retry?: number;
 }
 /**
- * Stream metrics for monitoring
- */
-interface StreamMetrics {
-    eventsSent: number;
-    eventsDropped: number;
-    bytesWritten: number;
-    bufferHighWatermark: number;
-    lastEventTime: 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;
 }
-
 /**
- * SSE Client Types for BlaizeJS
- * Location: packages/blaize-client/src/sse/types.ts
+ * Connection states for SSE streams
  */
-
+type SSEConnectionState = 'connecting' | 'connected' | 'disconnected' | 'closed';
 /**
- * Event handlers map
+ * 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 EventHandlers {
-    [event: string]: Set<(data: any) => void>;
+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;
 }
 /**
- * SSE connection configuration options
+ * Extended SSE stream with additional control methods
  */
-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;
+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;
     /**
-     * Whether to wait for connection before resolving the promise.
-     * If false, returns the client immediately without waiting.
-     * Default: true
+     * Ping the client to keep connection alive
+     * @param comment - Optional comment to include in ping
      */
-    waitForConnection?: boolean;
+    ping(comment?: string): void;
     /**
-     * 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.
+     * Set retry interval for client reconnection
+     * @param milliseconds - Retry interval in milliseconds
      */
-    connectionTimeout?: number;
+    setRetry(milliseconds: number): void;
+    /**
+     * Flush any buffered events immediately
+     */
+    flush(): void;
+    getMetrics(): StreamMetrics;
 }
 /**
- * Metrics for SSE connection monitoring
+ * SSE event serialization format
  */
-interface SSEClientMetrics {
-    eventsReceived: number;
-    bytesReceived: number;
-    connectionDuration: number;
-    reconnectAttempts: number;
-    lastEventId?: string;
+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;
 }
 /**
- * Reconnection delay calculation strategy
+ * SSE event handler function type
+ * @template T - Type of the event data
  */
-type ReconnectStrategy = (attempt: number) => number;
+type SSEEventHandler<T = unknown> = (event: SSEEvent<T>) => void | Promise<void>;
 /**
- * SSE Client interface with type-safe event handling
+ * SSE event listener registration
  */
-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;
+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;
 }
 /**
- * Close event for SSE connections
+ * SSE metrics for monitoring stream performance
  */
-interface CloseEvent {
-    reconnect: boolean;
-    reason?: string;
+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;
 }
 /**
- * Internal SSE connection factory
- * Returns a Promise that resolves to an SSEClient instance
+ * SSE stream manager for handling multiple clients
  */
-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 {
-    POST: any;
-} ? 'POST' : T extends {
-    PUT: any;
-} ? 'PUT' : T extends {
-    DELETE: any;
-} ? 'DELETE' : T extends {
-    PATCH: any;
-} ? 'PATCH' : T extends {
-    HEAD: any;
-} ? 'HEAD' : T extends {
-    OPTIONS: any;
-} ? 'OPTIONS' : never;
-type BuildRoutesRegistry<TRoutes extends Record<string, any>> = {
-    [Method in ExtractMethod<TRoutes[keyof TRoutes]> as `$${Lowercase<Method>}`]: {
-        [K in keyof TRoutes as ExtractMethod<TRoutes[K]> extends Method ? K : never]: TRoutes[K];
-    };
-};
-type GetRouteMethodOptions<TRoute> = TRoute extends {
-    GET: infer M;
-} ? M : TRoute extends {
-    POST: infer M;
-} ? M : TRoute extends {
-    PUT: infer M;
-} ? M : TRoute extends {
-    DELETE: infer M;
-} ? M : TRoute extends {
-    PATCH: infer M;
-} ? M : TRoute extends {
-    HEAD: infer M;
-} ? M : TRoute extends {
-    OPTIONS: infer M;
-} ? M : never;
-type IsNever$1<T> = [T] extends [never] ? true : false;
-type BuildArgsObject<P, Q, B> = (IsNever$1<P> extends true ? {} : {
-    params: Infer<P>;
-}) & (IsNever$1<Q> extends true ? {} : {
-    query: Infer<Q>;
-}) & (IsNever$1<B> extends true ? {} : {
-    body: Infer<B>;
-});
-type IsEmptyObject<T> = keyof T extends never ? true : false;
-type BuildArgs<P, Q, B> = IsEmptyObject<BuildArgsObject<P, Q, B>> extends true ? void : BuildArgsObject<P, Q, B>;
-type CreateClientMethod<TRoute> = GetRouteMethodOptions<TRoute> extends RouteMethodOptions<infer P, infer Q, infer B, infer R> ? BuildArgs<P, Q, B> extends void ? () => Promise<R extends z.ZodType ? Infer<R> : unknown> : (args: BuildArgs<P, Q, B>) => Promise<R extends z.ZodType ? Infer<R> : unknown> : never;
-type CreateClient<TRoutes extends Record<string, Record<string, any>>> = {
-    [Method in keyof TRoutes]: {
-        [RouteName in keyof TRoutes[Method]]: CreateClientMethod<TRoutes[Method][RouteName]>;
-    };
-};
-interface ClientConfig {
-    baseUrl: string;
-    defaultHeaders?: Record<string, string>;
-    timeout?: number;
-    sse?: SSEClientOptions;
-}
-interface InternalRequestArgs {
-    params?: Record<string, any>;
-    query?: Record<string, any>;
-    body?: any;
-}
-interface RequestOptions {
-    method: string;
-    url: string;
-    headers: Record<string, string>;
-    body?: string;
-    timeout: number;
+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;
 }
 /**
- * Detect if a route has SSE support
- * SSE routes have a special 'SSE' method key
+ * Result type for operations that can fail
  */
-type HasSSEMethod<TRoute> = TRoute extends {
-    SSE: any;
-} ? true : false;
+type RegistryResult<T> = {
+    success: true;
+    value: T;
+} | {
+    success: false;
+    error: string;
+};
 /**
- * Extract SSE event types from route schema
+ * Connection metadata stored in the registry
  */
-type ExtractSSEEvents<TRoute> = TRoute extends {
-    SSE: {
-        events?: infer E;
-    };
-} ? E extends z.ZodType ? z.infer<E> : Record<string, unknown> : Record<string, unknown>;
+interface ConnectionEntry {
+    stream: SSEStream;
+    connectedAt: number;
+    lastActivity: number;
+    clientIp?: string;
+    userAgent?: string;
+}
 /**
- * Extract SSE query parameters from route
+ * Internal connection registry interface
  */
-type ExtractSSEQuery<TRoute> = TRoute extends {
-    SSE: {
-        schema?: {
-            query?: infer Q;
-        };
-    };
-} ? Q extends z.ZodType ? z.infer<Q> : Record<string, unknown> : never;
+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;
+}
 /**
- * Extract SSE params from route
+ * Extended stream interface for typed events
  */
-type ExtractSSEParams<TRoute> = TRoute extends {
-    SSE: {
-        schema?: {
-            params?: infer P;
-        };
-    };
-} ? P extends z.ZodType ? z.infer<P> : Record<string, string> : never;
+interface TypedSSEStream<TEvents extends Record<string, z.ZodType>> extends SSEStreamExtended {
+    send<K extends keyof TEvents>(event: K & string, data: z.infer<TEvents[K]>): void;
+}
 /**
- * Build SSE method arguments
+ * Schema for SSE route validation with generic type parameters
  */
-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;
-};
+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;
+}
 /**
- * Create SSE client method
+ * SSE route handler function with stream as first parameter
+ * This is the user-facing API - they write handlers with this signature
  */
-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;
+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;
 /**
- * Extract SSE routes from registry
+ * 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 ExtractSSERoutes<TRoutes extends Record<string, any>> = {
-    [K in keyof TRoutes as HasSSEMethod<TRoutes[K]> extends true ? K : never]: TRoutes[K];
+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;
 };
 /**
- * Enhanced client with SSE support
+ * Buffered event with metadata
  */
-type CreateEnhancedClient<TRoutes extends Record<string, any>, TRegistry> = TRegistry & {
-    $sse: {
-        [K in keyof ExtractSSERoutes<TRoutes>]: CreateSSEMethod<TRoutes[K]>;
-    };
-};
-
+interface BufferedEvent {
+    id: string;
+    event: string;
+    data: unknown;
+    size: number;
+    timestamp: number;
+    correlationId: string;
+}
 /**
- * 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
+ * Stream metrics for monitoring
  */
+interface StreamMetrics {
+    eventsSent: number;
+    eventsDropped: number;
+    bytesWritten: number;
+    bufferHighWatermark: number;
+    lastEventTime: number;
+}
 
 /**
- * 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')
- * ];
- * ```
+ * SSE Client Types for BlaizeJS
+ * Location: packages/blaize-client/src/sse/types.ts
  */
-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
+ * Event handlers map
  */
-type CorsHttpMethod = HttpMethod | 'CONNECT' | 'TRACE';
+interface EventHandlers {
+    [event: string]: Set<(data: any) => void>;
+}
 /**
- * Main CORS configuration options
- *
- * @example
- * ```typescript
- * const corsOptions: CorsOptions = {
- *   origin: 'https://example.com',
- *   methods: ['GET', 'POST'],
- *   credentials: true,
- *   maxAge: 86400
- * };
- * ```
+ * SSE connection configuration options
  */
-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;
+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 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
+     * Whether to wait for connection before resolving the promise.
+     * If false, returns the client immediately without waiting.
+     * Default: true
      */
-    preflightContinue?: boolean;
+    waitForConnection?: boolean;
     /**
-     * HTTP status code for successful OPTIONS requests
-     *
-     * Some legacy browsers require 200, while 204 is more correct.
-     *
-     * @default 204
+     * 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.
      */
-    optionsSuccessStatus?: number;
+    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 {
+    POST: any;
+} ? 'POST' : T extends {
+    PUT: any;
+} ? 'PUT' : T extends {
+    DELETE: any;
+} ? 'DELETE' : T extends {
+    PATCH: any;
+} ? 'PATCH' : T extends {
+    HEAD: any;
+} ? 'HEAD' : T extends {
+    OPTIONS: any;
+} ? 'OPTIONS' : never;
+type BuildRoutesRegistry<TRoutes extends Record<string, any>> = {
+    [Method in ExtractMethod<TRoutes[keyof TRoutes]> as `$${Lowercase<Method>}`]: {
+        [K in keyof TRoutes as ExtractMethod<TRoutes[K]> extends Method ? K : never]: TRoutes[K];
+    };
+};
+type GetRouteMethodOptions<TRoute> = TRoute extends {
+    GET: infer M;
+} ? M : TRoute extends {
+    POST: infer M;
+} ? M : TRoute extends {
+    PUT: infer M;
+} ? M : TRoute extends {
+    DELETE: infer M;
+} ? M : TRoute extends {
+    PATCH: infer M;
+} ? M : TRoute extends {
+    HEAD: infer M;
+} ? M : TRoute extends {
+    OPTIONS: infer M;
+} ? M : never;
+type IsNever$1<T> = [T] extends [never] ? true : false;
+type BuildArgsObject<P, Q, B> = (IsNever$1<P> extends true ? {} : {
+    params: Infer<P>;
+}) & (IsNever$1<Q> extends true ? {} : {
+    query: Infer<Q>;
+}) & (IsNever$1<B> extends true ? {} : {
+    body: Infer<B>;
+});
+type IsEmptyObject<T> = keyof T extends never ? true : false;
+type BuildArgs<P, Q, B> = IsEmptyObject<BuildArgsObject<P, Q, B>> extends true ? void : BuildArgsObject<P, Q, B>;
+type CreateClientMethod<TRoute> = GetRouteMethodOptions<TRoute> extends RouteMethodOptions<infer P, infer Q, infer B, infer R> ? BuildArgs<P, Q, B> extends void ? () => Promise<R extends z.ZodType ? Infer<R> : unknown> : (args: BuildArgs<P, Q, B>) => Promise<R extends z.ZodType ? Infer<R> : unknown> : never;
+type CreateClient<TRoutes extends Record<string, Record<string, any>>> = {
+    [Method in keyof TRoutes]: {
+        [RouteName in keyof TRoutes[Method]]: CreateClientMethod<TRoutes[Method][RouteName]>;
+    };
+};
+interface ClientConfig {
+    baseUrl: string;
+    defaultHeaders?: Record<string, string>;
+    timeout?: number;
+    sse?: SSEClientOptions;
+}
+interface InternalRequestArgs {
+    params?: Record<string, any>;
+    query?: Record<string, any>;
+    body?: any;
+}
+interface RequestOptions {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: string;
+    timeout: number;
 }
 /**
- * Internal CORS validation result
- * Used by middleware implementation
+ * Detect if a route has SSE support
+ * SSE routes have a special 'SSE' method key
  */
-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;
-}
+type HasSSEMethod<TRoute> = TRoute extends {
+    SSE: any;
+} ? true : false;
 /**
- * CORS preflight request information
- * Extracted from OPTIONS request headers
+ * Extract SSE event types from route schema
  */
-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[];
-}
+type ExtractSSEEvents<TRoute> = TRoute extends {
+    SSE: {
+        events?: infer E;
+    };
+} ? E extends z.ZodType ? z.infer<E> : Record<string, unknown> : Record<string, unknown>;
 /**
- * Cache entry for origin validation results
- * Used for performance optimization
+ * Extract SSE query parameters from route
  */
-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;
-}
+type ExtractSSEQuery<TRoute> = TRoute extends {
+    SSE: {
+        schema?: {
+            query?: infer Q;
+        };
+    };
+} ? Q extends z.ZodType ? z.infer<Q> : Record<string, unknown> : never;
 /**
- * Configuration for CORS origin validation cache
+ * Extract SSE params from route
  */
-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;
-}
+type ExtractSSEParams<TRoute> = TRoute extends {
+    SSE: {
+        schema?: {
+            params?: infer P;
+        };
+    };
+} ? P extends z.ZodType ? z.infer<P> : Record<string, string> : never;
 /**
- * Statistics for CORS middleware performance monitoring
+ * Build SSE method arguments
  */
-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;
-}
+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;
+};
 /**
- * Cache entry type
+ * Create SSE client method
  */
-interface CacheEntry {
-    allowed: boolean;
-    expiresAt: number;
-    lastAccessed: number;
-}
+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;
 /**
- * Cache configuration
+ * Extract SSE routes from registry
  */
-interface CacheConfig {
-    ttl: number;
-    maxSize: number;
-}
+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
@@ -2468,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>;
@@ -2730,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
@@ -2899,6 +2949,31 @@ declare function createRouteFactory<TState extends State = State, TServices exte
     };
 };
 
+/**
+ * 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
  */
@@ -3244,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;
@@ -3266,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;
@@ -3297,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;
@@ -3310,4 +3420,4 @@ declare const Blaize: {
     VERSION: string;
 };
 
-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 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, 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 };