@gravity-rail/sdk 0.21.0 → 0.32.0

package/dist/realtime.cjs

@@ -20,14 +20,28 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/realtime/index.ts
 var realtime_exports = {};
 __export(realtime_exports, {
+  ACCOUNT_ACTIVITY_CHANNEL: () => ACCOUNT_ACTIVITY_CHANNEL,
+  ACCOUNT_PRESENCE_CHANNEL: () => ACCOUNT_PRESENCE_CHANNEL,
+  ACTIVITY_CHANNEL: () => ACTIVITY_CHANNEL,
+  ACTIVITY_MEMBER_CHANNEL: () => ACTIVITY_MEMBER_CHANNEL,
+  AccountRealtimeClient: () => AccountRealtimeClient,
   OperatorSessionClient: () => OperatorSessionClient,
+  PRESENCE_CHANNEL: () => PRESENCE_CHANNEL,
+  RealtimeSocketClient: () => RealtimeSocketClient,
   WorkspaceRealtimeClient: () => WorkspaceRealtimeClient,
+  buildAccountWsUrl: () => buildAccountWsUrl,
   buildWorkspaceWsUrl: () => buildWorkspaceWsUrl,
+  initAccountSocket: () => initAccountSocket,
   initWorkspaceSocket: () => initWorkspaceSocket,
+  isAccountSocketConnected: () => isAccountSocketConnected,
   isActiveCallPhase: () => isActiveCallPhase,
+  isActivityInvalidation: () => isActivityInvalidation,
   isWorkspaceSocketConnected: () => isWorkspaceSocketConnected,
+  onAccountSocketConnection: () => onAccountSocketConnection,
   onWorkspaceSocketConnection: () => onWorkspaceSocketConnection,
-  subscribeWorkspaceChannel: () => subscribeWorkspaceChannel
+  subscribeAccountChannel: () => subscribeAccountChannel,
+  subscribeWorkspaceChannel: () => subscribeWorkspaceChannel,
+  workspaceChannel: () => workspaceChannel
 });
 module.exports = __toCommonJS(realtime_exports);
 
@@ -35,19 +49,37 @@ module.exports = __toCommonJS(realtime_exports);
 function isActiveCallPhase(phase) {
   return phase === "dialing" || phase === "live" || phase === "onHold";
 }
+var ACTIVITY_CHANNEL = "activity";
+var ACTIVITY_MEMBER_CHANNEL = "activity:me";
+var ACCOUNT_ACTIVITY_CHANNEL = "account:activity";
+var ACCOUNT_PRESENCE_CHANNEL = "account:presence";
+var PRESENCE_CHANNEL = "presence";
+function isActivityInvalidation(event) {
+  if (event.type !== "invalidate") return false;
+  const data = event.data;
+  if (typeof data !== "object" || data === null) return false;
+  const scope = data.scope;
+  return scope === "workspace" || scope === "member" || scope === "account";
+}
 
-// src/realtime/workspace-client.ts
+// src/realtime/socket-client.ts
 var HEARTBEAT_INTERVAL_MS = 3e4;
 var RECONNECT_DELAY_MS = 3e3;
 var MAX_RECONNECT_ATTEMPTS = 5;
 var CLOSE_DELAY_MS = 1e3;
+var MAX_SUBSCRIBE_RETRY_DELAY_MS = 3e4;
 function createSocketState() {
   return {
     ws: null,
     connected: false,
     connecting: false,
+    lastError: null,
     listeners: /* @__PURE__ */ new Map(),
     subscribedChannels: /* @__PURE__ */ new Set(),
+    subscriptionRevision: 0,
+    subscriptionRetryChannels: /* @__PURE__ */ new Set(),
+    subscriptionRetryAttempts: 0,
+    subscriptionRetryTimer: null,
     reconnectAttempts: 0,
     reconnectTimer: null,
     heartbeatTimer: null,
@@ -55,12 +87,7 @@ function createSocketState() {
     intentionalClose: false
   };
 }
-function buildWorkspaceWsUrl(session) {
-  const isSsl = session.apiUrl.startsWith("https");
-  const host = session.apiUrl.replace(/^https?:\/\//, "");
-  return `${isSsl ? "wss" : "ws"}://${host}/api/v2/w/${session.workspaceUuid}/ws/realtime`;
-}
-var WorkspaceRealtimeClient = class {
+var RealtimeSocketClient = class {
   session = null;
   getSessionFn;
   state = createSocketState();
@@ -75,6 +102,16 @@ var WorkspaceRealtimeClient = class {
       }
     }
   }
+  /**
+   * Whether replacing `previous` with `next` invalidates the open socket.
+   *
+   * The token always does; the rest is mount-specific — a workspace client
+   * changing workspace is a different socket, and an account client has no
+   * such axis.
+   */
+  sessionRequiresReconnect(previous, next) {
+    return previous?.accessToken !== next.accessToken || previous?.apiUrl !== next.apiUrl;
+  }
   resolveSession() {
     return this.session ?? this.getSessionFn?.() ?? null;
   }
@@ -89,8 +126,54 @@ var WorkspaceRealtimeClient = class {
       this.state.closeTimer = null;
     }
   }
+  clearSubscriptionRetry(channel) {
+    if (channel) {
+      this.state.subscriptionRetryChannels.delete(channel);
+    } else {
+      this.state.subscriptionRetryChannels.clear();
+    }
+    if (this.state.subscriptionRetryChannels.size > 0) return;
+    if (this.state.subscriptionRetryTimer) {
+      clearTimeout(this.state.subscriptionRetryTimer);
+      this.state.subscriptionRetryTimer = null;
+    }
+    this.state.subscriptionRetryAttempts = 0;
+  }
+  scheduleSubscriptionRetry(channels) {
+    for (const channel of channels) {
+      if (this.state.listeners.has(channel) && !this.state.subscribedChannels.has(channel)) {
+        this.state.subscriptionRetryChannels.add(channel);
+      }
+    }
+    if (this.state.subscriptionRetryChannels.size === 0 || this.state.subscriptionRetryTimer) {
+      return;
+    }
+    this.state.subscriptionRetryAttempts += 1;
+    const delay = Math.min(
+      RECONNECT_DELAY_MS * this.state.subscriptionRetryAttempts,
+      MAX_SUBSCRIBE_RETRY_DELAY_MS
+    );
+    this.state.subscriptionRetryTimer = setTimeout(() => {
+      this.state.subscriptionRetryTimer = null;
+      const retryChannels = Array.from(this.state.subscriptionRetryChannels).filter(
+        (channel) => this.state.listeners.has(channel) && !this.state.subscribedChannels.has(channel)
+      );
+      for (const channel of this.state.subscriptionRetryChannels) {
+        if (!retryChannels.includes(channel)) {
+          this.state.subscriptionRetryChannels.delete(channel);
+        }
+      }
+      if (retryChannels.length === 0) {
+        this.state.subscriptionRetryAttempts = 0;
+        return;
+      }
+      if (this.state.connected && this.state.ws?.readyState === WebSocket.OPEN) {
+        this.state.ws.send(JSON.stringify({ type: "subscribe", channels: retryChannels }));
+      }
+    }, delay);
+  }
   setSession(session) {
-    const changed = this.session?.accessToken !== session.accessToken || this.session?.workspaceUuid !== session.workspaceUuid || this.session?.apiUrl !== session.apiUrl;
+    const changed = this.sessionRequiresReconnect(this.session, session);
     this.session = session;
     if (changed && this.state.ws) {
       this.closeConnection();
@@ -117,6 +200,7 @@ var WorkspaceRealtimeClient = class {
       if (channelListeners && channelListeners.size === 0) {
         this.state.listeners.delete(channel);
         this.state.subscribedChannels.delete(channel);
+        this.clearSubscriptionRetry(channel);
         if (this.state.connected && this.state.ws?.readyState === WebSocket.OPEN) {
           this.state.ws.send(JSON.stringify({ type: "unsubscribe", channels: [channel] }));
         }
@@ -144,6 +228,44 @@ var WorkspaceRealtimeClient = class {
   isConnected() {
     return this.state.connected;
   }
+  /**
+   * Whether the server has acknowledged this channel subscription.
+   *
+   * This is stricter than having a local listener: it becomes true only after
+   * a `subscribed` frame, returns to false on disconnect or server-driven
+   * unsubscribe, and stays false while automatic subscribe retry is pending.
+   * Consumers that must order a command after subscription admission should
+   * observe {@link getSubscriptionRevision} and re-read this method.
+   */
+  isSubscribed(channel) {
+    return this.state.subscribedChannels.has(channel);
+  }
+  /**
+   * Monotonic local revision of acknowledged subscription state.
+   *
+   * It increments when `subscribed` or `unsubscribed` changes the server-
+   * acknowledged set. It is not a protocol sequence number and resets with a
+   * new client instance; its purpose is external-store invalidation before a
+   * consumer calls {@link isSubscribed} again.
+   */
+  getSubscriptionRevision() {
+    return this.state.subscriptionRevision;
+  }
+  /**
+   * A socket is open or opening and has not yet said `protocol.init`.
+   *
+   * Real state, read off the state machine. Consumers used to report a
+   * literal `false` here and render "Available" over a socket that had never
+   * connected; a toggle that cannot distinguish "not live" from "cannot tell
+   * yet" is the shape of that bug.
+   */
+  isConnecting() {
+    return this.state.connecting;
+  }
+  /** The last failure the socket gave up on, or null. See {@link SocketState.lastError}. */
+  getLastError() {
+    return this.state.lastError;
+  }
   ensureConnection() {
     const session = this.resolveSession();
     if (!session) return;
@@ -152,17 +274,21 @@ var WorkspaceRealtimeClient = class {
     this.clearCloseTimer();
     this.state.connecting = true;
     this.state.intentionalClose = false;
-    const ws = new WebSocket(buildWorkspaceWsUrl(session));
+    this.notifyConnectionListeners();
+    const ws = new WebSocket(this.buildUrl(session));
     ws.onopen = () => {
       ws.send(JSON.stringify({ type: "login", token: session.accessToken }));
     };
     ws.onmessage = (event) => {
+      if (this.state.ws !== null && this.state.ws !== ws) return;
       try {
         const msg = JSON.parse(String(event.data));
         if (msg.type === "protocol.init" && !this.state.connected) {
           this.state.connected = true;
+          this.readProtocolInit(msg);
           this.state.connecting = false;
           this.state.reconnectAttempts = 0;
+          this.state.lastError = null;
           if (this.state.heartbeatTimer) clearInterval(this.state.heartbeatTimer);
           this.state.heartbeatTimer = setInterval(() => {
             if (this.state.ws?.readyState === WebSocket.OPEN) {
@@ -183,13 +309,40 @@ var WorkspaceRealtimeClient = class {
         if (msg.type === "subscribed" && Array.isArray(msg.channels)) {
           for (const ch of msg.channels) {
             this.state.subscribedChannels.add(ch);
+            this.clearSubscriptionRetry(ch);
           }
+          this.state.subscriptionRevision += 1;
+          this.notifyConnectionListeners();
+          return;
+        }
+        if (msg.type === "subscribe_error" && Array.isArray(msg.errors)) {
+          const retryableChannels = [];
+          for (const rawError of msg.errors) {
+            if (!rawError || typeof rawError !== "object") continue;
+            const error = rawError;
+            if (typeof error.channel !== "string") continue;
+            if (error.retryable === true) {
+              retryableChannels.push(error.channel);
+            } else {
+              this.clearSubscriptionRetry(error.channel);
+            }
+          }
+          this.scheduleSubscriptionRetry(retryableChannels);
           return;
         }
         if (msg.type === "unsubscribed" && Array.isArray(msg.channels)) {
           for (const ch of msg.channels) {
             this.state.subscribedChannels.delete(ch);
           }
+          this.state.subscriptionRevision += 1;
+          this.notifyConnectionListeners();
+          this.scheduleSubscriptionRetry(msg.channels);
+          return;
+        }
+        if (msg.type === "error") {
+          const message = msg.message;
+          this.state.lastError = typeof message === "string" && message ? message : "Realtime error";
+          this.notifyConnectionListeners();
           return;
         }
         if (msg.type === "event" && msg.channel && msg.event) {
@@ -208,16 +361,22 @@ var WorkspaceRealtimeClient = class {
       }
     };
     ws.onclose = () => {
+      if (this.state.ws !== null && this.state.ws !== ws) return;
       this.state.connected = false;
       this.state.connecting = false;
       this.state.ws = null;
       this.state.subscribedChannels.clear();
+      this.clearSubscriptionRetry();
       if (this.state.heartbeatTimer) {
         clearInterval(this.state.heartbeatTimer);
         this.state.heartbeatTimer = null;
       }
+      const willRetry = !this.state.intentionalClose && this.state.listeners.size > 0 && this.state.reconnectAttempts < MAX_RECONNECT_ATTEMPTS;
+      if (!willRetry && !this.state.intentionalClose && this.state.listeners.size > 0) {
+        this.state.lastError = "Realtime connection lost";
+      }
       this.notifyConnectionListeners();
-      if (!this.state.intentionalClose && this.state.listeners.size > 0 && this.state.reconnectAttempts < MAX_RECONNECT_ATTEMPTS) {
+      if (willRetry) {
         this.state.reconnectAttempts += 1;
         this.state.reconnectTimer = setTimeout(() => {
           this.ensureConnection();
@@ -242,11 +401,47 @@ var WorkspaceRealtimeClient = class {
     this.state.ws?.close();
     this.state.ws = null;
     this.state.connected = false;
+    this.clearIdentity();
     this.state.connecting = false;
     this.state.subscribedChannels.clear();
+    this.clearSubscriptionRetry();
     this.notifyConnectionListeners();
   }
 };
+
+// src/realtime/workspace-client.ts
+function buildWorkspaceWsUrl(session) {
+  const isSsl = session.apiUrl.startsWith("https");
+  const host = session.apiUrl.replace(/^https?:\/\//, "");
+  return `${isSsl ? "wss" : "ws"}://${host}/api/v2/w/${session.workspaceUuid}/ws/realtime`;
+}
+var WorkspaceRealtimeClient = class extends RealtimeSocketClient {
+  memberId = null;
+  buildUrl(session) {
+    return buildWorkspaceWsUrl(session);
+  }
+  readProtocolInit(msg) {
+    this.memberId = typeof msg.memberId === "number" ? msg.memberId : null;
+  }
+  clearIdentity() {
+    this.memberId = null;
+  }
+  sessionRequiresReconnect(previous, next) {
+    return super.sessionRequiresReconnect(previous, next) || previous?.workspaceUuid !== next.workspaceUuid;
+  }
+  /**
+   * Member id the server authenticated this socket as, or null before
+   * `protocol.init` arrives.
+   *
+   * Channels whose Redis key is workspace-wide can carry events addressed to
+   * one member (presence acks, for example). Consumers compare the event's
+   * addressee against this so a reply meant for another operator cannot be
+   * applied locally.
+   */
+  getMemberId() {
+    return this.memberId;
+  }
+};
 var defaultClient = new WorkspaceRealtimeClient();
 function initWorkspaceSocket(session) {
   defaultClient.setSession(session);
@@ -261,6 +456,59 @@ function isWorkspaceSocketConnected() {
   return defaultClient.isConnected();
 }
 
+// src/realtime/account-client.ts
+function buildAccountWsUrl(session) {
+  const isSsl = session.apiUrl.startsWith("https");
+  const host = session.apiUrl.replace(/^https?:\/\//, "");
+  return `${isSsl ? "wss" : "ws"}://${host}/api/v2/ws/realtime`;
+}
+function workspaceChannel(workspaceUuid, channel) {
+  return `w/${workspaceUuid}/${channel}`;
+}
+var AccountRealtimeClient = class extends RealtimeSocketClient {
+  accountUuid = null;
+  workspaceUuids = [];
+  buildUrl(session) {
+    return buildAccountWsUrl(session);
+  }
+  readProtocolInit(msg) {
+    this.accountUuid = typeof msg.accountUuid === "string" ? msg.accountUuid : null;
+    this.workspaceUuids = Array.isArray(msg.workspaceUuids) ? msg.workspaceUuids.filter((value) => typeof value === "string") : [];
+  }
+  clearIdentity() {
+    this.accountUuid = null;
+    this.workspaceUuids = [];
+  }
+  /** Account uuid the server authenticated this socket as, or null. */
+  getAccountUuid() {
+    return this.accountUuid;
+  }
+  /**
+   * Workspaces the server's grant map admitted at `protocol.init`.
+   *
+   * A **hint for rendering**, never an authorization decision: the server
+   * re-checks its own map on every subscribe, and refreshes it on a floor, so
+   * this snapshot can be stale in either direction. Use it to decide which
+   * panes are worth opening, not which data a viewer may see.
+   */
+  getWorkspaceUuids() {
+    return this.workspaceUuids;
+  }
+};
+var defaultClient2 = new AccountRealtimeClient();
+function initAccountSocket(session) {
+  defaultClient2.setSession(session);
+}
+function subscribeAccountChannel(channel, listener) {
+  return defaultClient2.subscribe(channel, listener);
+}
+function onAccountSocketConnection(listener) {
+  return defaultClient2.onConnection(listener);
+}
+function isAccountSocketConnected() {
+  return defaultClient2.isConnected();
+}
+
 // src/audio/pcm.ts
 var SERVER_SAMPLE_RATE = 24e3;
 var TARGET_SAMPLE_RATE = 24e3;
@@ -495,7 +743,7 @@ var OperatorSessionClient = class {
    * microphone before sending so the operator's audio is flowing the instant
    * the bridge registers.
    */
-  async answerCall(interactionId) {
+  async answerCall(interactionId, answerToken) {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
       throw new Error("Operator session WebSocket is not connected");
     }
@@ -503,7 +751,10 @@ var OperatorSessionClient = class {
       throw new Error("Operator session is not ready");
     }
     await this.startMicrophone();
-    this.sendCustom("operator.call.answer", { interaction_id: interactionId });
+    this.sendCustom("operator.call.answer", {
+      interaction_id: interactionId,
+      answer_token: answerToken
+    });
   }
   /**
    * Mute or unmute the operator's outbound microphone. Muting gates mic frames
@@ -668,13 +919,27 @@ var OperatorSessionClient = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ACCOUNT_ACTIVITY_CHANNEL,
+  ACCOUNT_PRESENCE_CHANNEL,
+  ACTIVITY_CHANNEL,
+  ACTIVITY_MEMBER_CHANNEL,
+  AccountRealtimeClient,
   OperatorSessionClient,
+  PRESENCE_CHANNEL,
+  RealtimeSocketClient,
   WorkspaceRealtimeClient,
+  buildAccountWsUrl,
   buildWorkspaceWsUrl,
+  initAccountSocket,
   initWorkspaceSocket,
+  isAccountSocketConnected,
   isActiveCallPhase,
+  isActivityInvalidation,
   isWorkspaceSocketConnected,
+  onAccountSocketConnection,
   onWorkspaceSocketConnection,
-  subscribeWorkspaceChannel
+  subscribeAccountChannel,
+  subscribeWorkspaceChannel,
+  workspaceChannel
 });
 //# sourceMappingURL=realtime.cjs.map