@raisindb/client 0.5.9 → 0.5.11

package/dist/index.js

@@ -99,6 +99,7 @@ __export(src_exports, {
   UploadErrorCode: () => UploadErrorCode,
   UploadManager: () => UploadManager,
   Uploader: () => Uploader,
+  VisitorChatError: () => VisitorChatError,
   WorkspaceClient: () => WorkspaceClient,
   WorkspaceManager: () => WorkspaceManager,
   calculateChunkCount: () => calculateChunkCount,
@@ -120,6 +121,7 @@ __export(src_exports, {
   createSqlHandler: () => createSqlHandler,
   createSubscriptionAdapter: () => createSubscriptionAdapter,
   decodeMessage: () => decodeMessage,
+  defaultVisitorSessionStore: () => defaultVisitorSessionStore,
   encodeMessage: () => encodeMessage,
   getChunkRange: () => getChunkRange,
   getContentType: () => getContentType,
@@ -872,6 +874,7 @@ var RequestType = /* @__PURE__ */ ((RequestType2) => {
   RequestType2["NodeUpdate"] = "node_update";
   RequestType2["NodeDelete"] = "node_delete";
   RequestType2["NodeGet"] = "node_get";
+  RequestType2["NodeGetByLocalizedPath"] = "node_get_by_localized_path";
   RequestType2["NodeQuery"] = "node_query";
   RequestType2["NodeQueryByPath"] = "node_query_by_path";
   RequestType2["NodeQueryByProperty"] = "node_query_by_property";
@@ -973,6 +976,8 @@ var RequestType = /* @__PURE__ */ ((RequestType2) => {
   RequestType2["ScheduledInvocationCancel"] = "scheduled_invocation_cancel";
   RequestType2["ScheduledInvocationList"] = "scheduled_invocation_list";
   RequestType2["ScheduledInvocationGet"] = "scheduled_invocation_get";
+  RequestType2["VisitorChatStart"] = "visitor_chat_start";
+  RequestType2["VisitorChatSend"] = "visitor_chat_send";
   return RequestType2;
 })(RequestType || {});
 var ResponseStatus = /* @__PURE__ */ ((ResponseStatus2) => {
@@ -1256,7 +1261,8 @@ var EventHandler = class {
     this.filterSubscriptions.set(hash, {
       serverId: subscriptionId,
       filters: {},
-      callbacks: /* @__PURE__ */ new Set([callback])
+      callbacks: /* @__PURE__ */ new Set([callback]),
+      synthetic: true
     });
     this.subscriptions.set(subscriptionId, hash);
     this.callbackToHash.set(callback, hash);
@@ -1291,11 +1297,12 @@ var EventHandler = class {
   async restoreSubscriptions(options) {
     if (!options?.retry) {
       for (const entry of this.filterSubscriptions.values()) {
+        if (entry.synthetic) continue;
         this.subscriptions.delete(entry.serverId);
         entry.restorePending = true;
       }
     }
-    const entriesToRestore = Array.from(this.filterSubscriptions.entries()).filter(([, entry]) => entry.restorePending);
+    const entriesToRestore = Array.from(this.filterSubscriptions.entries()).filter(([, entry]) => entry.restorePending && !entry.synthetic);
     let failureCount = 0;
     let lastError;
     for (const [hash, entry] of entriesToRestore) {
@@ -1528,6 +1535,27 @@ var NodeOperations = class {
     const result = await this.sendRequest(payload, "node_history");
     return result ?? [];
   }
+  /**
+   * Get a node by its localized URL path (plan Phase 12).
+   *
+   * @param locale - Locale code (`fr`, `fr-CA`)
+   * @param path - The node's path in that locale (`/produits/chaise`)
+   * @returns The translated node with `canonical_path`,
+   *   `canonical_localized_path`, hreflang `alternates` and a `redirect`
+   *   hint, or `null` when nothing resolves (missing, hidden in the locale
+   *   or not readable — the same answer)
+   *
+   * @example
+   * ```typescript
+   * const hit = await ws.nodes().getByLocalizedPath('fr', '/produits/chaise');
+   * if (hit?.redirect) redirect301(`/fr${hit.canonical_localized_path}`);
+   * ```
+   */
+  async getByLocalizedPath(locale, path) {
+    const payload = { locale, path };
+    const result = await this.sendRequest(payload, "node_get_by_localized_path");
+    return result ?? null;
+  }
   /**
    * List a node's revision history by path (newest first).
    *
@@ -4487,7 +4515,8 @@ function normalizeHomePath(home) {
 // src/conversations.ts
 var DEFAULT_SEND_MESSAGE_INACTIVITY_TIMEOUT_MS = 12e4;
 var ConversationManager = class {
-  constructor(baseUrl, repository, authManager, options = {}, executeSql) {
+  constructor(baseUrl, repository, authManager, options = {}, executeSql, visitor) {
+    this.visitor = visitor;
     this.baseUrl = baseUrl.replace(/\/$/, "");
     this.repository = repository;
     this.authManager = authManager;
@@ -4608,6 +4637,45 @@ var ConversationManager = class {
       ]
     };
   }
+  /**
+   * Start (or resume) an ANONYMOUS conversation with an agent — a public
+   * website's chat, without login.
+   *
+   * Works on an anonymous connection only, and only with an agent that allows
+   * anonymous visitors (`anonymous.enabled: true` on its raisin:AIAgent). The
+   * server keeps the conversation in an ephemeral visitor session that only
+   * this browser session can read; the session secret is kept in
+   * sessionStorage (override with `options.store`), so a reload continues the
+   * same conversation. Then use `sendMessage`, `getMessages`, `subscribe` and
+   * `ConversationStore` / `useConversation` exactly as for a signed-in user.
+   *
+   * @example
+   * ```typescript
+   * const convo = await db.conversations.startAnonymous('/agents/website-assistant');
+   * for await (const ev of db.conversations.sendMessage(convo.conversationPath, 'Hello')) {
+   *   if (ev.type === 'text_chunk') append(ev.text);
+   *   if (ev.type === 'failed') showLimit(ev.code); // e.g. RATE_LIMITED, LIMIT_REACHED
+   * }
+   * ```
+   */
+  async startAnonymous(agent, options) {
+    if (!this.visitor) {
+      throw new Error("Anonymous chat needs a WebSocket database: use client.database(repo).");
+    }
+    return this.visitor.start(this.normalizeAgentPath(agent), options);
+  }
+  /** Forget the stored anonymous session for `agent` (the next start begins a new one). */
+  forgetAnonymous(agent, options) {
+    this.visitor?.forget(this.normalizeAgentPath(agent), options);
+  }
+  /** Whether this tab remembers an anonymous conversation with `agent`. */
+  hasStoredAnonymous(agent, options) {
+    return this.visitor?.remembers(this.normalizeAgentPath(agent), options) ?? false;
+  }
+  /** Whether `conversationPath` is an anonymous conversation of this client. */
+  isAnonymous(conversationPath) {
+    return this.visitor?.isAnonymous(conversationPath) ?? false;
+  }
   /**
    * Open an existing conversation by path.
    * Returns null if not found.
@@ -4653,6 +4721,7 @@ var ConversationManager = class {
    * Mark a conversation as read by setting unread_count to 0.
    */
   async markAsRead(conversationPath) {
+    if (this.isAnonymous(conversationPath)) return;
     const workspace = "raisin:access_control";
     await this.sqlQuery(
       `UPDATE '${workspace}' SET properties = jsonb_set(properties, '{unread_count}', '0'::jsonb) WHERE path = $1 AND node_type = 'raisin:Conversation'`,
@@ -4663,6 +4732,7 @@ var ConversationManager = class {
    * Mark a single message as read by the current user.
    */
   async markMessageAsRead(messagePath) {
+    if (messagePath.startsWith("/visitors/")) return;
     const workspace = "raisin:access_control";
     const now = (/* @__PURE__ */ new Date()).toISOString();
     await this.sqlQuery(
@@ -4687,6 +4757,18 @@ var ConversationManager = class {
    */
   async *sendMessage(conversationPath, content, options) {
     const shouldStream = options?.stream !== false;
+    if (this.visitor?.isAnonymous(conversationPath)) {
+      if (!shouldStream) {
+        await this.visitor.post(conversationPath, content);
+        yield { type: "waiting", timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+        return;
+      }
+      yield* this.visitor.stream(conversationPath, content, {
+        signal: options?.signal,
+        inactivityTimeoutMs: options?.inactivityTimeoutMs ?? DEFAULT_SEND_MESSAGE_INACTIVITY_TIMEOUT_MS
+      });
+      return;
+    }
     logger.debug("[ConversationManager] Starting SSE stream for message send");
     if (!shouldStream) {
       await this.createUserMessage(conversationPath, content);
@@ -4774,6 +4856,10 @@ var ConversationManager = class {
    */
   async createUserMessage(conversationPath, content) {
     logger.debug("[ConversationManager] Creating user message", { path: conversationPath });
+    if (this.visitor?.isAnonymous(conversationPath)) {
+      await this.visitor.post(conversationPath, content);
+      return;
+    }
     const workspace = "raisin:access_control";
     const properties = await this.loadConversationProperties(conversationPath, workspace);
     const flowInstanceId = typeof properties?.flow_instance_id === "string" ? properties.flow_instance_id.trim() : "";
@@ -4825,6 +4911,12 @@ var ConversationManager = class {
    * initiated messages, etc.). Auto-reconnects on disconnect.
    */
   subscribe(conversationPath, onEvent, options) {
+    if (this.visitor?.isAnonymous(conversationPath)) {
+      const stop = this.visitor.listen(conversationPath, onEvent);
+      options?.signal?.addEventListener("abort", stop, { once: true });
+      return { unsubscribe: stop, waitUntilConnected: async () => {
+      } };
+    }
     logger.info("[ConversationManager] Subscribing to SSE", { path: conversationPath });
     const sseUrl = `${this.baseUrl}/api/conversations/${this.repository}/events`;
     const headers = {};
@@ -5264,6 +5356,272 @@ var ConversationManager = class {
   }
 };
 
+// src/visitor-chat.ts
+function defaultVisitorSessionStore() {
+  const memory = /* @__PURE__ */ new Map();
+  const storage = () => {
+    try {
+      return typeof sessionStorage !== "undefined" ? sessionStorage : null;
+    } catch {
+      return null;
+    }
+  };
+  return {
+    get(key) {
+      try {
+        return storage()?.getItem(key) ?? memory.get(key) ?? null;
+      } catch {
+        return memory.get(key) ?? null;
+      }
+    },
+    set(key, value) {
+      memory.set(key, value);
+      try {
+        storage()?.setItem(key, value);
+      } catch {
+      }
+    },
+    remove(key) {
+      memory.delete(key);
+      try {
+        storage()?.removeItem(key);
+      } catch {
+      }
+    }
+  };
+}
+var VisitorChatError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = "VisitorChatError";
+    this.code = code;
+  }
+};
+var REBIND_CODES = /* @__PURE__ */ new Set(["NO_SESSION", "UNKNOWN_CONVERSATION"]);
+function asError(err) {
+  const e = err;
+  return new VisitorChatError(e?.message ?? String(err), e?.code ?? "UNAVAILABLE");
+}
+var VisitorChat = class {
+  constructor(repository, send, events, onReconnected) {
+    this.repository = repository;
+    this.send = send;
+    this.events = events;
+    this.byPath = /* @__PURE__ */ new Map();
+    this.token = null;
+    onReconnected?.(() => {
+      void this.rebindAll();
+    });
+  }
+  /** Whether `conversationPath` is a visitor conversation started here. */
+  isAnonymous(conversationPath) {
+    return this.byPath.has(conversationPath);
+  }
+  storeOf(options) {
+    if (options.store === false) return null;
+    return options.store ?? defaultVisitorSessionStore();
+  }
+  keyOf(agent, options) {
+    return options.storageKey ?? `raisindb:visitor:${this.repository}:${agent}`;
+  }
+  /** Start (or resume) a visitor conversation with `agent` (`/agents/<name>`). */
+  async start(agent, options = {}) {
+    const store = this.storeOf(options);
+    const key = this.keyOf(agent, options);
+    const sessionToken = options.sessionToken ?? this.token ?? store?.get(`${key}:session`) ?? void 0;
+    const conversationId = options.newConversation ? void 0 : options.conversationId ?? store?.get(`${key}:conversation`) ?? void 0;
+    let res;
+    try {
+      res = await this.send(
+        { agent, session_token: sessionToken, conversation_id: conversationId },
+        "visitor_chat_start"
+      );
+    } catch (err) {
+      const e = asError(err);
+      if ((conversationId || sessionToken) && !options.conversationId && !options.sessionToken && ["UNKNOWN_CONVERSATION", "INVALID_CONVERSATION", "SESSION_EXPIRED", "SESSION_MISMATCH"].includes(e.code)) {
+        store?.remove(`${key}:conversation`);
+        if (e.code !== "UNKNOWN_CONVERSATION" && e.code !== "INVALID_CONVERSATION") {
+          store?.remove(`${key}:session`);
+          this.token = null;
+        }
+        return this.start(agent, { ...options, newConversation: true });
+      }
+      throw e;
+    }
+    const token = res.session_token ?? sessionToken ?? this.token;
+    if (!token) throw new VisitorChatError("the server returned no session", "UNAVAILABLE");
+    this.token = token;
+    store?.set(`${key}:session`, token);
+    store?.set(`${key}:conversation`, res.conversation_id);
+    const path = res.conversation_path;
+    let entry = this.byPath.get(path);
+    if (!entry) {
+      entry = {
+        agent: res.agent,
+        conversationId: res.conversation_id,
+        subscriptionId: res.subscription_id,
+        listeners: /* @__PURE__ */ new Set(),
+        options
+      };
+      this.byPath.set(path, entry);
+    }
+    this.route(entry);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    return {
+      id: res.conversation_id,
+      type: "ai_chat",
+      agentRef: res.agent,
+      conversationPath: path,
+      conversationWorkspace: res.conversation_workspace,
+      anonymous: true,
+      conversationId: res.conversation_id,
+      sessionToken: token,
+      limits: res.limits,
+      initialEvents: [{ type: "waiting", timestamp: now }]
+    };
+  }
+  /** Route the server's forwarded events for this conversation to its listeners. */
+  route(entry) {
+    this.events.removeFlowEventListener(entry.subscriptionId);
+    this.events.addFlowEventListener(entry.subscriptionId, (msg) => {
+      const event = msg.payload;
+      if (!event || typeof event.type !== "string") return;
+      for (const listener of entry.listeners) {
+        try {
+          listener(event);
+        } catch (err) {
+          logger.error("[VisitorChat] listener failed", err);
+        }
+      }
+    });
+  }
+  /** Re-prove the session on a new connection, for every conversation started here. */
+  async rebindAll() {
+    for (const entry of this.byPath.values()) {
+      try {
+        await this.send(
+          { agent: entry.agent, session_token: this.token, conversation_id: entry.conversationId },
+          "visitor_chat_start"
+        );
+        this.route(entry);
+      } catch (err) {
+        logger.warn("[VisitorChat] could not resume a conversation after reconnect", err);
+      }
+    }
+  }
+  /** Listen to a visitor conversation's events. Returns an unsubscribe function. */
+  listen(conversationPath, listener) {
+    const entry = this.require(conversationPath);
+    entry.listeners.add(listener);
+    return () => {
+      entry.listeners.delete(listener);
+    };
+  }
+  require(conversationPath) {
+    const entry = this.byPath.get(conversationPath);
+    if (!entry) {
+      throw new VisitorChatError(
+        "not a visitor conversation of this client; call startAnonymous first",
+        "UNKNOWN_CONVERSATION"
+      );
+    }
+    return entry;
+  }
+  /** Make sure this connection is bound (after a reconnect nothing else may read the home). */
+  async ensureBound(conversationPath) {
+    const entry = this.require(conversationPath);
+    await this.send(
+      { agent: entry.agent, session_token: this.token, conversation_id: entry.conversationId },
+      "visitor_chat_start"
+    ).catch((err) => {
+      throw asError(err);
+    });
+  }
+  /** Send one visitor message. Events arrive through {@link listen}. */
+  async post(conversationPath, text) {
+    const entry = this.require(conversationPath);
+    const once = async () => await this.send(
+      { conversation_id: entry.conversationId, text },
+      "visitor_chat_send"
+    );
+    try {
+      const res = await once();
+      return { messageId: res.message_id, messagesLeft: res.messages_left };
+    } catch (err) {
+      const e = asError(err);
+      if (!REBIND_CODES.has(e.code)) throw e;
+      await this.ensureBound(conversationPath);
+      this.route(entry);
+      const res = await once().catch((again) => {
+        throw asError(again);
+      });
+      return { messageId: res.message_id, messagesLeft: res.messages_left };
+    }
+  }
+  /**
+   * Send one visitor message and stream the turn: `text_chunk`,
+   * `tool_call_started`, `tool_call_completed`, … until `done`. A refusal
+   * ends the stream with `failed` (its `code` says why). No event for
+   * `inactivityTimeoutMs` ends it with a synthetic `waiting`.
+   */
+  async *stream(conversationPath, text, options = {}) {
+    const queue = [];
+    let wake = null;
+    const push = (event) => {
+      queue.push(event);
+      wake?.();
+    };
+    const stop = this.listen(conversationPath, push);
+    const onAbort = () => push({ type: "failed", error: "aborted", code: "ABORTED", timestamp: (/* @__PURE__ */ new Date()).toISOString() });
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    const timeout = options.inactivityTimeoutMs ?? 12e4;
+    try {
+      try {
+        await this.post(conversationPath, text);
+      } catch (err) {
+        const e = asError(err);
+        yield { type: "failed", error: e.message, code: e.code, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+        return;
+      }
+      for (; ; ) {
+        if (!queue.length) {
+          const idle = await new Promise((resolve) => {
+            const timer = timeout > 0 ? setTimeout(() => resolve(true), timeout) : null;
+            wake = () => {
+              if (timer) clearTimeout(timer);
+              resolve(false);
+            };
+          });
+          wake = null;
+          if (idle && !queue.length) {
+            yield { type: "waiting", timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+            return;
+          }
+        }
+        const event = queue.shift();
+        yield event;
+        if (event.type === "done" || event.type === "failed" || event.type === "waiting") return;
+      }
+    } finally {
+      stop();
+      options.signal?.removeEventListener("abort", onAbort);
+    }
+  }
+  /** Whether the store remembers a conversation with `agent`. */
+  remembers(agent, options = {}) {
+    const store = this.storeOf(options);
+    return !!store?.get(`${this.keyOf(agent, options)}:conversation`);
+  }
+  /** Forget the stored session (e.g. a "new chat" button that should start a new session). */
+  forget(agent, options = {}) {
+    const store = this.storeOf(options);
+    const key = this.keyOf(agent, options);
+    store?.remove(`${key}:session`);
+    store?.remove(`${key}:conversation`);
+    this.token = null;
+  }
+};
+
 // src/flow-client.ts
 var FlowClient = class _FlowClient {
   /**
@@ -6156,7 +6514,13 @@ var Database = class _Database {
         this.repository,
         this.httpOptions.authManager,
         {},
-        (query, params) => this.executeSql(query, params)
+        (query, params) => this.executeSql(query, params),
+        new VisitorChat(
+          this.repository,
+          (payload, requestType) => this.sendRequest(payload, requestType),
+          this.eventHandler,
+          this.httpOptions.onReconnected
+        )
       );
     }
     return this._conversationManager;
@@ -10023,7 +10387,11 @@ var _RaisinClient = class _RaisinClient extends import_events4.EventEmitter {
       void 0,
       () => this.getUploadManager(),
       (options) => this.signAssetUrl(options),
-      { httpBaseUrl: this._httpBaseUrl, authManager: this.authManager }
+      {
+        httpBaseUrl: this._httpBaseUrl,
+        authManager: this.authManager,
+        onReconnected: (callback) => this.onReconnected(callback)
+      }
     );
   }
   /**
@@ -11403,6 +11771,34 @@ var ConversationStore = class {
     this._watchdogIntervalMs = options.watchdogIntervalMs ?? 3e4;
     if (this._conversationPath) {
       this.ensureSubscription();
+    } else if (this.createOptions?.anonymous) {
+      void this.resumeAnonymous();
+    }
+  }
+  anonymousOptions() {
+    const a = this.createOptions?.anonymous;
+    if (!a) return null;
+    return a === true ? {} : a;
+  }
+  /**
+   * Resume the visitor conversation this tab already has (the session secret
+   * and conversation id live in sessionStorage), and load its history. A tab
+   * without one starts nothing until the first message.
+   */
+  async resumeAnonymous() {
+    const opts = this.anonymousOptions();
+    if (!opts || !this.createOptions || this._conversationPath) return;
+    const agent = this.createOptions.participant;
+    try {
+      if (!this.manager.hasStoredAnonymous(agent, opts)) return;
+      const convo = await this.manager.startAnonymous(agent, opts);
+      if (this._conversationPath) return;
+      this._conversationPath = convo.conversationPath;
+      this._conversationType = convo.type;
+      this.ensureSubscription();
+      await this.loadMessages();
+    } catch (err) {
+      logger.debug("[ConversationStore] No visitor conversation to resume", err);
     }
   }
   // ==========================================================================
@@ -11457,7 +11853,8 @@ var ConversationStore = class {
         throw new Error("No conversationPath and no createOptions provided");
       }
       try {
-        const convo = await this.manager.create({
+        const anonymous = this.anonymousOptions();
+        const convo = anonymous ? await this.manager.startAnonymous(this.createOptions.participant, anonymous) : await this.manager.create({
           participant: this.createOptions.participant,
           input: this.createOptions.input
         });
@@ -13345,6 +13742,7 @@ function createRaisinVue(vue) {
   UploadErrorCode,
   UploadManager,
   Uploader,
+  VisitorChatError,
   WorkspaceClient,
   WorkspaceManager,
   calculateChunkCount,
@@ -13366,6 +13764,7 @@ function createRaisinVue(vue) {
   createSqlHandler,
   createSubscriptionAdapter,
   decodeMessage,
+  defaultVisitorSessionStore,
   encodeMessage,
   getChunkRange,
   getContentType,