@lumibase/sdk 0.20.0 → 0.22.0

package/dist/index.cjs

@@ -111,12 +111,52 @@ function toErrorBody(status, body) {
 function createLumiClient(opts) {
   const fetcher = opts.fetcher ?? globalThis.fetch;
   const base = opts.url.replace(/\/$/, "");
-  async function rawRequest(path, init = {}) {
+  let currentToken = opts.token;
+  let currentRefreshToken = opts.refreshToken;
+  let refreshInFlight = null;
+  async function attemptRefresh() {
+    if (!currentRefreshToken) return false;
+    if (!refreshInFlight) {
+      refreshInFlight = (async () => {
+        try {
+          const res = await fetcher(`${base}/api/v1/auth/refresh`, {
+            method: "POST",
+            headers: {
+              "content-type": "application/json",
+              "x-lumi-site": opts.siteId
+            },
+            // Body transport is CSRF-exempt (the token isn't ambient).
+            body: JSON.stringify({ refreshToken: currentRefreshToken })
+          });
+          if (!res.ok) return false;
+          const data = parseResponseBody(await res.text())?.data;
+          if (!data?.token || !data.refreshToken) return false;
+          currentToken = data.token;
+          currentRefreshToken = data.refreshToken;
+          try {
+            opts.onTokensRefreshed?.({
+              token: data.token,
+              refreshToken: data.refreshToken,
+              refreshTokenExpiresAt: data.refreshTokenExpiresAt
+            });
+          } catch {
+          }
+          return true;
+        } catch {
+          return false;
+        } finally {
+          refreshInFlight = null;
+        }
+      })();
+    }
+    return refreshInFlight;
+  }
+  async function rawRequest(path, init = {}, retried = false) {
     const headers = new Headers(init.headers);
     for (const [key, value] of Object.entries(opts.headers ?? {})) {
       headers.set(key, value);
     }
-    headers.set("authorization", `Bearer ${opts.token}`);
+    headers.set("authorization", `Bearer ${currentToken}`);
     headers.set("x-lumi-site", opts.siteId);
     if (!headers.has("content-type") && init.body) {
       headers.set("content-type", "application/json");
@@ -125,6 +165,11 @@ function createLumiClient(opts) {
     const text = await res.text();
     const body = parseResponseBody(text);
     if (!res.ok) {
+      if (res.status === 401 && !retried && currentRefreshToken && path !== "/api/v1/auth/refresh") {
+        if (await attemptRefresh()) {
+          return rawRequest(path, init, true);
+        }
+      }
       if (res.status === 401 && opts.onUnauthorized) {
         try {
           opts.onUnauthorized();
@@ -137,7 +182,9 @@ function createLumiClient(opts) {
   }
   const baseClient = {
     url: opts.url,
-    token: opts.token,
+    get token() {
+      return currentToken;
+    },
     siteId: opts.siteId,
     fetcher,
     rawRequest,
@@ -323,6 +370,7 @@ var RealtimeClient = class {
   opts;
   ws = null;
   subscriptions = /* @__PURE__ */ new Map();
+  subscriptionFilters = /* @__PURE__ */ new Map();
   presenceListeners = /* @__PURE__ */ new Set();
   currentPresence = {};
   sessionId = null;
@@ -355,14 +403,20 @@ var RealtimeClient = class {
    * Subscribe to item mutation events for a specific collection.
    * Multiple handlers per collection are supported.
    *
+   * `opts.filter` is an optional Directus-style condition rule evaluated
+   * server-side over the event envelope (`collection`/`action`/`itemId`) —
+   * studio broadcasts are signal-only, so row data is never filterable. The
+   * filter is per-collection: the most recent subscribe call's filter wins.
+   *
    * @returns Unsubscribe function.
    */
-  subscribe(collection, callback) {
+  subscribe(collection, callback, opts = {}) {
     if (!this.subscriptions.has(collection)) {
       this.subscriptions.set(collection, /* @__PURE__ */ new Set());
     }
     this.subscriptions.get(collection).add(callback);
-    this._send({ type: "subscribe", collection });
+    if (opts.filter) this.subscriptionFilters.set(collection, opts.filter);
+    this._send({ type: "subscribe", collection, ...opts.filter ? { filter: opts.filter } : {} });
     return () => this.unsubscribe(collection, callback);
   }
   /** Remove a specific handler from a collection subscription. */
@@ -372,6 +426,7 @@ var RealtimeClient = class {
     set.delete(callback);
     if (set.size === 0) {
       this.subscriptions.delete(collection);
+      this.subscriptionFilters.delete(collection);
       this._send({ type: "unsubscribe", collection });
     }
   }
@@ -436,7 +491,8 @@ var RealtimeClient = class {
     ws.addEventListener("open", () => {
       this.backoffMs = this.opts.initialBackoffMs ?? 1e3;
       for (const collection of this.subscriptions.keys()) {
-        this._sendRaw({ type: "subscribe", collection });
+        const filter = this.subscriptionFilters.get(collection);
+        this._sendRaw({ type: "subscribe", collection, ...filter ? { filter } : {} });
       }
       if (Object.keys(this.currentPresence).length > 0) {
         this._sendRaw({ type: "presence", ...this.currentPresence });

package/dist/index.d.cts

@@ -1371,8 +1371,29 @@ interface LumiClientOptions {
      * is thrown so a host (e.g. Studio) can clear the stale token and route
      * the operator back to the login screen. Errors thrown by the callback
      * are swallowed so they never mask the original `LumiError`.
+     *
+     * When auto-refresh is enabled (see `refreshToken`), `onUnauthorized`
+     * fires only AFTER a refresh attempt has also failed.
      */
     onUnauthorized?: () => void;
+    /**
+     * Rotating refresh token (body transport). When set, a `401` triggers a
+     * single `POST /api/v1/auth/refresh` with this token; on success the new
+     * access token is adopted and the original request is retried once. The
+     * refresh token rotates each call, so the new pair is surfaced via
+     * {@link onTokensRefreshed} for the host to persist. Omit to keep the
+     * legacy behaviour (no retry; `onUnauthorized` fires immediately).
+     */
+    refreshToken?: string;
+    /**
+     * Called after a successful silent refresh with the rotated token pair so
+     * the host can persist them (the old refresh token is now revoked).
+     */
+    onTokensRefreshed?: (tokens: {
+        token: string;
+        refreshToken: string;
+        refreshTokenExpiresAt?: string;
+    }) => void;
 }
 interface LumiResponse<T> {
     data: T;
@@ -1542,6 +1563,7 @@ declare class RealtimeClient {
     private readonly opts;
     private ws;
     private readonly subscriptions;
+    private readonly subscriptionFilters;
     private presenceListeners;
     private currentPresence;
     private sessionId;
@@ -1557,9 +1579,16 @@ declare class RealtimeClient {
      * Subscribe to item mutation events for a specific collection.
      * Multiple handlers per collection are supported.
      *
+     * `opts.filter` is an optional Directus-style condition rule evaluated
+     * server-side over the event envelope (`collection`/`action`/`itemId`) —
+     * studio broadcasts are signal-only, so row data is never filterable. The
+     * filter is per-collection: the most recent subscribe call's filter wins.
+     *
      * @returns Unsubscribe function.
      */
-    subscribe(collection: string, callback: RealtimeEventCallback): () => void;
+    subscribe(collection: string, callback: RealtimeEventCallback, opts?: {
+        filter?: Record<string, unknown>;
+    }): () => void;
     /** Remove a specific handler from a collection subscription. */
     unsubscribe(collection: string, callback: RealtimeEventCallback): void;
     /** Update the current user's presence. Sent immediately and on reconnect. */

package/dist/index.d.ts

@@ -1371,8 +1371,29 @@ interface LumiClientOptions {
      * is thrown so a host (e.g. Studio) can clear the stale token and route
      * the operator back to the login screen. Errors thrown by the callback
      * are swallowed so they never mask the original `LumiError`.
+     *
+     * When auto-refresh is enabled (see `refreshToken`), `onUnauthorized`
+     * fires only AFTER a refresh attempt has also failed.
      */
     onUnauthorized?: () => void;
+    /**
+     * Rotating refresh token (body transport). When set, a `401` triggers a
+     * single `POST /api/v1/auth/refresh` with this token; on success the new
+     * access token is adopted and the original request is retried once. The
+     * refresh token rotates each call, so the new pair is surfaced via
+     * {@link onTokensRefreshed} for the host to persist. Omit to keep the
+     * legacy behaviour (no retry; `onUnauthorized` fires immediately).
+     */
+    refreshToken?: string;
+    /**
+     * Called after a successful silent refresh with the rotated token pair so
+     * the host can persist them (the old refresh token is now revoked).
+     */
+    onTokensRefreshed?: (tokens: {
+        token: string;
+        refreshToken: string;
+        refreshTokenExpiresAt?: string;
+    }) => void;
 }
 interface LumiResponse<T> {
     data: T;
@@ -1542,6 +1563,7 @@ declare class RealtimeClient {
     private readonly opts;
     private ws;
     private readonly subscriptions;
+    private readonly subscriptionFilters;
     private presenceListeners;
     private currentPresence;
     private sessionId;
@@ -1557,9 +1579,16 @@ declare class RealtimeClient {
      * Subscribe to item mutation events for a specific collection.
      * Multiple handlers per collection are supported.
      *
+     * `opts.filter` is an optional Directus-style condition rule evaluated
+     * server-side over the event envelope (`collection`/`action`/`itemId`) —
+     * studio broadcasts are signal-only, so row data is never filterable. The
+     * filter is per-collection: the most recent subscribe call's filter wins.
+     *
      * @returns Unsubscribe function.
      */
-    subscribe(collection: string, callback: RealtimeEventCallback): () => void;
+    subscribe(collection: string, callback: RealtimeEventCallback, opts?: {
+        filter?: Record<string, unknown>;
+    }): () => void;
     /** Remove a specific handler from a collection subscription. */
     unsubscribe(collection: string, callback: RealtimeEventCallback): void;
     /** Update the current user's presence. Sent immediately and on reconnect. */

package/dist/index.js

@@ -34,12 +34,52 @@ function toErrorBody(status, body) {
 function createLumiClient(opts) {
   const fetcher = opts.fetcher ?? globalThis.fetch;
   const base = opts.url.replace(/\/$/, "");
-  async function rawRequest(path, init = {}) {
+  let currentToken = opts.token;
+  let currentRefreshToken = opts.refreshToken;
+  let refreshInFlight = null;
+  async function attemptRefresh() {
+    if (!currentRefreshToken) return false;
+    if (!refreshInFlight) {
+      refreshInFlight = (async () => {
+        try {
+          const res = await fetcher(`${base}/api/v1/auth/refresh`, {
+            method: "POST",
+            headers: {
+              "content-type": "application/json",
+              "x-lumi-site": opts.siteId
+            },
+            // Body transport is CSRF-exempt (the token isn't ambient).
+            body: JSON.stringify({ refreshToken: currentRefreshToken })
+          });
+          if (!res.ok) return false;
+          const data = parseResponseBody(await res.text())?.data;
+          if (!data?.token || !data.refreshToken) return false;
+          currentToken = data.token;
+          currentRefreshToken = data.refreshToken;
+          try {
+            opts.onTokensRefreshed?.({
+              token: data.token,
+              refreshToken: data.refreshToken,
+              refreshTokenExpiresAt: data.refreshTokenExpiresAt
+            });
+          } catch {
+          }
+          return true;
+        } catch {
+          return false;
+        } finally {
+          refreshInFlight = null;
+        }
+      })();
+    }
+    return refreshInFlight;
+  }
+  async function rawRequest(path, init = {}, retried = false) {
     const headers = new Headers(init.headers);
     for (const [key, value] of Object.entries(opts.headers ?? {})) {
       headers.set(key, value);
     }
-    headers.set("authorization", `Bearer ${opts.token}`);
+    headers.set("authorization", `Bearer ${currentToken}`);
     headers.set("x-lumi-site", opts.siteId);
     if (!headers.has("content-type") && init.body) {
       headers.set("content-type", "application/json");
@@ -48,6 +88,11 @@ function createLumiClient(opts) {
     const text = await res.text();
     const body = parseResponseBody(text);
     if (!res.ok) {
+      if (res.status === 401 && !retried && currentRefreshToken && path !== "/api/v1/auth/refresh") {
+        if (await attemptRefresh()) {
+          return rawRequest(path, init, true);
+        }
+      }
       if (res.status === 401 && opts.onUnauthorized) {
         try {
           opts.onUnauthorized();
@@ -60,7 +105,9 @@ function createLumiClient(opts) {
   }
   const baseClient = {
     url: opts.url,
-    token: opts.token,
+    get token() {
+      return currentToken;
+    },
     siteId: opts.siteId,
     fetcher,
     rawRequest,
@@ -246,6 +293,7 @@ var RealtimeClient = class {
   opts;
   ws = null;
   subscriptions = /* @__PURE__ */ new Map();
+  subscriptionFilters = /* @__PURE__ */ new Map();
   presenceListeners = /* @__PURE__ */ new Set();
   currentPresence = {};
   sessionId = null;
@@ -278,14 +326,20 @@ var RealtimeClient = class {
    * Subscribe to item mutation events for a specific collection.
    * Multiple handlers per collection are supported.
    *
+   * `opts.filter` is an optional Directus-style condition rule evaluated
+   * server-side over the event envelope (`collection`/`action`/`itemId`) —
+   * studio broadcasts are signal-only, so row data is never filterable. The
+   * filter is per-collection: the most recent subscribe call's filter wins.
+   *
    * @returns Unsubscribe function.
    */
-  subscribe(collection, callback) {
+  subscribe(collection, callback, opts = {}) {
     if (!this.subscriptions.has(collection)) {
       this.subscriptions.set(collection, /* @__PURE__ */ new Set());
     }
     this.subscriptions.get(collection).add(callback);
-    this._send({ type: "subscribe", collection });
+    if (opts.filter) this.subscriptionFilters.set(collection, opts.filter);
+    this._send({ type: "subscribe", collection, ...opts.filter ? { filter: opts.filter } : {} });
     return () => this.unsubscribe(collection, callback);
   }
   /** Remove a specific handler from a collection subscription. */
@@ -295,6 +349,7 @@ var RealtimeClient = class {
     set.delete(callback);
     if (set.size === 0) {
       this.subscriptions.delete(collection);
+      this.subscriptionFilters.delete(collection);
       this._send({ type: "unsubscribe", collection });
     }
   }
@@ -359,7 +414,8 @@ var RealtimeClient = class {
     ws.addEventListener("open", () => {
       this.backoffMs = this.opts.initialBackoffMs ?? 1e3;
       for (const collection of this.subscriptions.keys()) {
-        this._sendRaw({ type: "subscribe", collection });
+        const filter = this.subscriptionFilters.get(collection);
+        this._sendRaw({ type: "subscribe", collection, ...filter ? { filter } : {} });
       }
       if (Object.keys(this.currentPresence).length > 0) {
         this._sendRaw({ type: "presence", ...this.currentPresence });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumibase/sdk",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "LumiBase JS SDK (REST + WebSocket) + typegen core. Isomorphic ESM.",
   "type": "module",
   "repository": {