@granular-software/sdk 0.3.4 → 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,109 @@ 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;
@@ -3963,7 +4064,7 @@ 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;
@@ -4168,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);
       }
@@ -4334,6 +4435,7 @@ var WSClient = class {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
     }
+    this.clearTokenRefreshTimer();
     if (this.ws) {
       this.ws.close(1e3, "Client disconnect");
       this.ws = null;
@@ -4820,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 ---
@@ -5030,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 } } },
@@ -5074,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;
@@ -5809,6 +6016,7 @@ var Granular = class {
   apiKey;
   apiUrl;
   httpUrl;
+  tokenProvider;
   WebSocketCtor;
   onUnexpectedClose;
   onReconnectError;
@@ -5826,11 +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.onUnexpectedClose = options.onUnexpectedClose;
     this.onReconnectError = options.onReconnectError;
-    this.httpUrl = this.apiUrl.replace("wss://", "https://").replace("/ws", "");
+    this.httpUrl = this.apiUrl.replace(/^wss:\/\//, "https://").replace(/^ws:\/\//, "http://").replace(/\/ws$/, "");
   }
   /**
    * Records/upserts a user and prepares them for sandbox connections
@@ -5914,6 +6123,7 @@ var Granular = class {
       url: this.apiUrl,
       sessionId: envData.environmentId,
       token: this.apiKey,
+      tokenProvider: this.tokenProvider,
       WebSocketCtor: this.WebSocketCtor,
       onUnexpectedClose: this.onUnexpectedClose,
       onReconnectError: this.onReconnectError