@rehers/rehers-roleplay-sdk 2.4.0 → 2.4.2

package/README.md

@@ -1,177 +1,287 @@
-# @rehers/rehers-roleplay-sdk
+# Roleplay SDK for the Seamless.AI Dashboard
 
-Lightweight vanilla JS SDK for embedding roleplay call sessions and bulk contact import. Opens a modal (dialog mode), mounts into a container (mount mode), or launches a scenario picker (add-to-scenario mode) — no framework dependencies.
+This SDK is only for embedding Roleplay inside the Seamless.AI dashboard.
 
-## Install
+Use it in these two places:
+
+- The dedicated Roleplay page or tab inside the Seamless dashboard
+- The Contact Search screen, where clicking `Roleplay` opens a dialog for a single contact
+
+The SDK must be initialized with the currently logged-in Seamless user before either embed flow is used.
+
+## Load the SDK
+
+Seamless can load the SDK in any of these three ways.
+
+### Option 1: Downloaded SDK file
+
+If Seamless is hosting the SDK file directly inside the dashboard:
+
+```html
+<script src="/path/to/roleplay-sdk.js"></script>
+```
+
+### Option 2: npm package
+
+If Seamless is bundling the SDK through the frontend codebase:
 
 ```bash
 npm install @rehers/rehers-roleplay-sdk
 ```
 
-Or load via CDN:
+```js
+import SeamlessRoleplay from "@rehers/rehers-roleplay-sdk";
+```
+
+### Option 3: CDN script
+
+If Seamless wants to load the SDK without bundling it:
 
 ```html
 <script src="https://unpkg.com/@rehers/rehers-roleplay-sdk"></script>
 ```
 
-## Usage
+## Get the logged-in Seamless user
+
+Use the existing Seamless dashboard session and call:
+
+```js
+const meResponse = await fetch("https://api.seamless.ai/api/users/me", {
+  method: "GET",
+  credentials: "include",
+  headers: {
+    accept: "application/json, text/plain, */*",
+  },
+}).then((res) => res.json());
+```
+
+Normalize the response before reading fields:
+
+```js
+const me = meResponse.data ?? meResponse;
+```
+
+## Required mapping for `init()`
+
+These are the values Seamless must pass into `SeamlessRoleplay.init(...)`:
+
+| SDK field | Seamless `/api/users/me` field |
+|---|---|
+| `userId` | `String(me.id)` |
+| `userEmail` | `me.username` |
+| `userRole` | Optional. Suggested mapping from `me.orgRole` / `me.isOrgAdmin` |
+
+Example:
+
+```js
+const seamlessUserId = String(me.id);
+const seamlessUserEmail = me.username;
+const seamlessUserRole =
+  me.orgRole === "owner" ? "owner" :
+  me.isOrgAdmin ? "admin" :
+  "member";
+```
+
+For the response shape currently returned by Seamless, this means:
+
+```js
+const seamlessUserId = String(me.id);
+const seamlessUserEmail = me.username;
+```
+
+## Initialize the SDK once
+
+Initialize the SDK once per page load using the logged-in Seamless user. Reuse that same initialized SDK for both the full-page embed and the Contact Search dialog.
+
+```js
+let roleplayReadyPromise;
+
+function ensureRoleplaySdkReady() {
+  if (roleplayReadyPromise) return roleplayReadyPromise;
+
+  roleplayReadyPromise = (async () => {
+    const meResponse = await fetch("https://api.seamless.ai/api/users/me", {
+      method: "GET",
+      credentials: "include",
+      headers: {
+        accept: "application/json, text/plain, */*",
+      },
+    }).then((res) => res.json());
+
+    const me = meResponse.data ?? meResponse;
+
+    const seamlessUserId = String(me.id);
+    const seamlessUserEmail = me.username;
+    const seamlessUserRole =
+      me.orgRole === "owner" ? "owner" :
+      me.isOrgAdmin ? "admin" :
+      "member";
+
+    await new Promise((resolve, reject) => {
+      SeamlessRoleplay.init({
+        publishableKey: ROLEPLAY_PUBLISHABLE_KEY,
+        userId: seamlessUserId,
+        userEmail: seamlessUserEmail,
+        userRole: seamlessUserRole,
+        onReady: resolve,
+        onError: reject,
+      });
+    });
+  })();
+
+  return roleplayReadyPromise;
+}
+```
+
+## Embed in the full Roleplay page
+
+Use `mount(container)` when Seamless has a dedicated Roleplay page or tab and the full content area should be the Roleplay app.
 
 ```html
-<script src="https://unpkg.com/@rehers/rehers-roleplay-sdk"></script>
-<script>
-  // 1. Initialize with a publishable key
-  SeamlessRoleplay.init({
-    publishableKey: 'pk_live_abc123',
-    userId: 'user_789',
-    userEmail: 'john@example.com',
-    userRole: 'member',                        // optional — "owner", "admin", or "member"
-    onReady: function() {
-      console.log('SDK ready');
+<div id="roleplay-root" style="width: 100%; height: 100%;"></div>
+```
+
+```js
+async function mountRoleplayPage() {
+  await ensureRoleplaySdkReady();
+
+  const container = document.getElementById("roleplay-root");
+  SeamlessRoleplay.mount(container);
+}
+```
+
+If the Seamless page or tab is torn down, unmount the SDK:
+
+```js
+SeamlessRoleplay.unmount();
+```
+
+## Embed in Contact Search
+
+Use `open(contactData)` when the user clicks a `Roleplay` button from a single contact row on the Contact Search screen.
+
+```js
+async function openRoleplayForContact(contact) {
+  await ensureRoleplaySdkReady();
+
+  SeamlessRoleplay.open({
+    name: contact.name,
+    domain: contact.domain,
+    company: contact.company,
+    title: contact.title,
+    liUrl: contact.linkedinUrl,
+    companyDescription: contact.companyDescription,
+    onCallStarted(data) {
+      console.log("Roleplay call started", data.callId);
+    },
+    onCallEnded(data) {
+      console.log("Roleplay call ended", data.callId, data.duration);
     },
-    onError: function(err) {
-      console.error('SDK error:', err.code, err.message);
+    onClose() {
+      console.log("Roleplay dialog closed");
+    },
+    onError(err) {
+      console.error("Roleplay dialog error", err);
     },
   });
+}
+```
 
-  // 2. Open the roleplay modal for a contact (dialog mode)
-  SeamlessRoleplay.open({
-    name: 'Jane Smith',
-    domain: 'acme.com',
-    company: 'Acme Corp',
-    title: 'VP of Sales',
-    companyDescription: 'Enterprise software company', // optional
-    liUrl: 'https://linkedin.com/in/jane-smith',       // optional
-    onCallStarted: function(data) { console.log('Call started:', data.callId); },
-    onCallEnded: function(data) { console.log('Call ended:', data.callId, data.duration); },
-    onClose: function() { console.log('Dialog closed'); },
-    onError: function(data) { console.error('Error:', data.code, data.message); },
-  });
+The contact object passed to `open(...)` should map to:
 
-  // 2b. Or mount the full app into a container (full-page embed)
-  SeamlessRoleplay.mount(document.getElementById('roleplay-container'));
+| SDK field | Contact Search value |
+|---|---|
+| `name` | Contact full name |
+| `domain` | Company domain |
+| `company` | Company name |
+| `title` | Contact title |
+| `liUrl` | LinkedIn profile URL, if available |
+| `companyDescription` | Company description, if available |
 
-  // 2c. Or mount a call for a specific contact into a container
-  SeamlessRoleplay.mount(document.getElementById('roleplay-container'), {
-    name: 'Jane Smith',
-    domain: 'acme.com',
-    company: 'Acme Corp',
-    title: 'VP of Sales',
-  });
+## Optional: add contacts to a scenario
+
+If Seamless wants to send multiple contacts into a scenario picker dialog, use `addToScenario(...)`.
+
+```js
+async function addContactsToScenario(contacts) {
+  await ensureRoleplaySdkReady();
 
-  // 3. Add contacts to a scenario in bulk
   SeamlessRoleplay.addToScenario({
-    contacts: [
-      { name: 'Sarah Chen', company: 'Stripe', title: 'VP of Sales', domain: 'stripe.com', liUrl: 'https://linkedin.com/in/sarachen' },
-      { name: 'Mike Ross', company: 'Acme', title: 'CRO', domain: 'acme.com', liUrl: 'https://linkedin.com/in/mikeross' },
-    ],
-    onComplete: function(data) {
-      console.log('Added', data.addedCount, 'contacts to', data.scenarioName);
+    contacts: contacts.map((contact) => ({
+      name: contact.name,
+      company: contact.company,
+      title: contact.title,
+      domain: contact.domain,
+      liUrl: contact.linkedinUrl,
+      companyDescription: contact.companyDescription,
+    })),
+    onComplete(data) {
+      console.log("Scenario import complete", data);
+    },
+    onClose() {
+      console.log("Add to scenario dialog closed");
+    },
+    onError(err) {
+      console.error("Add to scenario error", err);
     },
-    onClose: function() { console.log('Dialog closed'); },
-    onError: function(err) { console.error('Error:', err.code, err.message); },
   });
-
-  // Close and destroy
-  SeamlessRoleplay.close();
-  SeamlessRoleplay.destroy();
-</script>
+}
 ```
 
-## Trial Mode
+## Minimal API surface
+
+### `SeamlessRoleplay.init(options)`
+
+Initializes the SDK with the logged-in Seamless user.
+
+```js
+SeamlessRoleplay.init({
+  publishableKey,
+  userId,
+  userEmail,
+  userRole,
+  onReady,
+  onError,
+});
+```
 
-When the backend returns `USER_NOT_FOUND`, it includes a `paymentLink` in the response. The SDK automatically captures it and renders a trial screen directing the user to sign up — no client-side configuration needed.
+### `SeamlessRoleplay.mount(container)`
 
-## API
+Mounts the full Roleplay app into a dashboard container.
 
-### `SeamlessRoleplay.init(options)`
+### `SeamlessRoleplay.open(contactData)`
 
-| Option | Type | Required | Description |
-|---|---|---|---|
-| `publishableKey` | `string` | Yes | Publishable API key |
-| `userId` | `string` | Yes | Your user's unique identifier |
-| `userEmail` | `string` | Yes | User email for secure account matching |
-| `userRole` | `string` | No | User role — `"owner"`, `"admin"`, or `"member"` |
-| `userToken` | `string` | No | Signed JWT for identity verification |
-| `origin` | `string` | No | Override app origin (dev only) |
-| `onReady` | `function` | No | Called when session is ready |
-| `onError` | `function` | No | Called on init error `({ code, message })` |
-
-### `SeamlessRoleplay.open(data)`
-
-Opens the roleplay in a modal dialog overlay.
-
-| Field | Type | Required | Description |
-|---|---|---|---|
-| `name` | `string` | Yes | Full name of the contact |
-| `domain` | `string` | Yes | Company domain (e.g. "stripe.com") |
-| `company` | `string` | Yes | Company name |
-| `title` | `string` | Yes | Job title |
-| `companyDescription` | `string` | No | Brief company description |
-| `liUrl` | `string` | No | LinkedIn profile URL |
-| `onCallStarted` | `function` | No | `({ callId })` |
-| `onCallEnded` | `function` | No | `({ callId, duration? })` |
-| `onClose` | `function` | No | Called when dialog closes |
-| `onError` | `function` | No | `({ code, message })` |
-
-### `SeamlessRoleplay.mount(container, data?)`
-
-Mounts into a DOM element. Two modes:
-
-- **`mount(container)`** — embeds the full Roleplay app (dashboard, scenarios, call logs)
-- **`mount(container, data)`** — embeds a roleplay call for a specific contact (same `data` options as `open()`)
+Opens the Roleplay dialog for a single contact.
 
 ### `SeamlessRoleplay.addToScenario(options)`
 
-Opens a compact dialog for selecting a scenario and importing contacts in bulk.
-
-| Field | Type | Required | Description |
-|---|---|---|---|
-| `contacts` | `array` | Yes | 1–25 contacts to import |
-| `contacts[].name` | `string` | Yes | Full name |
-| `contacts[].company` | `string` | Yes | Company name |
-| `contacts[].title` | `string` | Yes | Job title |
-| `contacts[].domain` | `string` | Yes | Company domain |
-| `contacts[].liUrl` | `string` | No | LinkedIn profile URL |
-| `contacts[].companyDescription` | `string` | No | Brief company description |
-| `onComplete` | `function` | No | `({ scenarioId, scenarioName, addedCount, skippedCount })` |
-| `onClose` | `function` | No | Called when dialog closes |
-| `onError` | `function` | No | `({ code, message })` |
+Opens the bulk add-to-scenario dialog for 1 to 25 contacts.
 
 ### `SeamlessRoleplay.close()`
 
-Closes the active dialog or unmounts.
-
-### `SeamlessRoleplay.destroy()`
+Closes the active dialog.
 
-Tears down everything — clears tokens, timers, and DOM elements.
+### `SeamlessRoleplay.unmount()`
 
-## Auth Flow
+Unmounts the full-page Roleplay embed.
 
-```
-SDK                                      Backend
-─────────────────                        ─────────────────
-POST /api/sdk/session
-  X-Publishable-Key: pk_live_abc123
-  Body: { userId, userEmail, userRole? }
-                                         1. Validate key + origin
-                                         2. Validate userId + userEmail combo
-                                         3. Find/create user
-                                         4. Mint JWT (1hr TTL)
-                                ←────    { sessionToken, expiresIn }
-                                         OR { error: "USER_NOT_FOUND" }
+### `SeamlessRoleplay.destroy()`
 
-Token stored in memory (not localStorage)
-Auto-refreshes at 80% of TTL
-```
+Destroys the SDK state, timers, mount, and dialogs.
 
-## Error Handling
+## Trial and upgrade handling
 
-All public methods are wrapped in try/catch — the SDK will never throw an uncaught exception that could crash the host page. Errors are logged to `console.error` with a `[SeamlessRoleplay]` prefix and routed to the relevant `onError` callback when provided.
+If the backend responds with `USER_NOT_FOUND` during SDK session creation, the SDK handles the upgrade or trial UI automatically. Seamless does not need separate client-side logic for that case.
 
 ## TypeScript
 
-Full type declarations are included:
+Type declarations are included with the SDK package.
 
 ```ts
-import type { SeamlessRoleplaySDK, SeamlessRoleplayOpenData, AddToScenarioOptions } from '@rehers/rehers-roleplay-sdk';
+import type {
+  SeamlessRoleplaySDK,
+  SeamlessRoleplayInitOptions,
+  SeamlessRoleplayOpenData,
+  AddToScenarioOptions,
+} from "@rehers/rehers-roleplay-sdk";
 ```

package/index.d.ts

@@ -1,9 +1,9 @@
 export interface SeamlessRoleplayInitOptions {
   /** Publishable API key (starts with pk_live_ or pk_test_) */
   publishableKey: string;
-  /** Your user's unique identifier */
+  /** Logged-in Seamless user ID. Pass String(me.id) from GET /api/users/me */
   userId: string;
-  /** User email — required for secure account matching */
+  /** Logged-in Seamless user email. Pass me.username from GET /api/users/me */
   userEmail: string;
   /** Optional user role for syncing permissions ("owner" | "admin" | "member") */
   userRole?: "owner" | "admin" | "member";
@@ -78,8 +78,8 @@ export interface SeamlessRoleplaySDK {
   init(options: SeamlessRoleplayInitOptions): void;
   /** Open the roleplay modal for a contact (dialog mode). */
   open(data: SeamlessRoleplayOpenData): void;
-  /** Mount the full Roleplay app into a container (no data), or a call embed for a specific contact (with data). */
-  mount(container: HTMLElement, data?: SeamlessRoleplayOpenData): void;
+  /** Mount the full Roleplay app into a container. */
+  mount(container: HTMLElement): void;
   /** Open the add-to-scenario dialog for bulk contact import. */
   addToScenario(options: AddToScenarioOptions): void;
   /** Close the active dialog. Does not affect mount. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rehers/rehers-roleplay-sdk",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "Seamless Roleplay SDK — embed roleplay call sessions via a modal + iframe",
   "main": "roleplay-sdk.js",
   "types": "index.d.ts",

package/roleplay-sdk.js

@@ -35,7 +35,6 @@
   // ── Mount state (persistent embed — survives dialog open/close) ───
   var mountIframe = null;
   var mountContainer = null;
-  var mountContactData = null;
   var mountCallbacks = { onCallStarted: null, onCallEnded: null, onClose: null, onError: null };
   var mountListener = null;
 
@@ -219,7 +218,6 @@
 
     mountIframe = null;
     mountContainer = null;
-    mountContactData = null;
     mountCallbacks = { onCallStarted: null, onCallEnded: null, onClose: null, onError: null };
   }
 
@@ -279,10 +277,10 @@
         case "ROLEPLAY_READY":
           getSessionToken()
             .then(function (token) {
-              dispatchInitToTarget(mountIframe, mountContactData, null);
+              dispatchInitToTarget(mountIframe, null, null);
             })
             .catch(function () {
-              dispatchInitToTarget(mountIframe, mountContactData, null);
+              dispatchInitToTarget(mountIframe, null, null);
             });
           break;
 
@@ -571,13 +569,9 @@
     },
 
     /**
-     * Mount the roleplay into a container element.
-     *
-     * Two modes:
-     *   mount(container)             — full app embed (dashboard, scenarios, call logs, etc.)
-     *   mount(container, contactData) — roleplay call embed for a specific contact
+     * Mount the full Roleplay app into a container element.
      */
-    mount: function (container, data) {
+    mount: function (container) {
       try {
         if (!initCalled) {
           logError("mount", "init() must be called first");
@@ -588,37 +582,22 @@
           return;
         }
 
-        // If contact data is provided, validate required fields
-        var hasContactData = data && data.name && data.domain && data.company && data.title;
-        if (data && !hasContactData && (data.name || data.domain || data.company || data.title)) {
-          logError("mount", "contact data requires { name, domain, company, title }");
-          return;
-        }
-
         // Tear down any existing mount (re-mount)
         if (mountIframe) teardownMount();
 
-        mountContactData = hasContactData ? data : null;
-        mountCallbacks.onCallStarted = (data && data.onCallStarted) || null;
-        mountCallbacks.onCallEnded = (data && data.onCallEnded) || null;
-        mountCallbacks.onClose = (data && data.onClose) || null;
-        mountCallbacks.onError = (data && data.onError) || null;
+        mountCallbacks = { onCallStarted: null, onCallEnded: null, onClose: null, onError: null };
         mountContainer = container;
 
         // Listen for messages
         mountListener = handleMountMessage;
         window.addEventListener("message", mountListener);
 
-        // No contact data → full app embed at root; with contact → /embed/roleplay-call
-        var iframeEl = createIframe(hasContactData ? "/embed/roleplay-call" : "/");
+        var iframeEl = createIframe("/");
         mountIframe = iframeEl;
         container.appendChild(iframeEl);
       } catch (e) {
         logError("mount", e);
         teardownMount();
-        if (data && typeof data.onError === "function") {
-          try { data.onError({ code: "SDK_ERROR", message: e.message || "Unexpected error during mount" }); } catch (_) {}
-        }
       }
     },