@helpway/react 0.4.0 → 0.4.2

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,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _helpway_widget_core from '@helpway/widget-core';
-import { HelpwayAPI, WidgetStore } from '@helpway/widget-core';
+import { HelpwayMethods, 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';
@@ -60,7 +60,7 @@ interface HelpwayWidgetProps {
     src?: string;
 }
 
-type HelpwayPublicAPI = HelpwayAPI;
+type HelpwayPublicAPI = HelpwayMethods;
 /**
  * Render this once at the root of your app (e.g. in `_app.tsx`,
  * `layout.tsx`, or `main.tsx`). Unmounting cleanly tears down the
@@ -84,7 +84,7 @@ interface SupportProviderProps {
     apiUrl?: string;
     locale?: string;
     initialConversationId?: string;
-    onReady?: (api: HelpwayAPI) => void;
+    onReady?: (api: HelpwayMethods) => void;
     customLauncherSelector?: string;
     onOpen?: () => void;
     onClose?: () => void;
@@ -238,9 +238,10 @@ interface MessageBubbleProps {
     sender: "visitor" | "team" | "ai";
     senderName?: string;
     parts?: TimelineItemPart[] | null;
+    timestamp?: string;
 }
 /** Single message bubble — Intercom-style, renders text + image/file parts */
-declare function MessageBubble({ text, sender, senderName, parts }: MessageBubbleProps): react_jsx_runtime.JSX.Element;
+declare function MessageBubble({ text, sender, senderName, parts, timestamp }: MessageBubbleProps): react_jsx_runtime.JSX.Element;
 
 interface MessageListProps {
     items: TimelineItem[];