@characterxyz/react 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charky Labs Pvt Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @characterxyz/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Your Character XYZ agent in React and Next.js: the ready-made widget as a component, and a hook for
+building your own UI. Includes [`@characterxyz/widget`](https://www.npmjs.com/package/@characterxyz/widget)
+and [`@characterxyz/web`](https://www.npmjs.com/package/@characterxyz/web); install only this.
+
+```bash
+npm install @characterxyz/react
+```
+
+## The widget
+
+```tsx
+import { CharacterXYZWidget } from '@characterxyz/react';
+
+export function Support() {
+  return <CharacterXYZWidget publishableKey="cxyz_pk_live_…" accent="#e11d48" onReady={({ agent }) => console.log(agent.name)} />;
+}
+```
+
+It takes every widget setting as a prop (`agentId`, `display`, `position`, `mode`, `showCall`, …). Works
+in the Next.js App Router as is: the package is marked `'use client'`.
+
+## Your own UI
+
+```tsx
+import { useCharacterXYZ } from '@characterxyz/react';
+
+const { messages, busy, send, startCall, call, error } = useCharacterXYZ({ publishableKey: 'cxyz_pk_live_…' });
+```
+
+`messages` stream as the reply is written; `startCall()` must run from a click (it asks for the
+microphone), and `call` carries its phase, queue position and estimate.
+
+## Signed-in visitors
+
+Mint the session on your server with [`@characterxyz/server`](https://www.npmjs.com/package/@characterxyz/server)
+and pass `getSessionToken={() => fetch('/api/characterxyz/session').then((r) => r.json())}` instead of a key.
+
+Create keys and choose the sites they may run on in **Character XYZ › Settings › Developers**.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import * as react from 'react';
+import { CharacterXYZ, CxError, ChatMessage, CallState, Call, InitOptions } from '@characterxyz/web';
+export { Call, CallState, ChatMessage, CxError } from '@characterxyz/web';
+import { MountOptions } from '@characterxyz/widget';
+
+interface CharacterXYZWidgetProps extends MountOptions {
+    onReady?: (detail: {
+        agent: {
+            id: string;
+            name: string;
+        };
+    }) => void;
+    onOpen?: (view: 'chat' | 'call') => void;
+    onClose?: () => void;
+    onError?: (detail: {
+        code: string;
+        message: string;
+    }) => void;
+}
+interface CharacterXYZWidgetRef {
+    open(view?: 'chat' | 'call'): void;
+    close(): void;
+}
+/**
+ * The ready-made widget. Renders nothing in your tree: the widget lives in
+ * its own element at the end of <body>. Re-mounts when the key or agent changes.
+ */
+declare const CharacterXYZWidget: react.ForwardRefExoticComponent<CharacterXYZWidgetProps & react.RefAttributes<CharacterXYZWidgetRef>>;
+interface UseCharacterXYZ {
+    client: CharacterXYZ | null;
+    error: CxError | null;
+    messages: readonly ChatMessage[];
+    busy: boolean;
+    send(text: string): Promise<void>;
+    call: CallState | null;
+    startCall(): Promise<Call | null>;
+}
+/** The headless SDK as React state, for brands building their own UI. */
+declare function useCharacterXYZ(options: InitOptions): UseCharacterXYZ;
+
+export { CharacterXYZWidget, type CharacterXYZWidgetProps, type CharacterXYZWidgetRef, type UseCharacterXYZ, useCharacterXYZ };

package/dist/index.js

@@ -0,0 +1,3 @@
+'use client';
+import{CharacterXYZ as E}from"@characterxyz/web";import{mount as X}from"@characterxyz/widget";import{forwardRef as Y,useEffect as m,useImperativeHandle as Z,useRef as v,useState as d}from"react";var M=Y(function(r,h){let l=v(null),a=v(r);return a.current=r,Z(h,()=>({open:s=>l.current?.open(s),close:()=>l.current?.close()})),m(()=>{let{onReady:s,onOpen:p,onClose:y,onError:f,...g}=a.current,c=X(g);l.current=c;let i=c.element,n=(e,t)=>{let u=x=>t(x);return i.addEventListener(e,u),()=>i.removeEventListener(e,u)},C=[n("cx-ready",e=>a.current.onReady?.(e.detail)),n("cx-open",e=>a.current.onOpen?.(e.detail.view)),n("cx-close",()=>a.current.onClose?.()),n("cx-error",e=>a.current.onError?.(e.detail))];return()=>{C.forEach(e=>e()),c.destroy(),l.current=null}},[r.publishableKey,r.agentId,r.apiUrl]),null});function O(o){let[r,h]=d(null),[l,a]=d(null),[s,p]=d([]),[y,f]=d(!1),[g,c]=d(null),i=v(o);return i.current=o,m(()=>{let n=!1,C=null,e=[];return E.init(i.current).then(t=>{if(n)return t.destroy();C=t,h(t),e.push(t.chat.on("messages",p),t.chat.on("busy",f)),e.push(t.on("call",u=>{u&&e.push(u.on("state",c))})),t.chat.load().catch(()=>{})},t=>!n&&a(t)),()=>{n=!0,e.forEach(t=>t()),C?.destroy()}},[o.publishableKey,o.agentId,o.apiUrl]),{client:r,error:l,messages:s,busy:y,call:g,send:async n=>{await r?.chat.send(n)},startCall:async()=>r?r.startCall():null}}export{M as CharacterXYZWidget,O as useCharacterXYZ};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.tsx"],"sourcesContent":["/**\n * `@characterxyz/react`\n *\n * ```tsx\n * import { CharacterXYZWidget } from '@characterxyz/react';\n *\n * <CharacterXYZWidget publishableKey=\"cxyz_pk_live_…\" accent=\"#e11d48\" onReady={(a) => track(a)} />\n * ```\n *\n * Or build your own UI on the headless SDK:\n *\n * ```tsx\n * const { client, messages, send, startCall, call } = useCharacterXYZ({ publishableKey });\n * ```\n */\nimport { CharacterXYZ, type Call, type CallState, type ChatMessage, type CxError, type InitOptions } from '@characterxyz/web';\nimport { mount, type MountOptions, type WidgetHandle } from '@characterxyz/widget';\nimport { forwardRef, useEffect, useImperativeHandle, useRef, useState } from 'react';\n\nexport interface CharacterXYZWidgetProps extends MountOptions {\n  onReady?: (detail: { agent: { id: string; name: string } }) => void;\n  onOpen?: (view: 'chat' | 'call') => void;\n  onClose?: () => void;\n  onError?: (detail: { code: string; message: string }) => void;\n}\n\nexport interface CharacterXYZWidgetRef {\n  open(view?: 'chat' | 'call'): void;\n  close(): void;\n}\n\n/**\n * The ready-made widget. Renders nothing in your tree: the widget lives in\n * its own element at the end of <body>. Re-mounts when the key or agent changes.\n */\nexport const CharacterXYZWidget = forwardRef<CharacterXYZWidgetRef, CharacterXYZWidgetProps>(function CharacterXYZWidget(props, ref) {\n  const handle = useRef<WidgetHandle | null>(null);\n  const latest = useRef(props);\n  latest.current = props;\n\n  useImperativeHandle(ref, () => ({\n    open: (v) => handle.current?.open(v),\n    close: () => handle.current?.close(),\n  }));\n\n  useEffect(() => {\n    const { onReady, onOpen, onClose, onError, ...opts } = latest.current;\n    void onReady;\n    void onOpen;\n    void onClose;\n    void onError;\n    const w = mount(opts);\n    handle.current = w;\n    const el = w.element;\n    const on = (name: string, fn: (e: CustomEvent) => void) => {\n      const h = (e: Event) => fn(e as CustomEvent);\n      el.addEventListener(name, h);\n      return () => el.removeEventListener(name, h);\n    };\n    const offs = [\n      on('cx-ready', (e) => latest.current.onReady?.(e.detail)),\n      on('cx-open', (e) => latest.current.onOpen?.(e.detail.view)),\n      on('cx-close', () => latest.current.onClose?.()),\n      on('cx-error', (e) => latest.current.onError?.(e.detail)),\n    ];\n    return () => {\n      offs.forEach((f) => f());\n      w.destroy();\n      handle.current = null;\n    };\n    // The widget's look is read at mount; a new key or agent is a new widget.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [props.publishableKey, props.agentId, props.apiUrl]);\n\n  return null;\n});\n\nexport interface UseCharacterXYZ {\n  client: CharacterXYZ | null;\n  error: CxError | null;\n  messages: readonly ChatMessage[];\n  busy: boolean;\n  send(text: string): Promise<void>;\n  call: CallState | null;\n  startCall(): Promise<Call | null>;\n}\n\n/** The headless SDK as React state, for brands building their own UI. */\nexport function useCharacterXYZ(options: InitOptions): UseCharacterXYZ {\n  const [client, setClient] = useState<CharacterXYZ | null>(null);\n  const [error, setError] = useState<CxError | null>(null);\n  const [messages, setMessages] = useState<readonly ChatMessage[]>([]);\n  const [busy, setBusy] = useState(false);\n  const [call, setCall] = useState<CallState | null>(null);\n  const opts = useRef(options);\n  opts.current = options;\n\n  useEffect(() => {\n    let cancelled = false;\n    let c: CharacterXYZ | null = null;\n    const offs: Array<() => void> = [];\n    CharacterXYZ.init(opts.current).then(\n      (cl) => {\n        if (cancelled) return cl.destroy();\n        c = cl;\n        setClient(cl);\n        offs.push(cl.chat.on('messages', setMessages), cl.chat.on('busy', setBusy));\n        offs.push(\n          cl.on('call', (k) => {\n            if (k) offs.push(k.on('state', setCall));\n          }),\n        );\n        void cl.chat.load().catch(() => {});\n      },\n      (e) => !cancelled && setError(e),\n    );\n    return () => {\n      cancelled = true;\n      offs.forEach((f) => f());\n      c?.destroy();\n    };\n  }, [options.publishableKey, options.agentId, options.apiUrl]);\n\n  return {\n    client,\n    error,\n    messages,\n    busy,\n    call,\n    send: async (text) => {\n      await client?.chat.send(text);\n    },\n    startCall: async () => (client ? client.startCall() : null),\n  };\n}\n\nexport type { Call, CallState, ChatMessage, CxError } from '@characterxyz/web';\n"],"mappings":"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","names":["CharacterXYZ","mount","forwardRef","useEffect","useImperativeHandle","useRef","useState","CharacterXYZWidget","props","ref","handle","latest","v","onReady","onOpen","onClose","onError","opts","w","el","on","name","fn","h","e","offs","f","useCharacterXYZ","options","client","setClient","error","setError","messages","setMessages","busy","setBusy","call","setCall","cancelled","c","cl","k","text"]}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@characterxyz/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Character XYZ for React: the widget as a component, and hooks over the headless SDK.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "react": ">=17"
+  },
+  "dependencies": {
+    "@characterxyz/web": "^0.1.1",
+    "@characterxyz/widget": "^0.1.1"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/characterxyz/characterxyz-sdk.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://character.xyz",
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }