@volley/recognition-client-sdk 0.1.200

package/README.md

@@ -0,0 +1,168 @@
+# @volley/recognition-client-sdk
+
+TypeScript SDK for real-time speech recognition via WebSocket.
+
+## Installation
+
+```bash
+npm install @volley/recognition-client-sdk
+```
+
+## Quick Start
+
+```typescript
+import { createClientWithBuilder } from '@volley/recognition-client-sdk';
+
+// Create client with builder pattern
+const client = createClientWithBuilder(builder =>
+  builder
+    .url('ws://localhost:3101/ws/v1/recognize')
+    .provider('deepgram')
+    .model('nova-2')
+    .onTranscript(result => {
+      console.log('Final:', result.finalTranscript);
+      console.log('Interim:', result.pendingTranscript);
+    })
+    .onError(error => console.error(error))
+    .build()
+);
+
+// Stream audio
+await client.connect();
+client.sendAudio(pcm16AudioChunk);  // Call repeatedly with audio chunks
+await client.stopRecording();       // Wait for final transcript
+```
+
+## Configuration
+
+### Basic Setup
+
+```typescript
+builder
+  .url('ws://localhost:3101/ws/v1/recognize')
+  .provider('deepgram')           // deepgram, google, assemblyai
+  .model('nova-2')                 // Provider-specific model
+  .language('en')                  // Language code
+  .interimResults(true)            // Enable partial transcripts
+```
+
+### Event Handlers
+
+```typescript
+builder
+  .onTranscript(result => {})     // Handle transcription results
+  .onError(error => {})            // Handle errors
+  .onConnected(() => {})           // Connection established
+  .onDisconnected((code) => {})   // Connection closed
+  .onMetadata(meta => {})          // Timing information
+```
+
+### Optional Parameters
+
+```typescript
+builder
+  .gameContext({                   // Context for better recognition
+    gameId: 'session-123',
+    prompt: 'Expected responses: yes, no, maybe'
+  })
+  .userId('user-123')              // User identification
+  .platform('web')                 // Platform identifier
+  .logger((level, msg, data) => {})  // Custom logging
+```
+
+## API Reference
+
+### Client Methods
+
+```typescript
+await client.connect();           // Establish connection
+client.sendAudio(chunk);          // Send PCM16 audio
+await client.stopRecording();     // End and get final transcript
+client.getAudioUtteranceId();     // Get session UUID
+client.getState();                // Get current state
+client.isConnected();             // Check connection status
+```
+
+### TranscriptionResult
+
+```typescript
+{
+  finalTranscript?: string;       // Confirmed text
+  pendingTranscript?: string;     // Yet to confirm text (can change by ASR vendors)
+  is_finished?: boolean;          // Transcription complete (last one)
+  voiceStart?: number;            // Voice activity start (ms)
+  voiceDuration?: number;         // Voice duration (ms)
+}
+```
+
+## Providers
+
+### Deepgram
+```typescript
+builder.provider('deepgram').model('nova-2')  // or 'nova-2-general'
+```
+
+
+## Audio Format
+
+The SDK expects PCM16 audio:
+- Format: Linear PCM (16-bit signed integers)
+- Sample Rate: 16kHz recommended
+- Channels: Mono
+Please reach out to AI team if ther are essential reasons that we need other formats.
+
+## Error Handling
+
+```typescript
+builder.onError(error => {
+  console.error(`Error ${error.code}: ${error.message}`);
+});
+
+// Check disconnection type
+import { isNormalDisconnection } from '@volley/recognition-client-sdk';
+
+builder.onDisconnected((code, reason) => {
+  if (!isNormalDisconnection(code)) {
+    console.error('Unexpected disconnect:', code);
+  }
+});
+```
+
+## Publishing
+
+This package uses automated publishing via semantic-release with npm Trusted Publishers (OIDC).
+
+### First-Time Setup (One-time)
+
+After the first manual publish, configure npm Trusted Publishers:
+
+1. Go to https://www.npmjs.com/package/@volley/recognition-client-sdk/access
+2. Click "Add publisher" → Select "GitHub Actions"
+3. Configure:
+   - **Organization**: `Volley-Inc`
+   - **Repository**: `recognition-service`
+   - **Workflow**: `sdk-release.yml`
+   - **Environment**: Leave empty (not required)
+
+### How It Works
+
+- **Automated releases**: Push to `dev` branch triggers semantic-release
+- **Version bumping**: Based on conventional commits (feat/fix/BREAKING CHANGE)
+- **No tokens needed**: Uses OIDC authentication with npm
+- **Provenance**: Automatic supply chain attestation
+- **Path filtering**: Only releases when SDK or libs change
+
+### Manual Publishing (Not Recommended)
+
+If needed for testing:
+
+```bash
+cd packages/client-sdk-ts
+npm login --scope=@volley
+pnpm build
+npm publish --provenance --access public
+```
+
+## License
+
+Proprietary