@isi-ui7/bos7-shared 0.2.0

package/src/workflow/use-workflow-tracker.ts

@@ -0,0 +1,109 @@
+'use client';
+
+// Client-side hook for list pages that trigger CRUD-via-workflow operations.
+// Subscribes to /api/notifications/stream (notif7 SSE proxy) and fires
+// onComplete when an `instance.completed` event matches a tracked instance ID.
+//
+// The matched ID is workflow7's instance UUID — returned by the BFF as
+// `instance_id` (see respondWfStarted). NOT the idempotency key
+// (`wf_instance_id`); that's a separate UUID used by the service-task layer.
+
+import { useCallback, useEffect, useRef } from 'react';
+import { useSSE } from '@isi-ui7/realtime';
+
+// notif7's Notification struct has no JSON tags → Go field-name form
+// (EventType, RefID, Payload). Lowercase variants kept for forward-compat
+// if json tags are added later.
+export type WfNotifEvent = {
+  EventType?: string;
+  event_type?: string;
+  RefID?: string;
+  ref_id?: string;
+  Payload?: { instance_id?: string; workflow_id?: string; result?: string; reason?: string };
+  payload?: { instance_id?: string; workflow_id?: string; result?: string; reason?: string };
+};
+
+export type WfCompletionResult = {
+  status: 'success' | 'error';
+  /** Human-readable detail from payload.result (success) or payload.reason (error). */
+  message?: string;
+};
+
+// Terminal event types dispatched by workflow7. instance.failed is sent when a
+// service task exhausts retries; instance.cancelled when the flow is aborted.
+const DEFAULT_COMPLETION_EVENTS = ['instance.completed', 'instance.cancelled', 'instance.failed'];
+const ERROR_EVENT_TYPES = new Set(['instance.cancelled', 'instance.failed']);
+
+export type UseWorkflowTrackerOptions = {
+  /** SSE endpoint. Default: `/api/notifications/stream`. */
+  streamUrl?: string;
+  /** Event types treated as "workflow done". Default: all three terminal event types. */
+  completionEventTypes?: string[];
+  /** Fired when a tracked instance reaches a terminal state. */
+  onComplete?: (instanceId: string, result: WfCompletionResult) => void;
+  /** Disable subscription (e.g. when the page is not visible). Default: true. */
+  enabled?: boolean;
+};
+
+export type UseWorkflowTrackerReturn = {
+  /** Register a workflow instance UUID to watch for completion. */
+  track: (instanceId: string | undefined) => void;
+  /** Read-only snapshot of currently-tracked instance IDs. */
+  pending: () => string[];
+};
+
+export function useWorkflowTracker(options: UseWorkflowTrackerOptions = {}): UseWorkflowTrackerReturn {
+  const {
+    streamUrl = '/api/notifications/stream',
+    completionEventTypes = DEFAULT_COMPLETION_EVENTS,
+    onComplete,
+    enabled = true,
+  } = options;
+
+  const pendingRef = useRef<Set<string>>(new Set());
+  const onCompleteRef = useRef(onComplete);
+  const completionSetRef = useRef<Set<string>>(new Set(completionEventTypes));
+
+  useEffect(() => {
+    onCompleteRef.current = onComplete;
+  }, [onComplete]);
+  useEffect(() => {
+    completionSetRef.current = new Set(completionEventTypes);
+  }, [completionEventTypes]);
+
+  const handleMessage = useCallback((event: MessageEvent) => {
+    try {
+      const parsed = JSON.parse(event.data) as WfNotifEvent;
+      const type = parsed.EventType ?? parsed.event_type ?? '';
+      if (!completionSetRef.current.has(type)) return;
+      // workflow7's notif7Dispatcher sets RefID = instance UUID and also
+      // duplicates it into Payload.instance_id. Read whichever arrives.
+      const ref =
+        parsed.RefID ??
+        parsed.ref_id ??
+        parsed.Payload?.instance_id ??
+        parsed.payload?.instance_id ??
+        '';
+      if (!ref || !pendingRef.current.has(ref)) return;
+      pendingRef.current.delete(ref);
+      const isError = ERROR_EVENT_TYPES.has(type);
+      const payload = parsed.Payload ?? parsed.payload;
+      const message = isError
+        ? (payload?.reason ?? undefined)
+        : (payload?.result ?? undefined);
+      onCompleteRef.current?.(ref, { status: isError ? 'error' : 'success', message });
+    } catch {
+      /* ignore non-JSON heartbeats */
+    }
+  }, []);
+
+  useSSE(streamUrl, { enabled, onMessage: handleMessage });
+
+  const track = useCallback((instanceId: string | undefined) => {
+    if (instanceId) pendingRef.current.add(instanceId);
+  }, []);
+
+  const pending = useCallback(() => Array.from(pendingRef.current), []);
+
+  return { track, pending };
+}