npm package: @glydeunity/voice-sdk
Description: GLYDE Voice Agent SDK - AI-powered voice and text chat interactions for web applications
Author: GLYDE Inc.
Latest version: 1.6.32

# @glydeunity/voice-sdk

Customer and web developer guide for the packaged GLYDE Voice SDK.

Version: latest (see `package.json`)

## What You Get

- Drop-in CDN widget via `window.GlydeChat`
- Headless clients: `GlydeVoice`, `GlydeText`
- React components/hooks for custom app UIs

## CDN Widget (recommended)

### Auto-init script tag

```html
<script
  src="https://unpkg.com/@glydeunity/voice-sdk@latest/dist/glyde-chat.umd.js"
  data-publishable-key="YOUR_PUBLISHABLE_KEY"
  data-context-type="discovery"
  data-context-id="YOUR_CLIENT_UUID"
></script>
```

### Manual init

```html
<script src="https://unpkg.com/@glydeunity/voice-sdk@latest/dist/glyde-chat.umd.js"></script>
<script>
  GlydeChat.init({
    publishableKey: 'YOUR_PUBLISHABLE_KEY',
    contextType: 'screening',
    contextId: 'APPLICATION_UUID',
    unityBaseUrl: 'https://api.glydeunity.com',
    displayMode: 'floating',
    defaultMode: 'voice',
    allowModeSwitch: true,
  });
</script>
```

## Scenario Configurations (from current CDN test patterns)

### 1) Known Applicant

```js
{
  contextType: 'screening',
  contextId: 'APPLICATION_UUID',
}
```

### 2) Known Candidate (Discovery)

```js
{
  contextType: 'candidate_discover',
  contextId: 'CANDIDATE_UUID',
}
```

### 3) Job Page Visitor

```js
{
  contextType: 'job_apply',
  contextId: 'JOB_UUID',
}
```

### 4) Unknown Visitor

```js
{
  contextType: 'discovery',
  contextId: 'CLIENT_UUID',
}
```

## Voice Playback Speed

Agent speech plays at **1.2x** by default (20% faster). Override with `playbackSpeed`:

```js
GlydeChat.init({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
  contextType: 'screening',
  contextId: 'APPLICATION_UUID',
  playbackSpeed: 1.0,   // 1.0 = normal, 1.2 = default, range 0.5-2.0
});
```

## Continuity Controls

Use these to tune chat history sent to the backend:

- `skipContinuityLimit: true` -> send full history
- `limitToLast: 5` -> current CDN test behavior
- `limitToLast: 50` -> long-running candidate/discovery flows

Example:

```js
GlydeChat.init({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
  contextType: 'screening',
  contextId: 'APPLICATION_UUID',
  skipContinuityLimit: false,
  limitToLast: 5,
});
```

## Display Modes

- `floating` - launcher bubble + chat panel
- `modal` - overlay panel
- `inline` - embed directly into a container
- `mobile` - full viewport mobile layout

Examples:

```js
GlydeChat.init({ ...config, displayMode: 'modal', dimensions: { width: 500, height: 600 } });
GlydeChat.render('#chat-container', { ...config, displayMode: 'inline', dimensions: { width: '100%', height: 650 } });
GlydeChat.init({ ...config, displayMode: 'mobile' });
```

## `GlydeChat` Global API

- `GlydeChat.init(config)`
- `GlydeChat.render(container, config)`
- `GlydeChat.destroy()`
- `GlydeChat.version`

## Script Data Attributes

Supported attributes for auto-init:

- `data-publishable-key`, `data-api-key`, `data-auth-token`
- `data-context-type`, `data-context-id`
- `data-unity-url`
- `data-auto-init`
- `data-default-mode`, `data-position`, `data-theme`
- `data-display-mode`, `data-container-id`
- `data-width`, `data-height`, `data-max-width`, `data-max-height`
- `data-dimensions`
- `data-show-header`, `data-allow-close`, `data-allow-mode-switch`

## NPM Usage

```bash
npm install @glydeunity/voice-sdk
```

```ts
import { GlydeVoice, GlydeText, ChatWidget, useVoiceAgent, useTextChat } from '@glydeunity/voice-sdk';
```

## Context Rules

Default behavior: if `contextType` is omitted, the SDK now defaults to `discovery`.

| Context Type | Required `contextId` |
|---|---|
| `screening` | `application_uuid` |
| `job_apply` | `job_uuid` |
| `candidate_discover` | `candidate_uuid` |
| `candidate_apply` | `candidate_uuid:job_uuid` |
| `discovery` | optional (`client_uuid` recommended) |
| `recruiter`, `custom`, `phone` | optional |

Text mode and voice mode both use the same `contextType` semantics. If you are using a non-screening flow (for example `discovery` with a `client_uuid`), always pass `contextType` explicitly to avoid screening-only initialization paths.

## Troubleshooting

- If widget does not appear, verify auth key and `data-auto-init` settings.
- If voice fails, ensure HTTPS and microphone permissions.
- If context errors occur, validate `contextType` + `contextId` format.
- If text mode calls `/api/unity/screening/summary/*` unexpectedly, ensure the text component receives the same `contextType` used by voice mode.