@plyaz/types 1.36.0 → 1.36.1

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';

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

@@ -11,6 +11,7 @@ import type { RootStoreSlice, RootStoreHook } from '../../store';
 import type { CoreBaseDomainServiceConfig } from '../domain';
 import type { CoreBaseServiceConfig, CoreBaseMapperInstance, CoreBaseValidatorInstance } from '../domain';
 import type { CoreDomainServiceInstance, CoreObservabilityConfig, CoreServiceEntry } from '../init';
+import type { PackageErrorLike } from '../../errors';
 /**
  * Base store interface for frontend services.
  *
@@ -971,6 +972,94 @@ export interface CorePlyazStoreConfig {
     /** Callback when a flag value changes */
     onFlagChange?: (key: string, prevValue: FeatureFlagValue | undefined, newValue: FeatureFlagValue) => void;
 }
+/**
+ * Streaming configuration for PlyazProvider
+ *
+ * When enabled, automatically establishes SSE connection and routes
+ * messages to the stream store. Domain services register handlers
+ * to process events and update their stores.
+ *
+ * @example
+ * ```typescript
+ * // Enable streaming with default settings
+ * streaming: {
+ *   enabled: true,
+ * }
+ *
+ * // Custom configuration
+ * streaming: {
+ *   enabled: true,
+ *   endpoint: '/api/events/stream',
+ *   channels: ['uploads', 'system'],
+ *   autoConnect: true,
+ *   reconnect: {
+ *     enabled: true,
+ *     maxAttempts: 10,
+ *     delay: 1000,
+ *   },
+ * }
+ * ```
+ */
+export interface CorePlyazStreamConfig {
+    /**
+     * Enable streaming (SSE connection).
+     * When true, PlyazProvider establishes SSE connection on mount.
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * SSE endpoint URL.
+     * @default '/api/events/stream'
+     */
+    endpoint?: string;
+    /**
+     * Channels to subscribe to.
+     * @default ['uploads', 'downloads', 'generations', 'system']
+     */
+    channels?: string[];
+    /**
+     * Auto-connect on mount.
+     * @default true
+     */
+    autoConnect?: boolean;
+    /**
+     * Reconnection configuration.
+     */
+    reconnect?: {
+        /**
+         * Enable auto-reconnection on disconnect.
+         * @default true
+         */
+        enabled?: boolean;
+        /**
+         * Max reconnection attempts.
+         * @default 10
+         */
+        maxAttempts?: number;
+        /**
+         * Base delay between attempts (ms). Uses exponential backoff.
+         * @default 1000
+         */
+        delay?: number;
+    };
+    /**
+     * Enable debug logging for streaming.
+     * @default false (uses verbose from config)
+     */
+    debug?: boolean;
+    /**
+     * Callback when connected to stream.
+     */
+    onConnect?: () => void;
+    /**
+     * Callback when disconnected from stream.
+     */
+    onDisconnect?: () => void;
+    /**
+     * Callback on connection error.
+     */
+    onError?: (error: PackageErrorLike) => void;
+}
 /**
  * Full provider configuration
  */
@@ -987,6 +1076,22 @@ export interface CorePlyazConfig {
      * Store integration configuration.
      */
     store?: CorePlyazStoreConfig;
+    /**
+     * Streaming configuration (SSE real-time events).
+     *
+     * When enabled, PlyazProvider automatically establishes SSE connection
+     * and routes messages to the stream store. Domain services can register
+     * handlers to process events and update their stores.
+     *
+     * @example
+     * ```typescript
+     * streaming: {
+     *   enabled: true,
+     *   channels: ['uploads', 'system'],
+     * }
+     * ```
+     */
+    streaming?: CorePlyazStreamConfig;
     /** App context (webapp, backoffice, mobile) */
     appContext?: CoreAppContext;
     /** Environment (production, staging, development, test) */
@@ -1046,9 +1151,9 @@ export interface CoreBaseFrontendServiceConstructorConfig<TConfig extends CoreBa
  */
 export interface CoreInitializationErrorProps {
     /** The error that occurred */
-    error: Error;
+    error: PackageErrorLike;
     /** Custom error component override */
-    errorComponent?: (error: Error) => ReactNode;
+    errorComponent?: (error: PackageErrorLike) => ReactNode;
 }
 /**
  * Props for initialization loading component
@@ -1138,7 +1243,7 @@ export interface CorePlyazContextValue extends CorePlyazServices {
     /** Whether services are initialized and ready */
     isReady: boolean;
     /** Initialization error if any */
-    error: Error | null;
+    error: PackageErrorLike | null;
     /** Re-initialize services */
     reinitialize: () => Promise<void>;
 }
@@ -1167,11 +1272,80 @@ export interface CorePlyazProviderProps {
     /** Loading component to show while initializing */
     loading?: ReactNode;
     /** Error component to show on initialization failure */
-    error?: (error: Error) => ReactNode;
+    error?: (error: PackageErrorLike) => ReactNode;
     /** Callback when services are ready */
     onReady?: (services: CorePlyazServices) => void;
     /** Callback on initialization error */
-    onError?: (error: Error) => void;
+    onError?: (error: PackageErrorLike) => void;
     /** Skip showing loading state (render children immediately) */
     skipLoadingState?: boolean;
 }
+/**
+ * Store getter function for declarative stream handlers.
+ * Returns the root store state for accessing domain stores.
+ */
+export type CoreStreamStoreGetter = () => RootStoreSlice | undefined;
+/**
+ * Stream handler IDs type.
+ * Use this to define strongly-typed handler ID objects.
+ *
+ * @typeParam TKeys - Union type of handler key names
+ *
+ * @example
+ * ```typescript
+ * // Define handler IDs with type safety
+ * protected static readonly STREAM_HANDLER_IDS: CoreStreamHandlerIds<
+ *   'UPLOAD_PROGRESS' | 'DOWNLOAD_PROGRESS' | 'GENERATE_PROGRESS'
+ * > = {
+ *   UPLOAD_PROGRESS: 'files:upload-progress',
+ *   DOWNLOAD_PROGRESS: 'files:download-progress',
+ *   GENERATE_PROGRESS: 'files:generate-progress',
+ * } as const;
+ * ```
+ */
+export type CoreStreamHandlerIds<TKeys extends string> = Readonly<Record<TKeys, string>>;
+/**
+ * Declarative stream handler configuration.
+ *
+ * Allows defining stream handlers as configuration objects
+ * instead of manual registration code.
+ *
+ * @typeParam TData - Type of message.data payload (default: unknown)
+ *
+ * @example
+ * ```typescript
+ * const handler: CoreStreamHandlerDeclaration<FilesUploadStreamProgress> = {
+ *   id: 'files:upload-progress',
+ *   channels: ['uploads', 'upload:'],
+ *   events: ['progress', 'upload:progress'],
+ *   priority: 100,
+ *   handler: (message, getStore) => {
+ *     // message.data is typed as FilesUploadStreamProgress
+ *     const filesStore = getStore()?.files;
+ *     filesStore?.setUploadProgress(message.data.fileId, { ... });
+ *   },
+ * };
+ * ```
+ */
+export interface CoreStreamHandlerDeclaration<TData = unknown> {
+    /** Unique handler ID (use STREAM_HANDLER_IDS values) */
+    id: string;
+    /** Channels to listen to (supports prefix matching with trailing colon) */
+    channels: string[];
+    /** Event types to listen to */
+    events: string[];
+    /** Handler priority (higher = called first). Default: 100 */
+    priority?: number;
+    /**
+     * Handler function.
+     * Receives the typed message and a store getter function.
+     *
+     * @param message - Stream message with typed data
+     * @param getStore - Function to get root store state
+     */
+    handler: (message: {
+        event: string;
+        data: TData;
+        timestamp?: number;
+    }, getStore: CoreStreamStoreGetter) => void;
+}