@memori.ai/memori-react 8.40.4 → 8.41.1

package/src/helpers/nats/getNatsConfig.ts

@@ -9,6 +9,87 @@ export interface NatsConfig {
   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 } : {}),
+  };
 }
 
 /**
@@ -59,11 +140,6 @@ export async function getNatsConfig(
     }
   }
 
-  const data = (await response.json()) as Partial<NatsConfig>;
-
-  if (!data.url || !data.token) {
-    throw new Error('Invalid response from NATS config service');
-  }
-
-  return { url: data.url, token: data.token };
+  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

@@ -4,7 +4,7 @@
 // this hook *receives* asynchronous events on the session channel (progress /
 // dialog.text_entered_response / error).
 import { useEffect, useRef, useState, useCallback } from 'react';
-import { getNatsConfig } from './getNatsConfig';
+import { getNatsConfig, NatsConfig } from './getNatsConfig';
 import {
   useNatsSession,
   NatsSessionEvent,
@@ -39,9 +39,7 @@ export function useNats({
   onDialogResponse,
   onError,
 }: UseNatsOptions) {
-  const [config, setConfig] = useState<{ url: string; token: string } | null>(
-    null
-  );
+  const [config, setConfig] = useState<NatsConfig | null>(null);
   const [configError, setConfigError] = useState<Error | null>(null);
 
   // Keep callbacks in refs so the dispatcher identity stays stable.
@@ -75,7 +73,11 @@ export function useNats({
     getNatsConfig(baseUrl, sessionId, controller.signal)
       .then(cfg => {
         if (!cancelled) {
-          console.info('[NATS] config received, server url:', cfg.url);
+          console.info('[NATS] config received', {
+            url: cfg.url,
+            jetStream: !!cfg.stream,
+            stream: cfg.stream,
+          });
           setConfig(cfg);
           setConfigError(null);
         }
@@ -111,7 +113,7 @@ export function useNats({
     }
   }, []);
 
-  useNatsSession(sessionId, config?.url, config?.token, handleMessage);
+  useNatsSession(sessionId, config ?? undefined, handleMessage);
 
   return {
     /** True once connection config has been retrieved. */

package/src/helpers/nats/useNatsSession.ts

@@ -1,11 +1,23 @@
 // helpers/nats/useNatsSession.ts - Subscribe to a session's NATS channel.
 //
-// Opens a W3C WebSocket connection (via `wsconnect`), subscribes to the
-// session subject (`sessions.<sessionId>`) and forwards every decoded event to
-// `onMessage`. The cleanup (`nc.close()`) is essential: without it, every
-// `sessionId` change would leave orphan connections / iterators.
-import { useEffect, useRef } from 'react';
+// Opens a W3C WebSocket connection (via `wsconnect`), then either:
+// - core NATS: subscribes to the session subject directly, or
+// - JetStream: consumes from the configured stream (ordered consumer by default).
+//
+// When JetStream is enabled, reconnects on tab visibility / network resume and
+// replays the last message per subject to recover events missed while Safari
+// (or other browsers) suspend the WebSocket in background.
+//
+// The cleanup (`consumerMessages.stop()` + `nc.close()`) is essential: without
+// it, every `sessionId` change would leave orphan connections / iterators.
+import { useEffect, useRef, useState, type MutableRefObject } from 'react';
 import { wsconnect, NatsConnection } from '@nats-io/nats-core';
+import {
+  jetstream,
+  DeliverPolicy,
+  type ConsumerMessages,
+} from '@nats-io/jetstream';
+import type { NatsConfig } from './getNatsConfig';
 
 /**
  * `progress` event: job advancement updates.
@@ -52,6 +64,8 @@ export type NatsSessionEvent =
   | NatsDialogResponseEvent
   | NatsErrorEvent;
 
+type JetStreamConsumeMode = 'live' | 'catch-up';
+
 function readString(
   raw: Record<string, unknown>,
   camelKey: string,
@@ -143,49 +157,198 @@ export function normalizeNatsEvent(raw: Record<string, unknown>): NatsSessionEve
   } as NatsSessionEvent;
 }
 
+function decodeMessage(
+  subject: string,
+  received: number,
+  raw: Record<string, unknown>,
+  onMessage: (event: NatsSessionEvent) => void
+) {
+  const payload = normalizeNatsEvent(raw);
+  console.debug(
+    `[NATS] message #${received} on ${subject} (eventType=${payload.eventType})`,
+    payload
+  );
+  onMessage(payload);
+}
+
+async function consumeCoreSubscription(
+  nc: NatsConnection,
+  subject: string,
+  onMessage: (event: NatsSessionEvent) => void
+) {
+  const sub = nc.subscribe(subject);
+  console.info('[NATS] subscribed to subject', subject);
+  let received = 0;
+  for await (const msg of sub) {
+    received += 1;
+    try {
+      decodeMessage(
+        subject,
+        received,
+        msg.json<Record<string, unknown>>(),
+        onMessage
+      );
+    } catch (err) {
+      console.error('[NATS] message decode error', err);
+    }
+  }
+  console.info(
+    `[NATS] subscription on ${subject} closed (received ${received} messages)`
+  );
+}
+
+async function consumeJetStream(
+  nc: NatsConnection,
+  config: Pick<NatsConfig, 'stream' | 'consumer'>,
+  subject: string,
+  mode: JetStreamConsumeMode,
+  onMessage: (event: NatsSessionEvent) => void,
+  setConsumerMessages: (messages: ConsumerMessages) => void
+) {
+  const js = jetstream(nc);
+  const consumer = config.consumer
+    ? await js.consumers.get(config.stream!, config.consumer)
+    : await js.consumers.get(config.stream!, {
+        filter_subjects: [subject],
+        deliver_policy:
+          mode === 'catch-up'
+            ? DeliverPolicy.LastPerSubject
+            : DeliverPolicy.New,
+      });
+
+  console.info(
+    '[NATS] JetStream consumer ready',
+    config.consumer
+      ? { stream: config.stream, consumer: config.consumer, subject, mode }
+      : { stream: config.stream, subject, mode }
+  );
+
+  const messages = await consumer.consume();
+  setConsumerMessages(messages);
+  let received = 0;
+  for await (const msg of messages) {
+    received += 1;
+    try {
+      decodeMessage(subject, received, msg.json(), onMessage);
+    } catch (err) {
+      console.error('[NATS] message decode error', err);
+    }
+  }
+  console.info(
+    `[NATS] JetStream consumer on ${subject} closed (received ${received} messages)`
+  );
+}
+
+function closeNatsSession(
+  consumerMessagesRef: MutableRefObject<ConsumerMessages | null>,
+  connRef: MutableRefObject<NatsConnection | null>
+) {
+  consumerMessagesRef.current?.stop();
+  consumerMessagesRef.current = null;
+  connRef.current?.close();
+  connRef.current = null;
+}
+
 /**
  * Open a NATS WebSocket connection, subscribe to the session subject and
  * forward decoded events to `onMessage`.
  *
  * `onMessage` is kept in a ref so callers do not need to memoize it: the
- * connection is only (re)opened when `sessionId`, `natsWsUrl` or `natsToken`
+ * connection is only (re)opened when `sessionId`, `config` or `resumeGeneration`
  * change.
  *
  * @param sessionId Current session UUID (subscription is skipped when falsy).
- * @param natsWsUrl WebSocket URL of the NATS server.
- * @param natsToken Bearer token for authentication.
+ * @param config Connection config from `/api/nats` (url + token required).
  * @param onMessage Callback invoked for each decoded event.
  */
 export function useNatsSession(
   sessionId: string | undefined,
-  natsWsUrl: string | undefined,
-  natsToken: string | undefined,
+  config: NatsConfig | undefined,
   onMessage: (event: NatsSessionEvent) => void
 ) {
   const connRef = useRef<NatsConnection | null>(null);
+  const consumerMessagesRef = useRef<ConsumerMessages | null>(null);
   const onMessageRef = useRef(onMessage);
+  const wasHiddenRef = useRef(false);
+  const [resumeGeneration, setResumeGeneration] = useState(0);
 
   // Keep the latest callback without retriggering the connection effect.
   useEffect(() => {
     onMessageRef.current = onMessage;
   }, [onMessage]);
 
+  // Reconnect when the tab returns from background or the network comes back.
   useEffect(() => {
-    if (!sessionId || !natsWsUrl || !natsToken) {
+    if (!sessionId || !config?.stream) {
+      return;
+    }
+
+    const requestResume = () => {
+      if (document.visibilityState !== 'visible') {
+        return;
+      }
+      console.info('[NATS] resuming JetStream after visibility/network change');
+      setResumeGeneration(generation => generation + 1);
+    };
+
+    const onVisibilityChange = () => {
+      if (document.visibilityState === 'hidden') {
+        wasHiddenRef.current = true;
+        return;
+      }
+      if (wasHiddenRef.current) {
+        wasHiddenRef.current = false;
+        requestResume();
+      }
+    };
+
+    const onPageShow = (event: PageTransitionEvent) => {
+      if (event.persisted) {
+        requestResume();
+      }
+    };
+
+    document.addEventListener('visibilitychange', onVisibilityChange);
+    window.addEventListener('online', requestResume);
+    window.addEventListener('pageshow', onPageShow);
+
+    return () => {
+      document.removeEventListener('visibilitychange', onVisibilityChange);
+      window.removeEventListener('online', requestResume);
+      window.removeEventListener('pageshow', onPageShow);
+    };
+  }, [sessionId, config?.stream]);
+
+  useEffect(() => {
+    if (!sessionId || !config?.url || !config.token) {
       console.debug(
         '[NATS] subscription skipped (missing sessionId/url/token)',
-        { sessionId, hasUrl: !!natsWsUrl, hasToken: !!natsToken }
+        {
+          sessionId,
+          hasUrl: !!config?.url,
+          hasToken: !!config?.token,
+        }
       );
       return;
     }
+
     let closed = false;
-    const subject = sessionId;
+    const subject = config.subject ?? `sessions.${sessionId}`;
+    const useJetStream = !!config.stream;
+    const jetStreamMode: JetStreamConsumeMode =
+      useJetStream && resumeGeneration > 0 ? 'catch-up' : 'live';
 
     (async () => {
-      console.info('[NATS] connecting to', natsWsUrl, 'for session', sessionId);
+      console.info(
+        '[NATS] connecting to',
+        config.url,
+        'for session',
+        sessionId,
+        useJetStream ? `(JetStream/${jetStreamMode})` : '(core)'
+      );
       const nc = await wsconnect({
-        servers: [natsWsUrl],
-        token: natsToken,
+        servers: [config.url],
+        token: config.token,
       });
       if (closed) {
         console.debug(
@@ -197,34 +360,35 @@ export function useNatsSession(
       connRef.current = nc;
       console.info('[NATS] connected to', nc.getServer());
 
-      const sub = nc.subscribe(subject);
-      console.info('[NATS] subscribed to subject', subject);
-      let received = 0;
-      for await (const msg of sub) {
-        received += 1;
-        try {
-          const payload = normalizeNatsEvent(
-            msg.json<Record<string, unknown>>()
-          );
-          console.debug(
-            `[NATS] message #${received} on ${subject} (eventType=${payload.eventType})`,
-            payload
-          );
-          onMessageRef.current(payload);
-        } catch (err) {
-          console.error('[NATS] message decode error', err);
-        }
+      const dispatch = (event: NatsSessionEvent) => {
+        onMessageRef.current(event);
+      };
+
+      if (useJetStream) {
+        await consumeJetStream(
+          nc,
+          config,
+          subject,
+          jetStreamMode,
+          dispatch,
+          messages => {
+            consumerMessagesRef.current = messages;
+          }
+        );
+      } else {
+        await consumeCoreSubscription(nc, subject, dispatch);
       }
-      console.info(
-        `[NATS] subscription on ${subject} closed (received ${received} messages)`
-      );
     })().catch(err => console.error('[NATS] connection error', err));
 
     return () => {
       console.info('[NATS] cleanup: closing connection for subject', subject);
       closed = true;
-      connRef.current?.close();
-      connRef.current = null;
+      closeNatsSession(consumerMessagesRef, connRef);
     };
-  }, [sessionId, natsWsUrl, natsToken]);
+  }, [sessionId, config, resumeGeneration]);
+
+  // Reset catch-up generation when the active session changes.
+  useEffect(() => {
+    setResumeGeneration(0);
+  }, [sessionId]);
 }

package/src/index.stories.tsx

@@ -202,3 +202,19 @@ WithLocalNats.args = {
   spokenLang: 'IT',
   integrationID: 'ee1c3d98-7819-4506-ba28-818e79ba86cb',
 };
+
+export const WithFunctionalities = Template.bind({});
+WithFunctionalities.args = {
+  memoriName: 'test324',
+  ownerUserName: 'andrea.patini',
+  memoriID: 'd661a9ca-e907-4396-a986-5095ccd582d6',
+  ownerUserID: '69fcc557-9cb6-4e5e-b8ab-140cff975492',
+  tenantID: 'localhost:3000',
+  engineURL: 'http://localhost:7778/memori/v2',
+  apiURL: 'http://localhost:7778/api/v2',
+  baseURL: 'http://localhost:3000',
+  layout: 'FULLPAGE',
+  uiLang: 'IT',
+  spokenLang: 'IT',
+  integrationID: 'ee1c3d98-7819-4506-ba28-818e79ba86cb',
+};

package/src/locales/de.json

@@ -75,6 +75,7 @@
   "errorFetchingSession": "Fehler beim Laden der Sitzung",
   "errorGettingReferralURL": "Fehler beim Laden des Referrals",
   "errorReopeningSession": "Fehler beim erneuten Öffnen der Sitzung",
+  "sessionExpiredReopening": "Sitzung abgelaufen, Sitzung wird neu geöffnet",
   "ageVerification": "Altersüberprüfung",
   "ageVerificationText": "Um mit diesem Zwilling interagieren zu können, müssen Sie mindestens sein {{minAge}} Jahre alt.",
   "nsfw": "NSFW: Dieser Agent enthält Inhalte für Erwachsene",

package/src/locales/en.json

@@ -77,6 +77,7 @@
   "errorFetchingSession": "Error during session loading",
   "errorGettingReferralURL": "Error during referral loading",
   "errorReopeningSession": "Error during session reopening",
+  "sessionExpiredReopening": "Session expired, reopening session",
   "ageVerification": "Age verification",
   "ageVerificationText": "To interact with this agent, you must be at least {{minAge}} years old.",
   "nsfw": "NSFW: This agent contains adult contents",

package/src/locales/es.json

@@ -75,6 +75,7 @@
   "errorFetchingSession": "Error durante el cargamento de la sesión",
   "errorGettingReferralURL": "Error durante el cargamento del référent",
   "errorReopeningSession": "Error durante el re-abrir la sesión",
+  "sessionExpiredReopening": "Sesión expirada, reabriendo sesión",
   "ageVerification": "Verificación de edad",
   "ageVerificationText": "Para interactuar con este Gemelo, debes tener al menos {{minAge}} años.",
   "nsfw": "NSFW: Este gemelo contiene contenido para adultos",

package/src/locales/fr.json

@@ -74,6 +74,7 @@
   "errorFetchingSession": "Erreur lors du chargement de la session",
   "errorGettingReferralURL": "Erreur lors du chargement du référent",
   "errorReopeningSession": "Erreur lors de la re-ouverture de la session",
+  "sessionExpiredReopening": "Session expirée, réouverture en cours",
   "ageVerification": "Vérification de l'âge",
   "ageVerificationText": "Pour interagir avec ce Agent, vous devez être au minimum {{minAge}} ans.",
   "nsfw": "NSFW : Ce jumeau contient du contenu pour adultes",

package/src/locales/it.json

@@ -78,6 +78,7 @@
   "errorFetchingSession": "Errore durante il caricamento della sessione",
   "errorGettingReferralURL": "Errore durante il caricamento del riferimento",
   "errorReopeningSession": "Errore durante il riapertura della sessione",
+  "sessionExpiredReopening": "Sessione scaduta, riapertura in corso",
   "ageVerification": "Verifica dell'età",
   "ageVerificationText": "Per interagire con questo agente, devi aver almeno {{minAge}} anni.",
   "nsfw": "NSFW: Questo agente contiene contenuti per adulti",

package/src/version.ts

@@ -1,2 +1,2 @@
 // This file is auto-generated. Do not edit manually.
-export const version = '8.40.4';
+export const version = '8.41.1';