@customerhero/js 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CustomerHero
+
+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

@@ -0,0 +1,61 @@
+# @customerhero/js
+
+Framework-agnostic JavaScript client for the [CustomerHero](https://customerhero.app) chat widget. Use this package directly in vanilla JS / TS apps, or via the React bindings in [`@customerhero/react`](https://www.npmjs.com/package/@customerhero/react).
+
+## Install
+
+```bash
+npm install @customerhero/js
+```
+
+## Quick start
+
+```ts
+import { CustomerHeroChat } from "@customerhero/js";
+
+const chat = new CustomerHeroChat({
+  chatbotId: "bot_xxxxxxxxxxxxxxxxxxxx",
+});
+
+chat.subscribe((state) => {
+  // React to state changes — messages, open/closed, loading, etc.
+});
+
+chat.open();
+await chat.sendMessage("Hello!");
+```
+
+## Identify a signed-in user
+
+Link conversations to a user in your system by calling `identify` as soon as you know who the user is.
+
+```ts
+chat.identify({
+  userId: "usr_123",
+  email: "jane@example.com",
+  name: "Jane Doe",
+  // Optional HMAC for identity verification (recommended in production)
+  userHash: "<hmac-sha256(userId, secret)>",
+});
+```
+
+## Configuration
+
+| Option              | Type                              | Description                                                                 |
+| ------------------- | --------------------------------- | --------------------------------------------------------------------------- |
+| `chatbotId`         | `string` (required)               | The chatbot to connect to.                                                  |
+| `apiBase`           | `string`                          | API base URL. Defaults to `https://customerhero.app`.                       |
+| `primaryColor`      | `string`                          | Accent color override.                                                      |
+| `backgroundColor`   | `string`                          | Chat window background override.                                            |
+| `textColor`         | `string`                          | Text color override.                                                        |
+| `position`          | `"bottom-right" \| "bottom-left"` | Widget position.                                                            |
+| `placeholderText`   | `string`                          | Input placeholder override.                                                 |
+| `welcomeMessage`    | `string`                          | Welcome message override.                                                   |
+| `title`             | `string`                          | Header title override.                                                      |
+| `avatarUrl`         | `string`                          | Bot avatar URL override.                                                    |
+| `locale`            | `string`                          | Widget locale (e.g. `"en"`, `"es"`). Auto-detected from browser if omitted. |
+| `suggestedMessages` | `string[]`                        | Quick-reply options shown before the first message.                         |
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,324 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CustomerHeroChat: () => CustomerHeroChat,
+  DEFAULTS: () => DEFAULTS
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/defaults.ts
+var DEFAULTS = {
+  apiBase: "https://customerhero.app",
+  primaryColor: "#6C3CE1",
+  backgroundColor: "#FFFFFF",
+  textColor: "#1A1A2E",
+  position: "bottom-right",
+  placeholderText: "Type your message...",
+  welcomeMessage: "Hi! How can I help you today?",
+  title: "CustomerHero"
+};
+
+// src/i18n.ts
+var en = {
+  online: "Online",
+  typing: "Typing...",
+  unable_to_load: "Unable to load chat",
+  powered_by: "Powered by",
+  new_conversation: "New conversation",
+  open_chat: "Open chat",
+  close_chat: "Close chat",
+  send_message: "Send message",
+  helpful: "Helpful",
+  not_helpful: "Not helpful",
+  menu: "Menu"
+};
+var es = {
+  online: "En l\xEDnea",
+  typing: "Escribiendo...",
+  unable_to_load: "No se pudo cargar el chat",
+  powered_by: "Desarrollado por",
+  new_conversation: "Nueva conversaci\xF3n",
+  open_chat: "Abrir chat",
+  close_chat: "Cerrar chat",
+  send_message: "Enviar mensaje",
+  helpful: "\xDAtil",
+  not_helpful: "No \xFAtil",
+  menu: "Men\xFA"
+};
+var locales = { en, es };
+function createTranslate(locale) {
+  const resolved = resolveLocale(locale);
+  const translations = locales[resolved] ?? en;
+  return (key) => translations[key] ?? en[key] ?? key;
+}
+function resolveLocale(locale) {
+  if (locale) {
+    const base = locale.split("-")[0].toLowerCase();
+    if (locales[base]) return base;
+  }
+  if (typeof navigator !== "undefined" && navigator.language) {
+    const base = navigator.language.split("-")[0].toLowerCase();
+    if (locales[base]) return base;
+  }
+  return "en";
+}
+
+// src/client.ts
+function resolveConfig(userConfig, fetched) {
+  return {
+    chatbotId: userConfig.chatbotId,
+    apiBase: userConfig.apiBase ?? DEFAULTS.apiBase,
+    primaryColor: userConfig.primaryColor ?? fetched?.primaryColor ?? DEFAULTS.primaryColor,
+    backgroundColor: userConfig.backgroundColor ?? fetched?.backgroundColor ?? DEFAULTS.backgroundColor,
+    textColor: userConfig.textColor ?? fetched?.textColor ?? DEFAULTS.textColor,
+    position: userConfig.position ?? fetched?.position ?? DEFAULTS.position,
+    placeholderText: userConfig.placeholderText ?? fetched?.placeholderText ?? DEFAULTS.placeholderText,
+    welcomeMessage: userConfig.welcomeMessage ?? fetched?.welcomeMessage ?? DEFAULTS.welcomeMessage,
+    title: userConfig.title ?? fetched?.title ?? DEFAULTS.title,
+    avatarUrl: userConfig.avatarUrl ?? fetched?.avatarUrl,
+    suggestedMessages: userConfig.suggestedMessages ?? fetched?.suggestedMessages ?? []
+  };
+}
+function getStorage() {
+  try {
+    return typeof window !== "undefined" ? window.localStorage : null;
+  } catch {
+    return null;
+  }
+}
+var CustomerHeroChat = class {
+  state;
+  listeners = /* @__PURE__ */ new Set();
+  storage;
+  userConfig;
+  identityData = null;
+  t;
+  constructor(config) {
+    this.userConfig = config;
+    this.storage = getStorage();
+    this.t = createTranslate(config.locale);
+    const resolved = resolveConfig(config);
+    const storedConvId = this.storage?.getItem(`ch_conv_${config.chatbotId}`);
+    this.state = {
+      messages: [],
+      isOpen: false,
+      isLoading: false,
+      conversationId: storedConvId ?? null,
+      config: resolved,
+      configLoaded: false,
+      configError: null,
+      error: null,
+      identity: null
+    };
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  getState() {
+    return this.state;
+  }
+  setState(partial) {
+    this.state = { ...this.state, ...partial };
+    this.notifyListeners();
+  }
+  notifyListeners() {
+    for (const listener of this.listeners) {
+      listener(this.state);
+    }
+  }
+  async fetchConfig() {
+    const { chatbotId } = this.userConfig;
+    const apiBase = this.userConfig.apiBase ?? DEFAULTS.apiBase;
+    try {
+      const response = await fetch(`${apiBase}/api/widget/${chatbotId}/config`);
+      if (!response.ok) {
+        throw new Error(`Failed to fetch config: ${response.status}`);
+      }
+      const fetched = await response.json();
+      const resolved = resolveConfig(this.userConfig, fetched);
+      this.setState({ config: resolved, configLoaded: true });
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : "Failed to load widget config";
+      console.error("CustomerHero: Failed to fetch widget config", error);
+      this.setState({
+        configLoaded: true,
+        configError: errorMsg
+      });
+      return;
+    }
+    if (this.state.conversationId) {
+      await this.loadHistory();
+    }
+  }
+  async loadHistory() {
+    const { chatbotId, apiBase } = this.state.config;
+    const { conversationId } = this.state;
+    if (!conversationId) return;
+    try {
+      const response = await fetch(
+        `${apiBase}/api/chat/${chatbotId}/messages/${conversationId}`
+      );
+      if (!response.ok) {
+        this.storage?.removeItem(`ch_conv_${chatbotId}`);
+        this.setState({ conversationId: null });
+        return;
+      }
+      const data = await response.json();
+      const messages = (data.messages ?? []).map(
+        (m) => ({
+          id: m.id,
+          role: m.role,
+          content: m.content
+        })
+      );
+      if (messages.length > 0) {
+        this.setState({ messages });
+      }
+    } catch {
+    }
+  }
+  async sendMessage(message) {
+    const trimmed = message.trim();
+    if (!trimmed || this.state.isLoading) return;
+    const userMsg = { role: "user", content: trimmed };
+    this.setState({
+      messages: [...this.state.messages, userMsg],
+      isLoading: true,
+      error: null
+    });
+    const { chatbotId } = this.state.config;
+    const apiBase = this.state.config.apiBase;
+    try {
+      const response = await fetch(`${apiBase}/api/chat/${chatbotId}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          message: trimmed,
+          ...this.state.conversationId ? { conversationId: this.state.conversationId } : {},
+          ...this.identityData ? { identity: this.identityData } : {}
+        })
+      });
+      if (!response.ok) {
+        const data2 = await response.json().catch(() => null);
+        const errorMsg = data2?.error ?? `Request failed: ${response.status}`;
+        throw new Error(errorMsg);
+      }
+      const data = await response.json();
+      const botMsg = {
+        id: data.messageId,
+        role: "bot",
+        content: data.message
+      };
+      const conversationId = data.conversationId ?? this.state.conversationId;
+      if (conversationId) {
+        this.storage?.setItem(`ch_conv_${chatbotId}`, conversationId);
+      }
+      this.setState({
+        messages: [...this.state.messages, botMsg],
+        isLoading: false,
+        conversationId
+      });
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : "Something went wrong";
+      this.setState({
+        isLoading: false,
+        error: errorMsg
+      });
+    }
+  }
+  async rateMessage(messageId, rating) {
+    const { chatbotId, apiBase } = this.state.config;
+    const { conversationId } = this.state;
+    if (!conversationId) return;
+    try {
+      await fetch(`${apiBase}/api/chat/${chatbotId}/rate`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ conversationId, messageId, rating })
+      });
+    } catch (error) {
+      console.error("CustomerHero: Failed to rate message", error);
+    }
+  }
+  toggle() {
+    const willOpen = !this.state.isOpen;
+    if (willOpen && this.state.messages.length === 0 && !this.state.conversationId && this.state.config.welcomeMessage) {
+      this.setState({
+        isOpen: true,
+        messages: [{ role: "bot", content: this.state.config.welcomeMessage }]
+      });
+    } else {
+      this.setState({ isOpen: willOpen });
+    }
+  }
+  open() {
+    if (!this.state.isOpen) this.toggle();
+  }
+  close() {
+    if (this.state.isOpen) this.setState({ isOpen: false });
+  }
+  reset() {
+    const { chatbotId, welcomeMessage } = this.state.config;
+    this.storage?.removeItem(`ch_conv_${chatbotId}`);
+    this.setState({
+      messages: welcomeMessage ? [{ role: "bot", content: welcomeMessage }] : [],
+      conversationId: null,
+      isLoading: false,
+      error: null
+    });
+  }
+  identify(payload) {
+    const { userId, email, name, phone, company, userHash, ...rest } = payload;
+    const customProperties = {};
+    for (const [k, v] of Object.entries(rest)) {
+      if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+        customProperties[k] = v;
+      }
+    }
+    this.identityData = {
+      userId,
+      email,
+      name,
+      phone,
+      company,
+      userHash,
+      customProperties: Object.keys(customProperties).length > 0 ? customProperties : void 0
+    };
+    const { chatbotId, welcomeMessage } = this.state.config;
+    this.storage?.removeItem(`ch_conv_${chatbotId}`);
+    this.setState({
+      messages: welcomeMessage ? [{ role: "bot", content: welcomeMessage }] : [],
+      conversationId: null,
+      isLoading: false,
+      error: null,
+      identity: this.identityData
+    });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CustomerHeroChat,
+  DEFAULTS
+});

package/dist/index.d.cts

@@ -0,0 +1,122 @@
+type TranslationKey = "online" | "typing" | "unable_to_load" | "powered_by" | "new_conversation" | "open_chat" | "close_chat" | "send_message" | "helpful" | "not_helpful" | "menu";
+type TranslateFn = (key: TranslationKey) => string;
+
+interface CustomerHeroChatConfig {
+    /** The chatbot ID to connect to */
+    chatbotId: string;
+    /** API base URL (defaults to "https://customerhero.app") */
+    apiBase?: string;
+    /** Override primary/accent color */
+    primaryColor?: string;
+    /** Override chat window background color */
+    backgroundColor?: string;
+    /** Override text color */
+    textColor?: string;
+    /** Widget position */
+    position?: "bottom-right" | "bottom-left";
+    /** Override input placeholder text */
+    placeholderText?: string;
+    /** Override welcome message */
+    welcomeMessage?: string;
+    /** Override header title */
+    title?: string;
+    /** Override avatar URL */
+    avatarUrl?: string;
+    /** Widget locale (e.g. "en", "es"). Auto-detected from browser if omitted. */
+    locale?: string;
+    /** Predefined quick-reply options shown before the user sends a message */
+    suggestedMessages?: string[];
+}
+interface ResolvedConfig {
+    chatbotId: string;
+    apiBase: string;
+    primaryColor: string;
+    backgroundColor: string;
+    textColor: string;
+    position: "bottom-right" | "bottom-left";
+    placeholderText: string;
+    welcomeMessage: string;
+    title: string;
+    avatarUrl?: string;
+    suggestedMessages: string[];
+}
+interface ChatMessage {
+    /** Message ID from the API (only present for bot messages) */
+    id?: string;
+    role: "user" | "bot";
+    content: string;
+}
+type MessageRating = "positive" | "negative";
+interface IdentifyPayload {
+    /** Stable unique user ID from your system (required) */
+    userId: string;
+    /** User's email address */
+    email?: string;
+    /** User's display name */
+    name?: string;
+    /** User's phone number */
+    phone?: string;
+    /** User's company name */
+    company?: string;
+    /** HMAC-SHA256 hash for identity verification */
+    userHash?: string;
+    /** Additional custom properties (string, number, or boolean values) */
+    [key: string]: unknown;
+}
+interface IdentityData {
+    userId: string;
+    email?: string;
+    name?: string;
+    phone?: string;
+    company?: string;
+    userHash?: string;
+    customProperties?: Record<string, string | number | boolean>;
+}
+interface ChatState {
+    messages: ChatMessage[];
+    isOpen: boolean;
+    isLoading: boolean;
+    conversationId: string | null;
+    config: ResolvedConfig;
+    configLoaded: boolean;
+    configError: string | null;
+    error: string | null;
+    identity: IdentityData | null;
+}
+
+type Listener = (state: ChatState) => void;
+declare class CustomerHeroChat {
+    private state;
+    private listeners;
+    private storage;
+    private userConfig;
+    private identityData;
+    readonly t: TranslateFn;
+    constructor(config: CustomerHeroChatConfig);
+    subscribe(listener: Listener): () => void;
+    getState(): ChatState;
+    private setState;
+    private notifyListeners;
+    fetchConfig(): Promise<void>;
+    private loadHistory;
+    sendMessage(message: string): Promise<void>;
+    rateMessage(messageId: string, rating: MessageRating): Promise<void>;
+    toggle(): void;
+    open(): void;
+    close(): void;
+    reset(): void;
+    identify(payload: IdentifyPayload): void;
+}
+
+declare const DEFAULTS: {
+    apiBase: string;
+    primaryColor: string;
+    backgroundColor: string;
+    textColor: string;
+    position: "bottom-right";
+    placeholderText: string;
+    welcomeMessage: string;
+    title: string;
+};
+
+export { type ChatMessage, type ChatState, CustomerHeroChat, type CustomerHeroChatConfig, DEFAULTS, type IdentifyPayload, type IdentityData, type MessageRating, type ResolvedConfig, type TranslateFn, type TranslationKey };

package/dist/index.d.ts

@@ -0,0 +1,122 @@
+type TranslationKey = "online" | "typing" | "unable_to_load" | "powered_by" | "new_conversation" | "open_chat" | "close_chat" | "send_message" | "helpful" | "not_helpful" | "menu";
+type TranslateFn = (key: TranslationKey) => string;
+
+interface CustomerHeroChatConfig {
+    /** The chatbot ID to connect to */
+    chatbotId: string;
+    /** API base URL (defaults to "https://customerhero.app") */
+    apiBase?: string;
+    /** Override primary/accent color */
+    primaryColor?: string;
+    /** Override chat window background color */
+    backgroundColor?: string;
+    /** Override text color */
+    textColor?: string;
+    /** Widget position */
+    position?: "bottom-right" | "bottom-left";
+    /** Override input placeholder text */
+    placeholderText?: string;
+    /** Override welcome message */
+    welcomeMessage?: string;
+    /** Override header title */
+    title?: string;
+    /** Override avatar URL */
+    avatarUrl?: string;
+    /** Widget locale (e.g. "en", "es"). Auto-detected from browser if omitted. */
+    locale?: string;
+    /** Predefined quick-reply options shown before the user sends a message */
+    suggestedMessages?: string[];
+}
+interface ResolvedConfig {
+    chatbotId: string;
+    apiBase: string;
+    primaryColor: string;
+    backgroundColor: string;
+    textColor: string;
+    position: "bottom-right" | "bottom-left";
+    placeholderText: string;
+    welcomeMessage: string;
+    title: string;
+    avatarUrl?: string;
+    suggestedMessages: string[];
+}
+interface ChatMessage {
+    /** Message ID from the API (only present for bot messages) */
+    id?: string;
+    role: "user" | "bot";
+    content: string;
+}
+type MessageRating = "positive" | "negative";
+interface IdentifyPayload {
+    /** Stable unique user ID from your system (required) */
+    userId: string;
+    /** User's email address */
+    email?: string;
+    /** User's display name */
+    name?: string;
+    /** User's phone number */
+    phone?: string;
+    /** User's company name */
+    company?: string;
+    /** HMAC-SHA256 hash for identity verification */
+    userHash?: string;
+    /** Additional custom properties (string, number, or boolean values) */
+    [key: string]: unknown;
+}
+interface IdentityData {
+    userId: string;
+    email?: string;
+    name?: string;
+    phone?: string;
+    company?: string;
+    userHash?: string;
+    customProperties?: Record<string, string | number | boolean>;
+}
+interface ChatState {
+    messages: ChatMessage[];
+    isOpen: boolean;
+    isLoading: boolean;
+    conversationId: string | null;
+    config: ResolvedConfig;
+    configLoaded: boolean;
+    configError: string | null;
+    error: string | null;
+    identity: IdentityData | null;
+}
+
+type Listener = (state: ChatState) => void;
+declare class CustomerHeroChat {
+    private state;
+    private listeners;
+    private storage;
+    private userConfig;
+    private identityData;
+    readonly t: TranslateFn;
+    constructor(config: CustomerHeroChatConfig);
+    subscribe(listener: Listener): () => void;
+    getState(): ChatState;
+    private setState;
+    private notifyListeners;
+    fetchConfig(): Promise<void>;
+    private loadHistory;
+    sendMessage(message: string): Promise<void>;
+    rateMessage(messageId: string, rating: MessageRating): Promise<void>;
+    toggle(): void;
+    open(): void;
+    close(): void;
+    reset(): void;
+    identify(payload: IdentifyPayload): void;
+}
+
+declare const DEFAULTS: {
+    apiBase: string;
+    primaryColor: string;
+    backgroundColor: string;
+    textColor: string;
+    position: "bottom-right";
+    placeholderText: string;
+    welcomeMessage: string;
+    title: string;
+};
+
+export { type ChatMessage, type ChatState, CustomerHeroChat, type CustomerHeroChatConfig, DEFAULTS, type IdentifyPayload, type IdentityData, type MessageRating, type ResolvedConfig, type TranslateFn, type TranslationKey };

package/dist/index.js

@@ -0,0 +1,296 @@
+// src/defaults.ts
+var DEFAULTS = {
+  apiBase: "https://customerhero.app",
+  primaryColor: "#6C3CE1",
+  backgroundColor: "#FFFFFF",
+  textColor: "#1A1A2E",
+  position: "bottom-right",
+  placeholderText: "Type your message...",
+  welcomeMessage: "Hi! How can I help you today?",
+  title: "CustomerHero"
+};
+
+// src/i18n.ts
+var en = {
+  online: "Online",
+  typing: "Typing...",
+  unable_to_load: "Unable to load chat",
+  powered_by: "Powered by",
+  new_conversation: "New conversation",
+  open_chat: "Open chat",
+  close_chat: "Close chat",
+  send_message: "Send message",
+  helpful: "Helpful",
+  not_helpful: "Not helpful",
+  menu: "Menu"
+};
+var es = {
+  online: "En l\xEDnea",
+  typing: "Escribiendo...",
+  unable_to_load: "No se pudo cargar el chat",
+  powered_by: "Desarrollado por",
+  new_conversation: "Nueva conversaci\xF3n",
+  open_chat: "Abrir chat",
+  close_chat: "Cerrar chat",
+  send_message: "Enviar mensaje",
+  helpful: "\xDAtil",
+  not_helpful: "No \xFAtil",
+  menu: "Men\xFA"
+};
+var locales = { en, es };
+function createTranslate(locale) {
+  const resolved = resolveLocale(locale);
+  const translations = locales[resolved] ?? en;
+  return (key) => translations[key] ?? en[key] ?? key;
+}
+function resolveLocale(locale) {
+  if (locale) {
+    const base = locale.split("-")[0].toLowerCase();
+    if (locales[base]) return base;
+  }
+  if (typeof navigator !== "undefined" && navigator.language) {
+    const base = navigator.language.split("-")[0].toLowerCase();
+    if (locales[base]) return base;
+  }
+  return "en";
+}
+
+// src/client.ts
+function resolveConfig(userConfig, fetched) {
+  return {
+    chatbotId: userConfig.chatbotId,
+    apiBase: userConfig.apiBase ?? DEFAULTS.apiBase,
+    primaryColor: userConfig.primaryColor ?? fetched?.primaryColor ?? DEFAULTS.primaryColor,
+    backgroundColor: userConfig.backgroundColor ?? fetched?.backgroundColor ?? DEFAULTS.backgroundColor,
+    textColor: userConfig.textColor ?? fetched?.textColor ?? DEFAULTS.textColor,
+    position: userConfig.position ?? fetched?.position ?? DEFAULTS.position,
+    placeholderText: userConfig.placeholderText ?? fetched?.placeholderText ?? DEFAULTS.placeholderText,
+    welcomeMessage: userConfig.welcomeMessage ?? fetched?.welcomeMessage ?? DEFAULTS.welcomeMessage,
+    title: userConfig.title ?? fetched?.title ?? DEFAULTS.title,
+    avatarUrl: userConfig.avatarUrl ?? fetched?.avatarUrl,
+    suggestedMessages: userConfig.suggestedMessages ?? fetched?.suggestedMessages ?? []
+  };
+}
+function getStorage() {
+  try {
+    return typeof window !== "undefined" ? window.localStorage : null;
+  } catch {
+    return null;
+  }
+}
+var CustomerHeroChat = class {
+  state;
+  listeners = /* @__PURE__ */ new Set();
+  storage;
+  userConfig;
+  identityData = null;
+  t;
+  constructor(config) {
+    this.userConfig = config;
+    this.storage = getStorage();
+    this.t = createTranslate(config.locale);
+    const resolved = resolveConfig(config);
+    const storedConvId = this.storage?.getItem(`ch_conv_${config.chatbotId}`);
+    this.state = {
+      messages: [],
+      isOpen: false,
+      isLoading: false,
+      conversationId: storedConvId ?? null,
+      config: resolved,
+      configLoaded: false,
+      configError: null,
+      error: null,
+      identity: null
+    };
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  getState() {
+    return this.state;
+  }
+  setState(partial) {
+    this.state = { ...this.state, ...partial };
+    this.notifyListeners();
+  }
+  notifyListeners() {
+    for (const listener of this.listeners) {
+      listener(this.state);
+    }
+  }
+  async fetchConfig() {
+    const { chatbotId } = this.userConfig;
+    const apiBase = this.userConfig.apiBase ?? DEFAULTS.apiBase;
+    try {
+      const response = await fetch(`${apiBase}/api/widget/${chatbotId}/config`);
+      if (!response.ok) {
+        throw new Error(`Failed to fetch config: ${response.status}`);
+      }
+      const fetched = await response.json();
+      const resolved = resolveConfig(this.userConfig, fetched);
+      this.setState({ config: resolved, configLoaded: true });
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : "Failed to load widget config";
+      console.error("CustomerHero: Failed to fetch widget config", error);
+      this.setState({
+        configLoaded: true,
+        configError: errorMsg
+      });
+      return;
+    }
+    if (this.state.conversationId) {
+      await this.loadHistory();
+    }
+  }
+  async loadHistory() {
+    const { chatbotId, apiBase } = this.state.config;
+    const { conversationId } = this.state;
+    if (!conversationId) return;
+    try {
+      const response = await fetch(
+        `${apiBase}/api/chat/${chatbotId}/messages/${conversationId}`
+      );
+      if (!response.ok) {
+        this.storage?.removeItem(`ch_conv_${chatbotId}`);
+        this.setState({ conversationId: null });
+        return;
+      }
+      const data = await response.json();
+      const messages = (data.messages ?? []).map(
+        (m) => ({
+          id: m.id,
+          role: m.role,
+          content: m.content
+        })
+      );
+      if (messages.length > 0) {
+        this.setState({ messages });
+      }
+    } catch {
+    }
+  }
+  async sendMessage(message) {
+    const trimmed = message.trim();
+    if (!trimmed || this.state.isLoading) return;
+    const userMsg = { role: "user", content: trimmed };
+    this.setState({
+      messages: [...this.state.messages, userMsg],
+      isLoading: true,
+      error: null
+    });
+    const { chatbotId } = this.state.config;
+    const apiBase = this.state.config.apiBase;
+    try {
+      const response = await fetch(`${apiBase}/api/chat/${chatbotId}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          message: trimmed,
+          ...this.state.conversationId ? { conversationId: this.state.conversationId } : {},
+          ...this.identityData ? { identity: this.identityData } : {}
+        })
+      });
+      if (!response.ok) {
+        const data2 = await response.json().catch(() => null);
+        const errorMsg = data2?.error ?? `Request failed: ${response.status}`;
+        throw new Error(errorMsg);
+      }
+      const data = await response.json();
+      const botMsg = {
+        id: data.messageId,
+        role: "bot",
+        content: data.message
+      };
+      const conversationId = data.conversationId ?? this.state.conversationId;
+      if (conversationId) {
+        this.storage?.setItem(`ch_conv_${chatbotId}`, conversationId);
+      }
+      this.setState({
+        messages: [...this.state.messages, botMsg],
+        isLoading: false,
+        conversationId
+      });
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : "Something went wrong";
+      this.setState({
+        isLoading: false,
+        error: errorMsg
+      });
+    }
+  }
+  async rateMessage(messageId, rating) {
+    const { chatbotId, apiBase } = this.state.config;
+    const { conversationId } = this.state;
+    if (!conversationId) return;
+    try {
+      await fetch(`${apiBase}/api/chat/${chatbotId}/rate`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ conversationId, messageId, rating })
+      });
+    } catch (error) {
+      console.error("CustomerHero: Failed to rate message", error);
+    }
+  }
+  toggle() {
+    const willOpen = !this.state.isOpen;
+    if (willOpen && this.state.messages.length === 0 && !this.state.conversationId && this.state.config.welcomeMessage) {
+      this.setState({
+        isOpen: true,
+        messages: [{ role: "bot", content: this.state.config.welcomeMessage }]
+      });
+    } else {
+      this.setState({ isOpen: willOpen });
+    }
+  }
+  open() {
+    if (!this.state.isOpen) this.toggle();
+  }
+  close() {
+    if (this.state.isOpen) this.setState({ isOpen: false });
+  }
+  reset() {
+    const { chatbotId, welcomeMessage } = this.state.config;
+    this.storage?.removeItem(`ch_conv_${chatbotId}`);
+    this.setState({
+      messages: welcomeMessage ? [{ role: "bot", content: welcomeMessage }] : [],
+      conversationId: null,
+      isLoading: false,
+      error: null
+    });
+  }
+  identify(payload) {
+    const { userId, email, name, phone, company, userHash, ...rest } = payload;
+    const customProperties = {};
+    for (const [k, v] of Object.entries(rest)) {
+      if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+        customProperties[k] = v;
+      }
+    }
+    this.identityData = {
+      userId,
+      email,
+      name,
+      phone,
+      company,
+      userHash,
+      customProperties: Object.keys(customProperties).length > 0 ? customProperties : void 0
+    };
+    const { chatbotId, welcomeMessage } = this.state.config;
+    this.storage?.removeItem(`ch_conv_${chatbotId}`);
+    this.setState({
+      messages: welcomeMessage ? [{ role: "bot", content: welcomeMessage }] : [],
+      conversationId: null,
+      isLoading: false,
+      error: null,
+      identity: this.identityData
+    });
+  }
+};
+export {
+  CustomerHeroChat,
+  DEFAULTS
+};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@customerhero/js",
+  "version": "0.0.1",
+  "private": false,
+  "description": "Framework-agnostic JavaScript client for the CustomerHero chat widget.",
+  "keywords": [
+    "customerhero",
+    "chat",
+    "chatbot",
+    "customer-support",
+    "widget",
+    "sdk"
+  ],
+  "homepage": "https://customerhero.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/customerhero/customerhero-sdk.git",
+    "directory": "packages/js"
+  },
+  "bugs": {
+    "url": "https://github.com/customerhero/customerhero-sdk/issues"
+  },
+  "license": "MIT",
+  "author": "CustomerHero",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.9"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}