npm package: @glorified0561/ukti-voice-widget
Description: A React-based voice agent widget for web applications
Author: glorified0561
Latest version: 1.0.1

# UKTI Widget

A React-based voice agent widget for web applications that provides AI-powered conversational interfaces.

## Installation

### From npm Registry

```bash
npm install @glorified0561/ukti-voice-widget
```

### From GitHub Packages (Alternative)

If you need to install from GitHub Packages instead, configure your `.npmrc` file:

```bash
echo "@glorified0561:registry=https://npm.pkg.github.com" >> .npmrc
echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN" >> .npmrc
```

Then install:

```bash
npm install @glorified0561/ukti-voice-widget
```

### CDN Usage

For direct browser usage without a build step:

#### jsDelivr (Recommended)

```html
<!-- Include the widget CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@glorified0561/ukti-voice-widget@latest/dist-widget/ukti-widget.css">

<!-- Include the widget JavaScript -->
<script src="https://cdn.jsdelivr.net/npm/@glorified0561/ukti-voice-widget@latest/dist-widget/ukti-widget.js"></script>
```

#### Alternative CDN Options

**UNPKG:**
```html
<link rel="stylesheet" href="https://unpkg.com/@glorified0561/ukti-voice-widget@latest/dist-widget/ukti-widget.css">
<script src="https://unpkg.com/@glorified0561/ukti-voice-widget@latest/dist-widget/ukti-widget.js"></script>
```

**Skypack:**
```html
<link rel="stylesheet" href="https://cdn.skypack.dev/@glorified0561/ukti-voice-widget@latest/dist-widget/ukti-widget.css">
<script src="https://cdn.skypack.dev/@glorified0561/ukti-voice-widget@latest/dist-widget/ukti-widget.js"></script>
```

> **Note:** Replace `@latest` with a specific version number (e.g., `@1.0.0`) for production use to ensure consistency.

## Usage

### As a React Component

```jsx
import { UKTIWidget } from '@glorified0561/ukti-voice-widget'
import '@glorified0561/ukti-voice-widget/dist/ukti-widget.css'

function App() {
  const [isOpen, setIsOpen] = useState(false)

  return (
    <div>
      <button onClick={() => setIsOpen(true)}>
        Open Voice Agent
      </button>
      
      <UKTIWidget
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        apiUrl="https://your-api-url.com"
        agentId="your-agent-id"
        theme="light"
      />
    </div>
  )
}
```

### CDN/Browser Usage

```html
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@glorified0561/ukti-voice-widget@latest/dist-widget/ukti-widget.css">
</head>
<body>
  <!-- Your page content -->
  <button onclick="openUKTIWidget()">Open Voice Agent</button>

  <!-- Widget script -->
  <script src="https://cdn.jsdelivr.net/npm/@glorified0561/ukti-voice-widget@latest/dist-widget/ukti-widget.js" data-auto-init></script>
  
  <script>
    // Configure the widget (optional)
    initUKTIWidget({
      apiUrl: 'https://your-api-url.com',
      agentId: 'your-agent-id',
      theme: 'light'
    })
  </script>
</body>
</html>
```

## API Reference

### Components

#### UKTIWidget

Main widget component for React applications.

**Props:**
- `isOpen?: boolean` - Controls widget visibility
- `onClose?: () => void` - Callback when widget is closed
- `apiUrl?: string` - API endpoint URL
- `agentId?: string` - Agent identifier
- `theme?: 'light' | 'dark'` - Visual theme

#### AgentWidget

Standalone agent component without modal wrapper.

**Props:**
- `apiUrl?: string` - API endpoint URL
- `agentId?: string` - Agent identifier
- `theme?: 'light' | 'dark'` - Visual theme

### Global Functions (CDN Usage)

#### `initUKTIWidget(options?)`

Initialize the widget with configuration options.

```javascript
initUKTIWidget({
  apiUrl: 'https://your-api-url.com',
  agentId: 'your-agent-id',
  theme: 'light'
})
```

#### `openUKTIWidget()`

Open the widget modal.

#### `closeUKTIWidget()`

Close the widget modal.

#### `toggleUKTIWidget()`

Toggle widget modal open/closed state.

#### `destroyUKTIWidget()`

Completely remove the widget from the page.

## Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiUrl` | string | - | API endpoint for the voice agent |
| `agentId` | string | - | Unique identifier for the agent |
| `theme` | 'light' \| 'dark' | 'light' | Visual theme |
| `isOpen` | boolean | false | Initial open state (React only) |
| `onClose` | function | - | Close callback (React only) |

## Development

### Building

```bash
# Build library version (for npm)
npm run build:lib

# Build widget version (for CDN)
npm run build:widget

# Build both versions
npm run build:all
```

### Publishing

The package is automatically published to GitHub Packages when you:

1. Push a git tag starting with `v` (e.g., `v1.0.0`)
2. Manually trigger the publish workflow

To publish manually:

```bash
# Bump version and create tag
npm version patch  # or minor, major
git push origin main --tags

# Or use GitHub Actions workflow dispatch
```

## License

MIT

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## Support

For issues and questions, please use the [GitHub Issues](https://github.com/knacklabs/ukti-voice-widget/issues) page.