@returningai/widget-sdk 1.3.0 → 1.4.1

package/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+All notable changes to `@returningai/widget-sdk` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Security Notice — 2026-05-11] Refresh-token TTL change for Access Key Embed
+
+**This is a server-side change. No SDK code update is required. Customers do
+not need to publish a new build of their host pages — the change applies
+automatically the next time their users load the widget.**
+
+### What changed
+
+The ReturningAI widget auth backend (`/auth/serverless`) now issues
+**0-second-TTL refresh tokens** for Access Key Embed sessions (any auth
+request that includes a signed `embedToken` in the body). The SDK persists
+the refresh token with an already-expired `refreshTokenExpiry`, so on the
+next page load `loadFromStorage` wipes it and the SDK re-calls
+`/auth/serverless` for fresh `embedToken` validation.
+
+Public Embed sessions (auth via `data-*` identifier attributes only, no
+`embedToken`) keep the original 7-day refresh window — their identity
+arrives from the host page on every load anyway, so caching the refresh
+token doesn't change the security model.
+
+In addition, refresh tokens **issued before this date are now rejected** by
+`/auth/refresh`. Users with stored refresh tokens older than the cutoff
+will see a one-time `/auth/serverless` re-auth on their next page load.
+This is transparent provided their host page still supplies `embed-token`
+(Access Key Embed) or `data-email` / configured identifier attrs (Public
+Embed) — which is the normal embed state.
+
+### Why
+
+In the previous behavior, a host page that:
+
+1. Initially loaded with `embed-token` + `data-email` (auth succeeded,
+   7-day refresh token stored), and
+2. Later loaded without those attributes (e.g., the `embed-token` attribute
+   was removed or rotated)
+
+...would still authenticate as the original user via the cached refresh
+token until that token's 7-day TTL expired. This conflicted with the
+Access Key Embed promise that **every page load re-validates the embed
+token**. A revoked or expired `embedToken` should immediately end the
+session — not survive for up to a week in the user's browser.
+
+### Visible behavior changes
+
+| Scenario | Before | After |
+|---|---|---|
+| First load with `embed-token` (valid claims) | 200, stores 7-day refresh token | 200, stores already-expired refresh token |
+| Subsequent loads with `embed-token` still present | Used cached refresh token via `/auth/refresh` | Re-validates via `/auth/serverless` every load |
+| Subsequent loads after `embed-token` is removed/changed | Continued working for up to 7 days (gap) | Re-auth required; fails closed if no identity is present |
+| Public Embed loads (`data-email` only) | Unchanged | Unchanged |
+| Users mid-session (in-memory access token) | Unchanged | Unchanged until access token expires (~5 min) |
+
+### Action required
+
+**For most customers: none.** The change is backward-compatible with all
+documented embed patterns. Your existing `<script>` / custom-element
+embeds keep working with their pinned SDK version.
+
+**Possible visible effect:** existing logged-in users may see a single
+re-auth round-trip on their next page load (≈50–150 ms latency added).
+After that, normal behavior resumes.
+
+**If you're using Access Key Embed:** confirm your token-mint endpoint
+calls `issueEmbedTokenService(accessId, accessKey, { /* identifiers */ })`
+so the JWT carries `userIdentifiers` as a signed claim. With a correctly
+signed token, no `data-*` attributes are needed on the embed tag and
+re-auth on every load is transparent.
+
+---
+
+## [1.4.0] — 2026-05-02
+
+### Added
+- Bundled lottie-web (light build) loader instead of runtime CDN fetch.
+  Eliminates dependency on `cdnjs.cloudflare.com` at runtime — works
+  offline and behind corporate proxies.
+- `AnimationItem.destroy()` cleanup on `disconnectedCallback` to fix a
+  memory leak when widgets are repeatedly mounted/unmounted.
+- `data-rai-widget-root` attribute on the mount container for easier
+  selection in tests and external CSS.
+
+### Changed
+- Environment URLs (`api-url`, `widget-url`, `domain-key`, `v2-api-url`)
+  are now optional. The SDK resolves them from `domain-key` when present
+  and defaults to production otherwise. Existing embeds that explicitly
+  pass these attributes continue to work without modification.
+
+---
+
+## [1.3.0] — Server-signed identity (Access Key Embed) + security hardening
+
+Introduced Access Key Embed mode — JWT `embedToken` carries signed
+`userIdentifiers` claims. Server trusts token claims over body-level
+identifiers. SDK clears storage on every load when `embed-token` is
+present, forcing fresh `/auth/serverless` validation.

package/README.md

@@ -2,6 +2,8 @@
 
 Embed ReturningAI widgets on any website — React, Vue, Angular, or plain `<script>` tag. No external dependencies.
 
+> 🛡️ **2026-05-11 security notice — refresh-token TTL for Access Key Embed.** The auth backend now issues 0-TTL refresh tokens for Access Key Embed sessions, and rejects refresh tokens issued before this date. **No SDK update required.** See [CHANGELOG.md](./CHANGELOG.md) for the full rationale and behavior changes.
+
 ---
 
 ## Quick Start
@@ -10,11 +12,11 @@ Your access credentials stay on your server. Your server exchanges them for a **
 
 **Step 1 — Create an access key pair** (one-time, from your dashboard):
 
-Go to **Community Settings > Integrations > SDK Access** and click **Create SDK Key**. Enter a name and optional allowed origins (required in production; localhost is auto-allowed in dev).
+Go to **Community Settings > Integrations > SDK Access** and click **Create SDK Key**. Enter a name and the allowed origins for the sites that will embed the widget.
 
 The dashboard will display your `accessId` and `accessKey`. The `accessKey` is shown **once only** — save it securely.
 
-Store both values in your server environment variables.
+Store both values securely on your server.
 
 > **Rotating or revoking keys:** The same dashboard page lists existing keys and lets you revoke or replace them. Revocation takes effect immediately for token issuance, and forces active sessions to re-auth on their next page load.
 
@@ -22,7 +24,7 @@ Store both values in your server environment variables.
 
 ```js
 // Runs on YOUR SERVER — never in the browser
-const response = await fetch('https://YOUR_API_URL/v2/api/widget-access-keys/token', {
+const response = await fetch('https://api-v2.returning.ai/v2/api/widget-access-keys/token', {
   method: 'POST',
   headers: { 'Content-Type': 'application/json' },
   body: JSON.stringify({
@@ -52,11 +54,12 @@ const { data } = await response.json()
   data-widget-type="store"
   data-theme="dark"
   data-embed-token="eyJ..."
-  api-url="YOUR_API_URL"
   widget-url="YOUR_WIDGET_URL"
 ></script>
 ```
 
+The SDK uses ReturningAI endpoints by default. `api-url` is optional and only needed when you want to override the widget auth server.
+
 The server validates the token and extracts identity from its signed claims. If the token is expired, invalid, or its identifiers don't satisfy the widget's configured User Identifier Fields, the widget shows an error screen. Tokens expire after 15 minutes — regenerate on each page render.
 
 ---
@@ -86,7 +89,6 @@ Set the `data-widget-type` attribute to choose which widget to display. The Widg
 | `store` | Store / rewards widget |
 | `channel` | Channel widget |
 | `milestone` | Milestone widget |
-| `social` | Social widget |
 | `currency-view` | Currency widget |
 | `referral-conditions` | Referral widget |
 | `custom` | Custom widget |
@@ -102,7 +104,6 @@ All examples below use **Access Key Embed** (recommended) — identity is signed
   data-widget-type="store"
   data-theme="dark"
   data-embed-token="eyJ..."
-  api-url="YOUR_API_URL"
   widget-url="YOUR_WIDGET_URL"
 ></script>
 ```
@@ -116,27 +117,12 @@ All examples below use **Access Key Embed** (recommended) — identity is signed
   data-widget-type="channel"
   data-theme="dark"
   data-embed-token="eyJ..."
-  api-url="YOUR_API_URL"
   widget-url="YOUR_WIDGET_URL"
 ></script>
 ```
 
 > **Note:** `YOUR_WIDGET_ID` for channel widgets is the base64-encoded channel ID — find it under **Community Settings > Channels** in your dashboard. Alternatively, use the [custom element approach](#framework-usage-custom-elements) with separate `community-id` and `channel-id` attributes.
 
-### Social widget
-
-```html
-<div id="returning-ai-widget-YOUR_WIDGET_ID" style="width:100%;height:600px"></div>
-<script src="https://unpkg.com/@returningai/widget-sdk/dist/rai-widget.iife.js"
-  data-widget-id="YOUR_WIDGET_ID"
-  data-widget-type="social"
-  data-theme="dark"
-  data-embed-token="eyJ..."
-  api-url="YOUR_API_URL"
-  widget-url="YOUR_WIDGET_URL"
-></script>
-```
-
 ### Milestone widget
 
 ```html
@@ -146,7 +132,6 @@ All examples below use **Access Key Embed** (recommended) — identity is signed
   data-widget-type="milestone"
   data-theme="dark"
   data-embed-token="eyJ..."
-  api-url="YOUR_API_URL"
   widget-url="YOUR_WIDGET_URL"
 ></script>
 ```
@@ -160,7 +145,6 @@ All examples below use **Access Key Embed** (recommended) — identity is signed
   data-widget-type="custom"
   data-theme="dark"
   data-embed-token="eyJ..."
-  api-url="YOUR_API_URL"
   widget-url="YOUR_WIDGET_URL"
 ></script>
 ```
@@ -184,10 +168,9 @@ All attributes can be provided with or without the `data-` prefix — both work.
 |-----------|----------|---------|-------------|
 | `data-widget-id` | **Yes** | — | Your widget ID (from dashboard) |
 | `data-widget-type` | **Yes** | `store` | Widget type (see table above) |
-| `api-url` | **Yes**\* | — | Auth API base URL (from dashboard) |
+| `api-url` | No | ReturningAI widget auth server | Optional widget auth server override |
 | `widget-url` | **Yes**\* | — | Widget URL (from dashboard). \*Not required when using `data-bundle-url` |
 | `data-bundle-url` | No | — | URL to the widget IIFE bundle — triggers [bundle mode](#bundle-mode) (non-iframe) |
-| `data-domain-key` | Bundle mode | — | Environment key: `SGTR`, `STG`, or `PROD`. Required for bundle mode on external sites |
 | `data-theme` | No | `light` | `light` or `dark` |
 | `data-email` | Public Embed only | — | User's email for identification. **Access Key Embed:** omit — identity is signed into `data-embed-token` |
 | `data-embed-token` | Access Key Embed only | — | Short-lived JWT from your server. Carries signed user identifiers — no `data-*` identifier attributes needed |
@@ -197,7 +180,7 @@ All attributes can be provided with or without the `data-` prefix — both work.
 | `data-debug` | No | `false` | Verbose console logging |
 | `data-custom-data` | No | — | JSON object forwarded to the widget |
 | `data-retry-label` | No | `Retry` | Label text for the retry button on the error screen |
-| `data-v2-api-url` | Reserved | — | Reserved for future deployments where V2 API endpoints live on a different host than `api-url`. Currently unused — safe to omit |
+| `data-v2-api-url` | No | ReturningAI V2 API | Optional V2 API override for bundle mode |
 
 ### Custom element attributes
 
@@ -205,10 +188,9 @@ All attributes can be provided with or without the `data-` prefix — both work.
 |-----------|----------|---------|-------------|
 | `community-id` | **Yes**\* | — | Your community ID (raw ObjectId from dashboard). \*Custom widgets use `widget-id` instead |
 | `channel-id` | **Channel only** | — | Channel ID (raw ObjectId) — required for `<rai-channel-widget>` |
-| `api-url` | **Yes** | — | Auth API base URL (from dashboard) |
+| `api-url` | No | ReturningAI widget auth server | Optional widget auth server override |
 | `widget-url` | **Yes**\* | — | Widget URL (from dashboard). \*Not required when using `bundle-url` |
 | `bundle-url` | No | — | URL to the widget IIFE bundle — triggers [bundle mode](#bundle-mode) (non-iframe) |
-| `domain-key` | Bundle mode | — | Environment key: `SGTR`, `STG`, or `PROD`. Required for bundle mode on external sites |
 | `theme` | No | `light` | `light` or `dark` |
 | `data-email` | Public Embed only | — | User's email for identification. **Access Key Embed:** omit — identity is signed into `embed-token` |
 | `embed-token` | Access Key Embed only | — | Short-lived JWT from your server. Carries signed user identifiers — no `data-*` identifier attributes needed |
@@ -220,7 +202,7 @@ All attributes can be provided with or without the `data-` prefix — both work.
 | `debug` | No | `false` | Verbose console logging |
 | `custom-data` | No | — | JSON object forwarded to the widget |
 | `retry-label` | No | `Retry` | Label text for the retry button on the error screen |
-| `v2-api-url` | Reserved | — | Reserved for future deployments where V2 API endpoints live on a different host than `api-url`. Currently unused — safe to omit |
+| `v2-api-url` | No | ReturningAI V2 API | Optional V2 API override for bundle mode |
 
 > **`widget-id` vs `community-id`:** The script-tag method uses `data-widget-id` which is a pre-encoded identifier (base64). The custom element method uses raw ObjectIds — `community-id` for most widget types, plus `channel-id` for channel widgets. The SDK handles the encoding internally.
 
@@ -247,8 +229,7 @@ Custom elements don't need a container div — they size themselves using `width
   data-widget-type="store"
   data-email="user@example.com"
   data-user-id="12345"
-  data-account-id="abc"
-  api-url="YOUR_API_URL"
+  data-member-id="abc"
   widget-url="YOUR_WIDGET_URL"
 ></script>
 ```
@@ -257,15 +238,28 @@ In Public Embed mode, any `data-*` attribute not reserved by the SDK is forwarde
 
 ---
 
+## Endpoint URL Overrides
+
+The SDK uses ReturningAI endpoints by default.
+
+These fields are optional. Set them only when you need to override the default endpoints:
+
+- `api-url` / `data-api-url` — overrides the widget auth server used for SDK auth, refresh, logout, and error settings.
+- `v2-api-url` / `data-v2-api-url` — overrides the V2 API base URL used by bundle mode.
+
+These endpoint overrides do not replace `widget-url` or `bundle-url`; use the widget and bundle URLs from your dashboard.
+
+---
+
 ## Bundle Mode
 
 When you set the `bundle-url` attribute, the widget renders directly in the page DOM instead of inside an iframe. This gives full CSS cascade — `html[data-theme]` and Tailwind classes apply to the widget content naturally.
 
 - `widget-url` is **not** needed in bundle mode (the widget is loaded directly from `bundle-url`).
-- `api-url` **is still required** — it's where the SDK sends the auth request (`/auth/serverless`).
-- `domain-key` is required so the widget IIFE resolves the correct environment URLs.
+- ReturningAI endpoints are used by default.
+- `api-url` and `v2-api-url` are optional endpoint URL overrides.
 
-Both examples below use Access Key Embed:
+Both examples below use Access Key Embed and the default endpoints.
 
 ```html
 <!-- Script-tag approach -->
@@ -276,17 +270,13 @@ Both examples below use Access Key Embed:
   data-theme="dark"
   data-embed-token="eyJ..."
   data-bundle-url="YOUR_BUNDLE_URL"
-  data-domain-key="YOUR_DOMAIN_KEY"
-  api-url="YOUR_API_URL"
   data-eager
 ></script>
 
 <!-- Custom element approach -->
 <rai-store-widget
   community-id="YOUR_COMMUNITY_ID"
-  api-url="YOUR_API_URL"
   bundle-url="YOUR_BUNDLE_URL"
-  domain-key="YOUR_DOMAIN_KEY"
   embed-token="eyJ..."
   theme="dark"
   width="100%"
@@ -301,7 +291,6 @@ Each widget type has its own IIFE bundle and global name:
 |-------------|--------------|-------------------|
 | `store` | `RaiStoreWidget` | `<rai-store-widget>` |
 | `channel` | `RaiChannelWidget` | `<rai-channel-widget>` |
-| `social` | `RaiSocialWidget` | `<rai-social-widget>` |
 | `milestone` | `RaiMilestoneWidget` | `<rai-milestone-widget>` |
 | `currency-view` | `RaiCurrencyWidget` | `<rai-currency-widget>` |
 | `referral-conditions` | `RaiReferralWidget` | `<rai-referral-widget>` |
@@ -327,7 +316,6 @@ All examples below use **Access Key Embed** — pass the short-lived token your
   community-id="YOUR_COMMUNITY_ID"
   theme="dark"
   embed-token="eyJ..."
-  api-url="YOUR_API_URL"
   widget-url="YOUR_WIDGET_URL"
 ></rai-store-widget>
 
@@ -337,7 +325,6 @@ All examples below use **Access Key Embed** — pass the short-lived token your
   channel-id="YOUR_CHANNEL_ID"
   theme="dark"
   embed-token="eyJ..."
-  api-url="YOUR_API_URL"
   widget-url="YOUR_WIDGET_URL"
 ></rai-channel-widget>
 ```
@@ -355,7 +342,6 @@ export function StoreEmbed({ embedToken }: { embedToken: string }) {
       community-id="YOUR_COMMUNITY_ID"
       theme="dark"
       embed-token={embedToken}
-      api-url="YOUR_API_URL"
       widget-url="YOUR_WIDGET_URL"
     />
   )
@@ -368,7 +354,6 @@ export function ChannelEmbed({ embedToken }: { embedToken: string }) {
       channel-id="YOUR_CHANNEL_ID"
       theme="dark"
       embed-token={embedToken}
-      api-url="YOUR_API_URL"
       widget-url="YOUR_WIDGET_URL"
     />
   )
@@ -389,7 +374,6 @@ defineProps({ embedToken: String })
     community-id="YOUR_COMMUNITY_ID"
     theme="dark"
     :embed-token="embedToken"
-    api-url="YOUR_API_URL"
     widget-url="YOUR_WIDGET_URL"
   />
 
@@ -399,7 +383,6 @@ defineProps({ embedToken: String })
     channel-id="YOUR_CHANNEL_ID"
     theme="dark"
     :embed-token="embedToken"
-    api-url="YOUR_API_URL"
     widget-url="YOUR_WIDGET_URL"
   />
 </template>
@@ -421,7 +404,6 @@ import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'
   community-id="YOUR_COMMUNITY_ID"
   theme="dark"
   [attr.embed-token]="embedToken"
-  api-url="YOUR_API_URL"
   widget-url="YOUR_WIDGET_URL"
 ></rai-store-widget>
 
@@ -431,7 +413,6 @@ import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'
   channel-id="YOUR_CHANNEL_ID"
   theme="dark"
   [attr.embed-token]="embedToken"
-  api-url="YOUR_API_URL"
   widget-url="YOUR_WIDGET_URL"
 ></rai-channel-widget>
 ```
@@ -443,7 +424,6 @@ import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'
 | `<rai-store-widget>` | `community-id` | Store |
 | `<rai-channel-widget>` | `community-id` + `channel-id` | Channel |
 | `<rai-milestone-widget>` | `community-id` | Milestone |
-| `<rai-social-widget>` | `community-id` | Social |
 | `<rai-currency-widget>` | `community-id` | Currency |
 | `<rai-referral-widget>` | `community-id` | Referral |
 | `<rai-custom-widget>` | `widget-id` (not `community-id`) | Custom |