# @cloudcorp/widget

Embeddable voice AI widget. Add real-time voice agents to any website with a single script tag or npm import. Supports React, Vue, Angular, and Svelte.

## Install

```bash
npm install @cloudcorp/widget
```

## Quick Start

### Script Tag (CDN)

```html
<script
  src="https://unpkg.com/@cloudcorp/widget/dist/cloudvoice.js"
  data-agent="your-agent-id"
  data-server="https://your-server.com"
></script>
```

### ES Module

```js
import { Widget } from '@cloudcorp/widget'

const widget = new Widget({
  agent: 'your-agent-id',
  server: 'https://your-server.com',
})

widget.on('transcript', ({ role, text }) => {
  console.log(`${role}: ${text}`)
})
```

## Framework Integration

### React

```tsx
import { CloudVoice, useCloudVoice } from '@cloudcorp/widget/react'

// Component
function App() {
  return (
    <CloudVoice
      agent="your-agent-id"
      server="https://your-server.com"
      onTranscript={({ role, text }) => console.log(`${role}: ${text}`)}
      onReady={({ agentName }) => console.log(`Connected to ${agentName}`)}
    />
  )
}

// Hook
function App() {
  const { ready, sendText, close } = useCloudVoice({
    agent: 'your-agent-id',
    server: 'https://your-server.com',
  })

  return <div>{ready ? 'Connected' : 'Connecting...'}</div>
}
```

### Vue

```vue
<script setup>
import { CloudVoice, useCloudVoice } from '@cloudcorp/widget/vue'

// Composable
const { ready, sendText, close } = useCloudVoice({
  agent: 'your-agent-id',
  server: 'https://your-server.com',
})
</script>

<template>
  <!-- Or use the component with events -->
  <CloudVoice
    agent="your-agent-id"
    server="https://your-server.com"
    @transcript="({ role, text }) => console.log(`${role}: ${text}`)"
    @ready="({ agentName }) => console.log(`Connected to ${agentName}`)"
  />
</template>
```

### Angular

```typescript
import { CloudVoiceDirective } from '@cloudcorp/widget/angular'

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [CloudVoiceDirective],
  template: `
    <div
      cloudVoice
      [agent]="'your-agent-id'"
      [server]="'https://your-server.com'"
      (cvTranscript)="onTranscript($event)"
      (cvReady)="onReady($event)"
    ></div>
  `,
})
export class AppComponent {
  onTranscript({ role, text }) {
    console.log(`${role}: ${text}`)
  }
  onReady({ agentName }) {
    console.log(`Connected to ${agentName}`)
  }
}
```

### Svelte

```svelte
<script>
  import { cloudVoice, createCloudVoice } from '@cloudcorp/widget/svelte'

  // Action
  const params = {
    agent: 'your-agent-id',
    server: 'https://your-server.com',
    onTranscript: ({ role, text }) => console.log(`${role}: ${text}`),
  }

  // Or programmatic
  const { widget, sendText, close } = createCloudVoice({
    agent: 'your-agent-id',
    server: 'https://your-server.com',
  })
</script>

<div use:cloudVoice={params}></div>
```

## Configuration

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `agent` | `string` | Yes | Agent ID to connect to |
| `server` | `string` | No | Server URL. Defaults to current page origin |
| `apiKey` | `string` | No | API key for cross-origin usage |
| `sessionToken` | `string` | No | One-time session token (alternative to apiKey) |
| `platform` | `string` | No | Platform identifier. Default: `'widget'` |
| `idleText` | `string` | No | Text shown in idle state |
| `modes` | `InteractionMode[]` | No | Interaction modes to offer. Default: `['browser']` |
| `agentPhone` | `string` | No | Phone number for "I'll Call" mode |
| `whatsappNumber` | `string` | No | WhatsApp number for WhatsApp modes |
| `requireVerification` | `'email' \| 'phone' \| 'both' \| false` | No | OTP verification before connecting |
| `verifyMethod` | `'sms' \| 'voice' \| 'whatsapp'` | No | How to send verification codes. Default: `'sms'` |

## Interaction Modes

| Mode | Description |
|------|-------------|
| `browser` | Voice conversation directly in the browser |
| `callMe` | Agent calls the user's phone, transcript shows in widget |
| `illCall` | Shows a number to call, transcript shows in widget |
| `whatsapp` | Opens WhatsApp chat, transcript shows in widget |
| `whatsapp_call` | Voice call via WhatsApp number |

```html
<script
  src="https://unpkg.com/@cloudcorp/widget/dist/cloudvoice.js"
  data-agent="your-agent-id"
  data-modes="browser,callMe,whatsapp"
></script>
```

## Events

| Event | Payload | Description |
|-------|---------|-------------|
| `ready` | `{ agentName, version }` | Connected to agent |
| `transcript` | `{ role, text, isFinal }` | Speech transcript |
| `ended` | `{ reason }` | Conversation ended |
| `error` | `string` | Error message |
| `transfer` | `{ status, reason? }` | Human handoff status |
| `inputRequest` | `{ requestId, fieldName, fieldType, label, ... }` | Agent requesting user input |

## Methods

| Method | Description |
|--------|-------------|
| `sendText(text)` | Send a text message |
| `close()` | End the current session |
| `destroy()` | Remove the widget from the page |
| `on(event, handler)` | Listen for events |
| `off(event, handler)` | Remove event listener |

## CDN Data Attributes

All configuration can be set via `data-*` attributes on the script tag:

```html
<script
  src="https://unpkg.com/@cloudcorp/widget/dist/cloudvoice.js"
  data-agent="your-agent-id"
  data-server="https://your-server.com"
  data-api-key="cv_xxxxx"
  data-modes="browser,callMe,illCall,whatsapp,whatsapp_call"
  data-agent-phone="+1234567890"
  data-whatsapp-number="+1234567890"
  data-require-verification="phone"
  data-verify-method="voice"
  data-idle-text="Hi! How can I help?"
></script>
```

## License

UNLICENSED - proprietary software by [CloudCorp](https://cloudcorp.ai)