tchao 0.1.2 → 1.0.0

package/README.md

@@ -4,8 +4,6 @@ JavaScript SDK for integrating the Tchao chat widget into your application.
 
 ## Installation
 
-### Option 1: npm package
-
 ```bash
 npm install tchao
 # or
@@ -14,146 +12,191 @@ pnpm add tchao
 yarn add tchao
 ```
 
-### Option 2: Script tag
+## Quick Start
 
-```html
-<script src="https://tchao.app/widget.js" data-website-id="your-website-id"></script>
+### React (Recommended)
+
+```tsx
+import { useTchao } from "tchao/react";
+
+function App() {
+  const { isReady, open, identify } = useTchao({
+    websiteId: "your-website-id",
+  });
+
+  // Identify user when ready
+  useEffect(() => {
+    if (isReady && user) {
+      identify({ email: user.email, name: user.name });
+    }
+  }, [isReady, user, identify]);
+
+  return <button onClick={() => open()}>Chat with us</button>;
+}
 ```
 
-## Usage
+### React Provider (Simpler)
+
+```tsx
+import { TchaoProvider } from "tchao/react";
+
+function Layout({ children }) {
+  return (
+    <>
+      <TchaoProvider
+        websiteId="your-website-id"
+        visitor={{ email: user?.email, name: user?.name }}
+      />
+      {children}
+    </>
+  );
+}
+```
 
-### npm package
+### Vanilla JavaScript
 
 ```typescript
-import { Tchao } from 'tchao';
+import { tchao } from "tchao";
 
-// Initialize the widget
-const widget = await Tchao.init({
-  websiteId: 'your-website-id'
-});
+// Initialize (call once)
+await tchao.init({ websiteId: "your-website-id" });
 
-// Open the chat window
-widget.open();
+// All methods are safe - no try/catch needed
+tchao.identify({ email: "user@example.com" });
+tchao.open();
 ```
 
-### Script tag (global object)
+### Script Tag
 
 ```html
-<script src="https://tchao.app/widget.js" data-website-id="your-website-id"></script>
+<script
+  src="https://tchao.app/widget.js"
+  data-website-id="your-website-id"
+></script>
 <script>
-  // Widget auto-initializes, access via global object
-  window.Tchao.open();
-
-  // Listen for events
-  window.Tchao.on('ready', () => {
-    console.log('Widget ready!');
-  });
+  // Widget auto-initializes
+  window.Tchao.identify({ email: "user@example.com" });
 </script>
 ```
 
 ## API Reference
 
-### `Tchao.init(config)` (npm only)
-
-Initialize the Tchao widget programmatically.
-
-```typescript
-const widget = await Tchao.init({
-  websiteId: 'your-website-id', // Required
-  host: 'https://tchao.app'     // Optional, for self-hosted instances
-});
+### React Hook: `useTchao(config)`
+
+```tsx
+import { useTchao } from "tchao/react";
+
+const {
+  isReady,   // boolean - widget is initialized
+  isLoading, // boolean - widget is loading
+  error,     // Error | null - initialization error
+  show,      // () => void
+  hide,      // () => void
+  toggle,    // () => void
+  open,      // (message?: string) => void
+  identify,  // (info: VisitorInfo) => void
+  config,    // () => Partial<WidgetConfig>
+  on,        // (event, callback) => void
+  off,       // (event, callback) => void
+} = useTchao({ websiteId: "..." });
 ```
 
-Returns a `Promise<TchaoInstance>`.
-
-### Instance Methods
+### Safe API: `tchao`
 
-#### `widget.show()`
-Show the widget launcher button.
-
-#### `widget.hide()`
-Hide the widget launcher button.
-
-#### `widget.toggle()`
-Toggle the chat window open/closed.
-
-#### `widget.open()`
-Open the chat window.
-
-#### `widget.identify(info)`
-Identify the visitor with their information.
+All methods are safe to call at any time - they will queue and execute when ready.
 
 ```typescript
-widget.identify({
-  email: 'user@example.com',
-  name: 'John Doe',
-  avatar: 'https://example.com/avatar.jpg',
-  metadata: {
-    plan: 'pro',
-    userId: '12345'
-  }
+import { tchao } from "tchao";
+
+// Initialize
+await tchao.init({ websiteId: "your-website-id" });
+
+// Control methods (safe before/after init)
+tchao.show();
+tchao.hide();
+tchao.toggle();
+tchao.open();
+tchao.open("I need help with...");
+
+// Identify visitor
+tchao.identify({
+  email: "user@example.com",
+  name: "John Doe",
+  avatar: "https://example.com/avatar.jpg",
+  metadata: { plan: "pro", userId: "123" },
 });
-```
 
-#### `widget.config(options)`
-Update widget configuration.
+// Events
+tchao.on("message", (msg) => console.log(msg));
+tchao.on("open", () => console.log("Opened"));
+tchao.on("close", () => console.log("Closed"));
+tchao.on("ready", () => console.log("Ready"));
 
-```typescript
-widget.config({
-  position: 'bottom-left',  // 'bottom-right' | 'bottom-left'
-  primaryColor: '#6366f1',
-  themeMode: 'dark'         // 'light' | 'dark' | 'system'
-});
+// Cleanup
+tchao.destroy();
+
+// Status
+tchao.isReady(); // boolean
 ```
 
-#### `widget.on(event, callback)`
-Subscribe to widget events.
+### Init Config
 
 ```typescript
-widget.on('message', (message) => {
-  console.log('New message:', message.content);
-});
-
-widget.on('open', () => {
-  console.log('Chat opened');
-});
-
-widget.on('close', () => {
-  console.log('Chat closed');
-});
-
-widget.on('ready', () => {
-  console.log('Widget ready');
+tchao.init({
+  websiteId: "required",
+  host: "https://tchao.app",        // optional, for self-hosted
+  position: "bottom-right",          // "bottom-right" | "bottom-left"
+  primaryColor: "#6366f1",
+  themeMode: "system",               // "light" | "dark" | "system"
+  widgetStyle: "bubble",             // "bubble" | "name_line" | "question_cta"
+  agentName: "Support",
+  agentRole: "Customer Support",
+  agentImage: "https://...",
+  agentWelcomeMessage: "Hi! How can I help?",
+  hidePoweredBy: false,
 });
 ```
 
-#### `widget.off(event, callback)`
-Unsubscribe from widget events.
+### Events
 
-```typescript
-const handleMessage = (message) => console.log(message);
-widget.on('message', handleMessage);
-widget.off('message', handleMessage);
-```
+| Event | Callback | Description |
+|-------|----------|-------------|
+| `message` | `(message: Message) => void` | New message received |
+| `open` | `() => void` | Chat window opened |
+| `close` | `() => void` | Chat window closed |
+| `ready` | `() => void` | Widget initialized |
 
-#### `widget.destroy()` (npm only)
-Clean up and remove the widget from the page.
+### TypeScript
 
 ```typescript
-widget.destroy();
+import type {
+  TchaoConfig,
+  TchaoInstance,
+  VisitorInfo,
+  Message,
+  WidgetConfig,
+  TchaoEvent,
+  TchaoEventMap,
+} from "tchao";
+
+// React types
+import type { UseTchaoOptions, UseTchaoReturn } from "tchao/react";
 ```
 
-## TypeScript
+## Migration from v0.1.3
 
-Full TypeScript support is included. Import types as needed:
+The API is backward compatible. New additions:
 
 ```typescript
-import type {
-  TchaoConfig,
-  TchaoInstance,
-  VisitorInfo,
-  Message
-} from 'tchao';
+// New: Safe API (no try/catch needed)
+import { tchao } from "tchao";
+tchao.identify({ email: "..." }); // Works before init!
+
+// New: React hook
+import { useTchao } from "tchao/react";
+
+// New: React provider
+import { TchaoProvider } from "tchao/react";
 ```
 
 ## License

package/dist/npm.d.mts

@@ -1,97 +1,134 @@
-type SenderType = "VISITOR" | "AGENT" | "AI" | "SYSTEM";
-type ConversationStatus = "OPEN" | "IN_PROGRESS" | "CLOSED";
-type MessageStatus = "sending" | "sent" | "failed";
-type WidgetPosition = "bottom-right" | "bottom-left";
-type WidgetStyle = "bubble" | "name_line" | "question_cta";
-type ThemeMode = "light" | "dark" | "system";
 type VisitorInfo = {
     name?: string;
     email?: string;
     avatar?: string;
     metadata?: Record<string, unknown>;
 };
-type MessageReaction = {
-    emoji: string;
-    userIds: string[];
-};
-type Message = {
-    id: string;
-    content: string;
-    senderType: SenderType;
-    senderId: string;
-    screenshot?: string | null;
-    image?: string | null;
-    timestamp: number;
-    status?: MessageStatus;
-    reactions?: MessageReaction[] | null;
-};
 type WidgetConfig = {
     websiteId: string;
-    apiBaseUrl: string;
+    position?: "bottom-right" | "bottom-left";
+    primaryColor?: string;
+    widgetStyle?: "bubble" | "name_line" | "question_cta";
+    themeMode?: "light" | "dark" | "system";
+    agentName?: string;
+    agentRole?: string;
+    agentImage?: string;
+    agentWelcomeMessage?: string;
+    hidePoweredBy?: boolean;
+    bubbleIcon?: string;
+};
+type TchaoConfig = {
+    websiteId: string;
+    host?: string;
     convexUrl?: string;
-    position?: WidgetPosition;
+    position?: "bottom-right" | "bottom-left";
     primaryColor?: string;
-    widgetStyle?: WidgetStyle;
-    themeMode?: ThemeMode;
+    widgetStyle?: "bubble" | "name_line" | "question_cta";
+    themeMode?: "light" | "dark" | "system";
+    agentName?: string;
+    agentRole?: string;
+    agentImage?: string;
+    agentWelcomeMessage?: string;
+    hidePoweredBy?: boolean;
+    bubbleIcon?: string;
 };
-type SDKEventMap = {
+type Message = {
+    content: string;
+    sender: string;
+    timestamp: number;
+};
+type TchaoEventMap = {
     message: (message: Message) => void;
     open: () => void;
     close: () => void;
     ready: () => void;
 };
-type SDKMethods = {
+type TchaoEvent = keyof TchaoEventMap;
+type TchaoInstance = {
     show: () => void;
     hide: () => void;
     toggle: () => void;
-    open: () => void;
+    open: (message?: string) => void;
     identify: (info: VisitorInfo) => void;
-    config: (opts: Partial<WidgetConfig>) => void;
-    on: <K extends keyof SDKEventMap>(event: K, callback: SDKEventMap[K]) => void;
-    off: <K extends keyof SDKEventMap>(event: K, callback: SDKEventMap[K]) => void;
+    config: () => Partial<WidgetConfig>;
+    on: <E extends TchaoEvent>(event: E, callback: TchaoEventMap[E]) => void;
+    off: <E extends TchaoEvent>(event: E, callback: TchaoEventMap[E]) => void;
+    destroy: () => void;
+    isReady: () => boolean;
 };
-
-declare class TchaoSDK implements SDKMethods {
-    private readonly listeners;
-    private showCallback;
-    private hideCallback;
-    private toggleCallback;
-    private openCallback;
-    private identifyCallback;
-    private configCallback;
-    setCallbacks(callbacks: {
-        show: () => void;
-        hide: () => void;
-        toggle: () => void;
-        open: () => void;
-        identify: (info: VisitorInfo) => void;
-        config: (opts: Partial<WidgetConfig>) => void;
-    }): void;
-    show(): void;
-    hide(): void;
-    toggle(): void;
-    open(): void;
-    identify(info: VisitorInfo): void;
-    config(opts: Partial<WidgetConfig>): void;
-    on<K extends keyof SDKEventMap>(event: K, callback: SDKEventMap[K]): void;
-    off<K extends keyof SDKEventMap>(event: K, callback: SDKEventMap[K]): void;
-    emit<K extends keyof SDKEventMap>(event: K, ...args: Parameters<SDKEventMap[K]>): void;
-}
-
-type TchaoInitConfig = {
-    websiteId: string;
-    host?: string;
+type InternalTchaoInstance = {
+    show: () => void;
+    hide: () => void;
+    toggle: () => void;
+    open: (message?: string) => void;
+    identify: (info: VisitorInfo) => void;
+    config: () => Partial<WidgetConfig>;
+    on: (event: string, callback: (...args: unknown[]) => void) => void;
+    off: (event: string, callback: (...args: unknown[]) => void) => void;
 };
-
-type TchaoConfig = TchaoInitConfig;
-type TchaoInstance = SDKMethods & {
+declare global {
+    interface Window {
+        Tchao?: InternalTchaoInstance;
+        __TCHAO_CONFIG__?: TchaoConfig;
+    }
+}
+declare function init(config: TchaoConfig): Promise<TchaoInstance>;
+/**
+ * Safe API that works before initialization.
+ * Calls are queued and executed once the widget is ready.
+ */
+declare const tchao: {
+    /**
+     * Initialize the widget. Returns a promise that resolves with the instance.
+     */
+    init: typeof init;
+    /**
+     * Show the widget launcher. Safe to call before init.
+     */
+    show: () => void;
+    /**
+     * Hide the widget launcher. Safe to call before init.
+     */
+    hide: () => void;
+    /**
+     * Toggle the chat window. Safe to call before init.
+     */
+    toggle: () => void;
+    /**
+     * Open the chat window. Safe to call before init.
+     */
+    open: (message?: string) => void;
+    /**
+     * Identify the visitor. Safe to call before init.
+     */
+    identify: (info: VisitorInfo) => void;
+    /**
+     * Get the current widget configuration.
+     */
+    config: () => Partial<WidgetConfig>;
+    /**
+     * Subscribe to widget events. Safe to call before init.
+     */
+    on: <E extends TchaoEvent>(event: E, callback: TchaoEventMap[E]) => void;
+    /**
+     * Unsubscribe from widget events.
+     */
+    off: <E extends TchaoEvent>(event: E, callback: TchaoEventMap[E]) => void;
+    /**
+     * Destroy the widget and clean up resources.
+     */
     destroy: () => void;
+    /**
+     * Check if the widget is ready.
+     */
+    isReady: () => boolean;
+    /**
+     * Get the current instance (null if not initialized).
+     */
+    getInstance: () => TchaoInstance | null;
 };
-type TchaoEvents = SDKEventMap;
-
-declare function init(config: TchaoConfig): Promise<TchaoInstance>;
 declare const Tchao: {
     init: typeof init;
 };
 
-export { type ConversationStatus, type Message, type MessageReaction, type MessageStatus, type SenderType, Tchao, type TchaoConfig, type TchaoEvents, type TchaoInstance, TchaoSDK, type ThemeMode, type VisitorInfo, type WidgetConfig, type WidgetPosition, type WidgetStyle, Tchao as default, init };
+export { type Message, Tchao, type TchaoConfig, type TchaoEvent, type TchaoEventMap, type TchaoInstance, type VisitorInfo, type WidgetConfig, Tchao as default, init, tchao };