@corti/embedded-web 0.1.1 → 0.3.1

package/README.md

@@ -22,7 +22,7 @@ npm install @corti/embedded-web
 ```html
 <corti-embedded
   id="corti-component"
-  base-url="https://assistant.eu.corti.app" <!-- REQUIRED -->
+  baseurl="https://assistant.eu.corti.app" <!-- REQUIRED -->
 ></corti-embedded>
 ```
 
@@ -43,22 +43,29 @@ const interaction = await myComponent.createInteraction({
   }
 });
 
-await myComponent.configureSession({"defaultTemplateKey": "soap_note"});
+await myComponent.setInteractionOptions({
+  templates: {
+    defaultTemplate: {
+      behaviour: "fallback",
+      template: { source: "standard", id: "soap_note" },
+    },
+  },
+});
 await myComponent.addFacts([{"text": "Chest pain", "group": "other"}]);
-await myComponent.navigate('/interactions/123');
+await myComponent.navigate({ path: "/interactions/123" });
 await myComponent.show()
 ```
 
 #### Generic Event Listener (Web Component)
 
-Use `embedded-event` as the canonical event stream for web component integrations.
+Use `event` as the canonical event stream for web component integrations (formerly `embedded-event`).
 
 - Event detail shape is `{ name: string; payload: unknown }`.
 - Full event catalog and payload details are documented at:
   - https://docs.corti.ai/assistant/events
 
 ```js
-myComponent.addEventListener('embedded-event', event => {
+myComponent.addEventListener("event", event => {
   const { detail } = event;
   console.log(detail.name, detail.payload);
 });
@@ -67,55 +74,62 @@ myComponent.addEventListener('embedded-event', event => {
 ### React Component
 
 ```tsx
-import React, { useRef } from 'react';
+import React, { useRef } from "react";
 import {
   CortiEmbeddedReact,
   type CortiEmbeddedReactRef,
+  type CortiEmbeddedEvent,
+  type CortiEmbeddedReadyEvent,
   useCortiEmbeddedApi,
   useCortiEmbeddedStatus,
-} from '@corti/embedded-web/react';
+} from "@corti/embedded-web/react";
 
 function App() {
   const cortiRef = useRef<CortiEmbeddedReactRef>(null);
   const api = useCortiEmbeddedApi(cortiRef);
   const { status } = useCortiEmbeddedStatus(cortiRef);
 
-  const handleReady = () => {
-    console.log('Corti component is ready!');
+  const handleReady = (event: CortiEmbeddedReadyEvent) => {
+    console.log("Corti component is ready!", event.detail);
   };
 
-  const handleEvent = (
-    event: CustomEvent<{ name: string; payload: unknown }>,
-  ) => {
-    console.log('Event name:', event.detail.name);
-    console.log('Event payload:', event.detail.payload);
+  const handleEvent = (event: CortiEmbeddedEvent) => {
+    console.log("Event name:", event.detail.name);
+    console.log("Event payload:", event.detail.payload);
   };
 
   const handleAuth = async () => {
     try {
       const user = await api.auth({
-        access_token: 'your-token',
-        token_type: 'Bearer',
+        access_token: "your-token",
+        token_type: "Bearer",
         // ... rest of the token response
       });
-      console.log('Authenticated:', user);
-
-      await api.configureSession({ defaultTemplateKey: 'soap_note' });
+      console.log("Authenticated:", user);
+
+      await api.setInteractionOptions({
+        templates: {
+          defaultTemplate: {
+            behaviour: "fallback",
+            template: { source: "standard", id: "soap_note" },
+          },
+        },
+      });
       await api.createInteraction({
         encounter: {
           identifier: `encounter-${Date.now()}`,
-          status: 'planned',
-          type: 'first_consultation',
+          status: "planned",
+          type: "first_consultation",
           period: { startedAt: new Date().toISOString() },
         },
       });
     } catch (error) {
-      console.error('Auth failed:', error);
+      console.error("Auth failed:", error);
     }
   };
 
   return (
-    <div style={{ height: '100vh' }}>
+    <div style={{ height: "100vh" }}>
       <button onClick={handleAuth}>Authenticate</button>
 
       <CortiEmbeddedReact
@@ -124,8 +138,8 @@ function App() {
         visibility="visible"
         onReady={handleReady}
         onEvent={handleEvent}
-        onError={event => console.error('Embedded error:', event.detail)}
-        style={{ width: '100%', height: '500px' }}
+        onError={event => console.error("Embedded error:", event.detail)}
+        style={{ width: "100%", height: "500px" }}
       />
 
       <pre>{JSON.stringify(status, null, 2)}</pre>
@@ -137,7 +151,7 @@ function App() {
 ### Show/Hide the Component
 
 ```javascript
-const component = document.getElementById('corti-component');
+const component = document.getElementById("corti-component");
 
 // Show the chat interface
 component.show();
@@ -154,7 +168,7 @@ component.hide();
 
 Authentication is required before using the embedded app. The payload passed to
 `component.auth(...)` should come directly from your identity provider token
-response (for example, Keycloak/OIDC token endpoint response), plus `mode`.
+response (for example, Keycloak/OIDC token endpoint response).
 
 - API details and payload shape: https://docs.corti.ai/assistant/api-reference#auth
 - End-to-end authentication guidance: https://docs.corti.ai/assistant/authentication
@@ -164,23 +178,45 @@ not supported for the embedded app.
 
 ```javascript
 const authResponse = await component.auth({
-  // Use the full token response from your IdP + mode
+  // Use the full token response from your IdP
   access_token: 'YOUR_JWT',
   token_type: 'Bearer',
   // include other token fields from your provider response (expires_in, refresh_token, etc.)
-  mode: 'stateful',
   ...
 });
 ```
 
-#### configureSession
+#### configureApp
+
+```javascript
+await component.configureApp({
+  ui: {
+    aiChat: true,
+    navigation: false,
+  },
+  appearance: {
+    primaryColor: "#000000",
+  },
+});
+```
+
+#### setInteractionOptions
 
 ```javascript
-await component.configureSession({
-  defaultLanguage: 'en',
-  defaultOutputLanguage: 'en',
-  defaultTemplateKey: 'discharge-summary',
-  defaultMode: 'virtual',
+await component.setInteractionOptions({
+  mode: {
+    fallback: "virtual",
+    options: ["in-person", "virtual"],
+  },
+  spokenLanguage: {
+    fallback: "en",
+  },
+  templates: {
+    defaultTemplate: {
+      behaviour: "fallback",
+      template: { source: "standard", id: "discharge-summary" },
+    },
+  },
 });
 ```
 
@@ -196,7 +232,7 @@ await component.addFacts([
 #### navigate
 
 ```javascript
-await component.navigate('/interactions/123');
+await component.navigate({ path: "/interactions/123" });
 ```
 
 #### createInteraction
@@ -205,14 +241,14 @@ await component.navigate('/interactions/123');
 const created = await component.createInteraction({
   assignedUserId: null,
   encounter: {
-    identifier: 'enc-123',
-    status: 'in-progress',
-    type: 'consult',
+    identifier: "enc-123",
+    status: "in-progress",
+    type: "consult",
     period: { startedAt: new Date().toISOString() },
-    title: 'Visit for cough',
+    title: "Visit for cough",
   },
   patient: {
-    identifier: 'pat-456',
+    identifier: "pat-456",
   },
 });
 ```
@@ -228,7 +264,7 @@ await component.stopRecording();
 #### getStatus (debugging)
 
 ```javascript
-console.log(component.getStatus());
+console.log(await component.getStatus());
 ```
 
 ## Architecture
@@ -245,7 +281,7 @@ The component uses a `PostMessageHandler` utility class that:
 The React component (`CortiEmbeddedReact`) is available as an additional export and provides:
 
 - **Hook-based API access**: `useCortiEmbeddedApi(ref)` exposes instance-bound methods (`auth`, `navigate`, `createInteraction`, etc.)
-- **Generic event stream**: `onEvent` receives all embedded events as `{ name, payload }`
+- **Generic event stream**: `onEvent` receives the wrapper's `event` `CustomEvent`, with `event.detail` shaped as `{ name, payload }`
 - **Status hook**: `useCortiEmbeddedStatus(ref)` keeps latest status/reactive state
 - **Multi-instance safety**: API methods are scoped to the ref you pass
 - **React Props**: Standard React props like `className`, `style`, etc.
@@ -259,15 +295,19 @@ import {
   type CortiEmbeddedReactRef,
   useCortiEmbeddedApi,
   useCortiEmbeddedStatus,
-} from '@corti/embedded-web/react';
+} from "@corti/embedded-web/react";
 ```
 
 ### Event Listener Setup
 
-- Use `onEvent` for all embedded events.
-- Event detail shape is `{ name: string; payload: unknown }`.
+- Use `onEvent` as the catch-all listener for the wrapper's generic `event` stream.
+- `onEvent` receives the raw `event` `CustomEvent`, and `event.detail` has the following shape: `{ name: string; payload: unknown }`.
+- That generic stream includes `embedded.ready` and other forwarded embedded events listed in our documentation.
+- `onReady` is a convenience listener for the raw `embedded.ready` `CustomEvent`.
+- Raw `ready`, `loaded`, and `error.triggered` are not forwarded through `onEvent`.
 - Full event catalog and payload details are documented at:
   - https://docs.corti.ai/assistant/events
+- `onEvent`, `onReady`, and `onError` pass through the raw `CustomEvent`.
 
 ```tsx
 <CortiEmbeddedReact
@@ -275,7 +315,7 @@ import {
   onEvent={event => {
     console.log(event.detail.name, event.detail.payload);
   }}
-  onReady={() => console.log('Ready')}
+  onReady={event => console.log("Ready", event.detail)}
   onError={event => console.error(event.detail)}
 />
 ```
@@ -297,9 +337,9 @@ function Example() {
   const api = useCortiEmbeddedApi(ref);
 
   const run = async () => {
-    await api.auth({ access_token: '...', token_type: 'Bearer', mode: 'stateful' });
+    await api.auth({ access_token: '...', token_type: 'Bearer' });
     const created = await api.createInteraction({ encounter: { ... } });
-    await api.navigate(`/session/${created.id}`);
+    await api.navigate({ path: `/session/${created.id}` });
   };
 
   return (
@@ -313,9 +353,11 @@ function Example() {
 
 For detailed React usage examples, see [docs/react-usage.md](./docs/react-usage.md).
 
+For configuration migration details, see [docs/migration-guide.md](./docs/migration-guide.md) and [docs/deprecation-timeline.md](./docs/deprecation-timeline.md).
+
 ## Package Structure
 
-- **Default export**: Web component only (`dist/web-bundle.js`)
+- **Default export**: Web component only (`dist/web-bundle.js`, readable non-minified bundle)
 - **React export**: Web component + React component (`@corti/embedded-web/react`)
 - **No dependencies**: Web component bundle has zero external dependencies
 - **Peer dependencies**: React components require React as peer dependency only

package/dist/CortiEmbedded.d.ts

@@ -1,18 +1,32 @@
-import type { Corti } from '@corti/sdk';
-import { LitElement, type PropertyValues } from 'lit';
-import type { ConfigureAppPayload, SetCredentialsPayload, AuthCredentials, ConfigureAppResponse, CortiEmbeddedAPI, InteractionDetails, CreateInteractionPayload, SessionConfig, User, GetStatusResponse, GetTemplatesResponse } from './types';
+import type { Corti } from "@corti/sdk";
+import { LitElement, type PropertyValues } from "lit";
+import type { ConfigureApplicationPayload, ConfigureApplicationResponse, ConfigurePayload, ConfigureResponse, CreateInteractionPayload, NavigatePayload, SetInteractionOptionsPayload, SetCredentialsPayload, CortiEmbeddedAPI, InteractionDetails, SessionConfig, User, GetStatusResponse, GetTemplatesResponse, KeycloakTokenResponse } from "./public-types.js";
+type DOMEventListener = ((event: Event) => void) | {
+    handleEvent(event: Event): void;
+};
+type DOMAddEventListenerOptions = boolean | {
+    capture?: boolean;
+    once?: boolean;
+    passive?: boolean;
+    signal?: AbortSignal;
+};
 export declare class CortiEmbedded extends LitElement implements CortiEmbeddedAPI {
     static styles: import("lit").CSSResult[];
     visibility: string;
     baseURL: string;
     private postMessageHandler;
     private normalizedBaseURL;
+    private warnedDeprecatedEventSubscriptions;
+    addEventListener(type: string, callback: DOMEventListener, options?: DOMAddEventListenerOptions): void;
+    private warnDeprecatedEventSubscription;
+    private getIframeAllowPolicy;
     connectedCallback(): void;
     disconnectedCallback(): void;
     private setupPostMessageHandler;
     private dispatchPublicEvent;
     private dispatchEmbeddedEvent;
     private dispatchErrorEvent;
+    private static warnDeprecatedAPI;
     private isRealIframeLoad;
     private handleIframeLoad;
     private getIframe;
@@ -22,7 +36,7 @@ export declare class CortiEmbedded extends LitElement implements CortiEmbeddedAP
      * @param credentials Authentication credentials
      * @returns Promise resolving to user information
      */
-    auth(credentials: AuthCredentials): Promise<User>;
+    auth(credentials: KeycloakTokenResponse): Promise<User>;
     /**
      * Create a new interaction
      * @param encounter Encounter request data
@@ -43,10 +57,10 @@ export declare class CortiEmbedded extends LitElement implements CortiEmbeddedAP
     addFacts(facts: Corti.FactsCreateInput[]): Promise<void>;
     /**
      * Navigate to a specific path within the embedded UI
-     * @param path Path to navigate to
+     * @param payload Navigation request payload or legacy path string
      * @returns Promise that resolves when navigation is complete
      */
-    navigate(path: string): Promise<void>;
+    navigate(payload: NavigatePayload | string): Promise<void>;
     /**
      * Start recording
      * @returns Promise that resolves when recording starts
@@ -67,7 +81,19 @@ export declare class CortiEmbedded extends LitElement implements CortiEmbeddedAP
      * @param config Component configuration
      * @returns Promise that resolves when configuration is applied
      */
-    configure(config: ConfigureAppPayload): Promise<ConfigureAppResponse>;
+    configureApp(config: ConfigureApplicationPayload): Promise<ConfigureApplicationResponse>;
+    /**
+     * Configure the component
+     * @param config Component configuration
+     * @returns Promise that resolves when configuration is applied
+     */
+    configure(config: ConfigurePayload): Promise<ConfigureResponse>;
+    /**
+     * Set one-shot interaction options for the embedded instance.
+     * @param config Interaction/session-level options
+     * @returns Promise that resolves when options are applied
+     */
+    setInteractionOptions(config: SetInteractionOptionsPayload): Promise<void>;
     /**
      * Set authentication credentials without triggering auth flow
      * @param credentials Authentication credentials to store
@@ -104,3 +130,4 @@ export declare class CortiEmbedded extends LitElement implements CortiEmbeddedAP
     };
     render(): import("lit-html").TemplateResult<1>;
 }
+export {};