@onedeskpro/chatbot-react 0.1.0 → 0.2.0

package/README.md

@@ -27,43 +27,95 @@ export default function App() {
 }
 ```
 
-`ChatbotProvider` accepts every `ChatbotInitOptions` field as a prop — `apiKey`, `apiBaseUrl`, `chatbotName`, `primaryColor`, `theme`, `position`, `welcomeMessage`, `placeholder`, `autoOpen`, `sessionId`. Only `apiKey` is required.
+`ChatbotProvider` accepts every `ChatbotInitOptions` field as a prop — `apiKey`, `apiBaseUrl`, `chatbotName`, `primaryColor`, `theme`, `position`, `welcomeMessage`, `placeholder`, `autoOpen`, `requestTimeoutMs`. Only `apiKey` is required. The `sessionId` prop is deprecated and ignored.
+
+`ChatbotWidget` handles the whole flow itself: it asks a new visitor for their name and phone number before the chat opens, and shows the controls and banners for handing a conversation to a human agent.
 
 The components are client-side; in Next.js App Router they carry `'use client'` already, so importing them from a server component is fine as long as the provider itself renders on the client.
 
 ## Custom UI
 
-`useChatbot` gives you the whole conversation state and controls:
+`useChatbot` gives you the whole conversation state and controls. A custom UI has to cover the two steps the built-in widget handles for you: identifying the visitor, and showing the conversation mode.
 
 ```tsx
 import { useChatbot } from '@onedeskpro/chatbot-react';
 
 function SupportPanel() {
-  const { messages, isLoading, isReady, sendMessage, resetSession } = useChatbot();
+  const {
+    messages,
+    isLoading,
+    isReady,
+    needsIdentify,
+    mode,
+    sendMessage,
+    submitIdentify,
+    requestHuman,
+    resetSession,
+  } = useChatbot();
 
   if (!isReady) return null;
 
+  if (needsIdentify) {
+    // Collect these from your own form. Phone must include the country code.
+    return (
+      <button
+        onClick={() => submitIdentify({ name: 'Ada Lovelace', phone: '+8801712345678' })}
+        disabled={isLoading}
+      >
+        Start chatting
+      </button>
+    );
+  }
+
   return (
     <div>
       {messages.map((m) => (
-        <p key={m.id}>{m.message.content}</p>
+        <p key={m.id}>
+          {m.message.type}: {m.message.content}
+        </p>
       ))}
-      <button onClick={() => sendMessage('Hello')} disabled={isLoading}>
+      {mode === 'waiting' && <p>Waiting for a human agent…</p>}
+      <button onClick={() => sendMessage('Hello')} disabled={isLoading || mode === 'closed'}>
         Send
       </button>
-      <button onClick={resetSession}>New conversation</button>
+      {mode === 'ai' && <button onClick={requestHuman}>Talk to a person</button>}
+      {mode === 'closed' && <button onClick={resetSession}>New conversation</button>}
     </div>
   );
 }
 ```
 
-`useChatbot` returns `messages`, `isOpen`, `isLoading`, `isReady`, `blockReason`, `error`, `sessionId`, `sendMessage`, `open`, `close`, `toggle`, and `resetSession`.
+`useChatbot` returns:
+
+| Field | Description |
+| --- | --- |
+| `messages` | The conversation. `message.type` is `'human'` (the visitor), `'ai'`, or `'agent'` (a human agent). |
+| `isOpen`, `isLoading`, `isReady` | Panel visibility, a request in flight, and whether the agent can answer. |
+| `needsIdentify` | `true` until the visitor has identified. `sendMessage` rejects while it is. |
+| `visitorToken`, `visitorName` | The identified visitor, or `null`. |
+| `mode` | `'ai'`, `'waiting'`, `'human'`, or `'closed'`. |
+| `blockReason`, `error` | Why the agent cannot answer, and the last error message. |
+| `submitIdentify({ name, phone, email? })` | Identifies the visitor and unlocks the chat. |
+| `sendMessage(text)` | Sends a message. |
+| `requestHuman()` | Escalates to a human agent. Does nothing unless `mode` is `'ai'` and a conversation has started. |
+| `resetSession()` | Clears a `closed` conversation. Does nothing in any other mode. |
+| `open()`, `close()`, `toggle()` | Control the built-in widget's panel. |
+| `sessionId` | Deprecated alias of `visitorToken`. |
 
-For custom chrome around the built-in behavior, `ChatbotHeadless` takes `renderLauncher` and `renderWindow` render props instead of shipping any markup of its own.
+`mode` also changes on its own — when the AI escalates, or an agent takes over, hands back, or closes the conversation — so render from it rather than from the result of your own calls. See the [`@onedeskpro/chatbot-core` README](https://www.npmjs.com/package/@onedeskpro/chatbot-core) for what each mode means.
+
+For custom chrome around the built-in behavior, `ChatbotHeadless` takes `renderLauncher` and `renderWindow` render props instead of shipping any markup of its own. Its render props do not carry the identify or handoff controls; read those from `useChatbot` inside your render function.
 
 ## Exports
 
-`ChatbotProvider`, `ChatbotWidget`, `ChatbotHeadless`, `useChatbot`, `ChatbotContext`, plus the `ChatbotInitOptions`, `ChatbotState`, `ChatMessage`, and `ChatbotEventMap` types.
+`ChatbotProvider`, `ChatbotWidget`, `ChatbotHeadless`, `useChatbot`, `ChatbotContext`, plus the `ChatbotProviderProps`, `ChatbotHeadlessProps`, `UseChatbotReturn`, `ChatbotInitOptions`, `ChatbotState`, `ChatMessage`, `ChatbotEventMap`, `ChatbotTicketMode`, and `TicketStatusData` types.
+
+## Upgrading from 0.1
+
+0.2.0 is a breaking release. The API no longer accepts the chat requests that 0.1 sends, so 0.1 cannot chat against the current API.
+
+- With `ChatbotWidget`, upgrading is enough.
+- With a custom UI built on `useChatbot`, add an identify step before the first `sendMessage`, and render `'agent'` messages. `resetSession` now only clears a `closed` conversation.
 
 ## License
 

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("react/jsx-runtime"),t=require("react"),h=require("@onedeskpro/chatbot-core"),b=t.createContext(null);function C(){const e=t.useContext(b);if(!e)throw new Error("useChatbot must be used inside <ChatbotProvider>.");return e}function f({children:e,...s}){const n=t.useRef(null);return n.current||(n.current=new h.ChatbotCore),t.useEffect(()=>{const o=n.current;return o.init(s).catch(r=>{console.error("[onedeskpro-chatbot] Failed to initialise:",r)}),()=>o.destroy()},[]),i.jsx(b.Provider,{value:n.current,children:e})}function g(){const e=C(),[s,n]=t.useState(()=>e.getState());t.useEffect(()=>{const a=e.on("state-change",d=>n({...d}));return n({...e.getState()}),a},[e]);const o=t.useCallback(a=>e.sendMessage(a),[e]),r=t.useCallback(()=>e.open(),[e]),c=t.useCallback(()=>e.close(),[e]),u=t.useCallback(()=>e.toggle(),[e]),l=t.useCallback(()=>e.resetSession(),[e]);return{messages:s.messages,isOpen:s.isOpen,isLoading:s.isLoading,isReady:s.isReady,blockReason:s.blockReason,error:s.error,sessionId:s.sessionId,sendMessage:o,open:r,close:c,toggle:u,resetSession:l}}function x(){const e=C();return t.useEffect(()=>{},[e]),i.jsx("div",{style:{display:"none"},"aria-hidden":"true"})}function p({renderLauncher:e,renderWindow:s}){const{isOpen:n,toggle:o,open:r,close:c,messages:u,sendMessage:l,isLoading:a,error:d}=g();return i.jsxs(i.Fragment,{children:[e({isOpen:n,toggle:o,open:r,close:c}),s({isOpen:n,messages:u,sendMessage:l,isLoading:a,error:d,close:c})]})}exports.ChatbotContext=b;exports.ChatbotHeadless=p;exports.ChatbotProvider=f;exports.ChatbotWidget=x;exports.useChatbot=g;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,s)=>(s=n==null?{}:e(i(n)),o(r||!n||!n.__esModule||!a.call(n,`default`)?t(s,`default`,{value:n,enumerable:!0}):s,n));let c=require("react");c=s(c,1);let l=require("@onedeskpro/chatbot-core"),u=require("react/jsx-runtime");var d=(0,c.createContext)(null);function f(){let e=(0,c.useContext)(d);if(!e)throw Error(`useChatbot must be used inside <ChatbotProvider>.`);return e}function p({children:e,...t}){let n=(0,c.useRef)(null);return n.current||=new l.ChatbotCore,(0,c.useEffect)(()=>{let e=n.current;return e.init(t).catch(e=>{console.error(`[onedeskpro-chatbot] Failed to initialise:`,e)}),()=>e.destroy()},[]),(0,u.jsx)(d.Provider,{value:n.current,children:e})}function m(){let e=f(),[t,n]=(0,c.useState)(()=>e.getState());(0,c.useEffect)(()=>{let t=e.on(`state-change`,e=>n({...e}));return n({...e.getState()}),t},[e]);let r=(0,c.useCallback)(t=>e.sendMessage(t),[e]),i=(0,c.useCallback)(t=>e.submitIdentify(t),[e]),a=(0,c.useCallback)(()=>e.requestHuman(),[e]),o=(0,c.useCallback)(()=>e.open(),[e]),s=(0,c.useCallback)(()=>e.close(),[e]),l=(0,c.useCallback)(()=>e.toggle(),[e]),u=(0,c.useCallback)(()=>e.resetSession(),[e]);return{messages:t.messages,isOpen:t.isOpen,isLoading:t.isLoading,isReady:t.isReady,needsIdentify:t.needsIdentify,blockReason:t.blockReason,error:t.error,visitorToken:t.visitorToken,visitorName:t.visitorName,mode:t.mode,sessionId:t.visitorToken,sendMessage:r,submitIdentify:i,requestHuman:a,open:o,close:s,toggle:l,resetSession:u}}function h(){let e=f();return(0,c.useEffect)(()=>{},[e]),(0,u.jsx)(`div`,{style:{display:`none`},"aria-hidden":`true`})}function g({renderLauncher:e,renderWindow:t}){let{isOpen:n,toggle:r,open:i,close:a,messages:o,sendMessage:s,isLoading:c,error:l}=m();return(0,u.jsxs)(u.Fragment,{children:[e({isOpen:n,toggle:r,open:i,close:a}),t({isOpen:n,messages:o,sendMessage:s,isLoading:c,error:l,close:a})]})}exports.ChatbotContext=d,exports.ChatbotHeadless=g,exports.ChatbotProvider=p,exports.ChatbotWidget=h,exports.useChatbot=m;

package/dist/index.d.cts

@@ -3,10 +3,12 @@ import { ChatbotCore } from '@onedeskpro/chatbot-core';
 import { ChatbotEventMap } from '@onedeskpro/chatbot-types';
 import { ChatbotInitOptions } from '@onedeskpro/chatbot-types';
 import { ChatbotState } from '@onedeskpro/chatbot-types';
+import { ChatbotTicketMode } from '@onedeskpro/chatbot-types';
 import { ChatMessage } from '@onedeskpro/chatbot-types';
 import { Context } from 'react';
 import { default as default_2 } from 'react';
 import { ReactNode } from 'react';
+import { TicketStatusData } from '@onedeskpro/chatbot-types';
 
 export declare const ChatbotContext: Context<ChatbotCore | null>;
 
@@ -45,6 +47,8 @@ export declare type ChatbotProviderProps = ChatbotInitOptions & {
 
 export { ChatbotState }
 
+export { ChatbotTicketMode }
+
 /**
  * Default floating widget — delegates rendering to the core Shadow DOM widget
  * that ChatbotCore.init() mounts into document.body. This component just
@@ -54,6 +58,8 @@ export declare function ChatbotWidget(): default_2.JSX.Element;
 
 export { ChatMessage }
 
+export { TicketStatusData }
+
 export declare function useChatbot(): UseChatbotReturn;
 
 export declare interface UseChatbotReturn {
@@ -61,10 +67,23 @@ export declare interface UseChatbotReturn {
     isOpen: boolean;
     isLoading: boolean;
     isReady: boolean;
+    needsIdentify: boolean;
     blockReason: ChatbotBlockReason;
     error: string | null;
+    visitorToken: string | null;
+    visitorName: string | null;
+    /** Ticket episode mode: ai | waiting | human | closed. */
+    mode: ChatbotTicketMode;
+    /** @deprecated Use visitorToken. */
     sessionId: string | null;
     sendMessage: (text: string) => Promise<void>;
+    submitIdentify: (payload: {
+        name: string;
+        phone: string;
+        email?: string;
+    }) => Promise<void>;
+    /** Escalate the open AI ticket to a human agent (no-op unless mode is `ai`). */
+    requestHuman: () => Promise<void>;
     open: () => void;
     close: () => void;
     toggle: () => void;

package/dist/index.d.ts

@@ -3,10 +3,12 @@ import { ChatbotCore } from '@onedeskpro/chatbot-core';
 import { ChatbotEventMap } from '@onedeskpro/chatbot-types';
 import { ChatbotInitOptions } from '@onedeskpro/chatbot-types';
 import { ChatbotState } from '@onedeskpro/chatbot-types';
+import { ChatbotTicketMode } from '@onedeskpro/chatbot-types';
 import { ChatMessage } from '@onedeskpro/chatbot-types';
 import { Context } from 'react';
 import { default as default_2 } from 'react';
 import { ReactNode } from 'react';
+import { TicketStatusData } from '@onedeskpro/chatbot-types';
 
 export declare const ChatbotContext: Context<ChatbotCore | null>;
 
@@ -45,6 +47,8 @@ export declare type ChatbotProviderProps = ChatbotInitOptions & {
 
 export { ChatbotState }
 
+export { ChatbotTicketMode }
+
 /**
  * Default floating widget — delegates rendering to the core Shadow DOM widget
  * that ChatbotCore.init() mounts into document.body. This component just
@@ -54,6 +58,8 @@ export declare function ChatbotWidget(): default_2.JSX.Element;
 
 export { ChatMessage }
 
+export { TicketStatusData }
+
 export declare function useChatbot(): UseChatbotReturn;
 
 export declare interface UseChatbotReturn {
@@ -61,10 +67,23 @@ export declare interface UseChatbotReturn {
     isOpen: boolean;
     isLoading: boolean;
     isReady: boolean;
+    needsIdentify: boolean;
     blockReason: ChatbotBlockReason;
     error: string | null;
+    visitorToken: string | null;
+    visitorName: string | null;
+    /** Ticket episode mode: ai | waiting | human | closed. */
+    mode: ChatbotTicketMode;
+    /** @deprecated Use visitorToken. */
     sessionId: string | null;
     sendMessage: (text: string) => Promise<void>;
+    submitIdentify: (payload: {
+        name: string;
+        phone: string;
+        email?: string;
+    }) => Promise<void>;
+    /** Escalate the open AI ticket to a human agent (no-op unless mode is `ai`). */
+    requestHuman: () => Promise<void>;
     open: () => void;
     close: () => void;
     toggle: () => void;

package/dist/index.js

@@ -1,62 +1,81 @@
-import { jsx as g, jsxs as C, Fragment as b } from "react/jsx-runtime";
-import { createContext as p, useContext as m, useRef as x, useEffect as l, useState as R, useCallback as i } from "react";
-import { ChatbotCore as S } from "@onedeskpro/chatbot-core";
-const f = p(null);
-function h() {
-  const e = m(f);
-  if (!e) throw new Error("useChatbot must be used inside <ChatbotProvider>.");
-  return e;
+import { createContext as e, useCallback as t, useContext as n, useEffect as r, useRef as i, useState as a } from "react";
+import { ChatbotCore as o } from "@onedeskpro/chatbot-core";
+import { Fragment as s, jsx as c, jsxs as l } from "react/jsx-runtime";
+//#region src/context.ts
+var u = e(null);
+function d() {
+	let e = n(u);
+	if (!e) throw Error("useChatbot must be used inside <ChatbotProvider>.");
+	return e;
 }
-function L({ children: e, ...t }) {
-  const s = x(null);
-  return s.current || (s.current = new S()), l(() => {
-    const n = s.current;
-    return n.init(t).catch((o) => {
-      console.error("[onedeskpro-chatbot] Failed to initialise:", o);
-    }), () => n.destroy();
-  }, []), /* @__PURE__ */ g(f.Provider, { value: s.current, children: e });
+//#endregion
+//#region src/chatbot-provider.tsx
+function f({ children: e, ...t }) {
+	let n = i(null);
+	return n.current ||= new o(), r(() => {
+		let e = n.current;
+		return e.init(t).catch((e) => {
+			console.error("[onedeskpro-chatbot] Failed to initialise:", e);
+		}), () => e.destroy();
+	}, []), /* @__PURE__ */ c(u.Provider, {
+		value: n.current,
+		children: e
+	});
 }
-function v() {
-  const e = h(), [t, s] = R(() => e.getState());
-  l(() => {
-    const r = e.on("state-change", (d) => s({ ...d }));
-    return s({ ...e.getState() }), r;
-  }, [e]);
-  const n = i(
-    (r) => e.sendMessage(r),
-    [e]
-  ), o = i(() => e.open(), [e]), a = i(() => e.close(), [e]), c = i(() => e.toggle(), [e]), u = i(() => e.resetSession(), [e]);
-  return {
-    messages: t.messages,
-    isOpen: t.isOpen,
-    isLoading: t.isLoading,
-    isReady: t.isReady,
-    blockReason: t.blockReason,
-    error: t.error,
-    sessionId: t.sessionId,
-    sendMessage: n,
-    open: o,
-    close: a,
-    toggle: c,
-    resetSession: u
-  };
+//#endregion
+//#region src/hooks/use-chatbot.ts
+function p() {
+	let e = d(), [n, i] = a(() => e.getState());
+	r(() => {
+		let t = e.on("state-change", (e) => i({ ...e }));
+		return i({ ...e.getState() }), t;
+	}, [e]);
+	let o = t((t) => e.sendMessage(t), [e]), s = t((t) => e.submitIdentify(t), [e]), c = t(() => e.requestHuman(), [e]), l = t(() => e.open(), [e]), u = t(() => e.close(), [e]), f = t(() => e.toggle(), [e]), p = t(() => e.resetSession(), [e]);
+	return {
+		messages: n.messages,
+		isOpen: n.isOpen,
+		isLoading: n.isLoading,
+		isReady: n.isReady,
+		needsIdentify: n.needsIdentify,
+		blockReason: n.blockReason,
+		error: n.error,
+		visitorToken: n.visitorToken,
+		visitorName: n.visitorName,
+		mode: n.mode,
+		sessionId: n.visitorToken,
+		sendMessage: o,
+		submitIdentify: s,
+		requestHuman: c,
+		open: l,
+		close: u,
+		toggle: f,
+		resetSession: p
+	};
 }
-function M() {
-  const e = h();
-  return l(() => {
-  }, [e]), /* @__PURE__ */ g("div", { style: { display: "none" }, "aria-hidden": "true" });
+//#endregion
+//#region src/chatbot-widget.tsx
+function m() {
+	let e = d();
+	return r(() => {}, [e]), /* @__PURE__ */ c("div", {
+		style: { display: "none" },
+		"aria-hidden": "true"
+	});
 }
-function O({ renderLauncher: e, renderWindow: t }) {
-  const { isOpen: s, toggle: n, open: o, close: a, messages: c, sendMessage: u, isLoading: r, error: d } = v();
-  return /* @__PURE__ */ C(b, { children: [
-    e({ isOpen: s, toggle: n, open: o, close: a }),
-    t({ isOpen: s, messages: c, sendMessage: u, isLoading: r, error: d, close: a })
-  ] });
+function h({ renderLauncher: e, renderWindow: t }) {
+	let { isOpen: n, toggle: r, open: i, close: a, messages: o, sendMessage: c, isLoading: u, error: d } = p();
+	return /* @__PURE__ */ l(s, { children: [e({
+		isOpen: n,
+		toggle: r,
+		open: i,
+		close: a
+	}), t({
+		isOpen: n,
+		messages: o,
+		sendMessage: c,
+		isLoading: u,
+		error: d,
+		close: a
+	})] });
 }
-export {
-  f as ChatbotContext,
-  O as ChatbotHeadless,
-  L as ChatbotProvider,
-  M as ChatbotWidget,
-  v as useChatbot
-};
+//#endregion
+export { u as ChatbotContext, h as ChatbotHeadless, f as ChatbotProvider, m as ChatbotWidget, p as useChatbot };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onedeskpro/chatbot-react",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "React SDK for the Onedesk Pro Chatbot",
   "license": "MIT",
   "author": "Typetech IT <support@onedeskpro.com>",
@@ -50,23 +50,26 @@
     "react-dom": ">=18.0.0"
   },
   "dependencies": {
-    "@onedeskpro/chatbot-core": "0.1.0",
-    "@onedeskpro/chatbot-types": "0.1.0"
+    "@onedeskpro/chatbot-core": "0.2.0",
+    "@onedeskpro/chatbot-types": "0.2.0"
   },
   "devDependencies": {
-    "@testing-library/dom": "^10",
-    "@testing-library/jest-dom": "^6",
-    "@testing-library/react": "^16",
-    "@types/react": "^18.0.0",
-    "@types/react-dom": "^18.0.0",
-    "@vitejs/plugin-react": "^4.0.0",
-    "jsdom": "^25",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0",
-    "typescript": "^5.5.0",
-    "vite": "^5.0.0",
-    "vite-plugin-dts": "^4.0.0",
-    "vitest": "^2"
+    "@microsoft/api-extractor": "^7.59.4",
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.7",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.2",
+    "jsdom": "^30.1.2",
+    "msw": "^2.15.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "typescript": "^6",
+    "vite": "^8.3.4",
+    "vite-plugin-dts": "^5.1.2",
+    "vitest": "^5.0.4"
   },
   "scripts": {
     "build": "vite build && cp dist/index.d.ts dist/index.d.cts",