@sippet-ai/operator-widget 0.0.14 → 0.0.16

package/README.md

@@ -1,15 +1,6 @@
 # Sippet AI Operator Widget
 
-A web component (with React wrappers) for embedding Sippet AI telephony controls in any app.
-It provides a floating softphone UI, SIP/WebRTC call controls, queue handling, and light helpers
-built on `@sippet-ai/sdk-js`.
-
-## What it does
-
-- Renders a floating VoIP widget with phone, queue, contacts, history, and settings tabs.
-- Connects to SIP and WebRTC (mic/speaker selection and permissions).
-- Listens to queue entries and call history.
-- Exposes a small JS API (`sippet`) to trigger calls and query queues/history.
+A web component (with React wrappers) for embedding Sippet AI operator telephony controls.
 
 ## Install
 
@@ -17,9 +8,64 @@ built on `@sippet-ai/sdk-js`.
 npm install @sippet-ai/operator-widget
 ```
 
-`@sippet-ai/sdk-js` is a dependency of the widget, so it will be installed automatically.
+## Auth flow
+
+1. Ensure your operator exists in Sippet's 'Team members' section in the settings
+2. Operator logs in to your frontend.
+3. Your frontend calls your backend (never call Sippet mint endpoint directly from browser).
+4. Your backend validates the operator session and extracts the user's email.
+5. Your backend mints the operator token using one of these methods:
+   - SDK server RPC call (recommended): `issueOperatorAccessToken` via `createServerClient` from `@sippet-ai/sdk-js/server`
+   - REST endpoint: `POST /api/operator/access`
+6. Sippet finds the operator by email in the workspace tied to that secret key and returns an access token.
+7. Your backend returns that token to frontend.
+8. Frontend passes token to widget via `access-token` or `getAccessToken`.
+
+## Minting options on your backend
+
+### Option A: SDK server RPC call (recommended)
+
+```ts
+import { createServerClient } from '@sippet-ai/sdk-js/server';
+
+const sippet = createServerClient({
+  apiKey: process.env.SIPPET_SECRET_API_KEY!,
+});
+
+const result = await sippet.issueOperatorAccessToken({
+  input: { operatorEmail: operator.email },
+});
+
+if (!result.success) {
+  throw new Error(result.errors.map(error => error.message).join(', '));
+}
+
+return result.data.token;
+```
 
-## Quick start (Web Component)
+### Option B: Raw REST endpoint
+
+```ts
+const response = await fetch('https://api.sippet.ai/api/operator/access', {
+  method: 'POST',
+  headers: {
+    'content-type': 'application/json',
+    'x-api-key': process.env.SIPPET_SECRET_API_KEY!,
+  },
+  body: JSON.stringify({ operator_email: operator.email }),
+});
+
+if (!response.ok) throw new Error('Failed to mint operator access token');
+const body = await response.json();
+return body.token;
+```
+
+## Important requirement: operator email must exist in Sippet
+
+The `operator_email` must map to an existing invited/created user in your Sippet workspace (team members).
+If the email is not present in that workspace, token minting fails.
+
+## Quick start (Web Component, token auth)
 
 ```html
 <script type="module">
@@ -27,19 +73,12 @@ npm install @sippet-ai/operator-widget
 </script>
 
 <sippetai-voip-widget
-  api-key="YOUR_PUBLISHABLE_API_KEY"
-  sip-url="sip.sippet.ai"
-  sip-user="1001"
-  sip-password="1234"
-  sip-web-socket-url="wss://sip.sippet.ai:7443"
-  user-name="Agent"
-  user-email="agent@example.com"
+  access-token="YOUR_OPERATOR_ACCESS_TOKEN"
+  api-origin="https://api.sippet.ai"
 ></sippetai-voip-widget>
 ```
 
-The widget renders a launcher button at the bottom-right of the page. Clicking it opens the panel.
-
-## React usage
+## React usage (token auth)
 
 ```tsx
 import { SippetAIVoipWidget } from '@sippet-ai/operator-widget/react';
@@ -47,89 +86,84 @@ import { SippetAIVoipWidget } from '@sippet-ai/operator-widget/react';
 export function SupportWidget() {
   return (
     <SippetAIVoipWidget
-      apiKey="YOUR_PUBLISHABLE_API_KEY"
-      sipUrl="sip.sippet.ai"
-      sipUser="1001"
-      sipPassword="1234"
-      sipWebSocketUrl="wss://sip.sippet.ai:7443"
-      userName="Agent"
-      userEmail="agent@example.com"
+      accessToken="YOUR_OPERATOR_ACCESS_TOKEN"
+      apiOrigin="https://api.sippet.ai"
     />
   );
 }
 ```
 
-## Configuration
-
-- `api-key` (attribute) / `apiKey` (property). Required for contacts, history, queue polling, and realtime events.
-- `api-origin` (attribute) / `apiOrigin` (property). Optional override for a self-hosted or local API origin.
-- `sip-url`, `sip-user`, `sip-password`, `sip-web-socket-url`. Required for SIP calling.
-- `user-name`, `user-email`. Displayed in the widget.
+## Shared SDK + widget state
 
-## Methods & events
+If your app already uses `@sippet-ai/sdk-js/client`, pass that same client object
+to the widget as a property. This keeps SIP session/call state in one place, so
+SDK actions (for example joining a call) are reflected in the widget UI.
 
-Methods are available on the DOM element instance via the `sippet` helper.
-
-```ts
-import { sippet } from '@sippet-ai/operator-widget';
-
-sippet.setApiKey('YOUR_PUBLISHABLE_API_KEY');
-sippet.setApiOrigin('https://api.sippet.ai');
-
-await sippet.call('+15551234567');
-await sippet.answer();
-await sippet.decline();
-await sippet.hold();
+```tsx
+import { SippetAIVoipWidget } from '@sippet-ai/operator-widget/react';
+import * as sdkClient from '@sippet-ai/sdk-js/client';
 
-const queue = await sippet.getQueue();
-const activeCalls = await sippet.getActiveCalls();
-const callDetails = await sippet.callDetails('CALL_UUID');
+export function SupportWidget({ isWidgetOpen }: { isWidgetOpen: boolean }) {
+  return (
+    <SippetAIVoipWidget
+      client={sdkClient}
+      openWidget={isWidgetOpen}
+      getAccessToken={async () => {
+        const response = await fetch('/api/your-backend/operator-token', {
+          method: 'POST',
+        });
+        if (!response.ok) throw new Error('Failed to mint operator token');
+        const body = await response.json();
+        return body.token;
+      }}
+      apiOrigin="https://api.sippet.ai"
+    />
+  );
+}
 ```
 
-If the widget element already has `api-key`, you can omit `sippet.setApiKey`.
+## Token rotation with backend endpoint
 
-## Realtime events
-
-```ts
-import { initSocket, joinEventsChannel } from '@sippet-ai/operator-widget';
-
-initSocket({ publishableKey: 'YOUR_PUBLISHABLE_API_KEY' });
-
-const channel = joinEventsChannel();
+```tsx
+import { SippetAIVoipWidget } from '@sippet-ai/operator-widget/react';
 
-channel.on('incoming_call', payload => {
-  console.log('incoming_call', payload);
-});
+export function SupportWidget() {
+  return (
+    <SippetAIVoipWidget
+      apiOrigin="https://api.sippet.ai"
+      getAccessToken={async () => {
+        const response = await fetch('/api/your-backend/operator-token', {
+          method: 'POST',
+        });
+        if (!response.ok) throw new Error('Failed to mint operator token');
+        const body = await response.json();
+        return body.token;
+      }}
+    />
+  );
+}
 ```
 
-Known event names:
-
-- `incoming_call`
-- `call_answered`
-- `call_ended`
-- `operator_status_change`
-- `call_queue_entry_updated`
-- `call_queue_entry_deleted`
-- `call_participant_joined`
-- `call_participant_left`
-- `call_transcript_delta`
-- `call_transcript_completed`
-
-## Permissions and runtime behavior
-
-- Microphone access is required for calling; the widget prompts for audio permissions when opened.
-- Speaker selection uses `setSinkId` when supported by the browser; some browsers require a user gesture.
-- Queue entries are refreshed on realtime socket events and when the queue tab is opened (no polling loop).
+## Configuration
 
-## Using `@sippet-ai/sdk-js/client` directly
+- `access-token` / `accessToken`: operator bearer token.
+- `getAccessToken` (property only): async token resolver.
+- `api-origin` / `apiOrigin`: API origin override.
+- `client` (property only): shared SDK client instance from `@sippet-ai/sdk-js/client`.
+- `open-widget` / `openWidget`: controls whether the panel is open.
 
-If you need RPC calls outside the widget, use the SDK client directly:
+## Helper API
 
 ```ts
-import { listCalls } from '@sippet-ai/sdk-js/client';
-
-const calls = await listCalls({
-  headers: { 'x-api-key': 'YOUR_PUBLISHABLE_API_KEY' },
-  fields: ['id', 'callUuid', 'status'],
+import { sippet } from '@sippet-ai/operator-widget';
+import * as sdkClient from '@sippet-ai/sdk-js/client';
+
+sippet.setClient(sdkClient);
+sippet.setGetAccessToken(async () => {
+  const response = await fetch('/api/your-backend/operator-token', {
+    method: 'POST',
+  });
+  const body = await response.json();
+  return body.token;
 });
 ```