npm package: @onebudd/onebudd-sdk
Description: OneBudd STS SDK - Real-time voice AI conversations
Author: OneBudd
Latest version: 1.0.0

# @onebud/onebudd-sdk

> JavaScript/TypeScript SDK for OneBudd real-time voice AI.

[![npm](https://img.shields.io/npm/v/@onebud/onebudd-sdk)]()
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)]()

## Installation

```bash
npm install @onebud/onebudd-sdk
# or
yarn add @onebud/onebudd-sdk
# or
pnpm add @onebud/onebudd-sdk
```

---

## Quick Start

```typescript
import { OneBuddClient } from '@onebud/onebudd-sdk';

const client = new OneBuddClient('pk_test_xxx');

// Connect
const session = await client.startSession();
console.log('Connected:', session.id);

// Listen for events
client.on('audio', (bytes) => {
  // bytes is Uint8Array - play through Web Audio API
  playAudio(bytes);
});

client.on('transcript', ({ role, text, is_final }) => {
  console.log(`${role}: ${text}`);
});

// Send text (skips speech recognition)
client.sendMessage('Hello!');

// Or send audio (PCM 16kHz mono 16-bit)
client.sendAudio(audioBytes);

// End session
client.endSession();
```

---

## Configuration

```typescript
const client = new OneBuddClient('pk_xxx', {
  baseUrl: 'wss://api.onebudd.com',  // WebSocket URL
  autoReconnect: true,                // Auto-reconnect on disconnect
  maxReconnectAttempts: 5,            // Max reconnection attempts
  reconnectDelayMs: 1000,             // Base delay (exponential backoff)
});
```

---

## API Reference

### Methods

| Method | Description |
|--------|-------------|
| `startSession()` | Connect and start a new session |
| `endSession()` | End the current session |
| `sendAudio(chunk)` | Send raw PCM audio (Uint8Array) |
| `sendAudioWithMeta(chunk, seq?)` | Send audio with metadata |
| `sendMessage(text)` | Send text (bypasses STT) |
| `cancel(target?)` | Cancel active operations |

### Events

| Event | Payload | Description |
|-------|---------|-------------|
| `audio` | `Uint8Array` | TTS audio bytes |
| `transcript` | `{ role, text, is_final }` | Transcription |
| `state_change` | `{ from, to, trigger }` | Pipeline state |
| `error` | `{ code, message, fatal }` | Error occurred |
| `connected` | `SessionCapabilities` | Session ready |
| `disconnected` | `{ reason }` | Connection lost |
| `response_correction` | `{ original, corrected }` | After barge-in |

### Properties

| Property | Type | Description |
|----------|------|-------------|
| `isConnected` | `boolean` | Connection status |
| `sessionId` | `string \| null` | Current session ID |
| `capabilities` | `SessionCapabilities \| null` | Server capabilities |

---

## Browser Usage

```html
<script type="module">
  import { OneBuddClient } from 'https://cdn.jsdelivr.net/npm/@onebud/onebudd-sdk';
  
  const client = new OneBuddClient('pk_xxx');
  // ...
</script>
```

### Capturing Microphone Audio

```typescript
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const audioContext = new AudioContext({ sampleRate: 16000 });
const source = audioContext.createMediaStreamSource(stream);
const processor = audioContext.createScriptProcessor(4096, 1, 1);

processor.onaudioprocess = (e) => {
  const float32 = e.inputBuffer.getChannelData(0);
  const int16 = new Int16Array(float32.length);
  for (let i = 0; i < float32.length; i++) {
    int16[i] = Math.max(-32768, Math.min(32767, float32[i] * 32768));
  }
  client.sendAudio(new Uint8Array(int16.buffer));
};

source.connect(processor);
processor.connect(audioContext.destination);
```

---

## Node.js Usage

```typescript
import { OneBuddClient } from '@onebud/onebudd-sdk';
import { createReadStream } from 'fs';

const client = new OneBuddClient('pk_xxx');
await client.startSession();

// Stream audio file
const stream = createReadStream('audio.pcm');
stream.on('data', (chunk) => {
  client.sendAudio(new Uint8Array(chunk));
});
```

---

## Error Handling

```typescript
client.on('error', ({ code, message, fatal }) => {
  console.error(`Error [${code}]: ${message}`);
  if (fatal) {
    // Connection will be closed
  }
});

// Error codes
// AUTH_FAILED, RATE_LIMITED, INVALID_MESSAGE, SESSION_NOT_FOUND, etc.
```

---

## TypeScript

Full type definitions included:

```typescript
import type {
  SessionCapabilities,
  TranscriptPayload,
  ErrorPayload,
  StateChangePayload,
} from '@onebud/onebudd-sdk';
```

---

## License

MIT