@helpway/react 0.3.4 → 0.4.1

package/README.md

@@ -1,129 +1,112 @@
 # @helpway/react
 
-Official React SDK for [Helpway](https://helpway.ai) — AI-powered customer support in a single component.
-
-Two integration levels in one package:
-
-- **Drop-in**: mount `<HelpwayWidget apiKey="..." />` anywhere in your tree and you're done.
-- **Headless**: use `SupportProvider` + hooks (`useWidget`, `useConversations`, `useTimeline`, `useComposer`) to build your own chat UI against the same realtime backend.
+Official React SDK for [Helpway](https://helpway.ai) — AI-powered customer support widget with full programmatic control.
 
 ## Install
 
 ```bash
 npm install @helpway/react
-# or
-bun add @helpway/react
-# or
-pnpm add @helpway/react
 ```
 
 Peer dependencies: `react` ≥ 18 and `react-dom` ≥ 18.
 
-## Drop-in
-
-Grab your public API key from the Helpway dashboard → Settings → API keys (format: `pk_live_…`).
+## Quick start
 
 ```tsx
-// app/layout.tsx (Next.js App Router)
 import { HelpwayWidget } from "@helpway/react";
 
-export default function RootLayout({ children }: { children: React.ReactNode }) {
+export default function App() {
   return (
-    <html>
-      <body>
-        {children}
-        <HelpwayWidget apiKey="pk_live_XXXXXXXX" />
-      </body>
-    </html>
+    <>
+      <YourApp />
+      <HelpwayWidget apiKey="pk_live_xxx" />
+    </>
   );
 }
 ```
 
-```tsx
-// main.tsx (Vite / CRA)
-import { HelpwayWidget } from "@helpway/react";
-import { StrictMode } from "react";
-import { createRoot } from "react-dom/client";
-import App from "./App";
-
-createRoot(document.getElementById("root")!).render(
-  <StrictMode>
-    <App />
-    <HelpwayWidget apiKey="pk_live_XXXXXXXX" />
-  </StrictMode>,
-);
+## Programmatic API (`window.Helpway`)
+
+After the widget bootstraps, a type-safe global API is available:
+
+```ts
+window.Helpway.open()                        // open panel
+window.Helpway.close()                       // close panel
+window.Helpway.toggle()                      // toggle open/close
+window.Helpway.dismiss()                     // hide launcher + panel
+window.Helpway.show()                        // re-show after dismiss
+window.Helpway.shutdown()                    // full session reset
+
+window.Helpway.identify({                    // link visitor to contact
+  externalId: "u_123",
+  email: "jane@acme.com",
+  name: "Jane Doe",
+})
+
+window.Helpway.newConversation("Help!")      // open new conversation
+window.Helpway.openConversation("conv_abc")  // open specific conversation
+
+window.Helpway.unreadCount                   // getter: number
+window.Helpway.isOpen                        // getter: boolean
+
+window.Helpway.on("open", () => {})          // subscribe to events
+window.Helpway.on("unreadChange", (n) => {})
+window.Helpway.on("messageReceived", (msg) => {})
+window.Helpway.off("open", handler)          // unsubscribe
 ```
 
-The component injects the Helpway widget loader script into `document.body`, handles StrictMode double-mounts, and removes the script on unmount.
+TypeScript users get full auto-complete — the package augments `Window` automatically.
 
-### Props
+## Props
 
-| Prop     | Type     | Default                              | Description                                   |
-| -------- | -------- | ------------------------------------ | --------------------------------------------- |
-| `apiKey` | `string` | —                                    | Public key from the dashboard. Required.      |
-| `src`    | `string` | `https://api.helpway.ai/widget.js` | Override for staging / self-hosted setups.    |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | — | **Required.** Public key from dashboard. |
+| `apiUrl` | `string` | `https://api.helpway.ai` | Override for staging / self-hosted. |
+| `locale` | `string` | auto-detect | Widget language (`"en"`, `"tr"`, `"de"`…). |
+| `hideLauncher` | `boolean` | `false` | Hide the default floating bubble. |
+| `customLauncherSelector` | `string` | — | CSS selector for custom trigger element. |
+| `onReady` | `(api: HelpwayAPI) => void` | — | Full API object after bootstrap. |
+| `onOpen` | `() => void` | — | Panel opened. |
+| `onClose` | `() => void` | — | Panel closed. |
+| `onUnreadChange` | `(count: number) => void` | — | Unread count changed. |
 
-### Identifying logged-in users
+## Custom launcher
 
-After your user signs in, call the global `Helpway` identify function so the dashboard sees their real name and email instead of `Anonymous`:
+```tsx
+<HelpwayWidget
+  apiKey="pk_live_xxx"
+  hideLauncher
+  customLauncherSelector="#my-btn"
+/>
 
-```ts
-window.Helpway("identify", {
-  uniqueId: user.id,
-  name: user.name,
-  email: user.email,
-});
+<button id="my-btn">Support</button>
 ```
 
-## Headless
+## Headless hooks
 
-If you want to render your own chat UI (custom bubbles, different layout, embedded in your app instead of a floating button), use the provider + hooks:
+Build your own chat UI with the same realtime backend:
 
 ```tsx
 import { SupportProvider, useConversations, useTimeline, useComposer } from "@helpway/react";
 
-function ChatSurface() {
-  const { conversations, activeConversationId, setActive } = useConversations();
-  const { items } = useTimeline();
-  const { draft, setDraft, send } = useComposer();
-
-  return (
-    <div>
-      {/* render conversations, messages, composer — full control */}
-    </div>
-  );
+function Chat() {
+  const { conversations } = useConversations();
+  const { items } = useTimeline(conversations[0]?.id);
+  const { text, setText, submit } = useComposer(conversations[0]?.id);
+  // ...render your own UI
 }
 
-export default function App() {
-  return (
-    <SupportProvider apiKey="pk_live_XXXXXXXX">
-      <ChatSurface />
-    </SupportProvider>
-  );
-}
+<SupportProvider apiKey="pk_live_xxx">
+  <Chat />
+</SupportProvider>
 ```
 
-Exported hooks:
+Available hooks: `useWidget`, `useConversations`, `useTimeline`, `useComposer`, `usePresence`, `useUnread`, `useRealtime`.
 
-- `useWidget()` — global state, openers/closers
-- `useConversations()` — list + active conversation
-- `useTimeline()` — messages + events for the active conversation
-- `useComposer()` — draft state + send/attach
-- `usePresence()` — online team members
-- `useUnread()` — unread counts
-- `useRealtime()` — raw WebSocket event stream
-
-Full API docs: [helpway.ai/docs/react](https://helpway.ai/docs/react)
-
-## Styling
-
-The default themed widget ships opinionated styles. If you use `DefaultWidget`, pull in the stylesheet once:
-
-```ts
-import "@helpway/react/styles.css";
-```
+## Docs
 
-The headless hooks have no styles — bring your own.
+Full documentation: [helpway.ai/docs](https://helpway.ai/docs)
 
 ## License
 

package/dist/index.d.ts

@@ -1,48 +1,12 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _helpway_widget_core from '@helpway/widget-core';
-import { WidgetStore } from '@helpway/widget-core';
-export { ConversationSummary, RealtimeEvent, TimelineItem, WidgetState, WidgetStore, clearVisitorId, formatRelativeTime, formatTime, getInitials, getOrCreateVisitorId } from '@helpway/widget-core';
+import { HelpwayAPI, WidgetStore } from '@helpway/widget-core';
+export { ConversationSummary, HelpwayAPI, RealtimeEvent, TimelineItem, WidgetEventName, WidgetEvents, WidgetState, WidgetStore, clearVisitorId, formatRelativeTime, formatTime, getInitials, getOrCreateVisitorId } from '@helpway/widget-core';
 import * as react from 'react';
 import react__default, { ReactNode } from 'react';
 import * as _helpway_types from '@helpway/types';
 import { TimelineItem, RealtimeEvent, TimelineItemPart } from '@helpway/types';
 
-interface IdentifyData {
-    externalId: string;
-    email?: string;
-    name?: string;
-    image?: string;
-    metadata?: Record<string, unknown>;
-}
-/** Use a slice of the widget store with auto re-render */
-declare function useWidgetStore<T>(selector: (state: WidgetStore) => T): T;
-/** Hook to identify the current visitor (link to customer contact) */
-declare function useIdentify(): (data: IdentifyData) => Promise<void>;
-interface SupportProviderProps {
-    /** Public API key (pk_xxx) */
-    apiKey: string;
-    /** API base URL (default: auto-detect from script tag or window) */
-    apiUrl?: string;
-    /** Widget locale (e.g., "fr", "de"). Falls back to navigator.language → "en" */
-    locale?: string;
-    /** Deep link: auto-open this conversation after bootstrap (from ?hw_conv= URL param) */
-    initialConversationId?: string;
-    /** Callback to expose widget API to parent (for embed loader) */
-    onReady?: (api: {
-        identify: (data: IdentifyData) => Promise<void>;
-        openConversation: (id: string) => void;
-    }) => void;
-    children: ReactNode;
-}
-/**
- * Root provider for the Helpway widget.
- * Creates tRPC client, WebSocket connection, and state store.
- *
- * Visitor identity is managed via server-side cookies (hw_visitor).
- * No localStorage or client-side ID management needed.
- */
-declare function SupportProvider({ apiKey, apiUrl, locale, initialConversationId, onReady, children, }: SupportProviderProps): react_jsx_runtime.JSX.Element;
-
 interface HelpwayWidgetProps {
     /**
      * Public API key from the Helpway dashboard. Required.
@@ -67,12 +31,27 @@ interface HelpwayWidgetProps {
     initialConversationId?: string;
     /**
      * Called once after the widget has bootstrapped and exposes
-     * programmatic APIs (identify, openConversation).
+     * the full programmatic API object (also available as `window.Helpway`).
      */
-    onReady?: (api: {
-        identify: (data: IdentifyData) => Promise<void>;
-        openConversation: (id: string) => void;
-    }) => void;
+    onReady?: (api: HelpwayPublicAPI) => void;
+    /**
+     * Hide the default floating launcher button. Use with
+     * `customLauncherSelector` or `window.Helpway.open()` to trigger
+     * the widget from your own UI.
+     */
+    hideLauncher?: boolean;
+    /**
+     * CSS selector for a custom trigger element (e.g. `"#support-btn"`).
+     * Clicking the matched element calls `Helpway.open()`. Combine with
+     * `hideLauncher` to fully replace the default bubble.
+     */
+    customLauncherSelector?: string;
+    /** Fires when the widget panel opens */
+    onOpen?: () => void;
+    /** Fires when the widget panel closes */
+    onClose?: () => void;
+    /** Fires when the unread count changes */
+    onUnreadChange?: (count: number) => void;
     /**
      * @deprecated Legacy prop from the v0.1 script-loader era. If set,
      * the `/widget.js` suffix is stripped to derive `apiUrl`. New code
@@ -80,12 +59,46 @@ interface HelpwayWidgetProps {
      */
     src?: string;
 }
+
+type HelpwayPublicAPI = HelpwayAPI;
 /**
  * Render this once at the root of your app (e.g. in `_app.tsx`,
  * `layout.tsx`, or `main.tsx`). Unmounting cleanly tears down the
  * widget and its WebSocket connection — useful for route-scoped mounts.
  */
-declare function HelpwayWidget({ apiKey, apiUrl, locale, initialConversationId, onReady, src, }: HelpwayWidgetProps): react_jsx_runtime.JSX.Element;
+declare function HelpwayWidget({ apiKey, apiUrl, locale, initialConversationId, onReady, hideLauncher, customLauncherSelector, onOpen, onClose, onUnreadChange, src, }: HelpwayWidgetProps): react_jsx_runtime.JSX.Element;
+
+interface IdentifyData {
+    externalId: string;
+    email?: string;
+    name?: string;
+    image?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Use a slice of the widget store with auto re-render */
+declare function useWidgetStore<T>(selector: (state: WidgetStore) => T): T;
+/** Hook to identify the current visitor (link to customer contact) */
+declare function useIdentify(): (data: IdentifyData) => Promise<void>;
+interface SupportProviderProps {
+    apiKey: string;
+    apiUrl?: string;
+    locale?: string;
+    initialConversationId?: string;
+    onReady?: (api: HelpwayAPI) => void;
+    customLauncherSelector?: string;
+    onOpen?: () => void;
+    onClose?: () => void;
+    onUnreadChange?: (count: number) => void;
+    children: ReactNode;
+}
+/**
+ * Root provider for the Helpway widget.
+ * Creates tRPC client, WebSocket connection, and state store.
+ *
+ * Visitor identity is managed via server-side cookies (hw_visitor).
+ * No localStorage or client-side ID management needed.
+ */
+declare function SupportProvider({ apiKey, apiUrl, locale, initialConversationId, onReady, customLauncherSelector, onOpen, onClose, onUnreadChange, children, }: SupportProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Core widget state — connection status, visitor identity, website info.
@@ -216,8 +229,8 @@ declare function useRealtime(handler: (event: RealtimeEvent) => void): void;
  * Unified support widget — Intercom-style with tab navigation.
  * Two tabs: Home + Messages. Sub-views: conversation + new conversation.
  */
-declare function DefaultWidget({ initialOpen }?: {
-    initialOpen?: boolean;
+declare function DefaultWidget({ hideLauncher }?: {
+    hideLauncher?: boolean;
 }): react_jsx_runtime.JSX.Element;
 
 interface MessageBubbleProps {
@@ -292,4 +305,4 @@ declare function MarkdownContent({ bodyHtml, bodyMarkdown, className, }: {
     className?: string;
 }): react_jsx_runtime.JSX.Element | null;
 
-export { Composer, DefaultWidget, HelpwayWidget, type HelpwayWidgetProps, type IdentifyData, MarkdownContent, MessageBubble, MessageList, SupportProvider, linkifyText, renderMarkdown, useComposer, useConversations, useIdentify, usePresence, useRealtime, useTimeline, useUnread, useWidget, useWidgetStore };
+export { Composer, DefaultWidget, type HelpwayPublicAPI, HelpwayWidget, type HelpwayWidgetProps, type IdentifyData, MarkdownContent, MessageBubble, MessageList, SupportProvider, linkifyText, renderMarkdown, useComposer, useConversations, useIdentify, usePresence, useRealtime, useTimeline, useUnread, useWidget, useWidgetStore };