@dabalabs/agent 0.0.1-beta

package/README.md

@@ -0,0 +1,193 @@
+# daba-agent
+
+Embeddable voice AI assistant widget for [dabalabs](https://dabalabs.com) projects. Drop it into any site and visitors can press **Ctrl+Space**, talk in any language, and get a spoken reply — the agent can also read the page, fill out and submit forms, and navigate to other pages on request.
+
+Works natively in **Plain HTML**, **React**, **Next.js**, **Vue**, **Nuxt**, **Svelte**, **SvelteKit**, **Astro**, and any modern JavaScript stack.
+
+## Install
+
+```bash
+npm install @dabalabs/agent
+```
+
+## Quick Start
+
+### 1. Web Component (`<daba-agent>`) — Works in Any JS Framework / HTML
+
+Simply import `@dabalabs/agent` (or `@dabalabs/agent/custom-element`) and use `<daba-agent>` directly in your HTML or JSX/Vue/Svelte template:
+
+```html
+<daba-agent
+  project-id="YOUR_PROJECT_ID"
+  api-key="YOUR_API_KEY"
+  position="bottom-right"
+></daba-agent>
+```
+
+#### Plain HTML / Script Tag
+
+```html
+<script src="https://unpkg.com/@dabalabs/agent/dist/daba-agent.min.js"></script>
+<daba-agent project-id="YOUR_PROJECT_ID" api-key="YOUR_API_KEY"></daba-agent>
+```
+
+#### Vue 3 / Nuxt 3
+
+```vue
+<script setup>
+import '@dabalabs/agent/custom-element';
+</script>
+
+<template>
+  <daba-agent
+    project-id="YOUR_PROJECT_ID"
+    api-key="YOUR_API_KEY"
+    position="bottom-right"
+  />
+</template>
+```
+
+#### Svelte / SvelteKit / Astro
+
+```svelte
+<script>
+  import '@dabalabs/agent/custom-element';
+</script>
+
+<daba-agent project-id="YOUR_PROJECT_ID" api-key="YOUR_API_KEY" />
+```
+
+---
+
+### 2. React Component (`<DabaAgent />`) — React & Next.js
+
+```tsx
+"use client";
+
+import { DabaAgent } from "@dabalabs/agent/react";
+
+export function App() {
+  return (
+    <DabaAgent
+      projectId="YOUR_PROJECT_ID"
+      apiKey="YOUR_API_KEY"
+      position="bottom-right"
+      onStatusChange={(status) => console.log("Agent status:", status)}
+    />
+  );
+}
+```
+
+---
+
+### 3. Programmatic Class API (`new DabaAgent()`)
+
+```ts
+import { DabaAgent } from "@dabalabs/agent";
+
+const agent = new DabaAgent({
+  projectId: "YOUR_PROJECT_ID",
+  apiKey: "YOUR_API_KEY",
+  position: "bottom-right",
+});
+```
+
+Get a project ID and API key from the Developer section of your [dabalabs dashboard](https://dabalabs.com/dashboard/developer) — the same API key used for the [dabalabs](https://www.npmjs.com/package/dabalabs) video player works here too.
+
+## Custom Events on Web Component (`<daba-agent>`)
+
+The `<daba-agent>` element dispatches native DOM Custom Events:
+
+- `daba-status-change` (`e.detail.status`) — Fired when status changes (`idle`, `connecting`, `listening`, `thinking`, `speaking`)
+- `daba-transcript` (`e.detail: { role, text, isFinal }`) — Fired on user or agent transcript deltas
+- `daba-error` (`e.detail.error`) — Fired on network or session errors
+
+Example:
+```js
+const agentEl = document.querySelector('daba-agent');
+agentEl.addEventListener('daba-status-change', (e) => {
+  console.log('Status:', e.detail.status);
+});
+```
+
+## API keys are publishable
+
+The API key is meant to sit in your site's frontend source, the same trust model as a Stripe.js or Google Maps JS key. Server-side, it's restricted to the exact origins you list when you create it, and to the one agent project it was scoped to. It can't create, modify, or delete anything, and it can be revoked instantly from your dashboard.
+
+## Options
+
+| Option / Attribute | Type | Description |
+| --- | --- | --- |
+| `projectId` / `project-id` | `string` | Your agent project ID from the dashboard |
+| `apiKey` / `api-key` | `string` | Your publishable API key |
+| `position` | `"bottom-right" \| "bottom-left" \| "top-right" \| "top-left"` | Corner of the viewport for the default badge (default: `"bottom-right"`). |
+| `accentColor` / `accent-color` | `string` | Accent color hex for the badge's active-state indicator |
+| `hotkey` | `string \| null` | Keyboard shortcut to toggle the agent (default: `"ctrl+space"`). Pass `null` to disable. |
+| `gatewayUrl` / `gateway-url` | `string` (optional) | Base URL of the gateway (defaults to `"https://api.dabalabs.com"`) |
+| `onStatusChange` | `(status: DabaAgentStatus) => void` | Fired as the agent moves through status lifecycle (React / JS API) |
+| `onTranscript` | `(role: "user" \| "agent", text: string, isFinal: boolean) => void` | Fired with transcript deltas (React / JS API) |
+| `onError` | `(error: DabaError) => void` | Fired on connection or session errors (React / JS API) |
+
+## Methods (on `agent` instance or `element.dabaAgent`)
+
+- `agent.toggle()` — start or stop a session
+- `agent.destroy()` — tear down the session, remove the badge, and detach all listeners
+- `agent.currentStatus` — the current `DabaAgentStatus`
+- `agent.isActive` — whether a session is currently running
+
+## What the agent can do
+
+- **Talk.** Full duplex voice in and out over a single realtime connection — no separate transcription/TTS round trip.
+- **Read the page.** On session start, the agent is given the page title, visible text, navigable links, and form fields, so it can answer questions about the page and knows what it can act on.
+- **Fill out and submit forms.** The agent fills fields by label, then confirms with the visitor before submitting — it never submits silently. Password, card, and other sensitive-looking fields are refused outright, whether marked or not.
+- **Navigate.** Ask it to go to another page and it will, resuming the same conversation on the other side rather than starting over.
+
+## Security guards
+
+- `data-daba-agent-ignore` on any element (or a container) excludes it and its subtree from page reading and from form-filling.
+- `data-daba-agent-restricted` on `<html>`, or `<meta name="daba-agent-restricted">` in `<head>`, opts an entire page out — the agent won't read the page or start a session there at all. Use this on account, billing, or checkout pages.
+- Password fields, payment fields (`autocomplete="cc-*"`), and labels that read like a PIN or security code are never filled or spoken back, regardless of how the model was asked.
+
+## Browser support
+
+Requires `WebSocket`, `AudioContext`, and `getUserMedia` — every evergreen browser. The widget itself renders no UI beyond the floating badge, so it has no layout dependencies on the host page.
+
+## License
+
+MIT
+
+## Environments
+
+By default the widget talks to Dabalabs production. Point it at staging
+with `env`:
+
+```html
+<div data-daba-agent
+  data-project-id="YOUR_PROJECT_ID"
+  data-api-key="YOUR_API_KEY"
+  data-daba-env="staging"
+></div>
+```
+
+```js
+new DabaAgent({
+  // ...
+  env: "staging",
+});
+```
+
+| `env` | Gateway |
+|---|---|
+| omitted | `https://api.dabalabs.com` |
+| `"production"` | `https://api.dabalabs.com` |
+| `"staging"` | `https://api-staging.dabalabs.com` |
+
+Production is the default in every direction — an embed that says nothing
+about its environment is a live site, so staging has to be asked for by
+name. An unrecognised value warns in the console and falls back to
+production rather than throwing, so a typo cannot take a customer's page
+down.
+
+`gatewayUrl` still overrides `env` when both are given: it is the only
+option that can name a host neither tier covers (a self-hosted
+deployment, a local gateway).

package/custom-element.d.ts

@@ -0,0 +1 @@
+export * from "./dist/custom-element";

package/custom-element.js

@@ -0,0 +1 @@
+export * from "./dist/custom-element.js";

package/dist/chunk-EF6D33VT.cjs

@@ -0,0 +1,103 @@
+'use strict';
+
+var chunkN4TBGDUO_cjs = require('./chunk-N4TBGDUO.cjs');
+
+// src/components/custom-element.ts
+var DabaAgentElement = class extends HTMLElement {
+  constructor() {
+    super(...arguments);
+    this.agent = null;
+  }
+  connectedCallback() {
+    if (this.agent) return;
+    const getAttr = (name) => this.getAttribute(name) ?? this.getAttribute(`data-${name}`);
+    const projectId = getAttr("project-id");
+    const apiKey = getAttr("api-key");
+    if (!projectId || !apiKey) {
+      console.error(
+        "daba-agent: <daba-agent> custom element requires project-id and api-key attributes.",
+        this
+      );
+      return;
+    }
+    const position = getAttr("position") ?? void 0;
+    const accentColor = getAttr("accent-color") ?? void 0;
+    const mode = getAttr("mode") ?? void 0;
+    const title = getAttr("title") ?? void 0;
+    const placeholder = getAttr("placeholder") ?? void 0;
+    const initialOpen = this.hasAttribute("initial-open") || this.hasAttribute("data-initial-open");
+    const hotkey = getAttr("hotkey") ?? void 0;
+    const gatewayUrl = getAttr("gateway-url") ?? void 0;
+    this.agent = new chunkN4TBGDUO_cjs.DabaAgent({
+      container: this,
+      projectId,
+      apiKey,
+      position,
+      accentColor,
+      mode,
+      title,
+      placeholder,
+      initialOpen,
+      hotkey,
+      gatewayUrl,
+      onStatusChange: (status) => {
+        this.dispatchEvent(
+          new CustomEvent("daba-status-change", { detail: { status }, bubbles: true, composed: true })
+        );
+      },
+      onTranscript: (role, text, isFinal) => {
+        this.dispatchEvent(
+          new CustomEvent("daba-transcript", {
+            detail: { role, text, isFinal },
+            bubbles: true,
+            composed: true
+          })
+        );
+      },
+      onError: (error) => {
+        this.dispatchEvent(
+          new CustomEvent("daba-error", { detail: { error }, bubbles: true, composed: true })
+        );
+      },
+      onChatToggle: (isOpen) => {
+        this.dispatchEvent(
+          new CustomEvent("daba-chat-toggle", { detail: { isOpen }, bubbles: true, composed: true })
+        );
+      }
+    });
+  }
+  disconnectedCallback() {
+    if (this.agent) {
+      this.agent.destroy();
+      this.agent = null;
+    }
+  }
+  get dabaAgent() {
+    return this.agent;
+  }
+  sendText(text) {
+    return this.agent?.sendText(text);
+  }
+  openChat() {
+    this.agent?.openChat();
+  }
+  closeChat() {
+    this.agent?.closeChat();
+  }
+  toggleChat() {
+    this.agent?.toggleChat();
+  }
+};
+function defineDabaAgentElement(tagName = "daba-agent") {
+  if (typeof window !== "undefined" && typeof customElements !== "undefined") {
+    if (!customElements.get(tagName)) {
+      customElements.define(tagName, DabaAgentElement);
+    }
+  }
+}
+defineDabaAgentElement();
+
+exports.DabaAgentElement = DabaAgentElement;
+exports.defineDabaAgentElement = defineDabaAgentElement;
+//# sourceMappingURL=chunk-EF6D33VT.cjs.map
+//# sourceMappingURL=chunk-EF6D33VT.cjs.map

package/dist/chunk-EF6D33VT.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/components/custom-element.ts"],"names":["DabaAgent"],"mappings":";;;;;AAGO,IAAM,gBAAA,GAAN,cAA+B,WAAA,CAAY;AAAA,EAA3C,WAAA,GAAA;AAAA,IAAA,KAAA,CAAA,GAAA,SAAA,CAAA;AACL,IAAA,IAAA,CAAQ,KAAA,GAA0B,IAAA;AAAA,EAAA;AAAA,EAElC,iBAAA,GAA0B;AACxB,IAAA,IAAI,KAAK,KAAA,EAAO;AAEhB,IAAA,MAAM,OAAA,GAAU,CAAC,IAAA,KACf,IAAA,CAAK,YAAA,CAAa,IAAI,CAAA,IAAK,IAAA,CAAK,YAAA,CAAa,CAAA,KAAA,EAAQ,IAAI,CAAA,CAAE,CAAA;AAE7D,IAAA,MAAM,SAAA,GAAY,QAAQ,YAAY,CAAA;AACtC,IAAA,MAAM,MAAA,GAAS,QAAQ,SAAS,CAAA;AAEhC,IAAA,IAAI,CAAC,SAAA,IAAa,CAAC,MAAA,EAAQ;AACzB,MAAA,OAAA,CAAQ,KAAA;AAAA,QACN,qFAAA;AAAA,QACA;AAAA,OACF;AACA,MAAA;AAAA,IACF;AAEA,IAAA,MAAM,QAAA,GAAY,OAAA,CAAQ,UAAU,CAAA,IAA2B,MAAA;AAC/D,IAAA,MAAM,WAAA,GAAc,OAAA,CAAQ,cAAc,CAAA,IAAK,MAAA;AAC/C,IAAA,MAAM,IAAA,GAAQ,OAAA,CAAQ,MAAM,CAAA,IAAuB,MAAA;AACnD,IAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,OAAO,CAAA,IAAK,MAAA;AAClC,IAAA,MAAM,WAAA,GAAc,OAAA,CAAQ,aAAa,CAAA,IAAK,MAAA;AAC9C,IAAA,MAAM,cAAc,IAAA,CAAK,YAAA,CAAa,cAAc,CAAA,IAAK,IAAA,CAAK,aAAa,mBAAmB,CAAA;AAC9F,IAAA,MAAM,MAAA,GAAS,OAAA,CAAQ,QAAQ,CAAA,IAAK,MAAA;AACpC,IAAA,MAAM,UAAA,GAAa,OAAA,CAAQ,aAAa,CAAA,IAAK,MAAA;AAE7C,IAAA,IAAA,CAAK,KAAA,GAAQ,IAAIA,2BAAA,CAAU;AAAA,MACzB,SAAA,EAAW,IAAA;AAAA,MACX,SAAA;AAAA,MACA,MAAA;AAAA,MACA,QAAA;AAAA,MACA,WAAA;AAAA,MACA,IAAA;AAAA,MACA,KAAA;AAAA,MACA,WAAA;AAAA,MACA,WAAA;AAAA,MACA,MAAA;AAAA,MACA,UAAA;AAAA,MACA,cAAA,EAAgB,CAAC,MAAA,KAAW;AAC1B,QAAA,IAAA,CAAK,aAAA;AAAA,UACH,IAAI,WAAA,CAAY,oBAAA,EAAsB,EAAE,MAAA,EAAQ,EAAE,MAAA,EAAO,EAAG,OAAA,EAAS,IAAA,EAAM,QAAA,EAAU,IAAA,EAAM;AAAA,SAC7F;AAAA,MACF,CAAA;AAAA,MACA,YAAA,EAAc,CAAC,IAAA,EAAM,IAAA,EAAM,OAAA,KAAY;AACrC,QAAA,IAAA,CAAK,aAAA;AAAA,UACH,IAAI,YAAY,iBAAA,EAAmB;AAAA,YACjC,MAAA,EAAQ,EAAE,IAAA,EAAM,IAAA,EAAM,OAAA,EAAQ;AAAA,YAC9B,OAAA,EAAS,IAAA;AAAA,YACT,QAAA,EAAU;AAAA,WACX;AAAA,SACH;AAAA,MACF,CAAA;AAAA,MACA,OAAA,EAAS,CAAC,KAAA,KAAU;AAClB,QAAA,IAAA,CAAK,aAAA;AAAA,UACH,IAAI,WAAA,CAAY,YAAA,EAAc,EAAE,MAAA,EAAQ,EAAE,KAAA,EAAM,EAAG,OAAA,EAAS,IAAA,EAAM,QAAA,EAAU,IAAA,EAAM;AAAA,SACpF;AAAA,MACF,CAAA;AAAA,MACA,YAAA,EAAc,CAAC,MAAA,KAAW;AACxB,QAAA,IAAA,CAAK,aAAA;AAAA,UACH,IAAI,WAAA,CAAY,kBAAA,EAAoB,EAAE,MAAA,EAAQ,EAAE,MAAA,EAAO,EAAG,OAAA,EAAS,IAAA,EAAM,QAAA,EAAU,IAAA,EAAM;AAAA,SAC3F;AAAA,MACF;AAAA,KACD,CAAA;AAAA,EACH;AAAA,EAEA,oBAAA,GAA6B;AAC3B,IAAA,IAAI,KAAK,KAAA,EAAO;AACd,MAAA,IAAA,CAAK,MAAM,OAAA,EAAQ;AACnB,MAAA,IAAA,CAAK,KAAA,GAAQ,IAAA;AAAA,IACf;AAAA,EACF;AAAA,EAEA,IAAW,SAAA,GAA8B;AACvC,IAAA,OAAO,IAAA,CAAK,KAAA;AAAA,EACd;AAAA,EAEO,SAAS,IAAA,EAAyC;AACvD,IAAA,OAAO,IAAA,CAAK,KAAA,EAAO,QAAA,CAAS,IAAI,CAAA;AAAA,EAClC;AAAA,EAEO,QAAA,GAAiB;AACtB,IAAA,IAAA,CAAK,OAAO,QAAA,EAAS;AAAA,EACvB;AAAA,EAEO,SAAA,GAAkB;AACvB,IAAA,IAAA,CAAK,OAAO,SAAA,EAAU;AAAA,EACxB;AAAA,EAEO,UAAA,GAAmB;AACxB,IAAA,IAAA,CAAK,OAAO,UAAA,EAAW;AAAA,EACzB;AACF;AAEO,SAAS,sBAAA,CAAuB,UAAU,YAAA,EAAoB;AACnE,EAAA,IAAI,OAAO,MAAA,KAAW,WAAA,IAAe,OAAO,mBAAmB,WAAA,EAAa;AAC1E,IAAA,IAAI,CAAC,cAAA,CAAe,GAAA,CAAI,OAAO,CAAA,EAAG;AAChC,MAAA,cAAA,CAAe,MAAA,CAAO,SAAS,gBAAgB,CAAA;AAAA,IACjD;AAAA,EACF;AACF;AAEA,sBAAA,EAAuB","file":"chunk-EF6D33VT.cjs","sourcesContent":["import { DabaAgent } from \"../agent\";\nimport type { DabaAgentPosition, DabaAgentMode } from \"../types\";\n\nexport class DabaAgentElement extends HTMLElement {\n  private agent: DabaAgent | null = null;\n\n  connectedCallback(): void {\n    if (this.agent) return;\n\n    const getAttr = (name: string): string | null =>\n      this.getAttribute(name) ?? this.getAttribute(`data-${name}`);\n\n    const projectId = getAttr(\"project-id\");\n    const apiKey = getAttr(\"api-key\");\n\n    if (!projectId || !apiKey) {\n      console.error(\n        \"daba-agent: <daba-agent> custom element requires project-id and api-key attributes.\",\n        this,\n      );\n      return;\n    }\n\n    const position = (getAttr(\"position\") as DabaAgentPosition) ?? undefined;\n    const accentColor = getAttr(\"accent-color\") ?? undefined;\n    const mode = (getAttr(\"mode\") as DabaAgentMode) ?? undefined;\n    const title = getAttr(\"title\") ?? undefined;\n    const placeholder = getAttr(\"placeholder\") ?? undefined;\n    const initialOpen = this.hasAttribute(\"initial-open\") || this.hasAttribute(\"data-initial-open\");\n    const hotkey = getAttr(\"hotkey\") ?? undefined;\n    const gatewayUrl = getAttr(\"gateway-url\") ?? undefined;\n\n    this.agent = new DabaAgent({\n      container: this,\n      projectId,\n      apiKey,\n      position,\n      accentColor,\n      mode,\n      title,\n      placeholder,\n      initialOpen,\n      hotkey,\n      gatewayUrl,\n      onStatusChange: (status) => {\n        this.dispatchEvent(\n          new CustomEvent(\"daba-status-change\", { detail: { status }, bubbles: true, composed: true }),\n        );\n      },\n      onTranscript: (role, text, isFinal) => {\n        this.dispatchEvent(\n          new CustomEvent(\"daba-transcript\", {\n            detail: { role, text, isFinal },\n            bubbles: true,\n            composed: true,\n          }),\n        );\n      },\n      onError: (error) => {\n        this.dispatchEvent(\n          new CustomEvent(\"daba-error\", { detail: { error }, bubbles: true, composed: true }),\n        );\n      },\n      onChatToggle: (isOpen) => {\n        this.dispatchEvent(\n          new CustomEvent(\"daba-chat-toggle\", { detail: { isOpen }, bubbles: true, composed: true }),\n        );\n      },\n    });\n  }\n\n  disconnectedCallback(): void {\n    if (this.agent) {\n      this.agent.destroy();\n      this.agent = null;\n    }\n  }\n\n  public get dabaAgent(): DabaAgent | null {\n    return this.agent;\n  }\n\n  public sendText(text: string): Promise<void> | undefined {\n    return this.agent?.sendText(text);\n  }\n\n  public openChat(): void {\n    this.agent?.openChat();\n  }\n\n  public closeChat(): void {\n    this.agent?.closeChat();\n  }\n\n  public toggleChat(): void {\n    this.agent?.toggleChat();\n  }\n}\n\nexport function defineDabaAgentElement(tagName = \"daba-agent\"): void {\n  if (typeof window !== \"undefined\" && typeof customElements !== \"undefined\") {\n    if (!customElements.get(tagName)) {\n      customElements.define(tagName, DabaAgentElement);\n    }\n  }\n}\n\ndefineDabaAgentElement();\n"]}