@rehers/rehers-roleplay-sdk 2.5.7 → 3.0.0

package/README.md

@@ -17,8 +17,8 @@ Add this once, above all your routes. It initializes the SDK for the logged-in S
 Production flow:
 
 1. Your backend requests a short-lived `userToken` from `POST /api/seamless/auth/user-token`
-2. Your frontend receives that `userToken`
-3. You pass `userToken` into the SDK
+2. Your frontend provides a `getUserToken()` callback that calls your backend route
+3. The SDK calls `getUserToken()` on startup and before the iframe session expires
 
 The browser should not mint sessions from raw identity fields in production.
 
@@ -26,11 +26,18 @@ The browser should not mint sessions from raw identity fields in production.
 import { SeamlessRoleplayProvider } from "@rehers/rehers-roleplay-sdk/react";
 
 function App() {
-  const userToken = useRoleplayUserToken(); // fetched from your backend
+  async function getUserToken() {
+    const tokenRes = await fetch("/api/roleplay/user-token", {
+      method: "POST",
+      credentials: "include",
+    }).then((r) => r.json());
+
+    return tokenRes.userToken;
+  }
 
   return (
     <SeamlessRoleplayProvider
-      userToken={userToken}
+      getUserToken={getUserToken}
       onReady={() => console.log("Roleplay SDK ready")}
       onError={(err) => console.error("Roleplay SDK error", err)}
     >
@@ -55,7 +62,9 @@ const tokenRes = await fetch("/api/roleplay/user-token", {
 const userToken = tokenRes.userToken;
 ```
 
-That's the only setup. Everything below just works.
+The SDK owns session refresh timing and will call `getUserToken()` again before
+the embedded app session expires. That's the only setup. Everything below just
+works.
 
 ---
 
@@ -221,7 +230,14 @@ import "@rehers/rehers-roleplay-sdk";
 
 // Initialize once
 SeamlessRoleplay.init({
-  userToken: "...",
+  getUserToken: async () => {
+    const res = await fetch("/api/roleplay/user-token", {
+      method: "POST",
+      credentials: "include",
+    });
+    const data = await res.json();
+    return data.userToken;
+  },
   onReady() { console.log("ready"); },
 });
 

package/index.d.ts

@@ -1,6 +1,12 @@
+export type SeamlessRoleplayUserTokenProvider = () => string | Promise<string>;
+
 interface SeamlessRoleplayInitBase {
-  /** Short-lived signed JWT minted by your backend for the signed-in user */
-  userToken: string;
+  /**
+   * Returns a fresh short-lived signed user JWT minted by your backend for the
+   * currently signed-in Seamless user. The SDK calls this on startup and before
+   * its iframe session expires.
+   */
+  getUserToken: SeamlessRoleplayUserTokenProvider;
   /** Override the app origin — where the iframe loads from (for dev/testing only) */
   origin?: string;
   /** Called when the SDK session is ready */
@@ -64,7 +70,7 @@ export interface AddToScenarioOptions {
 }
 
 export interface SeamlessRoleplaySDK {
-  /** Initialize the SDK with a short-lived user token. */
+  /** Initialize the SDK with a host-provided user token callback. */
   init(options: SeamlessRoleplayInitOptions): void;
   /** Open the roleplay modal for a contact (dialog mode). */
   open(data: SeamlessRoleplayOpenData): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rehers/rehers-roleplay-sdk",
-  "version": "2.5.7",
+  "version": "3.0.0",
   "sideEffects": true,
   "description": "Seamless Roleplay SDK — embed roleplay call sessions via a modal + iframe",
   "main": "roleplay-sdk.js",

package/react.d.ts

@@ -13,7 +13,7 @@ interface SeamlessRoleplayContextValue {
 export type SeamlessRoleplayProviderProps = SeamlessRoleplayInitOptions & {
     children: ReactNode;
 };
-export declare function SeamlessRoleplayProvider({ userToken, origin, onReady, onError, children, }: SeamlessRoleplayProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function SeamlessRoleplayProvider({ getUserToken, origin, onReady, onError, children, }: SeamlessRoleplayProviderProps): import("react/jsx-runtime").JSX.Element;
 export declare function useSeamlessRoleplay(): SeamlessRoleplayContextValue;
 export interface RoleplayDialogProps {
     open: boolean;

package/react.js

@@ -22,7 +22,7 @@ function getSDK() {
 }
 const SeamlessRoleplayContext = createContext(null);
 let providerMountCount = 0;
-export function SeamlessRoleplayProvider({ userToken, origin, onReady, onError, children, }) {
+export function SeamlessRoleplayProvider({ getUserToken, origin, onReady, onError, children, }) {
     const [state, setState] = useState({ isReady: false, error: null });
     const mountedRef = useRef(false);
     const onReadyRef = useCallbackRef(onReady);
@@ -37,7 +37,7 @@ export function SeamlessRoleplayProvider({ userToken, origin, onReady, onError,
         mountedRef.current = true;
         setState({ isReady: false, error: null });
         const initOptions = {
-            userToken,
+            getUserToken,
             origin,
             onReady: () => {
                 var _a;
@@ -60,7 +60,7 @@ export function SeamlessRoleplayProvider({ userToken, origin, onReady, onError,
             providerMountCount--;
             sdk.destroy();
         };
-    }, [sdk, userToken, origin]);
+    }, [sdk, getUserToken, origin]);
     const contextValue = useMemo(() => ({ ...state, sdk }), [state, sdk]);
     return (_jsx(SeamlessRoleplayContext.Provider, { value: contextValue, children: children }));
 }

package/roleplay-sdk.js

@@ -1,10 +1,10 @@
 /**
- * SeamlessRoleplay SDK v2
+ * SeamlessRoleplay SDK v3
  *
  * User-token auth model. No build step required.
  *
  * Usage:
- *   SeamlessRoleplay.init({ userToken: 'jwt...' });
+ *   SeamlessRoleplay.init({ getUserToken: async () => 'jwt...' });
  *   SeamlessRoleplay.open({ name: '...', domain: '...', company: '...', title: '...' });
  */
 (function () {
@@ -16,13 +16,17 @@
   var SDK_LOG_PREFIX = "[SeamlessRoleplay]";
 
   // ── Auth state ────────────────────────────────────────────────────
-  var userToken = null;
+  var getUserToken = null;
+  var latestUserToken = null;
+  var userTokenRequest = null;
   var paymentLink = null;
   var appOrigin = null;
 
   var sessionToken = null;
   var sessionExpiresAt = 0; // epoch ms
+  var sessionRefreshBufferMs = 30000;
   var refreshTimer = null;
+  var refreshRetryDelayMs = 5000;
   var fetchingSession = null; // single-flight Promise
   var activeSessionXhr = null;
   var activeInitVersion = 0;
@@ -89,6 +93,16 @@
     }
   }
 
+  function normalizeToken(value) {
+    if (typeof value !== "string") return null;
+    var trimmed = value.trim();
+    return trimmed ? trimmed : null;
+  }
+
+  function makeError(code, message) {
+    return { code: code, message: message };
+  }
+
   // ── Session management ────────────────────────────────────────────
 
   function clearSessionRequest() {
@@ -101,88 +115,236 @@
     fetchingSession = null;
   }
 
-  function fetchSession() {
+  function resolveUserToken() {
+    if (typeof getUserToken !== "function") {
+      return Promise.reject(
+        makeError("INVALID_INIT", "requires { getUserToken }")
+      );
+    }
+
+    if (userTokenRequest) return userTokenRequest;
+
+    userTokenRequest = Promise.resolve()
+      .then(function () {
+        return getUserToken();
+      })
+      .then(
+        function (value) {
+          userTokenRequest = null;
+          var token = normalizeToken(value);
+          if (!token) {
+            throw makeError(
+              "USER_TOKEN_ERROR",
+              "getUserToken() did not return a valid userToken"
+            );
+          }
+          latestUserToken = token;
+          return token;
+        },
+        function (err) {
+          userTokenRequest = null;
+          throw makeError(
+            (err && err.code) || "USER_TOKEN_ERROR",
+            (err && err.message) || "Failed to get a fresh userToken"
+          );
+        }
+      );
+
+    return userTokenRequest;
+  }
+
+  function dispatchRefreshToTarget(targetIframe) {
+    if (!sessionToken) return;
+    sendMsg(targetIframe, {
+      type: "seamless-session-refresh",
+      sessionToken: sessionToken,
+    });
+  }
+
+  function broadcastSessionRefresh() {
+    if (mountIframe) dispatchRefreshToTarget(mountIframe);
+    if (dialogIframe) dispatchRefreshToTarget(dialogIframe);
+  }
+
+  function notifySessionRefreshFailed(err) {
+    var error = {
+      code: "SESSION_REFRESH_FAILED",
+      message:
+        (err && err.message) ||
+        "Failed to refresh the SDK session before it expired",
+    };
+
+    try {
+      if (initCallbacks.onError) initCallbacks.onError(error);
+    } catch (_) {}
+    try {
+      if (mountCallbacks.onError) mountCallbacks.onError(error);
+    } catch (_) {}
+    try {
+      if (dialogCallbacks.onError) dialogCallbacks.onError(error);
+    } catch (_) {}
+    try {
+      if (dialogAddToScenarioCallbacks.onError) {
+        dialogAddToScenarioCallbacks.onError(error);
+      }
+    } catch (_) {}
+  }
+
+  function computeRefreshBuffer(ttlMs) {
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0) return 30000;
+    return Math.min(30000, Math.max(1000, Math.floor(ttlMs * 0.1)));
+  }
+
+  function computeRefreshDelay(ttlMs) {
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0) return 5000;
+
+    var eightyPercent = Math.floor(ttlMs * 0.8);
+    var oneMinuteBeforeExpiry = ttlMs - 60000;
+    var target =
+      oneMinuteBeforeExpiry > 0
+        ? Math.min(eightyPercent, oneMinuteBeforeExpiry)
+        : Math.floor(ttlMs * 0.5);
+
+    return Math.max(target, 1000);
+  }
+
+  function scheduleRefreshRetry(err) {
+    if (!initCalled || !sessionExpiresAt) return;
+    if (refreshTimer) clearTimeout(refreshTimer);
+
+    var remainingMs = sessionExpiresAt - Date.now();
+    if (remainingMs <= sessionRefreshBufferMs) {
+      notifySessionRefreshFailed(err);
+      return;
+    }
+
+    var delay = Math.min(
+      refreshRetryDelayMs,
+      Math.max(1000, remainingMs - sessionRefreshBufferMs)
+    );
+    refreshRetryDelayMs = Math.min(refreshRetryDelayMs * 2, 60000);
+
+    refreshTimer = setTimeout(function () {
+      fetchSession({ broadcastRefresh: true }).catch(scheduleRefreshRetry);
+    }, delay);
+  }
+
+  function fetchSession(options) {
+    options = options || {};
     var requestInitVersion = activeInitVersion;
 
     if (fetchingSession && fetchingSession.initVersion === requestInitVersion) {
+      if (options.broadcastRefresh) {
+        return fetchingSession.promise.then(function (result) {
+          if (
+            requestInitVersion === activeInitVersion &&
+            result &&
+            result.sessionToken
+          ) {
+            broadcastSessionRefresh();
+          }
+          return result;
+        });
+      }
       return fetchingSession.promise;
     }
 
-    var requestPromise = new Promise(function (resolve, reject) {
-      var url = getApiOrigin() + "/api/sdk/session";
-      var body = { userToken: userToken };
+    var requestPromise = resolveUserToken().then(function (freshUserToken) {
+      if (requestInitVersion !== activeInitVersion) {
+        throw makeError("ABORTED", "Stale session request ignored");
+      }
 
-      var xhr = new XMLHttpRequest();
-      activeSessionXhr = xhr;
-      xhr.open("POST", url, true);
-      xhr.setRequestHeader("Content-Type", "application/json");
-      xhr.withCredentials = false;
-      xhr.timeout = SESSION_TIMEOUT_MS;
+      return new Promise(function (resolve, reject) {
+        var url = getApiOrigin() + "/api/sdk/session";
+        var body = { userToken: freshUserToken };
 
-      function cleanupRequest() {
-        if (activeSessionXhr === xhr) {
-          activeSessionXhr = null;
-        }
-        if (fetchingSession && fetchingSession.promise === requestPromise) {
-          fetchingSession = null;
+        var xhr = new XMLHttpRequest();
+        activeSessionXhr = xhr;
+        xhr.open("POST", url, true);
+        xhr.setRequestHeader("Content-Type", "application/json");
+        xhr.withCredentials = false;
+        xhr.timeout = SESSION_TIMEOUT_MS;
+
+        function cleanupRequest() {
+          if (activeSessionXhr === xhr) {
+            activeSessionXhr = null;
+          }
+          if (fetchingSession && fetchingSession.promise === requestPromise) {
+            fetchingSession = null;
+          }
         }
-      }
 
-      xhr.onload = function () {
-        cleanupRequest();
+        xhr.onload = function () {
+          cleanupRequest();
 
-        if (requestInitVersion !== activeInitVersion) {
-          reject({ code: "ABORTED", message: "Stale session response ignored" });
-          return;
-        }
+          if (requestInitVersion !== activeInitVersion) {
+            reject({ code: "ABORTED", message: "Stale session response ignored" });
+            return;
+          }
 
-        var data;
-        try {
-          data = JSON.parse(xhr.responseText);
-        } catch (e) {
-          reject({ code: "PARSE_ERROR", message: "Invalid response from session endpoint" });
-          return;
-        }
+          var data;
+          try {
+            data = JSON.parse(xhr.responseText);
+          } catch (e) {
+            reject({ code: "PARSE_ERROR", message: "Invalid response from session endpoint" });
+            return;
+          }
 
-        if (xhr.status === 200 && data.sessionToken) {
-          sessionToken = data.sessionToken;
-          var ttl = (data.expiresIn || 3600) * 1000;
-          sessionExpiresAt = Date.now() + ttl;
-          scheduleRefresh(ttl);
-          resolve({ sessionToken: sessionToken });
-          return;
-        }
+          if (xhr.status === 200 && data.sessionToken) {
+            sessionToken = data.sessionToken;
+            var ttl = (data.expiresIn || 3600) * 1000;
+            sessionRefreshBufferMs = computeRefreshBuffer(ttl);
+            sessionExpiresAt = Date.now() + ttl;
+            refreshRetryDelayMs = 5000;
+            scheduleRefresh(ttl);
+            if (options.broadcastRefresh) broadcastSessionRefresh();
+            resolve({ sessionToken: sessionToken });
+            return;
+          }
 
-        if (data.error === "USER_NOT_FOUND") {
-          // Trial mode — not a fatal error
-          sessionToken = null;
-          if (data.paymentLink) paymentLink = data.paymentLink;
-          resolve({ trialMode: true });
-          return;
-        }
+          if (data.error === "USER_NOT_FOUND") {
+            // Trial mode — not a fatal error
+            sessionToken = null;
+            sessionExpiresAt = 0;
+            if (refreshTimer) {
+              clearTimeout(refreshTimer);
+              refreshTimer = null;
+            }
+            if (data.paymentLink) paymentLink = data.paymentLink;
+            resolve({ trialMode: true });
+            return;
+          }
 
-        reject({
-          code: data.error || "SESSION_ERROR",
-          message: data.message || "Failed to create session (HTTP " + xhr.status + ")",
-        });
-      };
+          reject({
+            code: data.error || "SESSION_ERROR",
+            message: data.message || "Failed to create session (HTTP " + xhr.status + ")",
+          });
+        };
 
-      xhr.onerror = function () {
-        cleanupRequest();
-        reject({ code: "NETWORK_ERROR", message: "Network error contacting session endpoint" });
-      };
+        xhr.onerror = function () {
+          cleanupRequest();
+          reject({ code: "NETWORK_ERROR", message: "Network error contacting session endpoint" });
+        };
 
-      xhr.ontimeout = function () {
-        cleanupRequest();
-        reject({ code: "TIMEOUT", message: "Session request timed out after " + SESSION_TIMEOUT_MS + "ms" });
-      };
+        xhr.ontimeout = function () {
+          cleanupRequest();
+          reject({ code: "TIMEOUT", message: "Session request timed out after " + SESSION_TIMEOUT_MS + "ms" });
+        };
 
-      xhr.onabort = function () {
-        cleanupRequest();
-        reject({ code: "ABORTED", message: "Session request was aborted" });
-      };
+        xhr.onabort = function () {
+          cleanupRequest();
+          reject({ code: "ABORTED", message: "Session request was aborted" });
+        };
 
-      xhr.send(JSON.stringify(body));
+        xhr.send(JSON.stringify(body));
+      });
+    });
+
+    requestPromise = requestPromise.catch(function (err) {
+      if (fetchingSession && fetchingSession.promise === requestPromise) {
+        fetchingSession = null;
+      }
+      throw err;
     });
 
     fetchingSession = {
@@ -194,7 +356,7 @@
   }
 
   function getSessionToken() {
-    if (sessionToken && Date.now() < sessionExpiresAt - 30000) {
+    if (sessionToken && Date.now() < sessionExpiresAt - sessionRefreshBufferMs) {
       return Promise.resolve(sessionToken);
     }
     return fetchSession().then(function (result) {
@@ -204,11 +366,9 @@
 
   function scheduleRefresh(ttlMs) {
     if (refreshTimer) clearTimeout(refreshTimer);
-    var delay = Math.max(ttlMs * 0.8, 5000);
+    var delay = computeRefreshDelay(ttlMs);
     refreshTimer = setTimeout(function () {
-      fetchSession().catch(function () {
-        // Silent — next open() will retry
-      });
+      fetchSession({ broadcastRefresh: true }).catch(scheduleRefreshRetry);
     }, delay);
   }
 
@@ -451,17 +611,17 @@
 
   var SeamlessRoleplay = {
     /**
-     * Initialize the SDK with a short-lived user token.
+     * Initialize the SDK with a host-provided user token callback.
      */
     init: function (opts) {
       try {
         var initVersion = activeInitVersion + 1;
-        var hasUserToken = !!(opts && opts.userToken && String(opts.userToken).trim());
+        var hasUserTokenProvider = !!(opts && typeof opts.getUserToken === "function");
 
-        if (!opts || !hasUserToken) {
+        if (!opts || !hasUserTokenProvider) {
           var error = {
             code: "INVALID_INIT",
-            message: "requires { userToken }",
+            message: "requires { getUserToken }",
           };
           logError("init", error.message);
           if (opts && typeof opts.onError === "function") {
@@ -479,9 +639,13 @@
         clearSessionRequest();
         sessionToken = null;
         sessionExpiresAt = 0;
+        sessionRefreshBufferMs = 30000;
+        refreshRetryDelayMs = 5000;
         paymentLink = null;
+        latestUserToken = null;
+        userTokenRequest = null;
 
-        userToken = opts.userToken || null;
+        getUserToken = opts.getUserToken;
         appOrigin = opts.origin || null;
         initCallbacks.onReady = opts.onReady || null;
         initCallbacks.onError = opts.onError || null;
@@ -809,10 +973,14 @@
         clearSessionRequest();
         teardownDialog();
         teardownMount();
-        userToken = null;
+        getUserToken = null;
+        latestUserToken = null;
+        userTokenRequest = null;
         paymentLink = null;
         sessionToken = null;
         sessionExpiresAt = 0;
+        sessionRefreshBufferMs = 30000;
+        refreshRetryDelayMs = 5000;
         initCallbacks = { onReady: null, onError: null };
         initCalled = false;
       } catch (e) {