@returningai/widget-sdk 1.3.0 → 1.4.0

package/README.md

@@ -52,11 +52,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>
 ```
 
+`api-url` is optional. The SDK resolves the widget server from `domain-key` when provided and uses production by default; pass `api-url` only if you need 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.
 
 ---
@@ -102,7 +103,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,7 +116,6 @@ 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>
 ```
@@ -132,7 +131,6 @@ All examples below use **Access Key Embed** (recommended) — identity is signed
   data-widget-type="social"
   data-theme="dark"
   data-embed-token="eyJ..."
-  api-url="YOUR_API_URL"
   widget-url="YOUR_WIDGET_URL"
 ></script>
 ```
@@ -146,7 +144,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 +157,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 +180,10 @@ 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 | Production widget server | Optional widget auth server override. Defaults from `domain-key` when provided |
 | `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-domain-key` | No | `PROD` | Environment key: `SGTR`, `STG`, or `PROD`. Used to resolve default environment URLs when overrides are omitted |
 | `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 +193,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 | Domain-key default | Optional V2 API override for bundle mode. Safe to omit for standard environments |
 
 ### Custom element attributes
 
@@ -205,10 +201,10 @@ 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 | Production widget server | Optional widget auth server override. Defaults from `domain-key` when provided |
 | `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 |
+| `domain-key` | No | `PROD` | Environment key: `SGTR`, `STG`, or `PROD`. Used to resolve default environment URLs when overrides are omitted |
 | `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 +216,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 | Domain-key default | Optional V2 API override for bundle mode. Safe to omit for standard environments |
 
 > **`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.
 
@@ -248,7 +244,6 @@ Custom elements don't need a container div — they size themselves using `width
   data-email="user@example.com"
   data-user-id="12345"
   data-account-id="abc"
-  api-url="YOUR_API_URL"
   widget-url="YOUR_WIDGET_URL"
 ></script>
 ```
@@ -262,10 +257,11 @@ In Public Embed mode, any `data-*` attribute not reserved by the SDK is forwarde
 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.
+- `api-url` is optional. The SDK resolves the widget auth server from `domain-key` when provided, or defaults to production.
+- `domain-key` is optional. When omitted, the SDK defaults to production (`PROD`).
+- Environment URL variables such as `window.api_url` are optional overrides. Standard `SGTR`, `STG`, and `PROD` environments resolve from `domain-key`.
 
-Both examples below use Access Key Embed:
+Both examples below use Access Key Embed and target staging. Omit `domain-key` for production.
 
 ```html
 <!-- Script-tag approach -->
@@ -276,17 +272,15 @@ 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-domain-key="STG"
   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"
+  domain-key="STG"
   embed-token="eyJ..."
   theme="dark"
   width="100%"
@@ -327,7 +321,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 +330,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 +347,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 +359,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 +379,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 +388,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 +409,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 +418,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>
 ```