@corti/embedded-web 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Henrik Cullen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,273 @@
+# Corti Embedded Web Component
+
+A web component and React component library that provides an embedded interface for Corti AI assistant.
+
+## Features
+
+- **Web Component & React**: Available as both a native web component and React component
+- **Show/Hide**: Control the visibility of the chat interface
+- **Authentication Support**: Built-in authentication message handling
+- **TypeScript Support**: Full TypeScript definitions included
+
+## Installation
+
+```bash
+npm install @corti/embedded-web
+```
+
+The package provides a web component by default. For React usage, also install React as a peer dependency:
+
+```bash
+npm install react @types/react
+```
+
+## Usage
+
+### Web Component
+
+```html
+<corti-embedded
+  id="corti-component"
+  base-url="https://assistant.eu.corti.app" <!-- REQUIRED -->
+></corti-embedded>
+```
+
+```js
+const myComponent = document.getElementById('corti-component');
+
+const userResponse = await myComponent.auth({...});
+
+const interaction = await myComponent.createInteraction({
+  "assignedUserId": null,
+  "encounter": {
+    "identifier": `encounter-${Date.now()}`,
+    "status": "planned",
+    "type": "first_consultation",
+    "period": {
+      "startedAt": "2025-11-11T16:14:59.923Z"
+    }
+  }
+});
+
+await myComponent.configureSession({"defaultTemplateKey": "soap_note"});
+await myComponent.addFacts([{"text": "Chest pain", "group": "other"}]);
+await myComponent.navigate('/interactions/123');
+await myComponent.show()
+```
+
+### React Component
+
+```tsx
+import React, { useRef } from 'react';
+import {
+  CortiEmbeddedReact,
+  type CortiEmbeddedReactRef,
+  type EmbeddedEventData,
+} from '@corti/embedded-web/react';
+
+function App() {
+  const cortiRef = useRef<CortiEmbeddedReactRef>(null);
+
+  const handleReady = () => {
+    console.log('Corti component is ready!');
+    cortiRef.current?.show();
+  };
+
+  const handleAuthChanged = (
+    event: CustomEvent<EmbeddedEventData['auth-changed']>,
+  ) => {
+    console.log('User authenticated:', event.detail.user);
+  };
+
+  const handleAuth = async () => {
+    if (!cortiRef.current) return;
+
+    try {
+      const user = await cortiRef.current.auth({
+        access_token: 'your-token',
+        token_type: 'Bearer',
+        // ... rest of the token response
+      });
+      console.log('Authenticated:', user);
+    } catch (error) {
+      console.error('Auth failed:', error);
+    }
+  };
+
+  return (
+    <div style={{ height: '100vh' }}>
+      <button onClick={handleAuth}>Authenticate</button>
+
+      <CortiEmbeddedReact
+        ref={cortiRef}
+        baseURL="https://assistant.eu.corti.app" // REQUIRED
+        visibility="visible"
+        onReady={handleReady}
+        style={{ width: '100%', height: '500px' }}
+        // or use className
+        className="w-full h-full"
+      />
+    </div>
+  );
+}
+```
+
+### Show/Hide the Component
+
+```javascript
+const component = document.getElementById('corti-component');
+
+// Show the chat interface
+component.show();
+
+// Hide the chat interface
+component.hide();
+```
+
+### API methods (recommended)
+
+- Use these named helpers for common tasks. They provide clearer intent and sensible defaults.
+
+#### auth
+
+```javascript
+const authResponse = await component.auth({
+  // Example: Keycloak-style token + mode
+  access_token: 'YOUR_JWT',
+  token_type: 'Bearer',
+  mode: 'stateful',
+  ...
+});
+```
+
+#### configureSession
+
+```javascript
+await component.configureSession({
+  defaultLanguage: 'en',
+  defaultOutputLanguage: 'en',
+  defaultTemplateKey: 'discharge-summary',
+  defaultMode: 'virtual',
+});
+```
+
+#### addFacts
+
+```javascript
+await component.addFacts([
+    { text: 'Patient reports chest pain', group: 'subjective' },
+    { text: 'BP 120/80', group: 'vitals' },
+  ],
+```
+
+#### navigate
+
+```javascript
+await component.navigate('/interactions/123');
+```
+
+#### createInteraction
+
+```javascript
+const created = await component.createInteraction({
+  assignedUserId: null,
+  encounter: {
+    identifier: 'enc-123',
+    status: 'in-progress',
+    type: 'consult',
+    period: { startedAt: new Date().toISOString() },
+    title: 'Visit for cough',
+  },
+  patient: {
+    identifier: 'pat-456',
+  },
+});
+```
+
+#### startRecording / stopRecording
+
+```javascript
+await component.startRecording();
+// ... later
+await component.stopRecording();
+```
+
+#### getStatus (debugging)
+
+```javascript
+console.log(component.getStatus());
+```
+
+## Architecture
+
+The component uses a `PostMessageHandler` utility class that:
+
+- Manages message listeners and cleanup
+- Tracks pending requests with unique IDs
+- Handles response correlation
+- Ensures proper cleanup on component destruction
+
+## React Component Features
+
+The React component (`CortiEmbeddedReact`) is available as an additional export and provides:
+
+- **All Web Component APIs**: Full access to all methods via ref
+- **React Event Handlers**: Native React event handling with proper typing
+- **TypeScript Support**: Complete type definitions
+- **Forward Ref**: Access to the underlying component instance
+- **React Props**: Standard React props like `className`, `style`, etc.
+
+### React Component Import
+
+```tsx
+import {
+  CortiEmbeddedReact,
+  CortiEmbedded, // Web component also available
+  type CortiEmbeddedReactProps,
+  type CortiEmbeddedReactRef,
+} from '@corti/embedded-web/react';
+```
+
+### Available Events (React)
+
+- `onReady`: Component is ready to receive API calls
+- `onAuthChanged`: User authentication status changed
+- `onInteractionCreated`: New interaction was created
+- `onRecordingStarted` / `onRecordingStopped`: Recording status changes
+- `onDocumentGenerated` / `onDocumentUpdated`: Document events
+- `onNavigationChanged`: Navigation within the embedded UI changed
+- `onUsage`: Usage data (credits used)
+- `onError`: An error occurred
+
+### Event Data Access
+
+Events in React carry data in the `detail` property:
+
+```tsx
+import type {
+  EmbeddedEventData,
+  CortiEmbeddedReactProps,
+} from '@corti/embedded-web/react';
+
+// Method 1: Use typed event handler interface
+const handleAuthChanged: CortiEmbeddedReactProps['onAuthChanged'] = event => {
+  console.log('User:', event.detail.user);
+};
+
+// Method 2: Cast events manually
+const handleDocumentGenerated = (event: Event) => {
+  const customEvent = event as CustomEvent<
+    EmbeddedEventData['document-generated']
+  >;
+  console.log('Document:', customEvent.detail.document);
+};
+```
+
+For detailed React usage examples, see [docs/react-usage.md](./docs/react-usage.md).
+
+## Package Structure
+
+- **Default export**: Web component only (`dist/web-bundle.js`)
+- **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

@@ -0,0 +1,102 @@
+import type { Corti } from '@corti/sdk';
+import { LitElement, type PropertyValues } from 'lit';
+import type { ConfigureAppPayload, SetCredentialsPayload } from './internal-types.js';
+import type { AuthCredentials, ComponentStatus, ConfigureAppResponsePayload, CortiEmbeddedAPI, InteractionDetails, InteractionPayload, SessionConfig, User } from './public-types.js';
+export declare class CortiEmbedded extends LitElement implements CortiEmbeddedAPI {
+    static styles: import("lit").CSSResult[];
+    visibility: string;
+    baseURL: string;
+    private postMessageHandler;
+    private normalizedBaseURL;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private setupPostMessageHandler;
+    private dispatchPublicEvent;
+    private dispatchErrorEvent;
+    private isRealIframeLoad;
+    private handleIframeLoad;
+    private getIframe;
+    protected updated(changedProps: PropertyValues): void;
+    /**
+     * Authenticate with the Corti system
+     * @param credentials Authentication credentials
+     * @returns Promise resolving to user information
+     */
+    auth(credentials: AuthCredentials): Promise<User>;
+    /**
+     * Create a new interaction
+     * @param encounter Encounter request data
+     * @returns Promise resolving to interaction details
+     */
+    createInteraction(encounter: InteractionPayload): Promise<InteractionDetails>;
+    /**
+     * Configure the current session
+     * @param config Session configuration
+     * @returns Promise that resolves when configuration is complete
+     */
+    configureSession(config: SessionConfig): Promise<void>;
+    /**
+     * Add facts to the current session
+     * @param facts Array of facts to add
+     * @returns Promise that resolves when facts are added
+     */
+    addFacts(facts: Corti.FactsCreateInput[]): Promise<void>;
+    /**
+     * Navigate to a specific path within the embedded UI
+     * @param path Path to navigate to
+     * @returns Promise that resolves when navigation is complete
+     */
+    navigate(path: string): Promise<void>;
+    /**
+     * Start recording
+     * @returns Promise that resolves when recording starts
+     */
+    startRecording(): Promise<void>;
+    /**
+     * Stop recording
+     * @returns Promise that resolves when recording stops
+     */
+    stopRecording(): Promise<void>;
+    /**
+     * Get current component status
+     * @returns Promise resolving to current status
+     */
+    getStatus(): Promise<ComponentStatus>;
+    /**
+     * Configure the component
+     * @param config Component configuration
+     * @returns Promise that resolves when configuration is applied
+     */
+    configure(config: ConfigureAppPayload): Promise<ConfigureAppResponsePayload>;
+    /**
+     * Set authentication credentials without triggering auth flow
+     * @param credentials Authentication credentials to store
+     * @returns Promise that resolves when credentials are set
+     */
+    setCredentials(credentials: SetCredentialsPayload): Promise<void>;
+    /**
+     * Show the embedded UI
+     */
+    show(): void;
+    /**
+     * Hide the embedded UI
+     */
+    hide(): void;
+    /**
+     * Check the current status of the iframe and PostMessageHandler
+     * Useful for debugging
+     * @deprecated Use getStatus() instead
+     */
+    getDebugStatus(): {
+        ready: boolean;
+        iframeExists: boolean;
+        iframeSrc: string | undefined;
+        iframeContentWindow: boolean;
+        iframeContentDocument: boolean;
+        iframeReadyState: DocumentReadyState | undefined;
+        postMessageHandlerExists: boolean;
+        postMessageHandlerReady: boolean;
+        baseURL: string;
+    };
+    render(): import("lit-html").TemplateResult<1>;
+}