@memori.ai/memori-react 9.0.0-alpha.0 → 9.0.0-alpha.10

package/src/helpers/nats/getNatsConfig.ts

@@ -0,0 +1,145 @@
+// helpers/nats/getNatsConfig.ts - Fetch NATS connection params (url + token)
+// from the backend, using the same baseUrl already used for /api/tts and /api/stt.
+
+/**
+ * Connection parameters returned by `GET /api/nats?sessionId=<uuid>`.
+ */
+export interface NatsConfig {
+  /** WebSocket URL of the NATS server (e.g. wss://nats.hz.slnode.net:8080). */
+  url: string;
+  /** Bearer token used to authenticate the WebSocket connection. */
+  token: string;
+  /**
+   * JetStream stream that stores session events. When set, the client consumes
+   * via JetStream instead of core NATS subscribe.
+   */
+  stream?: string;
+  /**
+   * Optional durable consumer name. When omitted, an ordered ephemeral consumer
+   * filtered to the session subject is used.
+   */
+  consumer?: string;
+  /**
+   * Subject to subscribe or filter on. Defaults to `sessions.<sessionId>` when omitted.
+   */
+  subject?: string;
+}
+
+function readStringField(
+  raw: Record<string, unknown>,
+  ...keys: string[]
+): string | undefined {
+  for (const key of keys) {
+    const value = raw[key];
+    if (typeof value === 'string' && value.length > 0) {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+function readBooleanField(
+  raw: Record<string, unknown>,
+  ...keys: string[]
+): boolean | undefined {
+  for (const key of keys) {
+    const value = raw[key];
+    if (typeof value === 'boolean') {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Normalizes raw `/api/nats` payloads (camelCase or snake_case) into {@link NatsConfig}.
+ */
+export function parseNatsConfig(raw: Record<string, unknown>): NatsConfig {
+  const url = readStringField(raw, 'url');
+  const token = readStringField(raw, 'token');
+
+  if (!url || !token) {
+    throw new Error('Invalid response from NATS config service');
+  }
+
+  const useJetStream = readBooleanField(raw, 'useJetStream', 'use_jetstream');
+  const stream = readStringField(raw, 'stream', 'streamName', 'stream_name');
+  const consumer = readStringField(
+    raw,
+    'consumer',
+    'consumerName',
+    'consumer_name',
+    'durableName',
+    'durable_name'
+  );
+  const subject = readStringField(
+    raw,
+    'subject',
+    'filterSubject',
+    'filter_subject'
+  );
+
+  if (useJetStream && !stream) {
+    throw new Error('Invalid response from NATS config service: JetStream enabled but stream missing');
+  }
+
+  return {
+    url,
+    token,
+    ...(stream ? { stream } : {}),
+    ...(consumer ? { consumer } : {}),
+    ...(subject ? { subject } : {}),
+  };
+}
+
+/**
+ * Fetch the NATS connection config for a given session.
+ *
+ * Mirrors the error-handling style of the tts/stt helpers: the backend may
+ * answer with 400 (sessionId missing), 404 (invalid session) or 500 (NATS
+ * config missing). Any non-ok response throws with a descriptive message.
+ *
+ * @param baseUrl Same baseUrl used for `/api/tts` and `/api/stt`.
+ * @param sessionId Current session UUID.
+ * @param signal Optional AbortSignal to cancel the request.
+ */
+export async function getNatsConfig(
+  baseUrl: string,
+  sessionId: string,
+  signal?: AbortSignal
+): Promise<NatsConfig> {
+  if (!sessionId) {
+    throw new Error('Missing sessionId for NATS config request');
+  }
+
+  const response = await fetch(
+    `${baseUrl}/api/nats?sessionId=${encodeURIComponent(sessionId)}`,
+    { signal }
+  );
+
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => ({} as any));
+
+    switch (response.status) {
+      case 400:
+        throw new Error(
+          errorData.error || 'NATS config error: missing sessionId'
+        );
+      case 404:
+        throw new Error(
+          errorData.error || 'NATS config error: invalid session'
+        );
+      case 500:
+        throw new Error(
+          errorData.error || 'NATS config error: NATS configuration missing'
+        );
+      default:
+        throw new Error(
+          errorData.error || `NATS config error: ${response.status}`
+        );
+    }
+  }
+
+  const data = (await response.json()) as Record<string, unknown>;
+  return parseNatsConfig(data);
+}

package/src/helpers/nats/isSessionExpiredError.test.ts

@@ -0,0 +1,38 @@
+import {
+  isSessionExpiredNatsError,
+  isSessionExpiredNatsResponse,
+} from './isSessionExpiredError';
+
+describe('isSessionExpiredNatsError', () => {
+  it('detects session not found from EnterTextAsync NATS error', () => {
+    expect(
+      isSessionExpiredNatsError({
+        eventType: 'error',
+        errorCode: 'EnterTextAsync Error',
+        errorMessage:
+          'Session with ID "c681a10b-37c1-4783-af3b-ecb592b93036" not found',
+        correlationID: 'f85a6882-92e1-4e18-9fb7-29d3bc06fd7b',
+      })
+    ).toBe(true);
+  });
+
+  it('detects SESSION_EXPIRED result code on dialog response', () => {
+    expect(
+      isSessionExpiredNatsResponse({
+        eventType: 'dialog_text_entered_response',
+        resultCode: -103,
+        correlationID: 'abc',
+      })
+    ).toBe(true);
+  });
+
+  it('ignores unrelated NATS errors', () => {
+    expect(
+      isSessionExpiredNatsError({
+        eventType: 'error',
+        errorCode: 'SomeOtherError',
+        errorMessage: 'Something went wrong',
+      })
+    ).toBe(false);
+  });
+});

package/src/helpers/nats/isSessionExpiredError.ts

@@ -0,0 +1,51 @@
+import type {
+  NatsDialogResponseEvent,
+  NatsErrorEvent,
+} from './useNatsSession';
+
+/** Backend result codes for missing / expired sessions. */
+const SESSION_NOT_FOUND = -101;
+const SESSION_EXPIRED = -103;
+
+const SESSION_NOT_FOUND_MESSAGE =
+  /session\s+with\s+id\s+["']?[^"']+["']?\s+not\s+found/i;
+
+function isExpiredResultCode(resultCode?: number): boolean {
+  return (
+    resultCode === 404 ||
+    resultCode === SESSION_EXPIRED ||
+    resultCode === SESSION_NOT_FOUND
+  );
+}
+
+function isExpiredErrorMessage(message?: string): boolean {
+  if (!message) return false;
+  return SESSION_NOT_FOUND_MESSAGE.test(message);
+}
+
+/** True when a NATS `error` event indicates the active session is gone or expired. */
+export function isSessionExpiredNatsError(event: NatsErrorEvent): boolean {
+  if (isExpiredResultCode(event.errorCode as number | undefined)) {
+    return true;
+  }
+
+  if (typeof event.errorCode === 'string') {
+    const code = event.errorCode.toUpperCase();
+    if (code.includes('SESSION_EXPIRED') || code.includes('SESSION_NOT_FOUND')) {
+      return true;
+    }
+  }
+
+  return isExpiredErrorMessage(event.errorMessage);
+}
+
+/** True when a NATS dialog response reports a missing or expired session. */
+export function isSessionExpiredNatsResponse(
+  event: NatsDialogResponseEvent
+): boolean {
+  if (isExpiredResultCode(event.resultCode)) {
+    return true;
+  }
+
+  return isExpiredErrorMessage(event.resultMessage);
+}

package/src/helpers/nats/useNats.ts

@@ -0,0 +1,124 @@
+// helpers/nats/useNats.ts - Orchestrates NATS config retrieval + subscription.
+//
+// Additive to the existing HTTP flow: text is sent via `postEnterTextAsync`;
+// this hook *receives* asynchronous events on the session channel (progress /
+// dialog.text_entered_response / error).
+import { useEffect, useRef, useState, useCallback } from 'react';
+import { getNatsConfig, NatsConfig } from './getNatsConfig';
+import {
+  useNatsSession,
+  NatsSessionEvent,
+  NatsProgressEvent,
+  NatsDialogResponseEvent,
+  NatsErrorEvent,
+} from './useNatsSession';
+
+export interface UseNatsOptions {
+  /** Same baseUrl used for /api/tts and /api/stt. */
+  baseUrl: string;
+  /** Current session UUID. Subscription is skipped while undefined. */
+  sessionId?: string;
+  /** `progress` events (e.g. to feed the typing indicator). */
+  onProgress?: (event: NatsProgressEvent) => void;
+  /** `dialog.text_entered_response` events (optional live updates). */
+  onDialogResponse?: (event: NatsDialogResponseEvent) => void;
+  /** `error` events (logging / user notification). */
+  onError?: (event: NatsErrorEvent) => void;
+}
+
+/**
+ * Subscribe to the NATS session channel and dispatch decoded events to the
+ * provided callbacks. Config is fetched from `/api/nats`; the subscription
+ * lifecycle (cleanup on unmount, reconnect on sessionId change) is handled by
+ * `useNatsSession`.
+ */
+export function useNats({
+  baseUrl,
+  sessionId,
+  onProgress,
+  onDialogResponse,
+  onError,
+}: UseNatsOptions) {
+  const [config, setConfig] = useState<NatsConfig | null>(null);
+  const [configError, setConfigError] = useState<Error | null>(null);
+
+  // Keep callbacks in refs so the dispatcher identity stays stable.
+  const onProgressRef = useRef(onProgress);
+  const onDialogResponseRef = useRef(onDialogResponse);
+  const onErrorRef = useRef(onError);
+  useEffect(() => {
+    onProgressRef.current = onProgress;
+    onDialogResponseRef.current = onDialogResponse;
+    onErrorRef.current = onError;
+  }, [onProgress, onDialogResponse, onError]);
+
+  // Fetch connection config whenever the active session changes.
+  useEffect(() => {
+    if (!sessionId) {
+      console.debug('[NATS] no sessionId, skipping config fetch');
+      setConfig(null);
+      setConfigError(null);
+      return;
+    }
+
+    const controller = new AbortController();
+    let cancelled = false;
+
+    console.info(
+      '[NATS] fetching config from',
+      `${baseUrl}/api/nats`,
+      'for session',
+      sessionId
+    );
+    getNatsConfig(baseUrl, sessionId, controller.signal)
+      .then(cfg => {
+        if (!cancelled) {
+          console.info('[NATS] config received', {
+            url: cfg.url,
+            jetStream: !!cfg.stream,
+            stream: cfg.stream,
+          });
+          setConfig(cfg);
+          setConfigError(null);
+        }
+      })
+      .catch(err => {
+        if (!cancelled && err?.name !== 'AbortError') {
+          console.error('[NATS] config error', err);
+          setConfig(null);
+          setConfigError(err instanceof Error ? err : new Error(String(err)));
+        }
+      });
+
+    return () => {
+      cancelled = true;
+      controller.abort();
+    };
+  }, [baseUrl, sessionId]);
+
+  const handleMessage = useCallback((event: NatsSessionEvent) => {
+    console.debug('[NATS] dispatching event', { eventType: event.eventType });
+    switch (event.eventType) {
+      case 'progress':
+        onProgressRef.current?.(event);
+        break;
+      case 'dialog_text_entered_response':
+        onDialogResponseRef.current?.(event);
+        break;
+      case 'error':
+        onErrorRef.current?.(event);
+        break;
+      default:
+        console.warn('Unknown NATS event', event);
+    }
+  }, []);
+
+  useNatsSession(sessionId, config ?? undefined, handleMessage);
+
+  return {
+    /** True once connection config has been retrieved. */
+    connected: !!config,
+    /** Last config-retrieval error, if any. */
+    configError,
+  };
+}