@warpy-ai/widget

Tiny, framework-agnostic loader for the Warpy embeddable widget.

This package does not bundle the widget UI. It simply injects the Warpy widget <script> (widget.js) and passes configuration via data-* attributes.

Install

npm i @warpy-ai/widget
# or
pnpm add @warpy-ai/widget
# or
yarn add @warpy-ai/widget

Quick start (vanilla)

import { mountWidget } from "@warpy-ai/widget"

const widget = mountWidget({
  agentId: "YOUR_AGENT_UUID",
  baseUrl: "https://YOUR_DASHBOARD_BASE_URL/",
  scriptSrc: "https://cdn.warpy.ai/widget.js"
})

// later
widget.unmount()

React

import { Widget } from "@warpy-ai/widget/react"

export function App() {
  return (
    <Widget
      agentId="YOUR_AGENT_UUID"
      baseUrl="https://YOUR_DASHBOARD_BASE_URL/"
      scriptSrc="https://cdn.warpy.ai/widget.js"
    />
  )
}

Vue

<script setup lang="ts">
import { Widget } from "@warpy-ai/widget/vue"
</script>

<template>
  <Widget
    agentId="YOUR_AGENT_UUID"
    scriptSrc="https://cdn.warpy.ai/widget.js"
  />
</template>

Svelte

<script>
  import Widget from "@warpy-ai/widget/svelte"
</script>

<Widget
  agentId="YOUR_AGENT_UUID"
  scriptSrc="https://cdn.warpy.ai/widget.js"
/>

Script tag (no package)

<script
  src="https://cdn.warpy.ai/widget.js"
  data-agent-id="YOUR_AGENT_UUID"
  data-base-url="https://YOUR_DASHBOARD_BASE_URL/"
></script>

Frontend-only mode (optional)

If you only use frontend actions/context tools and do not need backend endpoint tools or widget token refresh, you can omit baseUrl.

import { mountWidget } from "@warpy-ai/widget"

const widget = mountWidget({
  agentId: "YOUR_AGENT_UUID",
  scriptSrc: "https://cdn.warpy.ai/widget.js"
})

API

mountWidget(options)

options:

• agentId (required): Warpy agent UUID
• baseUrl (optional): your dashboard base URL (only needed when backend endpoint tools or widget token refresh must call your app backend)
• scriptSrc (required): URL to widget.js (e.g. https://cdn.warpy.ai/widget.js)
• containerId (optional): DOM id for the injected widget container

Returns:

• { unmount() }: removes the injected container + script

License

MIT