@uploadista/expo 0.0.15-beta.3 → 0.0.15-beta.5

package/src/hooks/use-flow-events.ts

@@ -0,0 +1,141 @@
+import type {
+  FlowEventFlowCancel,
+  FlowEventFlowEnd,
+  FlowEventFlowError,
+  FlowEventFlowPause,
+  FlowEventFlowStart,
+  FlowEventJobEnd,
+  FlowEventJobStart,
+  FlowEventNodeEnd,
+  FlowEventNodeError,
+  FlowEventNodePause,
+  FlowEventNodeResume,
+  FlowEventNodeStart,
+} from "@uploadista/core/flow";
+import { EventType } from "@uploadista/core/flow";
+import { useEffect } from "react";
+import { useUploadistaContext } from "../components/uploadista-provider";
+import { isFlowEvent } from "./event-utils";
+
+/**
+ * Options for handling flow execution events.
+ *
+ * All callbacks are optional - only provide handlers for events you care about.
+ */
+export interface UseFlowEventsOptions {
+  /** Called when a job starts execution */
+  onJobStart?: (event: FlowEventJobStart) => void;
+  /** Called when a job completes (success or failure) */
+  onJobEnd?: (event: FlowEventJobEnd) => void;
+  /** Called when a flow begins execution */
+  onFlowStart?: (event: FlowEventFlowStart) => void;
+  /** Called when a flow completes successfully */
+  onFlowEnd?: (event: FlowEventFlowEnd) => void;
+  /** Called when a flow encounters an error */
+  onFlowError?: (event: FlowEventFlowError) => void;
+  /** Called when a flow is paused by user request */
+  onFlowPause?: (event: FlowEventFlowPause) => void;
+  /** Called when a flow is cancelled by user request */
+  onFlowCancel?: (event: FlowEventFlowCancel) => void;
+  /** Called when a node starts processing */
+  onNodeStart?: (event: FlowEventNodeStart) => void;
+  /** Called when a node completes successfully */
+  onNodeEnd?: (event: FlowEventNodeEnd) => void;
+  /** Called when a node pauses (waiting for additional data) */
+  onNodePause?: (event: FlowEventNodePause) => void;
+  /** Called when a paused node resumes execution */
+  onNodeResume?: (event: FlowEventNodeResume) => void;
+  /** Called when a node encounters an error */
+  onNodeError?: (event: FlowEventNodeError) => void;
+}
+
+/**
+ * Structured hook for handling flow execution events with type-safe callbacks.
+ *
+ * This hook provides a clean API for listening to specific flow events without
+ * needing to manually filter events or use type guards.
+ *
+ * Must be used within UploadistaProvider.
+ *
+ * @param options - Object with optional callbacks for each flow event type
+ *
+ * @example
+ * ```tsx
+ * import { useFlowEvents } from '@uploadista/expo';
+ * import { View, Text } from 'react-native';
+ *
+ * function FlowMonitor() {
+ *   useFlowEvents({
+ *     onFlowStart: (event) => {
+ *       console.log('Flow started:', event.flowId);
+ *     },
+ *     onNodeStart: (event) => {
+ *       console.log('Node started:', event.nodeName);
+ *     },
+ *     onNodeEnd: (event) => {
+ *       console.log('Node completed:', event.nodeName, event.result);
+ *     },
+ *     onFlowEnd: (event) => {
+ *       console.log('Flow completed with outputs:', event.outputs);
+ *     },
+ *     onFlowError: (event) => {
+ *       console.error('Flow failed:', event.error);
+ *     },
+ *   });
+ *
+ *   return <View><Text>Monitoring flow execution...</Text></View>;
+ * }
+ * ```
+ */
+export function useFlowEvents(options: UseFlowEventsOptions): void {
+  const { subscribeToEvents } = useUploadistaContext();
+
+  useEffect(() => {
+    const unsubscribe = subscribeToEvents((event) => {
+      // Only handle flow events
+      if (!isFlowEvent(event)) return;
+
+      // Route to appropriate callback based on event type
+      switch (event.eventType) {
+        case EventType.JobStart:
+          options.onJobStart?.(event);
+          break;
+        case EventType.JobEnd:
+          options.onJobEnd?.(event);
+          break;
+        case EventType.FlowStart:
+          options.onFlowStart?.(event);
+          break;
+        case EventType.FlowEnd:
+          options.onFlowEnd?.(event);
+          break;
+        case EventType.FlowError:
+          options.onFlowError?.(event);
+          break;
+        case EventType.FlowPause:
+          options.onFlowPause?.(event);
+          break;
+        case EventType.FlowCancel:
+          options.onFlowCancel?.(event);
+          break;
+        case EventType.NodeStart:
+          options.onNodeStart?.(event);
+          break;
+        case EventType.NodeEnd:
+          options.onNodeEnd?.(event);
+          break;
+        case EventType.NodePause:
+          options.onNodePause?.(event);
+          break;
+        case EventType.NodeResume:
+          options.onNodeResume?.(event);
+          break;
+        case EventType.NodeError:
+          options.onNodeError?.(event);
+          break;
+      }
+    });
+
+    return unsubscribe;
+  }, [subscribeToEvents, options]);
+}

package/src/hooks/use-upload-events.ts

@@ -0,0 +1,218 @@
+import { UploadEventType } from "@uploadista/core/types";
+import { useEffect } from "react";
+import { useUploadistaContext } from "../components/uploadista-provider";
+import { isUploadEvent } from "./event-utils";
+
+/**
+ * Upload progress event data
+ */
+export interface UploadProgressEventData {
+  id: string;
+  progress: number;
+  total: number;
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  };
+}
+
+/**
+ * Upload started/complete event data (contains full UploadFile)
+ */
+export interface UploadFileEventData {
+  // This will contain the full UploadFile schema
+  [key: string]: unknown;
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  };
+}
+
+/**
+ * Upload failed event data
+ */
+export interface UploadFailedEventData {
+  id: string;
+  error: string;
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  };
+}
+
+/**
+ * Upload validation success event data
+ */
+export interface UploadValidationSuccessEventData {
+  id: string;
+  validationType: "checksum" | "mimetype";
+  algorithm?: string;
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  };
+}
+
+/**
+ * Upload validation failed event data
+ */
+export interface UploadValidationFailedEventData {
+  id: string;
+  reason: string;
+  expected: string;
+  actual: string;
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  };
+}
+
+/**
+ * Upload validation warning event data
+ */
+export interface UploadValidationWarningEventData {
+  id: string;
+  message: string;
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  };
+}
+
+/**
+ * Options for handling upload events.
+ *
+ * All callbacks are optional - only provide handlers for events you care about.
+ */
+export interface UseUploadEventsOptions {
+  /** Called when an upload starts */
+  onUploadStarted?: (data: UploadFileEventData) => void;
+  /** Called with upload progress updates */
+  onUploadProgress?: (data: UploadProgressEventData) => void;
+  /** Called when an upload completes successfully */
+  onUploadComplete?: (data: UploadFileEventData) => void;
+  /** Called when an upload fails */
+  onUploadFailed?: (data: UploadFailedEventData) => void;
+  /** Called when upload validation succeeds */
+  onUploadValidationSuccess?: (data: UploadValidationSuccessEventData) => void;
+  /** Called when upload validation fails */
+  onUploadValidationFailed?: (data: UploadValidationFailedEventData) => void;
+  /** Called when upload validation produces a warning */
+  onUploadValidationWarning?: (data: UploadValidationWarningEventData) => void;
+}
+
+/**
+ * Structured hook for handling upload events with type-safe callbacks.
+ *
+ * This hook provides a clean API for listening to specific upload events without
+ * needing to manually filter events or use type guards.
+ *
+ * Must be used within UploadistaProvider.
+ *
+ * @param options - Object with optional callbacks for each upload event type
+ *
+ * @example
+ * ```tsx
+ * import { useUploadEvents } from '@uploadista/expo';
+ * import { View, Text } from 'react-native';
+ *
+ * function UploadMonitor() {
+ *   useUploadEvents({
+ *     onUploadStarted: (data) => {
+ *       console.log('Upload started:', data.id);
+ *     },
+ *     onUploadProgress: (data) => {
+ *       const percent = (data.progress / data.total) * 100;
+ *       console.log(`Upload progress: ${percent}%`);
+ *     },
+ *     onUploadComplete: (data) => {
+ *       console.log('Upload completed:', data);
+ *     },
+ *     onUploadFailed: (data) => {
+ *       console.error('Upload failed:', data.error);
+ *     },
+ *   });
+ *
+ *   return <View><Text>Monitoring uploads...</Text></View>;
+ * }
+ * ```
+ */
+export function useUploadEvents(options: UseUploadEventsOptions): void {
+  const { subscribeToEvents } = useUploadistaContext();
+
+  useEffect(() => {
+    const unsubscribe = subscribeToEvents((event) => {
+      // Only handle upload events
+      if (!isUploadEvent(event)) return;
+
+      // Route to appropriate callback based on event type
+      // Note: flow context is at the top level of the event, not inside data
+      const flowContext = "flow" in event ? event.flow : undefined;
+
+      switch (event.type) {
+        case UploadEventType.UPLOAD_STARTED:
+          options.onUploadStarted?.({
+            ...(event.data as unknown as Omit<UploadFileEventData, "flow">),
+            flow: flowContext,
+          });
+          break;
+        case UploadEventType.UPLOAD_PROGRESS:
+          options.onUploadProgress?.({
+            ...(event.data as unknown as Omit<
+              UploadProgressEventData,
+              "flow"
+            >),
+            flow: flowContext,
+          });
+          break;
+        case UploadEventType.UPLOAD_COMPLETE:
+          options.onUploadComplete?.({
+            ...(event.data as unknown as Omit<UploadFileEventData, "flow">),
+            flow: flowContext,
+          });
+          break;
+        case UploadEventType.UPLOAD_FAILED:
+          options.onUploadFailed?.({
+            ...(event.data as unknown as Omit<UploadFailedEventData, "flow">),
+            flow: flowContext,
+          });
+          break;
+        case UploadEventType.UPLOAD_VALIDATION_SUCCESS:
+          options.onUploadValidationSuccess?.({
+            ...(event.data as unknown as Omit<
+              UploadValidationSuccessEventData,
+              "flow"
+            >),
+            flow: flowContext,
+          });
+          break;
+        case UploadEventType.UPLOAD_VALIDATION_FAILED:
+          options.onUploadValidationFailed?.({
+            ...(event.data as unknown as Omit<
+              UploadValidationFailedEventData,
+              "flow"
+            >),
+            flow: flowContext,
+          });
+          break;
+        case UploadEventType.UPLOAD_VALIDATION_WARNING:
+          options.onUploadValidationWarning?.({
+            ...(event.data as unknown as Omit<
+              UploadValidationWarningEventData,
+              "flow"
+            >),
+            flow: flowContext,
+          });
+          break;
+      }
+    });
+
+    return unsubscribe;
+  }, [subscribeToEvents, options]);
+}

package/src/hooks/use-uploadista-events.ts

@@ -0,0 +1,41 @@
+import type { UploadistaEvent } from "@uploadista/client-browser";
+import { useEffect } from "react";
+import { useUploadistaContext } from "../components/uploadista-provider";
+
+/**
+ * Simple hook that subscribes to all Uploadista events (both flow and upload events).
+ *
+ * This is a low-level hook that provides access to all events. For more structured
+ * event handling, consider using `useFlowEvents` or `useUploadEvents` instead.
+ *
+ * Must be used within UploadistaProvider.
+ *
+ * @param callback - Function called for every event emitted by the Uploadista client
+ *
+ * @example
+ * ```tsx
+ * import { useUploadistaEvents, isFlowEvent, isUploadEvent } from '@uploadista/expo';
+ *
+ * function MyComponent() {
+ *   useUploadistaEvents((event) => {
+ *     if (isFlowEvent(event)) {
+ *       console.log('Flow event:', event.eventType);
+ *     } else if (isUploadEvent(event)) {
+ *       console.log('Upload event:', event.type);
+ *     }
+ *   });
+ *
+ *   return <View><Text>Listening to all events...</Text></View>;
+ * }
+ * ```
+ */
+export function useUploadistaEvents(
+  callback: (event: UploadistaEvent) => void,
+): void {
+  const { subscribeToEvents } = useUploadistaContext();
+
+  useEffect(() => {
+    const unsubscribe = subscribeToEvents(callback);
+    return unsubscribe;
+  }, [subscribeToEvents, callback]);
+}

package/src/index.ts

@@ -74,6 +74,20 @@ export {
   type UseUploadistaClientReturn,
   useUploadistaClient,
 } from "./hooks/use-uploadista-client";
+// Export event hooks and utilities
+export { isFlowEvent, isUploadEvent } from "./hooks/event-utils";
+export { useUploadistaEvents } from "./hooks/use-uploadista-events";
+export { useFlowEvents, type UseFlowEventsOptions } from "./hooks/use-flow-events";
+export {
+  useUploadEvents,
+  type UseUploadEventsOptions,
+  type UploadProgressEventData,
+  type UploadFileEventData,
+  type UploadFailedEventData,
+  type UploadValidationSuccessEventData,
+  type UploadValidationFailedEventData,
+  type UploadValidationWarningEventData,
+} from "./hooks/use-upload-events";
 // Re-export service implementations and factories
 export {
   createAsyncStorageService,