@skippr/live-agent-sdk 0.36.0 → 0.38.0

package/README.md

@@ -89,6 +89,8 @@ The SDK supports two identity modes, configured per App Key in the Skippr dashbo
 
 Users log in via email OTP inside the widget. No backend integration needed. The SDK handles the full OTP flow: email input, code verification, and token persistence automatically.
 
+> **Best suited for development and testing.** Direct Auth persists tokens in the browser and has no automatic token refresh, so it works in production but isn't what we recommend there. For production, we suggest Secret Mode — your backend vouches for the user and controls token lifetime.
+
 **React:**
 
 ```tsx
@@ -105,7 +107,11 @@ Skippr.initialize({
 
 ### Secret Mode
 
-Your backend signs a JWT with the App Key's identity secret and passes it as `userToken`. The SDK exchanges it for a bearer token server-side and skips the login form entirely.
+Your backend signs a short-lived JWT with the App Key's identity secret. You give the SDK a `getUserToken` callback that returns a freshly signed JWT each time it's called; the SDK exchanges it for a bearer token server-side and skips the login form entirely.
+
+Because it's a callback (not a static token), the SDK can keep the session alive without a page reload: it invokes `getUserToken` to bootstrap, again proactively shortly before the current bearer expires, and once more if a request comes back `401`. Your callback should always return a *current* JWT from your source of truth — typically by re-minting it on your backend per call.
+
+The bearer's lifetime is the **session token lifetime** you set on the App Key in the dashboard (15 minutes to 24 hours, default 1 hour).
 
 **Step 1: Generate a signed JWT on your backend**
 
@@ -134,14 +140,14 @@ const userToken = jwt.sign(
 );
 ```
 
-**Step 2: Pass the token to the SDK**
+**Step 2: Give the SDK a callback that fetches a fresh token**
 
 **React:**
 
 ```tsx
 <LiveAgent
   appKey="pk_live_your_key"
-  userToken={userToken}
+  getUserToken={() => fetch('/api/skippr-token').then((r) => r.text())}
 />
 ```
 
@@ -150,10 +156,22 @@ const userToken = jwt.sign(
 ```js
 Skippr.initialize({
   appKey: 'pk_live_your_key',
-  userToken: 'eyJhbGciOiJIUzI1NiIs...',
+  getUserToken: () => fetch('/api/skippr-token').then((r) => r.text()),
 });
 ```
 
+The callback runs whenever the SDK needs a token, so each call should return a newly minted JWT (e.g. from the `/api/skippr-token` endpoint on your backend that signs the JWT shown in Step 1).
+
+#### Static token (testing)
+
+If you already hold a signed JWT and just want to drop it in, pass it as a static `userToken` string instead of a callback. The SDK exchanges it for a bearer token the same way.
+
+```tsx
+<LiveAgent appKey="pk_live_your_key" userToken={signedJwt} />
+```
+
+> **Best suited for quick tests.** A static token can't be re-minted, so once it expires the session cannot refresh — for production use the `getUserToken` callback above. When both are provided, `getUserToken` wins.
+
 ## Custom Components
 
 Any component rendered inside `<LiveAgent>` can use the `useLiveAgent` hook to access session state and controls:
@@ -189,7 +207,8 @@ Self-contained widget component. Renders a floating button that opens a sidebar
 |------|------|---------|-------------|
 | `appKey` | `string` | *required* | Publishable App Key from the Skippr dashboard |
 | `agentId` | `string` | — | Pin the widget to a specific module (pass that module's id). Omit to let the user pick from all your active modules at runtime. |
-| `userToken` | `string` | — | Signed JWT for secret mode identity verification |
+| `getUserToken` | `() => Promise<string>` | — | Async callback returning a freshly signed JWT for secret mode. The SDK calls it to bootstrap, again proactively before the bearer expires, and once more on a `401` to re-bootstrap. |
+| `userToken` | `string` | — | Static signed JWT for secret mode (testing). Exchanged for a bearer token but can't be refreshed once expired. `getUserToken` takes precedence when both are set. |
 | `position` | `'left' \| 'right'` | `'right'` | Side of the screen for the widget |
 | `variant` | `'floating' \| 'sidebar'` | `'floating'` | Widget display mode |
 | `minimizable` | `boolean` | `true` | Whether the widget can be minimized |
@@ -278,8 +297,8 @@ Available on `window.Skippr` when using the script tag bundle.
 
 | Method | Description |
 |--------|-------------|
-| `Skippr.initialize(config)` | Mount the widget. Accepts `appKey` (required), `agentId` (optional — omit for picker), `userToken`, `position`, `variant`, `minimizable`, `captureMode`, `agentControls`. |
-| `Skippr.logout()` | Clear stored auth token and show the login form (direct auth mode) |
+| `Skippr.initialize(config)` | Mount the widget. Accepts `appKey` (required), `agentId` (optional — omit for picker), `getUserToken`, `userToken`, `position`, `variant`, `minimizable`, `captureMode`, `agentControls`. |
+| `Skippr.logout()` | Revoke the current session server-side, clear stored auth tokens, and show the login form (direct auth mode) |
 | `Skippr.destroy()` | Remove the widget from the page and clear auth tokens |