@plyaz/types 1.35.4 → 1.36.1

package/dist/store/files/index.d.ts

@@ -3,4 +3,4 @@
  *
  * Store types for files/media domain.
  */
-export type { FilesStoreItem, GeneratedFileItem, FilesFrontendStoreState, FilesFrontendStoreData, FilesFrontendStoreActions, FilesFrontendStoreSlice, FilesStoreSelectors, } from './types';
+export type { FilesStoreItem, GeneratedFileItem, FileUploadProgressState, FileDownloadProgressState, FileGenerateProgress, FilesFrontendStoreState, FilesFrontendStoreData, FilesFrontendStoreActions, FilesFrontendStoreSlice, FilesStoreSelectors, } from './types';

package/dist/store/files/types.d.ts

@@ -6,7 +6,8 @@
  * API types are in @plyaz/types/api/endpoints/files.
  */
 import type { CoreBaseFrontendStore } from '../../core/frontend';
-import type { FilesEntity, FileType } from '../../core/domain/files';
+import type { FilesEntity, FileType, FilesDownloadStreamProgress } from '../../core/domain/files';
+import type { UploadProgressEvent } from '../../storage';
 /**
  * Serializable store item for files
  */
@@ -41,6 +42,35 @@ export interface GeneratedFileItem {
     filename: string;
     generatedAt: string;
 }
+/**
+ * Extended upload progress with status for store tracking
+ * Extends storage's UploadProgressEvent with additional UI state
+ */
+export interface FileUploadProgressState extends UploadProgressEvent {
+    /** Upload status for UI display */
+    status: 'pending' | 'uploading' | 'downloading' | 'processing' | 'generating' | 'completed' | 'failed' | 'cancelled';
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Download progress state for store tracking
+ * Extends core's FilesDownloadStreamProgress with additional UI state
+ */
+export interface FileDownloadProgressState extends FilesDownloadStreamProgress {
+}
+/**
+ * Progress state for document generation
+ */
+export interface FileGenerateProgress {
+    /** Template ID being generated */
+    templateId: string;
+    /** Progress percentage (0-100) */
+    percentage: number;
+    /** Generation status */
+    status: 'pending' | 'uploading' | 'downloading' | 'processing' | 'generating' | 'completed' | 'failed' | 'cancelled';
+    /** Error message if failed */
+    error?: string;
+}
 /**
  * Files store state
  */
@@ -55,6 +85,14 @@ export interface FilesFrontendStoreState {
     isLoading: boolean;
     isUploading: boolean;
     isGenerating: boolean;
+    /** Progress tracking for uploads (keyed by fileId) */
+    uploadProgress: Record<string, FileUploadProgressState>;
+    /** Progress tracking for downloads (keyed by fileId) */
+    downloadProgress: Record<string, FileDownloadProgressState>;
+    /** Progress tracking for document generation */
+    generateProgress: FileGenerateProgress | null;
+    /** Overall upload progress percentage (0-100) for bulk uploads */
+    overallUploadProgress: number;
 }
 /**
  * Files store data for setData()
@@ -85,6 +123,14 @@ export interface FilesFrontendStoreActions extends CoreBaseFrontendStore<FilesFr
     setLoading: (isLoading: boolean) => void;
     setUploading: (isUploading: boolean) => void;
     setGenerating: (isGenerating: boolean) => void;
+    setUploadProgress: (fileId: string, progress: Partial<FileUploadProgressState>) => void;
+    removeUploadProgress: (fileId: string) => void;
+    clearUploadProgress: () => void;
+    setDownloadProgress: (fileId: string, progress: Partial<FileDownloadProgressState>) => void;
+    removeDownloadProgress: (fileId: string) => void;
+    clearDownloadProgress: () => void;
+    setGenerateProgress: (progress: FileGenerateProgress | null) => void;
+    setOverallUploadProgress: (percentage: number) => void;
     reset: () => void;
 }
 /**

package/dist/store/index.d.ts

@@ -2,3 +2,4 @@ export type * from './types';
 export { STORE_KEYS, ALL_STORE_KEYS } from './keys';
 export type { StoreKey } from './keys';
 export type * from './files';
+export type * from './stream';

package/dist/store/stream/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Stream Store Types
+ *
+ * Export all stream store types.
+ *
+ * Note: This store is CONNECTION-ONLY.
+ * Domain-specific progress belongs in domain stores (files, etc.)
+ */
+export type { StreamMessageHandler, RegisteredStreamHandler, StreamMessageFilter, StreamStoreState, StreamStoreActions, StreamStoreSlice, StreamStoreSelectors, UseStreamStoreResult, UseStreamHandlerOptions, StreamErrorData, StreamSliceConfig, } from './types';

package/dist/store/stream/types.d.ts

@@ -0,0 +1,303 @@
+/**
+ * Stream Store Types
+ *
+ * Store state, actions, and slice types for real-time streaming.
+ * This is a GLOBAL store slice (like errors, featureFlags), NOT per-service.
+ *
+ * IMPORTANT: This store handles CONNECTION STATE and MESSAGE HISTORY only.
+ * - Domain-specific progress belongs in domain stores (files, etc.)
+ * - Stream errors go to the GLOBAL errors store (not stream store)
+ *
+ * Domain stores (like files) use selectors to filter messages from this store
+ * by type, subtype, scope, transport, etc.
+ */
+import type { PackageErrorLike } from '../../errors';
+import type { StreamMessage, StreamMessageType, StreamMessageSubtype, StreamMessageScope, StreamTransportType } from '../../core/events/streaming';
+/**
+ * Stream message handler function.
+ * Domain services register handlers to receive and process stream messages.
+ *
+ * @typeParam T - Type of message.data payload (default: unknown)
+ *
+ * @example
+ * ```typescript
+ * // Type-safe handler for upload progress
+ * const handler: StreamMessageHandler<FilesUploadStreamProgress> = (message) => {
+ *   // message.data is typed as FilesUploadStreamProgress
+ *   console.log(message.data.percentage);
+ * };
+ * ```
+ */
+export type StreamMessageHandler<T = unknown> = (message: StreamMessage<T>) => void;
+/**
+ * Registered message handler with metadata
+ */
+export interface RegisteredStreamHandler {
+    /** Handler function (stores as unknown for registry, typed at call site) */
+    handler: StreamMessageHandler<unknown>;
+    /** Channels this handler is interested in (empty = all channels) */
+    channels: string[];
+    /** Event types this handler is interested in (empty = all events) */
+    events: string[];
+    /** Handler priority (higher = called first) */
+    priority: number;
+}
+/**
+ * Options for filtering stream messages
+ */
+export interface StreamMessageFilter {
+    /** Filter by message type */
+    type?: StreamMessageType | StreamMessageType[];
+    /** Filter by message subtype */
+    subtype?: StreamMessageSubtype | StreamMessageSubtype[];
+    /** Filter by domain scope */
+    scope?: StreamMessageScope | StreamMessageScope[];
+    /** Filter by transport */
+    transport?: StreamTransportType | StreamTransportType[];
+    /** Filter by channel (exact or prefix match) */
+    channel?: string | string[];
+    /** Filter by event name */
+    event?: string | string[];
+    /** Limit number of results */
+    limit?: number;
+    /** Only messages after this timestamp */
+    since?: number;
+}
+/**
+ * Global stream store state
+ *
+ * This is a GLOBAL slice (like errors, featureFlags), NOT per-service like primaryStore.
+ * Handles CONNECTION STATE and MESSAGE HISTORY only.
+ *
+ * NOTE: Stream errors go to the GLOBAL errors store, NOT here.
+ * Domain progress belongs in domain stores (files, etc.).
+ */
+export interface StreamStoreState {
+    /** Whether SSE/WebSocket connection is established */
+    connected: boolean;
+    /** Connection error (if any) - also added to global errors store */
+    connectionError: PackageErrorLike | null;
+    /** Connection ID (from server) */
+    connectionId: string | null;
+    /** Transport type in use */
+    transport: 'sse' | 'websocket' | null;
+    /** Reconnect attempt count */
+    reconnectAttempts: number;
+    /**
+     * Recent messages with full metadata (type, subtype, scope, transport).
+     * Domain stores use selectors to filter messages from this list.
+     * Automatically trimmed to last N messages (configurable).
+     */
+    messages: StreamMessage[];
+    /** Maximum messages to keep */
+    maxMessages: number;
+    /**
+     * Currently subscribed channels
+     * Updated by domain services via subscribeToChannel/unsubscribeFromChannel
+     */
+    subscribedChannels: string[];
+    /**
+     * Registered message handlers by ID
+     * Domain services register handlers to receive their stream messages
+     */
+    handlers: Record<string, RegisteredStreamHandler>;
+}
+/**
+ * Stream store actions
+ *
+ * Note: No progress actions here - those belong in domain stores!
+ * Stream errors go to the GLOBAL errors store.
+ * This store manages connection state, message history, and routing.
+ */
+export interface StreamStoreActions {
+    /** Set connection state */
+    setConnected(connected: boolean): void;
+    /**
+     * Set connection error.
+     * NOTE: This also adds the error to the GLOBAL errors store.
+     */
+    setConnectionError(error: PackageErrorLike | null): void;
+    /** Set connection ID */
+    setConnectionId(id: string | null): void;
+    /** Set transport type */
+    setTransport(transport: 'sse' | 'websocket' | null): void;
+    /** Increment reconnect attempts */
+    incrementReconnectAttempts(): void;
+    /** Reset reconnect attempts */
+    resetReconnectAttempts(): void;
+    /**
+     * Add a message to history.
+     * Messages are stored with full metadata (type, subtype, scope, transport).
+     */
+    addMessage(message: StreamMessage): void;
+    /** Clear all messages */
+    clearMessages(): void;
+    /** Set max messages to keep */
+    setMaxMessages(max: number): void;
+    /**
+     * Get messages matching filter criteria.
+     * Domain stores use this to select their relevant messages.
+     *
+     * @example
+     * ```typescript
+     * // Get all upload progress messages
+     * const uploadMessages = getMessages({
+     *   type: 'progress',
+     *   subtype: 'upload',
+     *   scope: 'files',
+     * });
+     *
+     * // Get recent SSE messages
+     * const sseMessages = getMessages({
+     *   transport: 'sse',
+     *   limit: 10,
+     * });
+     * ```
+     */
+    getMessages(filter?: StreamMessageFilter): StreamMessage[];
+    /**
+     * Get the latest message matching filter criteria.
+     */
+    getLatestMessage(filter?: StreamMessageFilter): StreamMessage | undefined;
+    /** Subscribe to a channel */
+    subscribeToChannel(channel: string): void;
+    /** Subscribe to multiple channels */
+    subscribeToChannels(channels: string[]): void;
+    /** Unsubscribe from a channel */
+    unsubscribeFromChannel(channel: string): void;
+    /** Unsubscribe from all channels */
+    unsubscribeFromAllChannels(): void;
+    /** Check if subscribed to a channel */
+    isSubscribedToChannel(channel: string): boolean;
+    /**
+     * Register a message handler.
+     * Domain services use this to receive stream messages and update their own stores.
+     *
+     * @typeParam T - Type of message.data payload for type-safe handlers
+     * @param id - Unique handler ID (e.g., 'files', 'notifications')
+     * @param handler - Handler function (generic for type-safe message.data)
+     * @param options - Handler options (channels, events, priority)
+     *
+     * @example
+     * ```typescript
+     * // Type-safe handler for upload progress
+     * streamStore.registerHandler<FilesUploadStreamProgress>(
+     *   'files:upload',
+     *   (message) => {
+     *     // message.data is typed as FilesUploadStreamProgress
+     *     console.log(message.data.percentage);
+     *   },
+     *   { channels: ['uploads'], events: ['upload:progress'] }
+     * );
+     * ```
+     */
+    registerHandler<T = unknown>(id: string, handler: StreamMessageHandler<T>, options?: {
+        channels?: string[];
+        events?: string[];
+        priority?: number;
+    }): void;
+    /**
+     * Unregister a message handler.
+     *
+     * @param id - Handler ID to unregister
+     */
+    unregisterHandler(id: string): void;
+    /**
+     * Handle incoming stream message.
+     * - Adds message to history with metadata
+     * - Routes to registered handlers based on channel/event matching
+     * - Handles connection events (connected, heartbeat, close)
+     * - Adds error events to global errors store
+     */
+    handleMessage(message: StreamMessage): void;
+    /** Reset store to initial state */
+    reset(): void;
+}
+/**
+ * Complete stream store slice (state + actions)
+ */
+export interface StreamStoreSlice extends StreamStoreState, StreamStoreActions {
+}
+/**
+ * Stream store selectors
+ *
+ * Note: No progress/completed selectors - use domain store selectors instead!
+ * e.g., useUploadProgress() from files store
+ *
+ * Note: No error selectors - stream errors go to GLOBAL errors store.
+ * Use useErrors({ scope: 'stream' }) from errors store.
+ */
+export interface StreamStoreSelectors {
+    /** Select connection state */
+    selectConnected: (state: StreamStoreState) => boolean;
+    /** Select connection error */
+    selectConnectionError: (state: StreamStoreState) => Error | null;
+    /** Select connection ID */
+    selectConnectionId: (state: StreamStoreState) => string | null;
+    /** Select transport type */
+    selectTransport: (state: StreamStoreState) => 'sse' | 'websocket' | null;
+    /** Select subscribed channels */
+    selectSubscribedChannels: (state: StreamStoreState) => string[];
+    /** Select messages (with optional filter) */
+    selectMessages: (state: StreamStoreState, filter?: StreamMessageFilter) => StreamMessage[];
+    /** Check if connected */
+    selectIsConnected: (state: StreamStoreState) => boolean;
+    /** Check if reconnecting */
+    selectIsReconnecting: (state: StreamStoreState) => boolean;
+    /** Select registered handler IDs */
+    selectHandlerIds: (state: StreamStoreState) => string[];
+}
+/**
+ * Result type for useStreamStore hook
+ */
+export interface UseStreamStoreResult extends StreamStoreState {
+    /** Store actions */
+    actions: StreamStoreActions;
+}
+/**
+ * Stream error data from an error event message.
+ * Used by `onError` callback to create SerializedError.
+ */
+export interface StreamErrorData {
+    /** Error code (from STREAM_ERROR_CODES or custom) */
+    code?: string;
+    /** Error message */
+    message: string;
+    /** Error context/details */
+    context?: Record<string, unknown>;
+    /** Original error (if available) */
+    originalError?: Error;
+    /** Channel where error occurred */
+    channel?: string;
+    /** Event type that caused error */
+    event?: string;
+}
+/**
+ * Configuration for creating a stream slice.
+ * Used to wire up error routing to the global errors store.
+ */
+export interface StreamSliceConfig {
+    /**
+     * Callback to add errors to the global errors store.
+     * Called when:
+     * - setConnectionError is called with an error
+     * - handleMessage receives an 'error' event
+     * - A registered handler throws an error
+     *
+     * @param error - Stream error data to be serialized and added
+     */
+    onError?: (error: StreamErrorData) => void;
+}
+/**
+ * Options for useStreamHandler hook
+ */
+export interface UseStreamHandlerOptions {
+    /** Handler ID (must be unique) */
+    id: string;
+    /** Channels to listen to (empty = all) */
+    channels?: string[];
+    /** Event types to listen to (empty = all) */
+    events?: string[];
+    /** Handler priority (higher = called first, default: 0) */
+    priority?: number;
+}

package/dist/store/types.d.ts

@@ -10,6 +10,7 @@ import type { SerializedError, ErrorStoreActions, ErrorStoreSlice } from '../err
 import type { FeatureFlagStoreState, FeatureFlagStoreSlice } from '../features/feature-flag/store.types';
 import type { ExampleFrontendStoreSlice } from '../examples';
 import type { FilesFrontendStoreSlice } from './files/types';
+import type { StreamStoreSlice } from './stream/types';
 /**
  * Configuration for creating an error store.
  */
@@ -84,6 +85,8 @@ export interface RootStoreSlice {
     errors: ErrorStoreSlice;
     /** Feature flags slice (global) */
     featureFlags: FeatureFlagStoreSlice;
+    /** Stream events slice (global) - for real-time SSE/WebSocket */
+    stream: StreamStoreSlice;
     /** Example domain slice */
     example: ExampleFrontendStoreSlice;
     /** Files/media domain slice */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plyaz/types",
-  "version": "1.35.4",
+  "version": "1.36.1",
   "author": "Redeemer Pace",
   "license": "ISC",
   "description": "Provides shared TypeScript types and schema utilities for validation and parsing in the @playz ecosystem.",