@convokit/widget 0.0.1 → 0.0.3

package/README.md

@@ -1,6 +1,45 @@
 # @convokit/widget
 
-Beautiful AI chat widget for your website.
+Chat UI widgets for your website. The public API is intentionally small — **four drop‑in components**:
+
+| Component | Layout | Integration | You provide |
+|-----------|--------|--------------|-------------|
+| **PopupWidget** | Bubble (corner) | ConvoKit | `apiKey` (public ConvoKit key) |
+| **FullScreenWidget** | Full page | ConvoKit | `apiKey`, optional `onBack` |
+| **PopupBackendWidget** | Bubble | Your backend | `apiUrl`, `apiKey`, optional `authToken` |
+| **FullScreenBackendWidget** | Full page | Your backend | `apiUrl`, `apiKey`, optional `authToken`, `onBack` |
+
+All lower‑level/internal components (`PopupKey`, `FullScreenKey`, `PopupBackend`, `PopupControlled`, etc.) are **not exported** from the package anymore. The four widgets above are what you use in apps.
+
+---
+
+## What to call and how
+
+Use **one import** and **one component** per screen. All of these are from `@convokit/widget`. No separate CSS import needed (styles are in the bundle).
+
+| What to call | How (minimal) |
+|--------------|----------------|
+| **PopupWidget** | `<PopupWidget apiKey={key} />` — popup bubble, ConvoKit key. |
+| **FullScreenWidget** | `<FullScreenWidget apiKey={key} onBack={() => router.back()} />` — full-page chat, ConvoKit key. |
+| **PopupBackendWidget** | `<PopupBackendWidget apiUrl="/api/chat" apiKey={myKey} />` — popup, your backend. |
+| **FullScreenBackendWidget** | `<FullScreenBackendWidget apiUrl="/api/chat" apiKey={myKey} onBack={() => router.back()} />` — full-page, your backend. |
+
+**Optional props (all wrappers):** `title`, `welcomeMessage`, `widgetId`, `primaryColor`. Popup ones also accept `position`. Backend ones accept `authToken`. Full-screen ones accept `backLabel`. PopupWidget / FullScreenWidget also accept `persistMessages`.
+
+**If you need full control** (your own state/API), use the low-level components with a config object:
+
+| What to call | How |
+|--------------|-----|
+| **PopupKey** | `<PopupKey config={keyConfig} />` — config: `KeyConfig` (e.g. `{ key, title, position }`). |
+| **FullScreenKey** | `<FullScreenKey config={keyConfig} onBack={fn} backLabel="Back" />` |
+| **PopupBackend** | `<PopupBackend config={backendConfig} />` — config: `BackendConfig` (e.g. `{ apiUrl, apiKey }`). |
+| **FullScreenBackend** | `<FullScreenBackend config={backendConfig} onBack={fn} backLabel="Back" />` |
+| **PopupControlled** | `<PopupControlled config={controlledConfig} />` — you pass `messages`, `onMessagesUpdate`, `onSend`. |
+| **FullScreenControlled** | `<FullScreenControlled config={controlledConfig} onBack={fn} backLabel="Back" />` |
+
+**Types you can import:** `KeyConfig`, `BackendConfig`, `ControlledConfig`, `PopupWidgetProps`, `FullScreenWidgetProps`, `PopupBackendWidgetProps`, `FullScreenBackendWidgetProps`, `ChatMessage`, `ChatHistoryItem`, `ChatResponse`, `ThemeOptions`.
+
+---
 
 ## Installation
 
@@ -12,52 +51,207 @@ yarn add @convokit/widget
 pnpm add @convokit/widget
 ```
 
-## Usage
+---
+
+## Quick start (React / Vite)
+
+Add the chat bubble with one import. Styles are included in the bundle.
+
+```tsx
+// Any React entry (e.g. App.tsx)
+import { PopupWidget } from '@convokit/widget';
+
+export function App() {
+  return (
+    <div>
+      {/* Your app UI */}
+      <PopupWidget apiKey={import.meta.env.VITE_CONVOKIT_KEY ?? ''} />
+    </div>
+  );
+}
+```
+
+- **React (CRA / Vite / plain SPA)**: just import and render the widget anywhere in your tree.
+- Optional props (all wrappers): `title`, `welcomeMessage`, `widgetId`, `primaryColor`.
+- Popup widgets also accept `position`, `persistMessages`. Backend widgets accept `authToken`. Full‑screen widgets accept `onBack` and `backLabel`.
+
+If the required props are missing (`apiKey` for key‑based widgets, or `apiUrl`/`apiKey` for backend widgets), the widget renders nothing.
+
+### Next.js only: one import, no wrapper (recommended)
+
+If you use **Next.js App Router**, use the Next-specific entry so you don’t write `dynamic()` or a wrapper yourself:
+
+```tsx
+// app/layout.tsx (or any page)
+import { PopupWidgetNext } from '@convokit/widget/next';
+
+export default function Layout({ children }) {
+  return (
+    <html><body>
+      {children}
+      <PopupWidgetNext />
+    </body></html>
+  );
+}
+```
+
+- **`PopupWidgetNext`** uses `next/dynamic` with `ssr: false` and reads `process.env.NEXT_PUBLIC_CONVOKIT_KEY` if you don’t pass `apiKey`.
+- Optional: pass `apiKey`, `title`, `welcomeMessage`, `position`, etc. as props.
+- You still need **transpilePackages** (and optionally resolve alias for react) in `next.config.js` if you see duplicate-React errors; see “Next.js App Router (avoid duplicate React)” below.
+
+### Next.js App Router (avoid duplicate React)
 
-### React
+The widget is client-only (hooks, DOM). In Next.js you must use **one React instance** in the browser. If the widget resolves to a different copy of React than your app, you get errors like `Cannot read properties of undefined (reading 'ReactCurrentDispatcher')`.
+
+**Fix 1 — Load the widget only on the client (recommended):** use `next/dynamic` with `ssr: false` so the widget never runs on the server and always uses the client React.
 
 ```tsx
-import { ChatWidget } from '@convokit/widget';
+// app/layout.tsx or a client component
+'use client';
+
+import dynamic from 'next/dynamic';
 
-function App() {
+const PopupWidget = dynamic(
+  () => import('@convokit/widget').then((mod) => mod.PopupWidget),
+  { ssr: false }
+);
+
+export default function Layout({ children }) {
   return (
-    <ChatWidget
-      config={{
-        widgetId: 'your-widget-id',
-        apiUrl: 'https://api.convokit.dev',
-        primaryColor: '#000000',
-        title: 'Chat with us',
-        welcomeMessage: 'Hello! How can I help you?',
-        placeholder: 'Type a message...',
+    <>
+      {children}
+      <PopupWidget apiKey={process.env.NEXT_PUBLIC_CONVOKIT_KEY ?? ''} />
+    </>
+  );
+}
+```
+
+**Fix 2 — Use the app’s React for the widget:** in `next.config.js`, add `transpilePackages` and (if needed with pnpm) resolve `react` / `react-dom` to a single copy so the widget is bundled with your app’s React.
+
+```js
+// next.config.js
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  transpilePackages: ['@convokit/widget'],
+  webpack: (config) => {
+    config.resolve.alias = {
+      ...config.resolve.alias,
+      react: require.resolve('react'),
+      'react-dom': require.resolve('react-dom'),
+    };
+    return config;
+  },
+};
+module.exports = nextConfig;
+```
+
+Use **Fix 1** for a quick fix; use **Fix 1 + Fix 2** if you still see duplicate-React issues (e.g. with pnpm).
+
+### Other drop-in wrappers (all four)
+
+| Wrapper | Use case | Required props |
+|---------|----------|-----------------|
+| **PopupWidget** | Popup with ConvoKit key | `apiKey` |
+| **FullScreenWidget** | Full-page chat with ConvoKit key | `apiKey`, `onBack` (e.g. `() => router.back()`) |
+| **PopupBackendWidget** | Popup talking to your backend | `apiUrl`, `apiKey` |
+| **FullScreenBackendWidget** | Full-page chat talking to your backend | `apiUrl`, `apiKey`, `onBack` |
+
+#### React / Vite examples
+
+```tsx
+// Full-screen (Key mode)
+import { FullScreenWidget } from '@convokit/widget';
+
+export function ChatPage() {
+  const apiKey = import.meta.env.VITE_CONVOKIT_KEY ?? '';
+  return (
+    <FullScreenWidget
+      apiKey={apiKey}
+      onBack={() => {
+        // e.g. navigate(-1) with react-router
+      }}
+    />
+  );
+}
+
+// Popup (your backend)
+import { PopupBackendWidget } from '@convokit/widget';
+
+export function App() {
+  return (
+    <>
+      {/* your UI */}
+      <PopupBackendWidget apiUrl="/api/chat" apiKey={import.meta.env.VITE_BACKEND_KEY ?? ''} />
+    </>
+  );
+}
+
+// Full-screen (your backend)
+import { FullScreenBackendWidget } from '@convokit/widget';
+
+export function Support() {
+  return (
+    <FullScreenBackendWidget
+      apiUrl="/api/chat"
+      apiKey={import.meta.env.VITE_BACKEND_KEY ?? ''}
+      onBack={() => {
+        // go back / close
       }}
     />
   );
 }
 ```
 
-### Vanilla JavaScript
+#### Next.js (App Router) examples
+
+```tsx
+'use client';
+
+import dynamic from 'next/dynamic';
 
-```html
-<script src="https://unpkg.com/@convokit/widget"></script>
-<script>
-  ConvoKit.init({
-    widgetId: 'your-widget-id',
-    apiUrl: 'https://api.convokit.dev',
-  });
-</script>
+// Popup with ConvoKit key
+const PopupWidget = dynamic(
+  () => import('@convokit/widget').then((m) => m.PopupWidget),
+  { ssr: false }
+);
+
+// Full-screen (Key mode)
+const FullScreenWidget = dynamic(
+  () => import('@convokit/widget').then((m) => m.FullScreenWidget),
+  { ssr: false }
+);
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  const apiKey = process.env.NEXT_PUBLIC_CONVOKIT_KEY ?? '';
+  return (
+    <html>
+      <body>
+        {children}
+        <PopupWidget apiKey={apiKey} />
+      </body>
+    </html>
+  );
+}
+
+// Full-screen page (Key mode)
+export function FullScreenChatPage() {
+  const apiKey = process.env.NEXT_PUBLIC_CONVOKIT_KEY ?? '';
+  const router = useRouter();
+  return (
+    <FullScreenWidget apiKey={apiKey} onBack={() => router.back()} />
+  );
+}
 ```
 
-## Configuration
+---
+
+---
 
-| Option | Type | Required | Default | Description |
-|--------|------|----------|---------|-------------|
-| `widgetId` | string | Yes | - | Your widget ID from ConvoKit dashboard |
-| `apiUrl` | string | Yes | - | API endpoint URL |
-| `primaryColor` | string | No | `#000000` | Primary theme color |
-| `title` | string | No | `Chat` | Widget header title |
-| `welcomeMessage` | string | No | `Hello! How can I help you?` | Initial greeting message |
-| `placeholder` | string | No | `Type a message...` | Input placeholder text |
-| `position` | string | No | `bottom-right` | Widget position on screen |
+## Advanced configuration
+
+Internally, the widgets are built on config types (**KeyConfig**, **BackendConfig**, **ControlledConfig**, **ThemeOptions**). If you need to dive deeper into those (for example, to match server behavior or migrate from the old low‑level API), see `WIDGET_CONFIG_REFERENCE.md` in this repo.
+
+---
 
 ## Development
 
@@ -77,16 +271,6 @@ npm run build
 pnpm build
 ```
 
-## Features
-
-- 🎨 Customizable colors and branding
-- 📱 Mobile responsive
-- ⚡ Lightweight and fast
-- 🎯 TypeScript support
-- 🔌 Easy integration
-- 💬 Real-time chat
-- 🤖 AI-powered responses
-
 ## License
 
 MIT

package/dist/DemoErrorBoundary.d.ts

@@ -0,0 +1,17 @@
+import { default as React, Component, ErrorInfo, ReactNode } from 'react';
+
+export declare class DemoErrorBoundary extends Component<{
+    children: ReactNode;
+}, {
+    error: Error | null;
+}> {
+    state: {
+        error: Error | null;
+    };
+    static getDerivedStateFromError(error: Error): {
+        error: Error;
+    };
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    render(): string | number | boolean | import("react/jsx-runtime").JSX.Element | Iterable<React.ReactNode> | null | undefined;
+}
+//# sourceMappingURL=DemoErrorBoundary.d.ts.map

package/dist/DemoErrorBoundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DemoErrorBoundary.d.ts","sourceRoot":"","sources":["../src/DemoErrorBoundary.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAE/D,qBAAa,iBAAkB,SAAQ,SAAS,CAAC;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,EAAE;IAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CAAE,CAAC;IAChG,KAAK;eAAoB,KAAK,GAAG,IAAI;MAAG;IAExC,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,KAAK;;;IAI5C,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS;IAIpD,MAAM;CAcP"}

package/dist/FullScreenBackendWidget.d.ts

@@ -0,0 +1,36 @@
+import { default as React } from 'react';
+
+/**
+ * Minimal props for the full-screen widget that talks to your backend. No ConvoKit key in the browser.
+ */
+export interface FullScreenBackendWidgetProps {
+    /** Your backend chat endpoint URL (e.g. /api/chat). Required. */
+    apiUrl: string;
+    /** Your API key sent to your backend (e.g. X-API-Key header). Required. */
+    apiKey: string;
+    /** Called when user taps back (e.g. router.back()). */
+    onBack?: () => void;
+    /** Label for the back button. Default: 'Back'. */
+    backLabel?: string;
+    /** Optional auth token sent as Authorization: Bearer to your backend. */
+    authToken?: string;
+    /** Unique id for this instance. Default: 'convokit-widget'. */
+    widgetId?: string;
+    /** Header title. Default: 'Chat'. */
+    title?: string;
+    /** First message shown when chat opens. Default: 'How can I help you today?'. */
+    welcomeMessage?: string;
+    /** Primary color (e.g. '#7c3aed'). */
+    primaryColor?: string;
+}
+/**
+ * Drop-in full-screen chat widget (Backend mode). Widget talks to your API; you use convokit-server on the server.
+ * Use in a client component (e.g. add 'use client' in Next.js).
+ *
+ * @example
+ * import { FullScreenBackendWidget } from '@convokit/widget';
+ *
+ * <FullScreenBackendWidget apiUrl="/api/chat" apiKey={process.env.NEXT_PUBLIC_MY_API_KEY} onBack={() => router.back()} />
+ */
+export declare const FullScreenBackendWidget: React.FC<FullScreenBackendWidgetProps>;
+//# sourceMappingURL=FullScreenBackendWidget.d.ts.map

package/dist/FullScreenBackendWidget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FullScreenBackendWidget.d.ts","sourceRoot":"","sources":["../src/FullScreenBackendWidget.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAOD;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,EAAE,KAAK,CAAC,EAAE,CAAC,4BAA4B,CAsB1E,CAAC"}

package/dist/FullScreenWidget.d.ts

@@ -0,0 +1,34 @@
+import { default as React } from 'react';
+
+/**
+ * Minimal props for the full-screen key widget. Pass your public API key; everything else is optional.
+ */
+export interface FullScreenWidgetProps {
+    /** ConvoKit public API key (pk_live_... or pk_test_...). From ConvoKit dashboard. Required. */
+    apiKey: string;
+    /** Called when user taps back (e.g. router.back()). */
+    onBack?: () => void;
+    /** Label for the back button. Default: 'Back'. */
+    backLabel?: string;
+    /** Unique id for this instance. Default: 'convokit-widget'. */
+    widgetId?: string;
+    /** Header title. Default: 'Support'. */
+    title?: string;
+    /** First message shown when chat opens. Default: 'Hi! How can we help?'. */
+    welcomeMessage?: string;
+    /** Restore messages on reload. Default: false. */
+    persistMessages?: boolean;
+    /** Primary color (e.g. '#7c3aed'). */
+    primaryColor?: string;
+}
+/**
+ * Drop-in full-screen chat widget (Key mode). One component, minimal props.
+ * Use in a client component (e.g. add 'use client' in Next.js).
+ *
+ * @example
+ * import { FullScreenWidget } from '@convokit/widget';
+ *
+ * <FullScreenWidget apiKey={process.env.NEXT_PUBLIC_CONVOKIT_KEY} onBack={() => router.back()} />
+ */
+export declare const FullScreenWidget: React.FC<FullScreenWidgetProps>;
+//# sourceMappingURL=FullScreenWidget.d.ts.map

package/dist/FullScreenWidget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FullScreenWidget.d.ts","sourceRoot":"","sources":["../src/FullScreenWidget.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,+FAA+F;IAC/F,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAOD;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAqB5D,CAAC"}

package/dist/PopupBackendWidget.d.ts

@@ -0,0 +1,35 @@
+import { default as React } from 'react';
+import { BackendConfig } from './types';
+
+/**
+ * Minimal props for the popup widget that talks to your backend. No ConvoKit key in the browser.
+ */
+export interface PopupBackendWidgetProps {
+    /** Your backend chat endpoint URL (e.g. /api/chat). Required. */
+    apiUrl: string;
+    /** Your API key sent to your backend (e.g. X-API-Key header). Required. */
+    apiKey: string;
+    /** Optional auth token sent as Authorization: Bearer to your backend. */
+    authToken?: string;
+    /** Unique id for this instance. Default: 'convokit-widget'. */
+    widgetId?: string;
+    /** Header title. Default: 'Chat'. */
+    title?: string;
+    /** First message shown when chat opens. Default: 'How can I help you today?'. */
+    welcomeMessage?: string;
+    /** Position of the bubble. Default: 'bottom-right'. */
+    position?: BackendConfig['position'];
+    /** Primary color (e.g. '#7c3aed'). */
+    primaryColor?: string;
+}
+/**
+ * Drop-in popup chat widget (Backend mode). Widget talks to your API; you use convokit-server on the server.
+ * Use in a client component (e.g. add 'use client' in Next.js).
+ *
+ * @example
+ * import { PopupBackendWidget } from '@convokit/widget';
+ *
+ * <PopupBackendWidget apiUrl="/api/chat" apiKey={process.env.NEXT_PUBLIC_MY_API_KEY} />
+ */
+export declare const PopupBackendWidget: React.FC<PopupBackendWidgetProps>;
+//# sourceMappingURL=PopupBackendWidget.d.ts.map

package/dist/PopupBackendWidget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PopupBackendWidget.d.ts","sourceRoot":"","sources":["../src/PopupBackendWidget.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IACrC,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAQD;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,EAAE,KAAK,CAAC,EAAE,CAAC,uBAAuB,CAiBhE,CAAC"}