@plyaz/types 1.35.4 → 1.36.1

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;
+}

package/dist/core/index.cjs

@@ -1,5 +1,7 @@
 'use strict';
 
+var zod = require('zod');
+
 // @plyaz package - Built with tsup
 
 // src/core/modules.ts
@@ -326,6 +328,195 @@ var CORE_EVENTS = {
   }
 };
 
+// src/core/domain/files/enums.ts
+var SYSTEM_USER_ID = "00000000-0000-0000-0000-000000000000";
+var FILE_TYPES = {
+  IMAGE: "IMAGE",
+  VIDEO: "VIDEO",
+  AUDIO: "AUDIO",
+  DOCUMENT: "DOCUMENT"
+};
+var FILE_ACCESS_LEVELS = {
+  PUBLIC: "public",
+  PRIVATE: "private",
+  PROTECTED: "protected"
+};
+
+// src/core/domain/files/streaming.ts
+var FILES_STREAM_MESSAGE_TYPE = {
+  PROGRESS: "progress",
+  STATUS: "status",
+  ERROR: "error"
+};
+var FILES_STREAM_SUBTYPE = {
+  UPLOAD: "upload",
+  DOWNLOAD: "download",
+  GENERATE: "generate"
+};
+var FILES_STREAM_PROGRESS_STATUS = {
+  PENDING: "pending",
+  UPLOADING: "uploading",
+  DOWNLOADING: "downloading",
+  PROCESSING: "processing",
+  GENERATING: "generating",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  CANCELLED: "cancelled"
+};
+var FILES_STREAM_EVENT = {
+  // Upload events
+  UPLOAD_PROGRESS: "upload:progress",
+  UPLOAD_COMPLETED: "upload:completed",
+  UPLOAD_FAILED: "upload:failed",
+  UPLOAD_CANCELLED: "upload:cancelled",
+  // Download events
+  DOWNLOAD_PROGRESS: "download:progress",
+  DOWNLOAD_COMPLETED: "download:completed",
+  DOWNLOAD_FAILED: "download:failed",
+  DOWNLOAD_CANCELLED: "download:cancelled",
+  // Generation events
+  GENERATE_PROGRESS: "generate:progress",
+  GENERATE_COMPLETED: "generate:completed",
+  GENERATE_FAILED: "generate:failed"
+};
+var FILES_STREAM_CHANNEL_PREFIX = {
+  UPLOAD: "upload:",
+  DOWNLOAD: "download:",
+  GENERATE: "generate:"
+};
+var FILES_STREAM_BROADCAST_CHANNEL = {
+  UPLOADS: "uploads",
+  DOWNLOADS: "downloads",
+  GENERATIONS: "generations"
+};
+var FILES_STREAM_CHANNEL = {
+  // Prefixes (for building per-resource channels)
+  PREFIX: FILES_STREAM_CHANNEL_PREFIX,
+  // Broadcast channels
+  BROADCAST: FILES_STREAM_BROADCAST_CHANNEL
+};
+var MediaTypeSchema = zod.z.enum(["IMAGE", "VIDEO", "AUDIO", "DOCUMENT"]);
+var FileTypeSchema = zod.z.enum(["IMAGE", "VIDEO", "DOCUMENT", "AUDIO", "OTHER"]);
+var MediaAccessLevelSchema = zod.z.enum(["public", "private", "protected"]).nullable();
+var FilesDatabaseRowSchema = zod.z.object({
+  // Auto-generated fields
+  id: zod.z.string().uuid(),
+  created_at: zod.z.string(),
+  updated_at: zod.z.string(),
+  deleted_at: zod.z.string().nullable(),
+  // Required fields
+  user_id: zod.z.string().uuid(),
+  type: zod.z.string(),
+  // String in DB, validated as MediaType on create
+  filename: zod.z.string(),
+  original_filename: zod.z.string(),
+  mime_type: zod.z.string(),
+  file_size: zod.z.union([zod.z.bigint(), zod.z.number()]),
+  storage_path: zod.z.string(),
+  // Optional fields
+  cdn_url: zod.z.string().nullable(),
+  width: zod.z.number().nullable(),
+  height: zod.z.number().nullable(),
+  duration: zod.z.number().nullable(),
+  is_virus_scanned: zod.z.boolean(),
+  virus_scan_result: zod.z.string().nullable(),
+  metadata: zod.z.record(zod.z.string(), zod.z.unknown()).nullable(),
+  variants: zod.z.record(zod.z.string(), zod.z.unknown()).nullable(),
+  entity_type: zod.z.string().nullable(),
+  entity_id: zod.z.string().nullable(),
+  access_level: zod.z.string().nullable()
+});
+var CreateFilesSchema = zod.z.object({
+  // Required fields with defaults for optional scenarios
+  user_id: zod.z.string().uuid().default(SYSTEM_USER_ID),
+  type: MediaTypeSchema.default("DOCUMENT"),
+  filename: zod.z.string().min(1, "Filename is required"),
+  original_filename: zod.z.string().min(1, "Original filename is required"),
+  mime_type: zod.z.string().min(1, "MIME type is required"),
+  file_size: zod.z.union([zod.z.bigint(), zod.z.number()]).refine((val) => Number(val) >= 0, "File size must be non-negative"),
+  storage_path: zod.z.string().min(1, "Storage path is required"),
+  // Optional fields with defaults
+  cdn_url: zod.z.string().url().nullable().default(null),
+  width: zod.z.number().positive().nullable().default(null),
+  height: zod.z.number().positive().nullable().default(null),
+  duration: zod.z.number().positive().nullable().default(null),
+  is_virus_scanned: zod.z.boolean().default(false),
+  virus_scan_result: zod.z.string().nullable().default(null),
+  metadata: zod.z.record(zod.z.string(), zod.z.unknown()).nullable().default(null),
+  variants: zod.z.record(zod.z.string(), zod.z.unknown()).nullable().default(null),
+  entity_type: zod.z.string().nullable().default(null),
+  entity_id: zod.z.string().nullable().default(null),
+  access_level: MediaAccessLevelSchema.default(null)
+});
+var PatchFilesSchema = CreateFilesSchema.partial();
+var MediaVariantsDatabaseRowSchema = zod.z.object({
+  id: zod.z.string().uuid(),
+  media_id: zod.z.string().uuid(),
+  variant_name: zod.z.string(),
+  file_path: zod.z.string(),
+  cdn_url: zod.z.string().nullable(),
+  width: zod.z.number().nullable(),
+  height: zod.z.number().nullable(),
+  file_size: zod.z.number().nullable(),
+  created_at: zod.z.string()
+});
+var CreateMediaVariantSchema = MediaVariantsDatabaseRowSchema.omit({
+  id: true,
+  created_at: true
+});
+
+// src/core/events/streaming/types.ts
+var STREAM_TRANSPORT = {
+  SSE: "sse",
+  WEBSOCKET: "websocket"
+};
+var SYSTEM_STREAM_MESSAGE_TYPE = {
+  SYSTEM: "system",
+  NOTIFICATION: "notification",
+  DATA: "data"
+};
+var SYSTEM_STREAM_SUBTYPE = {
+  HEARTBEAT: "heartbeat",
+  CONNECTED: "connected",
+  DISCONNECTED: "disconnected",
+  RECONNECTING: "reconnecting"
+};
+var SYSTEM_STREAM_CHANNEL = {
+  SYSTEM: "system"
+};
+var STREAM_MESSAGE_TYPE = {
+  ...SYSTEM_STREAM_MESSAGE_TYPE,
+  ...FILES_STREAM_MESSAGE_TYPE
+};
+var STREAM_SUBTYPE = {
+  ...SYSTEM_STREAM_SUBTYPE,
+  ...FILES_STREAM_SUBTYPE
+};
+var STREAM_SCOPE = {
+  FILES: "files",
+  SYSTEM: "system"
+};
+var SYSTEM_STREAM_EVENT = {
+  CONNECTED: "connected",
+  DISCONNECTED: "disconnected",
+  HEARTBEAT: "heartbeat",
+  ERROR: "error"
+};
+var STREAM_EVENT = {
+  ...SYSTEM_STREAM_EVENT,
+  ...FILES_STREAM_EVENT
+};
+var STREAM_CHANNEL_PREFIX = {
+  ...FILES_STREAM_CHANNEL_PREFIX
+};
+var STREAM_BROADCAST_CHANNEL = {
+  ...SYSTEM_STREAM_CHANNEL,
+  ...FILES_STREAM_BROADCAST_CHANNEL
+};
+var STREAM_PROGRESS_STATUS = {
+  ...FILES_STREAM_PROGRESS_STATUS
+};
+
 // src/core/services/keys.ts
 var SERVICE_KEYS = {
   /** Example domain service (backend) */
@@ -349,6 +540,8 @@ exports.BACKEND_RUNTIMES = BACKEND_RUNTIMES;
 exports.CORE_EVENTS = CORE_EVENTS;
 exports.CacheEventAction = CacheEventAction;
 exports.CoreEventScope = CoreEventScope;
+exports.CreateFilesSchema = CreateFilesSchema;
+exports.CreateMediaVariantSchema = CreateMediaVariantSchema;
 exports.DATABASE_FIELDS = DATABASE_FIELDS;
 exports.DatabaseEventAction = DatabaseEventAction;
 exports.EVALUATION_REASONS = EVALUATION_REASONS;
@@ -360,13 +553,41 @@ exports.FEATURE_FLAG_PROVIDERS = FEATURE_FLAG_PROVIDERS;
 exports.FEATURE_FLAG_RULE_FIELD = FEATURE_FLAG_RULE_FIELD;
 exports.FEATURE_FLAG_TABLE = FEATURE_FLAG_TABLE;
 exports.FEATURE_FLAG_TYPES = FEATURE_FLAG_TYPES;
+exports.FILES_STREAM_BROADCAST_CHANNEL = FILES_STREAM_BROADCAST_CHANNEL;
+exports.FILES_STREAM_CHANNEL = FILES_STREAM_CHANNEL;
+exports.FILES_STREAM_CHANNEL_PREFIX = FILES_STREAM_CHANNEL_PREFIX;
+exports.FILES_STREAM_EVENT = FILES_STREAM_EVENT;
+exports.FILES_STREAM_MESSAGE_TYPE = FILES_STREAM_MESSAGE_TYPE;
+exports.FILES_STREAM_PROGRESS_STATUS = FILES_STREAM_PROGRESS_STATUS;
+exports.FILES_STREAM_SUBTYPE = FILES_STREAM_SUBTYPE;
+exports.FILE_ACCESS_LEVELS = FILE_ACCESS_LEVELS;
+exports.FILE_TYPES = FILE_TYPES;
 exports.FRONTEND_RUNTIMES = FRONTEND_RUNTIMES;
 exports.FeatureFlagEventAction = FeatureFlagEventAction;
+exports.FileTypeSchema = FileTypeSchema;
+exports.FilesDatabaseRowSchema = FilesDatabaseRowSchema;
+exports.MediaAccessLevelSchema = MediaAccessLevelSchema;
+exports.MediaTypeSchema = MediaTypeSchema;
+exports.MediaVariantsDatabaseRowSchema = MediaVariantsDatabaseRowSchema;
 exports.NODE_ENVIRONMENTS = NODE_ENVIRONMENTS;
 exports.NotificationEventAction = NotificationEventAction;
+exports.PatchFilesSchema = PatchFilesSchema;
 exports.SERVICE_KEYS = SERVICE_KEYS;
 exports.SORT_DIRECTION = SORT_DIRECTION;
+exports.STREAM_BROADCAST_CHANNEL = STREAM_BROADCAST_CHANNEL;
+exports.STREAM_CHANNEL_PREFIX = STREAM_CHANNEL_PREFIX;
+exports.STREAM_EVENT = STREAM_EVENT;
+exports.STREAM_MESSAGE_TYPE = STREAM_MESSAGE_TYPE;
+exports.STREAM_PROGRESS_STATUS = STREAM_PROGRESS_STATUS;
+exports.STREAM_SCOPE = STREAM_SCOPE;
+exports.STREAM_SUBTYPE = STREAM_SUBTYPE;
+exports.STREAM_TRANSPORT = STREAM_TRANSPORT;
+exports.SYSTEM_STREAM_CHANNEL = SYSTEM_STREAM_CHANNEL;
+exports.SYSTEM_STREAM_EVENT = SYSTEM_STREAM_EVENT;
+exports.SYSTEM_STREAM_MESSAGE_TYPE = SYSTEM_STREAM_MESSAGE_TYPE;
+exports.SYSTEM_STREAM_SUBTYPE = SYSTEM_STREAM_SUBTYPE;
 exports.SYSTEM_USERS = SYSTEM_USERS;
+exports.SYSTEM_USER_ID = SYSTEM_USER_ID;
 exports.SanitizationEventAction = SanitizationEventAction;
 exports.StorageEventAction = StorageEventAction;
 exports.StoreEventAction = StoreEventAction;