@granular-software/sdk 0.3.3 → 0.4.1

package/dist/index.mjs

@@ -3917,6 +3917,9 @@ if (typeof globalThis !== "undefined" && globalThis.WebSocket) {
   GlobalWebSocket = globalThis.WebSocket;
 }
 var READY_STATE_OPEN = 1;
+var TOKEN_REFRESH_LEEWAY_MS = 2 * 60 * 1e3;
+var TOKEN_REFRESH_RETRY_MS = 30 * 1e3;
+var MAX_TIMER_DELAY_MS = 2147483647;
 var WSClient = class {
   ws = null;
   url;
@@ -3930,6 +3933,7 @@ var WSClient = class {
   doc = Automerge.init();
   syncState = Automerge.initSyncState();
   reconnectTimer = null;
+  tokenRefreshTimer = null;
   isExplicitlyDisconnected = false;
   options;
   constructor(options) {
@@ -3938,12 +3942,113 @@ var WSClient = class {
     this.sessionId = options.sessionId;
     this.token = options.token;
   }
+  clearTokenRefreshTimer() {
+    if (this.tokenRefreshTimer) {
+      clearTimeout(this.tokenRefreshTimer);
+      this.tokenRefreshTimer = null;
+    }
+  }
+  decodeBase64Url(payload) {
+    const base64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64 + "=".repeat((4 - (base64.length % 4 || 4)) % 4);
+    if (typeof atob === "function") {
+      return atob(padded);
+    }
+    const maybeBuffer = globalThis.Buffer;
+    if (maybeBuffer) {
+      return maybeBuffer.from(padded, "base64").toString("utf8");
+    }
+    throw new Error("No base64 decoder available");
+  }
+  getTokenExpiryMs(token) {
+    const parts = token.split(".");
+    if (parts.length < 2) {
+      return null;
+    }
+    try {
+      const payloadRaw = this.decodeBase64Url(parts[1]);
+      const payload = JSON.parse(payloadRaw);
+      if (typeof payload.exp !== "number" || !Number.isFinite(payload.exp)) {
+        return null;
+      }
+      return payload.exp * 1e3;
+    } catch {
+      return null;
+    }
+  }
+  scheduleTokenRefresh() {
+    this.clearTokenRefreshTimer();
+    if (!this.options.tokenProvider || this.isExplicitlyDisconnected) {
+      return;
+    }
+    const expiresAt = this.getTokenExpiryMs(this.token);
+    if (!expiresAt) {
+      return;
+    }
+    const refreshInMs = Math.max(1e3, expiresAt - Date.now() - TOKEN_REFRESH_LEEWAY_MS);
+    const delay = Math.min(refreshInMs, MAX_TIMER_DELAY_MS);
+    this.tokenRefreshTimer = setTimeout(() => {
+      void this.refreshTokenInBackground();
+    }, delay);
+  }
+  async refreshTokenInBackground() {
+    if (!this.options.tokenProvider || this.isExplicitlyDisconnected) {
+      return;
+    }
+    try {
+      const refreshedToken = await this.options.tokenProvider();
+      if (typeof refreshedToken !== "string" || refreshedToken.length === 0) {
+        throw new Error("Token provider returned no token");
+      }
+      this.token = refreshedToken;
+      this.scheduleTokenRefresh();
+    } catch (error) {
+      if (this.isExplicitlyDisconnected) {
+        return;
+      }
+      console.warn("[Granular] Token refresh failed, retrying soon:", error);
+      this.clearTokenRefreshTimer();
+      this.tokenRefreshTimer = setTimeout(() => {
+        void this.refreshTokenInBackground();
+      }, TOKEN_REFRESH_RETRY_MS);
+    }
+  }
+  async resolveTokenForConnect() {
+    if (!this.options.tokenProvider) {
+      return this.token;
+    }
+    const expiresAt = this.getTokenExpiryMs(this.token);
+    const shouldRefresh = expiresAt !== null && expiresAt - Date.now() <= TOKEN_REFRESH_LEEWAY_MS;
+    if (!shouldRefresh) {
+      return this.token;
+    }
+    try {
+      const refreshedToken = await this.options.tokenProvider();
+      if (typeof refreshedToken !== "string" || refreshedToken.length === 0) {
+        throw new Error("Token provider returned no token");
+      }
+      this.token = refreshedToken;
+      return refreshedToken;
+    } catch (error) {
+      if (expiresAt > Date.now()) {
+        console.warn("[Granular] Token refresh failed, using current token:", error);
+        return this.token;
+      }
+      throw error;
+    }
+  }
   /**
    * Connect to the WebSocket server
    * @returns {Promise<void>} Resolves when connection is open
    */
   async connect() {
+    const token = await this.resolveTokenForConnect();
     this.isExplicitlyDisconnected = false;
+    this.scheduleTokenRefresh();
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
     let WebSocketClass = this.options.WebSocketCtor || GlobalWebSocket;
     if (!WebSocketClass) {
       try {
@@ -3959,12 +4064,16 @@ var WSClient = class {
       try {
         const wsUrl = new URL(this.url);
         wsUrl.searchParams.set("sessionId", this.sessionId);
-        wsUrl.searchParams.set("token", this.token);
+        wsUrl.searchParams.set("token", token);
         this.ws = new WebSocketClass(wsUrl.toString());
         if (!this.ws) throw new Error("Failed to create WebSocket");
         const socket = this.ws;
         if (typeof socket.on === "function") {
           socket.on("open", () => {
+            if (this.reconnectTimer) {
+              clearTimeout(this.reconnectTimer);
+              this.reconnectTimer = null;
+            }
             this.emit("open", {});
             resolve();
           });
@@ -3982,12 +4091,20 @@ var WSClient = class {
               reject(error);
             }
           });
-          socket.on("close", () => {
-            this.emit("close", {});
-            this.handleDisconnect();
+          socket.on("close", (code, reason) => {
+            this.handleDisconnect({
+              code,
+              reason: this.normalizeReason(reason),
+              // ws does not provide wasClean on Node-style close callback
+              wasClean: code === 1e3
+            });
           });
         } else {
           this.ws.onopen = () => {
+            if (this.reconnectTimer) {
+              clearTimeout(this.reconnectTimer);
+              this.reconnectTimer = null;
+            }
             this.emit("open", {});
             resolve();
           };
@@ -4008,9 +4125,12 @@ var WSClient = class {
               reject(error);
             }
           };
-          this.ws.onclose = () => {
-            this.emit("close", {});
-            this.handleDisconnect();
+          this.ws.onclose = (event) => {
+            this.handleDisconnect({
+              code: event.code,
+              reason: event.reason,
+              wasClean: event.wasClean
+            });
           };
         }
       } catch (error) {
@@ -4018,13 +4138,80 @@ var WSClient = class {
       }
     });
   }
-  handleDisconnect() {
+  normalizeReason(reason) {
+    if (reason === null || reason === void 0) return void 0;
+    if (typeof reason === "string") return reason;
+    if (typeof reason === "object" && reason && "toString" in reason) {
+      try {
+        const text = String(reason.toString());
+        return text || void 0;
+      } catch {
+        return void 0;
+      }
+    }
+    return void 0;
+  }
+  rejectPending(error) {
+    this.messageQueue.forEach((pending) => pending.reject(error));
+    this.messageQueue = [];
+  }
+  buildDisconnectError(info) {
+    const details = [
+      info.code !== void 0 ? `code=${info.code}` : void 0,
+      info.reason ? `reason=${info.reason}` : void 0
+    ].filter(Boolean).join(", ");
+    const suffix = details ? ` (${details})` : "";
+    return new Error(`WebSocket disconnected${suffix}`);
+  }
+  handleDisconnect(close = {}) {
+    const reconnectDelayMs = 3e3;
+    const unexpected = !this.isExplicitlyDisconnected;
+    const info = {
+      code: close.code,
+      reason: close.reason,
+      wasClean: close.wasClean,
+      unexpected,
+      timestamp: Date.now(),
+      reconnectScheduled: false
+    };
     this.ws = null;
-    if (!this.isExplicitlyDisconnected) {
+    this.emit("close", info);
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (unexpected) {
+      const disconnectError = this.buildDisconnectError(info);
+      this.rejectPending(disconnectError);
+      this.emit("disconnect", info);
+      info.reconnectScheduled = true;
+      info.reconnectDelayMs = reconnectDelayMs;
+      if (this.options.onUnexpectedClose) {
+        try {
+          this.options.onUnexpectedClose(info);
+        } catch (callbackError) {
+          console.error("[Granular] onUnexpectedClose callback failed:", callbackError);
+        }
+      }
       this.reconnectTimer = setTimeout(() => {
         console.log("[Granular] Attempting reconnect...");
-        this.connect().catch((e) => console.error("[Granular] Reconnect failed:", e));
-      }, 3e3);
+        this.connect().catch((error) => {
+          console.error("[Granular] Reconnect failed:", error);
+          const reconnectInfo = {
+            error: error instanceof Error ? error.message : String(error),
+            sessionId: this.sessionId,
+            timestamp: Date.now()
+          };
+          this.emit("reconnect_error", reconnectInfo);
+          if (this.options.onReconnectError) {
+            try {
+              this.options.onReconnectError(reconnectInfo);
+            } catch (callbackError) {
+              console.error("[Granular] onReconnectError callback failed:", callbackError);
+            }
+          }
+        });
+      }, reconnectDelayMs);
     }
   }
   handleMessage(message) {
@@ -4082,10 +4269,10 @@ var WSClient = class {
       const snapshotMessage = message;
       try {
         const bytes = new Uint8Array(snapshotMessage.data);
-        console.log("[Granular DEBUG] Loading snapshot bytes:", bytes.length);
+        console.log("[Granular DEBUG] Loading Automerge session snapshot bytes:", bytes.length);
         this.doc = Automerge.load(bytes);
         this.emit("sync", this.doc);
-        console.log("[Granular DEBUG] Snapshot loaded. Doc:", JSON.stringify(Automerge.toJS(this.doc)));
+        console.log("[Granular DEBUG] Automerge session snapshot loaded. Doc:", JSON.stringify(Automerge.toJS(this.doc)));
       } catch (e) {
         console.warn("[Granular] Failed to load snapshot message", e);
       }
@@ -4244,13 +4431,16 @@ var WSClient = class {
    */
   disconnect() {
     this.isExplicitlyDisconnected = true;
-    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this.clearTokenRefreshTimer();
     if (this.ws) {
-      this.ws.close();
+      this.ws.close(1e3, "Client disconnect");
       this.ws = null;
     }
-    this.messageQueue.forEach((q) => q.reject(new Error("Client explicitly disconnected")));
-    this.messageQueue = [];
+    this.rejectPending(new Error("Client explicitly disconnected"));
     this.rpcHandlers.clear();
     this.emit("disconnect", {});
   }
@@ -4732,6 +4922,13 @@ import { ${allImports} } from "./sandbox-tools";
    * Close the session and disconnect from the sandbox
    */
   async disconnect() {
+    try {
+      await this.client.call("client.goodbye", {
+        clientId: this.clientId,
+        timestamp: Date.now()
+      });
+    } catch (error) {
+    }
     this.client.disconnect();
   }
   // --- Event Handling ---
@@ -4795,7 +4992,7 @@ import { ${allImports} } from "./sandbox-tools";
       this.checkForToolChanges();
     });
     this.client.on("prompt", (prompt) => this.emit("prompt", prompt));
-    this.client.on("disconnect", () => this.emit("disconnect", {}));
+    this.client.on("disconnect", (payload) => this.emit("disconnect", payload || {}));
     this.client.on("job.status", (data) => {
       this.emit("job:status", data);
     });
@@ -4942,6 +5139,50 @@ var JobImplementation = class {
   }
 };
 
+// src/endpoints.ts
+var LOCAL_API_URL = "ws://localhost:8787/granular";
+var PRODUCTION_API_URL = "wss://api.granular.dev/v2/ws";
+function readEnv(name) {
+  if (typeof process === "undefined" || !process.env) return void 0;
+  return process.env[name];
+}
+function normalizeMode(value) {
+  if (!value) return void 0;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "local") return "local";
+  if (normalized === "prod" || normalized === "production") return "production";
+  if (normalized === "auto") return "auto";
+  return void 0;
+}
+function isTruthy(value) {
+  if (!value) return false;
+  const normalized = value.trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+function resolveEndpointMode(explicitMode) {
+  const explicit = normalizeMode(explicitMode);
+  if (explicit === "local" || explicit === "production") {
+    return explicit;
+  }
+  const envMode = normalizeMode(readEnv("GRANULAR_ENDPOINT_MODE") || readEnv("GRANULAR_ENV"));
+  if (envMode === "local" || envMode === "production") {
+    return envMode;
+  }
+  if (isTruthy(readEnv("GRANULAR_USE_LOCAL_ENDPOINTS")) || isTruthy(readEnv("GRANULAR_LOCAL"))) {
+    return "local";
+  }
+  if (isTruthy(readEnv("GRANULAR_USE_PRODUCTION_ENDPOINTS")) || isTruthy(readEnv("GRANULAR_PROD"))) {
+    return "production";
+  }
+  return readEnv("NODE_ENV") === "development" ? "local" : "production";
+}
+function resolveApiUrl(explicitApiUrl, mode) {
+  if (explicitApiUrl) {
+    return explicitApiUrl;
+  }
+  return resolveEndpointMode(mode) === "local" ? LOCAL_API_URL : PRODUCTION_API_URL;
+}
+
 // src/client.ts
 var STANDARD_MODULES_OPERATIONS = [
   { create: "entity", has: { id: { value: "auto-generated" }, createdAt: { value: void 0 } } },
@@ -4986,6 +5227,60 @@ var Environment = class _Environment extends Session {
   get apiEndpoint() {
     return this._apiEndpoint;
   }
+  getRuntimeBaseUrl() {
+    try {
+      const endpoint = new URL(this._apiEndpoint);
+      const graphqlSuffix = "/orchestrator/graphql";
+      if (endpoint.pathname.endsWith(graphqlSuffix)) {
+        endpoint.pathname = endpoint.pathname.slice(0, -graphqlSuffix.length);
+      } else if (endpoint.pathname.endsWith("/graphql")) {
+        endpoint.pathname = endpoint.pathname.slice(0, -"/graphql".length);
+      }
+      endpoint.search = "";
+      endpoint.hash = "";
+      return endpoint.toString().replace(/\/$/, "");
+    } catch {
+      return this._apiEndpoint.replace(/\/orchestrator\/graphql$/, "").replace(/\/$/, "");
+    }
+  }
+  /**
+   * Close the session and disconnect from the sandbox.
+   *
+   * Sends `client.goodbye` over WebSocket first, then issues an HTTP fallback
+   * to the runtime goodbye endpoint if no definitive WS-side runtime notify
+   * acknowledgement was observed.
+   */
+  async disconnect() {
+    let wsNotifiedRuntime = false;
+    try {
+      const goodbye = await this.rpc("client.goodbye", {
+        timestamp: Date.now()
+      });
+      wsNotifiedRuntime = Boolean(goodbye?.ok && goodbye?.via);
+    } catch {
+      wsNotifiedRuntime = false;
+    }
+    if (!wsNotifiedRuntime) {
+      try {
+        const runtimeBase = this.getRuntimeBaseUrl();
+        await fetch(
+          `${runtimeBase}/orchestrator/runtime/environments/${this.environmentId}/session-goodbye`,
+          {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              "Authorization": `Bearer ${this._apiKey}`
+            },
+            body: JSON.stringify({
+              reason: "sdk_disconnect_http_fallback"
+            })
+          }
+        );
+      } catch {
+      }
+    }
+    this.client.disconnect();
+  }
   // ==================== GRAPH CONTAINER READINESS ====================
   /** The last known graph container status, updated by checkReadiness() or on heartbeat */
   graphContainerStatus = null;
@@ -5721,7 +6016,10 @@ var Granular = class {
   apiKey;
   apiUrl;
   httpUrl;
+  tokenProvider;
   WebSocketCtor;
+  onUnexpectedClose;
+  onReconnectError;
   /** Sandbox-level effect registry: sandboxId → (toolName → ToolWithHandler) */
   sandboxEffects = /* @__PURE__ */ new Map();
   /** Active environments tracker: sandboxId → Environment[] */
@@ -5736,9 +6034,12 @@ var Granular = class {
       throw new Error("Granular client requires either apiKey or token. Set GRANULAR_API_KEY or GRANULAR_TOKEN, or pass one in options.");
     }
     this.apiKey = auth;
-    this.apiUrl = options.apiUrl || "wss://api.granular.dev/v2/ws";
+    this.apiUrl = resolveApiUrl(options.apiUrl, options.endpointMode);
+    this.tokenProvider = options.tokenProvider;
     this.WebSocketCtor = options.WebSocketCtor;
-    this.httpUrl = this.apiUrl.replace("wss://", "https://").replace("/ws", "");
+    this.onUnexpectedClose = options.onUnexpectedClose;
+    this.onReconnectError = options.onReconnectError;
+    this.httpUrl = this.apiUrl.replace(/^wss:\/\//, "https://").replace(/^ws:\/\//, "http://").replace(/\/ws$/, "");
   }
   /**
    * Records/upserts a user and prepares them for sandbox connections
@@ -5822,7 +6123,10 @@ var Granular = class {
       url: this.apiUrl,
       sessionId: envData.environmentId,
       token: this.apiKey,
-      WebSocketCtor: this.WebSocketCtor
+      tokenProvider: this.tokenProvider,
+      WebSocketCtor: this.WebSocketCtor,
+      onUnexpectedClose: this.onUnexpectedClose,
+      onReconnectError: this.onReconnectError
     });
     await client.connect();
     const graphqlEndpoint = `${this.httpUrl}/orchestrator/graphql`;