@blinkdotnew/sdk 2.6.0 → 2.6.2

package/dist/index.d.mts

@@ -941,7 +941,17 @@ declare class HttpClient {
     private readonly secretKey?;
     private getToken;
     private getValidToken?;
-    constructor(config: BlinkClientConfig, getToken: () => string | null, getValidToken?: () => Promise<string | null>);
+    private forceRefreshToken?;
+    constructor(config: BlinkClientConfig, getToken: () => string | null, getValidToken?: () => Promise<string | null>, forceRefreshToken?: () => Promise<string | null>);
+    /**
+     * Whether a 401 on this request is worth recovering from by forcing a
+     * user-token refresh and retrying once.
+     *
+     * Only meaningful for user-JWT auth: server-side `secretKey` 401s are real
+     * authorization failures a refresh cannot fix, and publishable-key requests
+     * carry no user token to refresh.
+     */
+    private canAttemptTokenRefresh;
     private shouldAttachPublishableKey;
     private shouldSkipSecretKey;
     private getAuthorizationHeader;
@@ -1285,6 +1295,7 @@ declare class BlinkAuth {
     private initializationPromise;
     private isInitialized;
     private storage;
+    private refreshPromise;
     constructor(config: BlinkClientConfig);
     /**
      * Generate project-scoped storage key
@@ -1672,6 +1683,18 @@ declare class BlinkAuth {
      * Refresh access token using refresh token
      */
     refreshToken(): Promise<boolean>;
+    /**
+     * Force a server-side token refresh and return the resulting access token.
+     *
+     * Used by the HTTP client to recover from a 401 even when the client-side
+     * expiry heuristics believe the access token is still valid (clock skew, a
+     * restored session with a stale `issued_at`, or a refresh race). Delegates to
+     * {@link refreshToken} so it shares the single-flight guard.
+     *
+     * @returns The new access token, or null if refresh was not possible.
+     */
+    forceRefreshAccessToken(): Promise<string | null>;
+    private performTokenRefresh;
     /**
      * Add auth state change listener
      */

package/dist/index.d.ts

@@ -941,7 +941,17 @@ declare class HttpClient {
     private readonly secretKey?;
     private getToken;
     private getValidToken?;
-    constructor(config: BlinkClientConfig, getToken: () => string | null, getValidToken?: () => Promise<string | null>);
+    private forceRefreshToken?;
+    constructor(config: BlinkClientConfig, getToken: () => string | null, getValidToken?: () => Promise<string | null>, forceRefreshToken?: () => Promise<string | null>);
+    /**
+     * Whether a 401 on this request is worth recovering from by forcing a
+     * user-token refresh and retrying once.
+     *
+     * Only meaningful for user-JWT auth: server-side `secretKey` 401s are real
+     * authorization failures a refresh cannot fix, and publishable-key requests
+     * carry no user token to refresh.
+     */
+    private canAttemptTokenRefresh;
     private shouldAttachPublishableKey;
     private shouldSkipSecretKey;
     private getAuthorizationHeader;
@@ -1285,6 +1295,7 @@ declare class BlinkAuth {
     private initializationPromise;
     private isInitialized;
     private storage;
+    private refreshPromise;
     constructor(config: BlinkClientConfig);
     /**
      * Generate project-scoped storage key
@@ -1672,6 +1683,18 @@ declare class BlinkAuth {
      * Refresh access token using refresh token
      */
     refreshToken(): Promise<boolean>;
+    /**
+     * Force a server-side token refresh and return the resulting access token.
+     *
+     * Used by the HTTP client to recover from a 401 even when the client-side
+     * expiry heuristics believe the access token is still valid (clock skew, a
+     * restored session with a stale `issued_at`, or a refresh race). Delegates to
+     * {@link refreshToken} so it shares the single-flight guard.
+     *
+     * @returns The new access token, or null if refresh was not possible.
+     */
+    forceRefreshAccessToken(): Promise<string | null>;
+    private performTokenRefresh;
     /**
      * Add auth state change listener
      */

package/dist/index.js

@@ -421,12 +421,25 @@ var HttpClient = class {
   // Permanent, non-expiring key (like Stripe's sk_live_...)
   getToken;
   getValidToken;
-  constructor(config, getToken, getValidToken) {
+  forceRefreshToken;
+  constructor(config, getToken, getValidToken, forceRefreshToken) {
     this.projectId = config.projectId;
     this.publishableKey = config.publishableKey;
     this.secretKey = config.secretKey || config.serviceToken;
     this.getToken = getToken;
     this.getValidToken = getValidToken;
+    this.forceRefreshToken = forceRefreshToken;
+  }
+  /**
+   * Whether a 401 on this request is worth recovering from by forcing a
+   * user-token refresh and retrying once.
+   *
+   * Only meaningful for user-JWT auth: server-side `secretKey` 401s are real
+   * authorization failures a refresh cannot fix, and publishable-key requests
+   * carry no user token to refresh.
+   */
+  canAttemptTokenRefresh(token) {
+    return !!this.forceRefreshToken && !this.secretKey && !!token;
   }
   shouldAttachPublishableKey(path, method) {
     if (method !== "GET" && method !== "POST") return false;
@@ -457,28 +470,37 @@ var HttpClient = class {
    */
   async request(path, options = {}) {
     const url = this.buildUrl(path, options.searchParams);
-    const token = this.getValidToken ? await this.getValidToken() : this.getToken();
     const method = options.method || "GET";
-    const headers = {
-      "Content-Type": "application/json",
-      ...options.headers
-    };
-    const auth = this.getAuthorizationHeader(url, token);
-    if (auth) {
-      headers.Authorization = auth;
-    } else if (this.publishableKey && !headers["x-blink-publishable-key"] && this.shouldAttachPublishableKey(path, method)) {
-      headers["x-blink-publishable-key"] = this.publishableKey;
-    }
-    const requestInit = {
-      method,
-      headers,
-      signal: options.signal
+    const sendRequest = (token) => {
+      const headers = {
+        "Content-Type": "application/json",
+        ...options.headers
+      };
+      const auth = this.getAuthorizationHeader(url, token);
+      if (auth) {
+        headers.Authorization = auth;
+      } else if (this.publishableKey && !headers["x-blink-publishable-key"] && this.shouldAttachPublishableKey(path, method)) {
+        headers["x-blink-publishable-key"] = this.publishableKey;
+      }
+      const requestInit = {
+        method,
+        headers,
+        signal: options.signal
+      };
+      if (options.body && method !== "GET") {
+        requestInit.body = typeof options.body === "string" ? options.body : JSON.stringify(options.body);
+      }
+      return fetch(url, requestInit);
     };
-    if (options.body && method !== "GET") {
-      requestInit.body = typeof options.body === "string" ? options.body : JSON.stringify(options.body);
-    }
     try {
-      const response = await fetch(url, requestInit);
+      const token = this.getValidToken ? await this.getValidToken() : this.getToken();
+      let response = await sendRequest(token);
+      if (response.status === 401 && this.canAttemptTokenRefresh(token)) {
+        const refreshedToken = await this.forceRefreshToken();
+        if (refreshedToken) {
+          response = await sendRequest(refreshedToken);
+        }
+      }
       if (!response.ok) {
         await this.handleErrorResponse(response);
       }
@@ -636,7 +658,6 @@ var HttpClient = class {
    */
   async uploadFile(path, file, filePath, options = {}) {
     const url = this.buildUrl(path);
-    const token = this.getValidToken ? await this.getValidToken() : this.getToken();
     const formData = new FormData();
     if (file instanceof File) {
       formData.append("file", file);
@@ -650,41 +671,57 @@ var HttpClient = class {
       throw new BlinkValidationError("Unsupported file type");
     }
     formData.append("path", filePath);
-    const headers = {};
-    const auth = this.getAuthorizationHeader(url, token);
-    if (auth) {
-      headers.Authorization = auth;
-    } else if (this.publishableKey && path.includes("/api/storage/") && !headers["x-blink-publishable-key"]) {
-      headers["x-blink-publishable-key"] = this.publishableKey;
-    }
-    try {
-      if (typeof XMLHttpRequest !== "undefined" && options.onProgress) {
-        return this.uploadWithProgress(url, formData, headers, options.onProgress);
+    const attempt = async (allowRetry) => {
+      const token = this.getValidToken ? await this.getValidToken() : this.getToken();
+      const headers = {};
+      const auth = this.getAuthorizationHeader(url, token);
+      if (auth) {
+        headers.Authorization = auth;
+      } else if (this.publishableKey && path.includes("/api/storage/") && !headers["x-blink-publishable-key"]) {
+        headers["x-blink-publishable-key"] = this.publishableKey;
       }
-      const response = await fetch(url, {
-        method: "POST",
-        headers,
-        body: formData
-      });
-      if (!response.ok) {
-        await this.handleErrorResponse(response);
-      }
-      const data = await this.parseResponse(response);
-      return {
-        data,
-        status: response.status,
-        headers: response.headers
-      };
-    } catch (error) {
-      if (error instanceof BlinkError) {
-        throw error;
+      try {
+        if (typeof XMLHttpRequest !== "undefined" && options.onProgress) {
+          return await this.uploadWithProgress(url, formData, headers, options.onProgress);
+        }
+        const response = await fetch(url, {
+          method: "POST",
+          headers,
+          body: formData
+        });
+        if (response.status === 401 && allowRetry && this.canAttemptTokenRefresh(token)) {
+          const refreshedToken = await this.forceRefreshToken();
+          if (refreshedToken) {
+            return attempt(false);
+          }
+        }
+        if (!response.ok) {
+          await this.handleErrorResponse(response);
+        }
+        const data = await this.parseResponse(response);
+        return {
+          data,
+          status: response.status,
+          headers: response.headers
+        };
+      } catch (error) {
+        if (allowRetry && error instanceof BlinkAuthError && this.canAttemptTokenRefresh(token)) {
+          const refreshedToken = await this.forceRefreshToken();
+          if (refreshedToken) {
+            return attempt(false);
+          }
+        }
+        if (error instanceof BlinkError) {
+          throw error;
+        }
+        throw new BlinkNetworkError(
+          `File upload failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+          0,
+          { originalError: error }
+        );
       }
-      throw new BlinkNetworkError(
-        `File upload failed: ${error instanceof Error ? error.message : "Unknown error"}`,
-        0,
-        { originalError: error }
-      );
-    }
+    };
+    return attempt(true);
   }
   /**
    * Upload with progress tracking using XMLHttpRequest
@@ -1376,6 +1413,7 @@ var BlinkAuth = class {
   initializationPromise = null;
   isInitialized = false;
   storage;
+  refreshPromise = null;
   constructor(config) {
     this.config = config;
     if (!config.projectId) {
@@ -2823,10 +2861,35 @@ var BlinkAuth = class {
    * Refresh access token using refresh token
    */
   async refreshToken() {
+    if (this.refreshPromise) {
+      return this.refreshPromise;
+    }
     const refreshToken = this.authState.tokens?.refresh_token;
     if (!refreshToken) {
       return false;
     }
+    this.refreshPromise = this.performTokenRefresh(refreshToken);
+    try {
+      return await this.refreshPromise;
+    } finally {
+      this.refreshPromise = null;
+    }
+  }
+  /**
+   * Force a server-side token refresh and return the resulting access token.
+   *
+   * Used by the HTTP client to recover from a 401 even when the client-side
+   * expiry heuristics believe the access token is still valid (clock skew, a
+   * restored session with a stale `issued_at`, or a refresh race). Delegates to
+   * {@link refreshToken} so it shares the single-flight guard.
+   *
+   * @returns The new access token, or null if refresh was not possible.
+   */
+  async forceRefreshAccessToken() {
+    const refreshed = await this.refreshToken();
+    return refreshed ? this.authState.tokens?.access_token || null : null;
+  }
+  async performTokenRefresh(refreshToken) {
     try {
       const response = await fetch(`${this.authUrl}/api/auth/refresh`, {
         method: "POST",
@@ -5136,6 +5199,9 @@ var BlinkAIImpl = class {
    * ```
    */
   createAgent(options) {
+    if (!options) {
+      throw new BlinkAIError("createAgent(options) requires an options object with at least a `model`.");
+    }
     const agent = new Agent(options);
     agent._setHttpClient(this.httpClient);
     return agent;
@@ -5150,6 +5216,11 @@ var BlinkAIImpl = class {
    * @returns The same Agent instance (with httpClient set)
    */
   bindAgent(agent) {
+    if (!agent) {
+      throw new BlinkAIError(
+        "bindAgent(agent) requires an Agent instance but received null/undefined. Create one first with `new Agent({...})` or `blink.ai.createAgent({...})`. (The useAgent() hook stays idle while its `agent` is null, so this only fires on a direct bindAgent() call with a missing agent.)"
+      );
+    }
     agent._setHttpClient(this.httpClient);
     return agent;
   }
@@ -6956,7 +7027,8 @@ var BlinkClientImpl = class {
     this._httpClient = new HttpClient(
       config,
       () => this.auth.getToken(),
-      () => this.auth.getValidToken()
+      () => this.auth.getValidToken(),
+      () => this.auth.forceRefreshAccessToken()
     );
     this.db = new BlinkDatabase(this._httpClient);
     this.storage = new BlinkStorageImpl(this._httpClient);

package/dist/index.mjs

@@ -419,12 +419,25 @@ var HttpClient = class {
   // Permanent, non-expiring key (like Stripe's sk_live_...)
   getToken;
   getValidToken;
-  constructor(config, getToken, getValidToken) {
+  forceRefreshToken;
+  constructor(config, getToken, getValidToken, forceRefreshToken) {
     this.projectId = config.projectId;
     this.publishableKey = config.publishableKey;
     this.secretKey = config.secretKey || config.serviceToken;
     this.getToken = getToken;
     this.getValidToken = getValidToken;
+    this.forceRefreshToken = forceRefreshToken;
+  }
+  /**
+   * Whether a 401 on this request is worth recovering from by forcing a
+   * user-token refresh and retrying once.
+   *
+   * Only meaningful for user-JWT auth: server-side `secretKey` 401s are real
+   * authorization failures a refresh cannot fix, and publishable-key requests
+   * carry no user token to refresh.
+   */
+  canAttemptTokenRefresh(token) {
+    return !!this.forceRefreshToken && !this.secretKey && !!token;
   }
   shouldAttachPublishableKey(path, method) {
     if (method !== "GET" && method !== "POST") return false;
@@ -455,28 +468,37 @@ var HttpClient = class {
    */
   async request(path, options = {}) {
     const url = this.buildUrl(path, options.searchParams);
-    const token = this.getValidToken ? await this.getValidToken() : this.getToken();
     const method = options.method || "GET";
-    const headers = {
-      "Content-Type": "application/json",
-      ...options.headers
-    };
-    const auth = this.getAuthorizationHeader(url, token);
-    if (auth) {
-      headers.Authorization = auth;
-    } else if (this.publishableKey && !headers["x-blink-publishable-key"] && this.shouldAttachPublishableKey(path, method)) {
-      headers["x-blink-publishable-key"] = this.publishableKey;
-    }
-    const requestInit = {
-      method,
-      headers,
-      signal: options.signal
+    const sendRequest = (token) => {
+      const headers = {
+        "Content-Type": "application/json",
+        ...options.headers
+      };
+      const auth = this.getAuthorizationHeader(url, token);
+      if (auth) {
+        headers.Authorization = auth;
+      } else if (this.publishableKey && !headers["x-blink-publishable-key"] && this.shouldAttachPublishableKey(path, method)) {
+        headers["x-blink-publishable-key"] = this.publishableKey;
+      }
+      const requestInit = {
+        method,
+        headers,
+        signal: options.signal
+      };
+      if (options.body && method !== "GET") {
+        requestInit.body = typeof options.body === "string" ? options.body : JSON.stringify(options.body);
+      }
+      return fetch(url, requestInit);
     };
-    if (options.body && method !== "GET") {
-      requestInit.body = typeof options.body === "string" ? options.body : JSON.stringify(options.body);
-    }
     try {
-      const response = await fetch(url, requestInit);
+      const token = this.getValidToken ? await this.getValidToken() : this.getToken();
+      let response = await sendRequest(token);
+      if (response.status === 401 && this.canAttemptTokenRefresh(token)) {
+        const refreshedToken = await this.forceRefreshToken();
+        if (refreshedToken) {
+          response = await sendRequest(refreshedToken);
+        }
+      }
       if (!response.ok) {
         await this.handleErrorResponse(response);
       }
@@ -634,7 +656,6 @@ var HttpClient = class {
    */
   async uploadFile(path, file, filePath, options = {}) {
     const url = this.buildUrl(path);
-    const token = this.getValidToken ? await this.getValidToken() : this.getToken();
     const formData = new FormData();
     if (file instanceof File) {
       formData.append("file", file);
@@ -648,41 +669,57 @@ var HttpClient = class {
       throw new BlinkValidationError("Unsupported file type");
     }
     formData.append("path", filePath);
-    const headers = {};
-    const auth = this.getAuthorizationHeader(url, token);
-    if (auth) {
-      headers.Authorization = auth;
-    } else if (this.publishableKey && path.includes("/api/storage/") && !headers["x-blink-publishable-key"]) {
-      headers["x-blink-publishable-key"] = this.publishableKey;
-    }
-    try {
-      if (typeof XMLHttpRequest !== "undefined" && options.onProgress) {
-        return this.uploadWithProgress(url, formData, headers, options.onProgress);
+    const attempt = async (allowRetry) => {
+      const token = this.getValidToken ? await this.getValidToken() : this.getToken();
+      const headers = {};
+      const auth = this.getAuthorizationHeader(url, token);
+      if (auth) {
+        headers.Authorization = auth;
+      } else if (this.publishableKey && path.includes("/api/storage/") && !headers["x-blink-publishable-key"]) {
+        headers["x-blink-publishable-key"] = this.publishableKey;
       }
-      const response = await fetch(url, {
-        method: "POST",
-        headers,
-        body: formData
-      });
-      if (!response.ok) {
-        await this.handleErrorResponse(response);
-      }
-      const data = await this.parseResponse(response);
-      return {
-        data,
-        status: response.status,
-        headers: response.headers
-      };
-    } catch (error) {
-      if (error instanceof BlinkError) {
-        throw error;
+      try {
+        if (typeof XMLHttpRequest !== "undefined" && options.onProgress) {
+          return await this.uploadWithProgress(url, formData, headers, options.onProgress);
+        }
+        const response = await fetch(url, {
+          method: "POST",
+          headers,
+          body: formData
+        });
+        if (response.status === 401 && allowRetry && this.canAttemptTokenRefresh(token)) {
+          const refreshedToken = await this.forceRefreshToken();
+          if (refreshedToken) {
+            return attempt(false);
+          }
+        }
+        if (!response.ok) {
+          await this.handleErrorResponse(response);
+        }
+        const data = await this.parseResponse(response);
+        return {
+          data,
+          status: response.status,
+          headers: response.headers
+        };
+      } catch (error) {
+        if (allowRetry && error instanceof BlinkAuthError && this.canAttemptTokenRefresh(token)) {
+          const refreshedToken = await this.forceRefreshToken();
+          if (refreshedToken) {
+            return attempt(false);
+          }
+        }
+        if (error instanceof BlinkError) {
+          throw error;
+        }
+        throw new BlinkNetworkError(
+          `File upload failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+          0,
+          { originalError: error }
+        );
       }
-      throw new BlinkNetworkError(
-        `File upload failed: ${error instanceof Error ? error.message : "Unknown error"}`,
-        0,
-        { originalError: error }
-      );
-    }
+    };
+    return attempt(true);
   }
   /**
    * Upload with progress tracking using XMLHttpRequest
@@ -1374,6 +1411,7 @@ var BlinkAuth = class {
   initializationPromise = null;
   isInitialized = false;
   storage;
+  refreshPromise = null;
   constructor(config) {
     this.config = config;
     if (!config.projectId) {
@@ -2821,10 +2859,35 @@ var BlinkAuth = class {
    * Refresh access token using refresh token
    */
   async refreshToken() {
+    if (this.refreshPromise) {
+      return this.refreshPromise;
+    }
     const refreshToken = this.authState.tokens?.refresh_token;
     if (!refreshToken) {
       return false;
     }
+    this.refreshPromise = this.performTokenRefresh(refreshToken);
+    try {
+      return await this.refreshPromise;
+    } finally {
+      this.refreshPromise = null;
+    }
+  }
+  /**
+   * Force a server-side token refresh and return the resulting access token.
+   *
+   * Used by the HTTP client to recover from a 401 even when the client-side
+   * expiry heuristics believe the access token is still valid (clock skew, a
+   * restored session with a stale `issued_at`, or a refresh race). Delegates to
+   * {@link refreshToken} so it shares the single-flight guard.
+   *
+   * @returns The new access token, or null if refresh was not possible.
+   */
+  async forceRefreshAccessToken() {
+    const refreshed = await this.refreshToken();
+    return refreshed ? this.authState.tokens?.access_token || null : null;
+  }
+  async performTokenRefresh(refreshToken) {
     try {
       const response = await fetch(`${this.authUrl}/api/auth/refresh`, {
         method: "POST",
@@ -5134,6 +5197,9 @@ var BlinkAIImpl = class {
    * ```
    */
   createAgent(options) {
+    if (!options) {
+      throw new BlinkAIError("createAgent(options) requires an options object with at least a `model`.");
+    }
     const agent = new Agent(options);
     agent._setHttpClient(this.httpClient);
     return agent;
@@ -5148,6 +5214,11 @@ var BlinkAIImpl = class {
    * @returns The same Agent instance (with httpClient set)
    */
   bindAgent(agent) {
+    if (!agent) {
+      throw new BlinkAIError(
+        "bindAgent(agent) requires an Agent instance but received null/undefined. Create one first with `new Agent({...})` or `blink.ai.createAgent({...})`. (The useAgent() hook stays idle while its `agent` is null, so this only fires on a direct bindAgent() call with a missing agent.)"
+      );
+    }
     agent._setHttpClient(this.httpClient);
     return agent;
   }
@@ -6954,7 +7025,8 @@ var BlinkClientImpl = class {
     this._httpClient = new HttpClient(
       config,
       () => this.auth.getToken(),
-      () => this.auth.getValidToken()
+      () => this.auth.getValidToken(),
+      () => this.auth.forceRefreshAccessToken()
     );
     this.db = new BlinkDatabase(this._httpClient);
     this.storage = new BlinkStorageImpl(this._httpClient);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blinkdotnew/sdk",
-  "version": "2.6.0",
+  "version": "2.6.2",
   "description": "Blink TypeScript SDK for client-side applications - Zero-boilerplate CRUD + auth + AI + analytics + notifications for modern SaaS/AI apps",
   "keywords": [
     "blink",