@plyaz/types 1.35.4 → 1.36.1

package/dist/core/events/streaming/responses.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Stream Response Types
+ *
+ * Response types for real-time streaming that follow the API patterns.
+ * Uses standard ErrorResponse from @plyaz/types/errors.
+ */
+import type { ErrorResponse, PackageErrorLike } from '../../../errors/types';
+import type { StreamAuthResult, StreamConnection, StreamMessage } from './types';
+/**
+ * Stream response wrapper - consistent with API ReturnResponseType
+ */
+export interface StreamResponse<T = unknown> {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Human-readable message */
+    message: string;
+    /** Response data payload */
+    data?: T;
+    /** Channel this response is for */
+    channel: string;
+    /** Unix timestamp when response was created */
+    timestamp: number;
+    /** Correlation ID for tracing */
+    correlationId?: string;
+}
+/**
+ * Stream error event - uses standard ErrorResponse
+ */
+export interface StreamErrorEvent {
+    /** Always false for errors */
+    success: false;
+    /** Standard ErrorResponse array from @plyaz/types/errors */
+    errors: ErrorResponse;
+    /** Channel this error occurred on */
+    channel: string;
+    /** Unix timestamp when error occurred */
+    timestamp: number;
+    /** Correlation ID for tracing */
+    correlationId?: string;
+}
+/**
+ * Paginated stream response for large datasets
+ */
+export interface PaginatedStreamResponse<T = unknown> extends StreamResponse<T[]> {
+    /** Pagination metadata */
+    pagination: {
+        /** Total items available */
+        total: number;
+        /** Current page number */
+        page: number;
+        /** Items per page */
+        pageSize: number;
+        /** Whether more items exist */
+        hasMore: boolean;
+    };
+}
+/**
+ * Configuration for stream endpoints
+ */
+export interface StreamEndpointConfig {
+    /** Unique endpoint key (like serviceKey in domain services) */
+    endpointKey: string;
+    /** Human-readable name */
+    name?: string;
+    /** Channels this endpoint manages */
+    channels: string[];
+    /** Whether endpoint is enabled */
+    enabled?: boolean;
+    /** Supported runtimes */
+    supportedRuntimes?: Array<'node' | 'bun' | 'deno' | 'edge'>;
+}
+/**
+ * Options for creating stream endpoints
+ */
+export interface StreamEndpointCreateOptions {
+    /** Broadcaster interface */
+    broadcaster: StreamBroadcasterInterface;
+    /** Optional auth adapter */
+    auth?: unknown;
+}
+/**
+ * Interface for StreamBroadcaster (for dependency injection)
+ */
+export interface StreamBroadcasterInterface {
+    /** Initialize event subscriptions and cleanup timer */
+    initialize(): void;
+    /** Broadcast message to a channel (fire-and-forget) */
+    broadcastToChannel(channel: string, message: unknown): void;
+    /** Send message to a specific connection */
+    sendToConnection(connectionId: string, message: unknown): Promise<void>;
+    /** Broadcast to all connections (system-wide) */
+    broadcastToAll(message: unknown): void;
+}
+/**
+ * Configuration for channel controllers
+ */
+export interface ChannelControllerConfig {
+    /** Channel scope (e.g., 'upload', 'generate', 'system') */
+    scope: string;
+    /** Channel patterns this controller handles */
+    patterns: string[];
+    /** Whether controller is enabled */
+    enabled?: boolean;
+}
+/**
+ * Context passed to stream middleware
+ */
+export interface StreamMiddlewareContext {
+    /** Active connection */
+    connection: StreamConnection;
+    /** Auth result for the connection */
+    authResult: StreamAuthResult;
+    /** Message being processed (if any) */
+    message?: StreamMessage;
+    /** Target channel (if any) */
+    channel?: string;
+}
+/**
+ * Result returned by stream middleware
+ */
+export interface StreamMiddlewareResult {
+    /** Whether to continue to next middleware */
+    continue: boolean;
+    /** Updated context (merged with current) */
+    context?: Partial<StreamMiddlewareContext>;
+    /** Error to return (if continue is false) */
+    error?: PackageErrorLike;
+}
+/**
+ * Stream middleware function signature
+ */
+export type StreamMiddleware = (context: StreamMiddlewareContext) => Promise<StreamMiddlewareResult>;
+/**
+ * Rate limit middleware configuration
+ */
+export interface RateLimitConfig {
+    /** Max connections per IP */
+    maxConnectionsPerIp?: number;
+    /** Max messages per second per connection */
+    maxMessagesPerSecond?: number;
+    /** Window size in ms */
+    windowMs?: number;
+}
+/**
+ * Entry for registering stream endpoints
+ */
+export interface StreamEndpointEntry {
+    /** Endpoint class with static create() */
+    endpoint: {
+        endpointKey: string;
+        create(config: StreamEndpointConfig, options: StreamEndpointCreateOptions): Promise<unknown>;
+    };
+    /** Endpoint configuration overrides */
+    config: Partial<StreamEndpointConfig>;
+}
+/**
+ * Configuration for StreamRegistry initialization
+ */
+export interface StreamRegistryConfig {
+    /** Stream endpoints to register */
+    endpoints: StreamEndpointEntry[];
+    /** Broadcaster instance */
+    broadcaster: StreamBroadcasterInterface;
+}

package/dist/core/events/streaming/types.d.ts

@@ -0,0 +1,408 @@
+/**
+ * Streaming Types
+ *
+ * Global types for real-time event streaming via SSE/WebSocket.
+ *
+ * Architecture:
+ * - Domain services define their own streaming constants (e.g., FILES_STREAM_SUBTYPE)
+ * - Global constants here MERGE domain-specific constants
+ * - System constants (heartbeat, connection) are defined here as base
+ *
+ * To add a new domain:
+ * 1. Create streaming constants in the domain folder (e.g., /domain/payments/streaming.ts)
+ * 2. Import domain constants here
+ * 3. Merge into global constants (STREAM_MESSAGE_TYPE, STREAM_SUBTYPE, etc.)
+ */
+import type { FilesStreamMessageType, FilesStreamSubtype, FilesStreamProgressStatus, FilesUploadStreamProgress, FilesDownloadStreamProgress, FilesGenerateStreamProgress, FilesStreamProgressData, FilesStreamChannel } from '../../domain/files';
+import type { CorePlyazStreamConfig } from '../../frontend';
+import type { RootStoreHook } from '../../../store';
+import type { PackageErrorLike } from '../../../errors';
+/**
+ * Supported transport types for streaming connections
+ */
+export declare const STREAM_TRANSPORT: {
+    readonly SSE: "sse";
+    readonly WEBSOCKET: "websocket";
+};
+export type StreamTransportType = (typeof STREAM_TRANSPORT)[keyof typeof STREAM_TRANSPORT];
+/**
+ * System-level message type categories.
+ * Used for connection lifecycle and system-wide events.
+ */
+export declare const SYSTEM_STREAM_MESSAGE_TYPE: {
+    readonly SYSTEM: "system";
+    readonly NOTIFICATION: "notification";
+    readonly DATA: "data";
+};
+export type SystemStreamMessageType = (typeof SYSTEM_STREAM_MESSAGE_TYPE)[keyof typeof SYSTEM_STREAM_MESSAGE_TYPE];
+/**
+ * System-level message subtypes (not domain-specific).
+ * Used for connection lifecycle and system events.
+ */
+export declare const SYSTEM_STREAM_SUBTYPE: {
+    readonly HEARTBEAT: "heartbeat";
+    readonly CONNECTED: "connected";
+    readonly DISCONNECTED: "disconnected";
+    readonly RECONNECTING: "reconnecting";
+};
+export type SystemStreamSubtype = (typeof SYSTEM_STREAM_SUBTYPE)[keyof typeof SYSTEM_STREAM_SUBTYPE];
+/**
+ * System channel for connection-level events.
+ */
+export declare const SYSTEM_STREAM_CHANNEL: {
+    readonly SYSTEM: "system";
+};
+export type SystemStreamChannel = (typeof SYSTEM_STREAM_CHANNEL)[keyof typeof SYSTEM_STREAM_CHANNEL];
+/**
+ * All message type categories.
+ * Merged from system + all domain-specific types.
+ *
+ * To add a new domain's message types:
+ * 1. Define `{DOMAIN}_STREAM_MESSAGE_TYPE` in the domain's streaming module
+ * 2. Import and spread into this object
+ */
+export declare const STREAM_MESSAGE_TYPE: {
+    readonly PROGRESS: "progress";
+    readonly STATUS: "status";
+    readonly ERROR: "error";
+    readonly SYSTEM: "system";
+    readonly NOTIFICATION: "notification";
+    readonly DATA: "data";
+};
+export type StreamMessageType = SystemStreamMessageType | FilesStreamMessageType;
+/**
+ * All message subtypes.
+ * Merged from system + all domain-specific subtypes.
+ *
+ * To add a new domain's subtypes:
+ * 1. Define `{DOMAIN}_STREAM_SUBTYPE` in the domain's streaming module
+ * 2. Import and spread into this object
+ */
+export declare const STREAM_SUBTYPE: {
+    readonly UPLOAD: "upload";
+    readonly DOWNLOAD: "download";
+    readonly GENERATE: "generate";
+    readonly HEARTBEAT: "heartbeat";
+    readonly CONNECTED: "connected";
+    readonly DISCONNECTED: "disconnected";
+    readonly RECONNECTING: "reconnecting";
+};
+export type StreamMessageSubtype = SystemStreamSubtype | FilesStreamSubtype;
+/**
+ * Message scope identifies the domain that owns the message.
+ * Used for routing messages to the correct domain store.
+ *
+ * To add a new domain:
+ * 1. Add the domain name to this constant
+ * 2. Create domain streaming types in the domain's types folder
+ */
+export declare const STREAM_SCOPE: {
+    readonly FILES: "files";
+    readonly SYSTEM: "system";
+};
+export type StreamMessageScope = (typeof STREAM_SCOPE)[keyof typeof STREAM_SCOPE];
+/**
+ * System stream events.
+ */
+export declare const SYSTEM_STREAM_EVENT: {
+    readonly CONNECTED: "connected";
+    readonly DISCONNECTED: "disconnected";
+    readonly HEARTBEAT: "heartbeat";
+    readonly ERROR: "error";
+};
+/**
+ * All stream events.
+ * Merged from system + all domain-specific events.
+ */
+export declare const STREAM_EVENT: {
+    readonly UPLOAD_PROGRESS: "upload:progress";
+    readonly UPLOAD_COMPLETED: "upload:completed";
+    readonly UPLOAD_FAILED: "upload:failed";
+    readonly UPLOAD_CANCELLED: "upload:cancelled";
+    readonly DOWNLOAD_PROGRESS: "download:progress";
+    readonly DOWNLOAD_COMPLETED: "download:completed";
+    readonly DOWNLOAD_FAILED: "download:failed";
+    readonly DOWNLOAD_CANCELLED: "download:cancelled";
+    readonly GENERATE_PROGRESS: "generate:progress";
+    readonly GENERATE_COMPLETED: "generate:completed";
+    readonly GENERATE_FAILED: "generate:failed";
+    readonly CONNECTED: "connected";
+    readonly DISCONNECTED: "disconnected";
+    readonly HEARTBEAT: "heartbeat";
+    readonly ERROR: "error";
+};
+/**
+ * All channel prefixes (for subscription matching).
+ */
+export declare const STREAM_CHANNEL_PREFIX: {
+    readonly UPLOAD: "upload:";
+    readonly DOWNLOAD: "download:";
+    readonly GENERATE: "generate:";
+};
+/**
+ * All broadcast channels (user-scoped).
+ */
+export declare const STREAM_BROADCAST_CHANNEL: {
+    readonly UPLOADS: "uploads";
+    readonly DOWNLOADS: "downloads";
+    readonly GENERATIONS: "generations";
+    readonly SYSTEM: "system";
+};
+/**
+ * All possible channel patterns.
+ * Union of system channel + all domain-specific channels.
+ */
+export type StreamChannel = SystemStreamChannel | FilesStreamChannel;
+/**
+ * Represents an active streaming connection
+ */
+export interface StreamConnection {
+    /** Unique connection identifier */
+    id: string;
+    /** Authenticated user ID (undefined for anonymous) */
+    userId?: string;
+    /** Transport type (SSE or WebSocket) */
+    transport: StreamTransportType;
+    /** Subscribed channels */
+    channels: Set<string>;
+    /** Connection creation timestamp */
+    createdAt: Date;
+    /** Last activity timestamp (for cleanup) */
+    lastActivity: Date;
+    /** Additional connection metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Serializable version of StreamConnection for storage/transmission
+ */
+export interface StreamConnectionInfo {
+    id: string;
+    userId?: string;
+    transport: StreamTransportType;
+    channels: string[];
+    createdAt: string;
+    lastActivity: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Message sent to streaming clients.
+ *
+ * @typeParam T - Payload data type (defaults to unknown)
+ */
+export interface StreamMessage<T = unknown> {
+    /** Event name (e.g., 'upload:progress', 'connected', 'heartbeat') */
+    event: string;
+    /** Event payload data */
+    data: T;
+    /** Optional message ID (for SSE reconnection) */
+    id?: string;
+    /** Optional retry interval in ms (for SSE) */
+    retry?: number;
+    /** Channel this message was sent to */
+    channel?: string;
+    /** Message type category */
+    type?: StreamMessageType;
+    /** Message subtype for granular filtering */
+    subtype?: StreamMessageSubtype;
+    /** Domain scope for routing to domain stores */
+    scope?: StreamMessageScope;
+    /** Transport used (sse or websocket) */
+    transport?: StreamTransportType;
+    /** Timestamp when message was created */
+    timestamp?: number;
+    /** Correlation ID for request tracing */
+    correlationId?: string;
+}
+/**
+ * Progress data union type.
+ * Currently files-only, will expand as domains add streaming support.
+ */
+export type StreamProgressData = FilesStreamProgressData;
+/**
+ * Progress status union type.
+ * Currently files-only, will expand as domains add streaming support.
+ */
+export type StreamProgressStatus = FilesStreamProgressStatus;
+/**
+ * All progress status constants.
+ */
+export declare const STREAM_PROGRESS_STATUS: {
+    readonly PENDING: "pending";
+    readonly UPLOADING: "uploading";
+    readonly DOWNLOADING: "downloading";
+    readonly PROCESSING: "processing";
+    readonly GENERATING: "generating";
+    readonly COMPLETED: "completed";
+    readonly FAILED: "failed";
+    readonly CANCELLED: "cancelled";
+};
+export type { FilesUploadStreamProgress, FilesDownloadStreamProgress, FilesGenerateStreamProgress };
+/**
+ * Channel subscription record
+ */
+export interface ChannelSubscription {
+    /** Channel name */
+    channel: string;
+    /** Connection ID */
+    connectionId: string;
+    /** Subscription timestamp */
+    subscribedAt: Date;
+}
+/**
+ * Result of authentication attempt
+ */
+export interface StreamAuthResult {
+    /** Whether authentication succeeded */
+    authenticated: boolean;
+    /** User ID (if authenticated) */
+    userId?: string;
+    /** Allowed channel patterns (e.g., ['upload:', 'generate:']) */
+    scopes?: string[];
+    /** Additional auth metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Base configuration for auth adapters
+ */
+export interface StreamAuthAdapterConfig {
+    /** Adapter name for logging */
+    name: string;
+    /** Whether adapter is enabled */
+    enabled?: boolean;
+}
+/**
+ * Configuration for token-based auth adapter
+ */
+export interface TokenAuthAdapterConfig extends StreamAuthAdapterConfig {
+    /** Token verification function */
+    verifyToken: (token: string) => Promise<{
+        valid: boolean;
+        userId?: string;
+        scopes?: string[];
+    }>;
+    /** Header name for token (default: 'Authorization') */
+    headerName?: string;
+}
+/**
+ * Base configuration for transport adapters
+ */
+export interface StreamTransportAdapterConfig {
+    /** Adapter name for logging */
+    name: string;
+    /** Heartbeat interval in ms (default: 30000) */
+    heartbeatInterval?: number;
+    /** Maximum concurrent connections (default: 1000) */
+    maxConnections?: number;
+}
+/**
+ * Configuration for StreamBroadcaster
+ */
+export interface StreamBroadcasterConfig {
+    /** Heartbeat interval in ms */
+    heartbeatInterval?: number;
+    /** Connection timeout in ms (for cleanup) */
+    connectionTimeout?: number;
+    /** Maximum stale connection age in ms before cleanup */
+    maxStaleAge?: number;
+}
+/**
+ * Statistics for stream manager
+ */
+export interface StreamManagerStats {
+    /** Total active connections */
+    totalConnections: number;
+    /** Connections by transport type */
+    connectionsByTransport: Record<StreamTransportType, number>;
+    /** Total channel subscriptions */
+    totalSubscriptions: number;
+    /** Unique channels with subscribers */
+    activeChannels: number;
+}
+/**
+ * Return type for useStreamConnection hook
+ *
+ * Note: Errors are added to the global error store automatically.
+ * Use useErrorStore or error hooks to access connection errors.
+ */
+export interface UseStreamConnectionResult {
+    /** Whether connection is established */
+    connected: boolean;
+    /** Reconnect function */
+    reconnect: () => void;
+    /** Disconnect function */
+    disconnect: () => void;
+}
+/**
+ * Options for useStreamConnection hook
+ *
+ * @template T - The expected message data type (defaults to unknown)
+ *
+ * @example
+ * ```typescript
+ * // Without generic (message.data is unknown)
+ * useStreamConnection({
+ *   channels: ['uploads'],
+ *   onMessage: (message) => { ... }
+ * });
+ *
+ * // With generic (message.data is properly typed)
+ * useStreamConnection<FilesUploadStreamProgress>({
+ *   channels: [`upload:${fileId}`],
+ *   onMessage: (message) => {
+ *     // message.data is FilesUploadStreamProgress
+ *     console.log(message.data.percentage);
+ *   }
+ * });
+ * ```
+ */
+export interface UseStreamConnectionOptions<T = unknown> {
+    /** Channels to subscribe to */
+    channels: StreamChannel[];
+    /** API endpoint URL (default: '/api/events/stream') */
+    endpoint?: string;
+    /** Whether to auto-connect on mount (default: true) */
+    autoConnect?: boolean;
+    /** Reconnect on error (default: true) */
+    autoReconnect?: boolean;
+    /** Max reconnect attempts (default: 5) */
+    maxReconnectAttempts?: number;
+    /** Reconnect delay in ms (default: 1000) */
+    reconnectDelay?: number;
+    /** Callback when connected */
+    onConnect?: () => void;
+    /** Callback when disconnected */
+    onDisconnect?: () => void;
+    /** Callback on error */
+    onError?: (error: PackageErrorLike) => void;
+    /** Callback on message received (message.data is typed as T) */
+    onMessage?: (message: StreamMessage<T>) => void;
+}
+/**
+ * Options for useStreamManager hook
+ *
+ * Used by PlyazProvider to manage SSE connection lifecycle.
+ */
+export interface UseStreamManagerOptions {
+    /** Streaming configuration (required when enabled) */
+    config?: CorePlyazStreamConfig;
+    /** Root store hook for accessing stream store */
+    store: RootStoreHook;
+    /** Enable verbose logging */
+    verbose?: boolean;
+    /** Whether streaming is enabled (default: false) */
+    enabled?: boolean;
+}
+/**
+ * Result type for useStreamManager hook
+ *
+ * Note: Errors are added to the global error store automatically.
+ * Use useErrorStore or error hooks to access connection errors.
+ */
+export interface UseStreamManagerResult {
+    /** Whether connected to SSE */
+    connected: boolean;
+    /** Subscribed channels */
+    channels: StreamChannel[];
+    /** Whether streaming is enabled */
+    enabled: boolean;
+}

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

@@ -2,5 +2,5 @@
  * Core Frontend Types
  * Type definitions for @plyaz/core frontend services
  */
-export type { CoreBaseFrontendStore, CoreBaseFrontendServiceConfig, CoreBaseFrontendServiceInterface, CoreStoreHandlers, CoreOptimisticUpdateConfig, OptimisticConflictResolution, CoreFetcherFunction, CoreServiceFetchers, CorePlyazApiConfig, FrontendFeatureFlagProvider, CorePlyazFeatureFlagConfig, CorePlyazStoreConfig, CorePlyazConfig, CoreFeatureFlagServiceLike, CoreFeatureFlagFetcherOptions, CoreFeatureFlagStoreInitConfig, CoreBaseFrontendServiceConstructorConfig, CoreInitializationErrorProps, CoreInitializationLoadingProps, CorePlyazServices, CorePlyazContextValue, CorePlyazProviderProps, } from './types';
+export type { CoreBaseFrontendStore, CoreBaseFrontendServiceConfig, CoreBaseFrontendServiceInterface, CoreStoreHandlers, CoreOptimisticUpdateConfig, OptimisticConflictResolution, CoreFetcherFunction, CoreServiceFetchers, CorePlyazApiConfig, FrontendFeatureFlagProvider, CorePlyazFeatureFlagConfig, CorePlyazStoreConfig, CorePlyazStreamConfig, CorePlyazConfig, CoreFeatureFlagServiceLike, CoreFeatureFlagFetcherOptions, CoreFeatureFlagStoreInitConfig, CoreBaseFrontendServiceConstructorConfig, CoreInitializationErrorProps, CoreInitializationLoadingProps, CorePlyazServices, CorePlyazContextValue, CorePlyazProviderProps, CoreStreamStoreGetter, CoreStreamHandlerIds, CoreStreamHandlerDeclaration, } from './types';
 export type { CoreFrontendFeatureFlagEventType, CoreFeatureFlagStore, CoreFeatureFlagServiceConfig, CoreFeatureFlagServiceInitConfig, CoreFeatureFlagServiceInterface, } from './featureFlags';