@orello/react 0.1.3

package/README.md

@@ -0,0 +1,72 @@
+# <img src="https://www.orello.space/_next/image?url=%2Ficons%2Forello.png&w=48&q=75" width="32" height="32" valign="middle" /> @orello/react
+
+React wrapper for embedding the **[Orello AI](https://orello.space)** widget. Supports real-time voice transcription, synthesis, and autonomous site navigation.
+
+> [!IMPORTANT]
+> **Orello AI** requires an active API key to connect to the assistant service. Sign up or log in at **[orello.space](https://orello.space)** to create your keys!
+
+### 🔑 Step-by-Step API Key Setup
+1. **Visit the Dashboard:** Go to **[orello.space](https://orello.space)** and log in.
+2. **Generate Key:** Navigate to **Developer Settings** > **API Keys** and click **Generate New Key**.
+3. **Save & Embed:** Copy the key and pass it as the `widgetKey` prop to the `<OrelloWidget>` component.
+
+## ✨ Features
+
+- **Voice-First**: Deepgram & ElevenLabs integration with browser fallbacks.
+- **Multimodal**: Visual page capture for AI awareness.
+- **Type-Safe**: Full TypeScript support.
+
+## Install
+
+```bash
+npm install @orello/react
+```
+
+## Basic Usage
+
+```tsx
+import { OrelloWidget } from "@orello/react";
+
+function App() {
+  return (
+    <>
+      <YourApp />
+      <OrelloWidget widgetKey="YOUR_WIDGET_KEY" />
+    </>
+  );
+}
+
+export default App;
+```
+
+## Recommended Usage (Explicit Assistant)
+
+```tsx
+<OrelloWidget
+  widgetKey="YOUR_WIDGET_KEY"
+  assistantId="ASSISTANT_UID"
+/>
+```
+
+## Props
+
+- `widgetKey` (required): Widget API key sent as `X-Api-Key`.
+- `assistantId` (optional): Assistant UID for `/api/v1/assistants/public/{agentId}`.
+- `scriptSrc` (optional): Embed script URL. Default: `https://cdn.orello.ai/orello.js`.
+- `apiBase` (optional): API base URL.
+- `agentEndpoint` (optional): Assistant endpoint template with `{agentId}`.
+- `widgetUrl` (optional): Widget iframe URL.
+- `wakeWord` (optional): Enables wake-word listener. Default: `true`.
+- `onReady` (optional): Called when `orello:ready` is emitted.
+- `onError` (optional): Called when `orello:error` is emitted.
+- `cleanupOnUnmount` (optional): Removes script + widget on unmount. Default: `false`.
+
+## Runtime API
+
+After init, runtime is exposed at `window.OrelloWidget`.
+
+```ts
+window.OrelloWidget?.open();
+window.OrelloWidget?.close();
+window.OrelloWidget?.toggle();
+```

package/dist/index.cjs

@@ -0,0 +1,137 @@
+"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, {
+  OrelloWidget: () => OrelloWidget
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/OrelloWidget.tsx
+var import_react = require("react");
+var DEFAULT_SCRIPT_SRC = "https://cdn.orello.ai/orello.js";
+function setOptionalAttribute(el, name, value) {
+  if (!value) return;
+  el.setAttribute(name, value);
+}
+function getExistingScript(scriptSrc) {
+  var _a;
+  const scripts = Array.from(document.querySelectorAll("script[src]"));
+  return (_a = scripts.find(
+    (item) => item.getAttribute("data-orello-react") === "true" && item.getAttribute("src") === scriptSrc
+  )) != null ? _a : null;
+}
+function OrelloWidget({
+  widgetKey,
+  assistantId,
+  scriptSrc = DEFAULT_SCRIPT_SRC,
+  apiBase,
+  agentEndpoint,
+  widgetUrl,
+  wakeWord = true,
+  onReady,
+  onError,
+  cleanupOnUnmount = false
+}) {
+  (0, import_react.useEffect)(() => {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      return;
+    }
+    if (!widgetKey || !widgetKey.trim()) {
+      console.error("[Orello React] Missing required prop: widgetKey");
+      return;
+    }
+    const handleReady = (event) => {
+      onReady == null ? void 0 : onReady(event);
+    };
+    const handleError = (event) => {
+      onError == null ? void 0 : onError(event);
+    };
+    window.addEventListener("orello:ready", handleReady);
+    window.addEventListener("orello:error", handleError);
+    const resolvedScriptSrc = scriptSrc.trim() || DEFAULT_SCRIPT_SRC;
+    const existingScript = getExistingScript(resolvedScriptSrc);
+    if (!existingScript) {
+      const script = document.createElement("script");
+      script.src = resolvedScriptSrc;
+      script.async = true;
+      script.setAttribute("data-orello-react", "true");
+      script.setAttribute("data-api-key", widgetKey);
+      script.setAttribute("data-key", widgetKey);
+      script.setAttribute("data-wake-word", wakeWord ? "true" : "false");
+      setOptionalAttribute(script, "data-agent-id", assistantId);
+      setOptionalAttribute(script, "data-api-base", apiBase);
+      setOptionalAttribute(script, "data-agent-endpoint", agentEndpoint);
+      setOptionalAttribute(script, "data-widget-url", widgetUrl);
+      document.head.appendChild(script);
+      return () => {
+        window.removeEventListener("orello:ready", handleReady);
+        window.removeEventListener("orello:error", handleError);
+        if (cleanupOnUnmount) {
+          const root = document.getElementById("orello-widget-root");
+          if (root) root.remove();
+          script.remove();
+          delete window.OrelloWidget;
+        }
+      };
+    }
+    existingScript.setAttribute("data-api-key", widgetKey);
+    existingScript.setAttribute("data-key", widgetKey);
+    existingScript.setAttribute("data-wake-word", wakeWord ? "true" : "false");
+    if (assistantId) {
+      existingScript.setAttribute("data-agent-id", assistantId);
+    }
+    if (apiBase) {
+      existingScript.setAttribute("data-api-base", apiBase);
+    }
+    if (agentEndpoint) {
+      existingScript.setAttribute("data-agent-endpoint", agentEndpoint);
+    }
+    if (widgetUrl) {
+      existingScript.setAttribute("data-widget-url", widgetUrl);
+    }
+    return () => {
+      window.removeEventListener("orello:ready", handleReady);
+      window.removeEventListener("orello:error", handleError);
+      if (cleanupOnUnmount) {
+        const root = document.getElementById("orello-widget-root");
+        if (root) root.remove();
+        existingScript.remove();
+        delete window.OrelloWidget;
+      }
+    };
+  }, [
+    widgetKey,
+    assistantId,
+    scriptSrc,
+    apiBase,
+    agentEndpoint,
+    widgetUrl,
+    wakeWord,
+    onReady,
+    onError,
+    cleanupOnUnmount
+  ]);
+  return null;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  OrelloWidget
+});

package/dist/index.d.cts

@@ -0,0 +1,70 @@
+type OrelloAgent = {
+    uid?: string;
+    name?: string;
+    description?: string;
+    firstMessage?: string;
+    voiceId?: string;
+    status?: string;
+    metadata?: Record<string, unknown>;
+};
+type OrelloWidgetConfig = {
+    agentId?: string;
+    apiBase?: string;
+    widgetUrl?: string;
+};
+type OrelloPointer = {
+    x: number;
+    y: number;
+};
+type OrelloWidgetActions = {
+    click: (selectorOrElement: string | Element) => boolean;
+    buttonClick: (selectorOrElement: string | Element) => boolean;
+    doubleClick: (selectorOrElement: string | Element) => boolean;
+    clickHold: (selectorOrElement: string | Element, durationMs?: number) => boolean;
+    scroll: (deltaX: number, deltaY: number, behavior?: ScrollBehavior) => void;
+    scrollBy: (deltaX: number, deltaY: number, behavior?: ScrollBehavior) => void;
+    touchScroll: (deltaY: number) => void;
+    mouseMove: (x: number, y: number) => OrelloPointer;
+    zoomIn: (step?: number) => number;
+    zoomOut: (step?: number) => number;
+    highlight: (selectorOrElement: string | Element, durationMs?: number) => boolean;
+    getPointer: () => OrelloPointer;
+    getZoom: () => number;
+};
+type OrelloRuntimeApi = {
+    version: string;
+    config: OrelloWidgetConfig;
+    agent?: OrelloAgent;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    actions: OrelloWidgetActions;
+    getDom: (path?: string) => unknown;
+};
+type OrelloReadyEvent = CustomEvent<{
+    agent?: OrelloAgent;
+}>;
+type OrelloErrorEvent = CustomEvent<{
+    message?: string;
+}>;
+declare global {
+    interface Window {
+        OrelloWidget?: OrelloRuntimeApi;
+    }
+}
+
+type OrelloWidgetProps = {
+    widgetKey: string;
+    assistantId?: string;
+    scriptSrc?: string;
+    apiBase?: string;
+    agentEndpoint?: string;
+    widgetUrl?: string;
+    wakeWord?: boolean;
+    onReady?: (event: OrelloReadyEvent) => void;
+    onError?: (event: OrelloErrorEvent) => void;
+    cleanupOnUnmount?: boolean;
+};
+declare function OrelloWidget({ widgetKey, assistantId, scriptSrc, apiBase, agentEndpoint, widgetUrl, wakeWord, onReady, onError, cleanupOnUnmount, }: OrelloWidgetProps): null;
+
+export { type OrelloAgent, type OrelloErrorEvent, type OrelloReadyEvent, type OrelloRuntimeApi, OrelloWidget, type OrelloWidgetActions, type OrelloWidgetConfig, type OrelloWidgetProps };

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+type OrelloAgent = {
+    uid?: string;
+    name?: string;
+    description?: string;
+    firstMessage?: string;
+    voiceId?: string;
+    status?: string;
+    metadata?: Record<string, unknown>;
+};
+type OrelloWidgetConfig = {
+    agentId?: string;
+    apiBase?: string;
+    widgetUrl?: string;
+};
+type OrelloPointer = {
+    x: number;
+    y: number;
+};
+type OrelloWidgetActions = {
+    click: (selectorOrElement: string | Element) => boolean;
+    buttonClick: (selectorOrElement: string | Element) => boolean;
+    doubleClick: (selectorOrElement: string | Element) => boolean;
+    clickHold: (selectorOrElement: string | Element, durationMs?: number) => boolean;
+    scroll: (deltaX: number, deltaY: number, behavior?: ScrollBehavior) => void;
+    scrollBy: (deltaX: number, deltaY: number, behavior?: ScrollBehavior) => void;
+    touchScroll: (deltaY: number) => void;
+    mouseMove: (x: number, y: number) => OrelloPointer;
+    zoomIn: (step?: number) => number;
+    zoomOut: (step?: number) => number;
+    highlight: (selectorOrElement: string | Element, durationMs?: number) => boolean;
+    getPointer: () => OrelloPointer;
+    getZoom: () => number;
+};
+type OrelloRuntimeApi = {
+    version: string;
+    config: OrelloWidgetConfig;
+    agent?: OrelloAgent;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    actions: OrelloWidgetActions;
+    getDom: (path?: string) => unknown;
+};
+type OrelloReadyEvent = CustomEvent<{
+    agent?: OrelloAgent;
+}>;
+type OrelloErrorEvent = CustomEvent<{
+    message?: string;
+}>;
+declare global {
+    interface Window {
+        OrelloWidget?: OrelloRuntimeApi;
+    }
+}
+
+type OrelloWidgetProps = {
+    widgetKey: string;
+    assistantId?: string;
+    scriptSrc?: string;
+    apiBase?: string;
+    agentEndpoint?: string;
+    widgetUrl?: string;
+    wakeWord?: boolean;
+    onReady?: (event: OrelloReadyEvent) => void;
+    onError?: (event: OrelloErrorEvent) => void;
+    cleanupOnUnmount?: boolean;
+};
+declare function OrelloWidget({ widgetKey, assistantId, scriptSrc, apiBase, agentEndpoint, widgetUrl, wakeWord, onReady, onError, cleanupOnUnmount, }: OrelloWidgetProps): null;
+
+export { type OrelloAgent, type OrelloErrorEvent, type OrelloReadyEvent, type OrelloRuntimeApi, OrelloWidget, type OrelloWidgetActions, type OrelloWidgetConfig, type OrelloWidgetProps };

package/dist/index.js

@@ -0,0 +1,110 @@
+// src/OrelloWidget.tsx
+import { useEffect } from "react";
+var DEFAULT_SCRIPT_SRC = "https://cdn.orello.ai/orello.js";
+function setOptionalAttribute(el, name, value) {
+  if (!value) return;
+  el.setAttribute(name, value);
+}
+function getExistingScript(scriptSrc) {
+  var _a;
+  const scripts = Array.from(document.querySelectorAll("script[src]"));
+  return (_a = scripts.find(
+    (item) => item.getAttribute("data-orello-react") === "true" && item.getAttribute("src") === scriptSrc
+  )) != null ? _a : null;
+}
+function OrelloWidget({
+  widgetKey,
+  assistantId,
+  scriptSrc = DEFAULT_SCRIPT_SRC,
+  apiBase,
+  agentEndpoint,
+  widgetUrl,
+  wakeWord = true,
+  onReady,
+  onError,
+  cleanupOnUnmount = false
+}) {
+  useEffect(() => {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      return;
+    }
+    if (!widgetKey || !widgetKey.trim()) {
+      console.error("[Orello React] Missing required prop: widgetKey");
+      return;
+    }
+    const handleReady = (event) => {
+      onReady == null ? void 0 : onReady(event);
+    };
+    const handleError = (event) => {
+      onError == null ? void 0 : onError(event);
+    };
+    window.addEventListener("orello:ready", handleReady);
+    window.addEventListener("orello:error", handleError);
+    const resolvedScriptSrc = scriptSrc.trim() || DEFAULT_SCRIPT_SRC;
+    const existingScript = getExistingScript(resolvedScriptSrc);
+    if (!existingScript) {
+      const script = document.createElement("script");
+      script.src = resolvedScriptSrc;
+      script.async = true;
+      script.setAttribute("data-orello-react", "true");
+      script.setAttribute("data-api-key", widgetKey);
+      script.setAttribute("data-key", widgetKey);
+      script.setAttribute("data-wake-word", wakeWord ? "true" : "false");
+      setOptionalAttribute(script, "data-agent-id", assistantId);
+      setOptionalAttribute(script, "data-api-base", apiBase);
+      setOptionalAttribute(script, "data-agent-endpoint", agentEndpoint);
+      setOptionalAttribute(script, "data-widget-url", widgetUrl);
+      document.head.appendChild(script);
+      return () => {
+        window.removeEventListener("orello:ready", handleReady);
+        window.removeEventListener("orello:error", handleError);
+        if (cleanupOnUnmount) {
+          const root = document.getElementById("orello-widget-root");
+          if (root) root.remove();
+          script.remove();
+          delete window.OrelloWidget;
+        }
+      };
+    }
+    existingScript.setAttribute("data-api-key", widgetKey);
+    existingScript.setAttribute("data-key", widgetKey);
+    existingScript.setAttribute("data-wake-word", wakeWord ? "true" : "false");
+    if (assistantId) {
+      existingScript.setAttribute("data-agent-id", assistantId);
+    }
+    if (apiBase) {
+      existingScript.setAttribute("data-api-base", apiBase);
+    }
+    if (agentEndpoint) {
+      existingScript.setAttribute("data-agent-endpoint", agentEndpoint);
+    }
+    if (widgetUrl) {
+      existingScript.setAttribute("data-widget-url", widgetUrl);
+    }
+    return () => {
+      window.removeEventListener("orello:ready", handleReady);
+      window.removeEventListener("orello:error", handleError);
+      if (cleanupOnUnmount) {
+        const root = document.getElementById("orello-widget-root");
+        if (root) root.remove();
+        existingScript.remove();
+        delete window.OrelloWidget;
+      }
+    };
+  }, [
+    widgetKey,
+    assistantId,
+    scriptSrc,
+    apiBase,
+    agentEndpoint,
+    widgetUrl,
+    wakeWord,
+    onReady,
+    onError,
+    cleanupOnUnmount
+  ]);
+  return null;
+}
+export {
+  OrelloWidget
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@orello/react",
+  "version": "0.1.3",
+  "description": "React wrapper for the Orello AI widget — embed intelligent conversational assistants into any React application.",
+  "author": "Orello Team <hello@orello.space>",
+  "license": "MIT",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/orello.space/orello.git",
+    "directory": "libs/react"
+  },
+  "keywords": [
+    "ai",
+    "react",
+    "chat-widget",
+    "conversational-ai",
+    "customer-support",
+    "agent",
+    "orello"
+  ],
+  "bugs": {
+    "url": "https://github.com/orello.space/orello/issues"
+  },
+  "homepage": "https://orello.space",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --minify",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "clean": "rm -rf dist",
+    "deploy": "npm run build && npm publish"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3"
+  }
+}