@helpway/react 0.1.0

package/README.md

@@ -0,0 +1,130 @@
+# @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.
+
+## 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_…`).
+
+```tsx
+// app/layout.tsx (Next.js App Router)
+import { HelpwayWidget } from "@helpway/react";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <HelpwayWidget apiKey="pk_live_XXXXXXXX" />
+      </body>
+    </html>
+  );
+}
+```
+
+```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>,
+);
+```
+
+The component injects the Helpway widget loader script into `document.body`, handles StrictMode double-mounts, and removes the script on unmount.
+
+### 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.    |
+
+### Identifying logged-in users
+
+After your user signs in, call the global `Helpway` identify function so the dashboard sees their real name and email instead of `Anonymous`:
+
+```ts
+window.Helpway("identify", {
+  uniqueId: user.id,
+  name: user.name,
+  email: user.email,
+});
+```
+
+## Headless
+
+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:
+
+```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>
+  );
+}
+
+export default function App() {
+  return (
+    <SupportProvider apiKey="pk_live_XXXXXXXX">
+      <ChatSurface />
+    </SupportProvider>
+  );
+}
+```
+
+Exported hooks:
+
+- `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";
+```
+
+The headless hooks have no styles — bring your own.
+
+## License
+
+MIT © Helpway

package/dist/index.d.ts

@@ -0,0 +1,257 @@
+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 * as react from 'react';
+import react__default, { ReactNode } from 'react';
+import * as _helpway_types from '@helpway/types';
+import { TimelineItem, RealtimeEvent, TimelineItemPart } from '@helpway/types';
+
+/**
+ * `<HelpwayWidget />` — one-line drop-in React component that loads
+ * the Helpway widget script and tears it down on unmount.
+ *
+ * This is the lowest-friction integration path for React / Next.js /
+ * Vite apps that don't need to render custom chat UI themselves. Under
+ * the hood it just injects `https://api.helpway.ai/widget.js` with the
+ * provided public key, exactly like the plain `<script>` snippet — but
+ * wrapped in a React lifecycle so it participates in StrictMode double
+ * mounts, SSR boundaries, and component cleanup without footguns.
+ *
+ * Power-user alternative: import `{ SupportProvider, useWidget, … }`
+ * from this same package for full programmatic control.
+ */
+interface HelpwayWidgetProps {
+    /**
+     * Public API key from the Helpway dashboard. Required.
+     * Format: `pk_live_…` or `pk_test_…`.
+     */
+    apiKey: string;
+    /**
+     * Override the default widget loader URL. Almost no one needs this —
+     * exposed for staging / self-hosted setups.
+     * @default "https://api.helpway.ai/widget.js"
+     */
+    src?: string;
+}
+/**
+ * Render this once at the root of your app (e.g. in `_app.tsx`,
+ * `layout.tsx`, or `main.tsx`). Unmounting removes the script and
+ * collapses the widget iframe — useful for route-scoped mounts.
+ */
+declare function HelpwayWidget({ apiKey, src, }: HelpwayWidgetProps): null;
+
+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;
+
+/**
+ * Core widget state — connection status, visitor identity, website info.
+ *
+ * Usage:
+ * ```tsx
+ * const { isReady, visitor, website, identify } = useWidget()
+ * ```
+ */
+declare function useWidget(): {
+    isReady: boolean;
+    isConnecting: boolean;
+    visitor: _helpway_types.PublicVisitor | null;
+    website: {
+        id: string;
+        name: string;
+        domain: string | null;
+        logoUrl: string | null;
+    } | null;
+    agentConfig: _helpway_widget_core.AgentConfig | null;
+    identify: (data: {
+        externalId: string;
+        email?: string;
+        name?: string;
+        image?: string;
+        metadata?: Record<string, unknown>;
+    }) => Promise<any>;
+};
+
+/**
+ * Conversation list + create new conversation.
+ */
+declare function useConversations(): {
+    conversations: _helpway_widget_core.ConversationSummary[];
+    create: (text: string) => Promise<any>;
+    isCreating: boolean;
+    setActiveConversation: (id: string | null) => void;
+};
+
+/**
+ * Timeline items for a conversation + real-time updates.
+ */
+declare function useTimeline(conversationId: string | null): {
+    items: TimelineItem[];
+    isLoading: boolean;
+    hasMore: boolean;
+    loadMore: () => Promise<void>;
+};
+
+interface PendingAttachment {
+    id: string;
+    file: File;
+    previewUrl: string | null;
+    isUploading: boolean;
+    error: string | null;
+    /** Resolved after upload — the part to include in sendMessage */
+    part: {
+        type: "image";
+        url: string;
+        mimeType: string;
+    } | {
+        type: "file";
+        url: string;
+        fileName: string;
+        fileSize: number;
+        mimeType: string;
+    } | null;
+}
+/**
+ * Composer state — text input + attachments + submit for a conversation.
+ */
+declare function useComposer(conversationId: string | null): {
+    text: string;
+    setText: react.Dispatch<react.SetStateAction<string>>;
+    submit: () => Promise<void>;
+    isSubmitting: boolean;
+    attachments: PendingAttachment[];
+    addFiles: (files: File[]) => Promise<void>;
+    removeAttachment: (id: string) => void;
+    sendError: string | null;
+    clearSendError: () => void;
+};
+
+/**
+ * Typing presence — show "is typing" + send own typing status.
+ *
+ * Debounced: only sends WS event when typing state *changes*.
+ * While typing, auto-stops after 3 seconds of inactivity.
+ *
+ * Usage:
+ * ```tsx
+ * const { isTyping, setTyping } = usePresence(conversationId)
+ * ```
+ */
+declare function usePresence(conversationId: string | null): {
+    isTyping: boolean;
+    isAiProcessing: boolean;
+    setTyping: (typing: boolean) => void;
+};
+
+/**
+ * Total unread count across all conversations.
+ *
+ * Usage:
+ * ```tsx
+ * const { totalUnread } = useUnread()
+ * ```
+ */
+declare function useUnread(): {
+    totalUnread: number;
+};
+
+/**
+ * Subscribe to raw WebSocket events.
+ * For advanced usage — most apps should use useTimeline/usePresence instead.
+ *
+ * Usage:
+ * ```tsx
+ * useRealtime((event) => {
+ *   if (event.type === 'timelineItemCreated') { ... }
+ * })
+ * ```
+ */
+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;
+}): react_jsx_runtime.JSX.Element;
+
+interface MessageBubbleProps {
+    text: string;
+    sender: "visitor" | "team" | "ai";
+    senderName?: string;
+    time: string;
+    parts?: TimelineItemPart[] | null;
+}
+/** Single message bubble — Intercom-style, renders text + image/file parts */
+declare function MessageBubble({ text, sender, senderName, time, parts }: MessageBubbleProps): react_jsx_runtime.JSX.Element;
+
+interface MessageListProps {
+    items: TimelineItem[];
+    visitorName?: string;
+    isTyping?: boolean;
+    isAiProcessing?: boolean;
+    hasMore?: boolean;
+    isLoadingMore?: boolean;
+    onLoadMore?: () => void;
+    /** Slot rendered after all messages but before typing indicators (e.g. email prompt) */
+    renderAfterMessages?: react__default.ReactNode;
+}
+/** Timeline with date separators, typing indicator, infinite scroll, and AI processing state */
+declare function MessageList({ items, visitorName, isTyping, isAiProcessing, hasMore, isLoadingMore, onLoadMore, renderAfterMessages, }: MessageListProps): react_jsx_runtime.JSX.Element;
+
+interface ComposerProps {
+    text: string;
+    onTextChange: (text: string) => void;
+    onSubmit: () => void;
+    onTyping?: (isTyping: boolean) => void;
+    isSubmitting?: boolean;
+    placeholder?: string;
+    /** Compact mode — single-line input without footer row */
+    compact?: boolean;
+    /** Pending attachments to preview */
+    attachments?: PendingAttachment[];
+    /** Called when files are added (paste, drop, or file picker) */
+    onAddFiles?: (files: File[]) => void;
+    /** Called to remove a pending attachment */
+    onRemoveAttachment?: (id: string) => void;
+    /** Disable entire composer (e.g. email required before sending) */
+    disabled?: boolean;
+}
+/** Widget composer — auto-resize, Enter-to-send, paste/drop attachments */
+declare function Composer({ text, onTextChange, onSubmit, onTyping, isSubmitting, placeholder, compact, attachments, onAddFiles, onRemoveAttachment, disabled, }: ComposerProps): react_jsx_runtime.JSX.Element;
+
+export { Composer, DefaultWidget, HelpwayWidget, type HelpwayWidgetProps, type IdentifyData, MessageBubble, MessageList, SupportProvider, useComposer, useConversations, useIdentify, usePresence, useRealtime, useTimeline, useUnread, useWidget, useWidgetStore };