{"_id":"@credufy/voice-sdk","name":"@credufy/voice-sdk","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@credufy/voice-sdk","version":"0.2.0","description":"Browser SDK for Credufy Voice — realtime AI voice agents over WebRTC, built for African languages and networks","type":"module","main":"dist/index.js","module":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"sideEffects":false,"publishConfig":{"access":"public"},"scripts":{"build":"tsc -p tsconfig.build.json","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"keywords":["voice","ai","voice-agent","tts","stt","webrtc","livekit","nigeria","africa"],"license":"MIT","homepage":"https://voice.credufy.com/docs","repository":{"type":"git","url":"git+https://github.com/credufy/credufy-voice-sdk.git"},"dependencies":{"livekit-client":"^2.21.0"},"devDependencies":{"@types/node":"^22.20.1","typescript":"^5.9.3"},"_id":"@credufy/voice-sdk@0.2.0","gitHead":"8c5eae3a1a6d137871e3cbb871708dc6c7e97df3","bugs":{"url":"https://github.com/credufy/credufy-voice-sdk/issues"},"_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-qz2q0287mXaDrfPI1rr8iDpLjeY1whIsfo5/AA7pLGtrJ9kRaM2dSqIjuzc/0EU9y/s6mLAkBkffdMrx0VfTVA==","shasum":"588bba7e61c16af418449b3671fdc1647d9f3c56","tarball":"https://registry.npmjs.org/@credufy/voice-sdk/-/voice-sdk-0.2.0.tgz","fileCount":18,"unpackedSize":56582,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIE5q6WC2hf1dEB/C4ZxFQTKQey2r72/c+CbsmIEfGoozAiAIp2nAG+lmKh+kZJK2jWHZ22iZPxOulHjszT/qH+/Kiw=="}]},"_npmUser":{"name":"credufy","email":"aliyuhgarba@credufy.com"},"directories":{},"maintainers":[{"name":"credufy","email":"aliyuhgarba@credufy.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/voice-sdk_0.2.0_1786522653705_0.5611910888940865"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-12T08:17:33.492Z","0.2.0":"2026-08-12T08:17:33.913Z","modified":"2026-08-12T08:17:34.256Z"},"maintainers":[{"name":"credufy","email":"aliyuhgarba@credufy.com"}],"description":"Browser SDK for Credufy Voice — realtime AI voice agents over WebRTC, built for African languages and networks","homepage":"https://voice.credufy.com/docs","keywords":["voice","ai","voice-agent","tts","stt","webrtc","livekit","nigeria","africa"],"repository":{"type":"git","url":"git+https://github.com/credufy/credufy-voice-sdk.git"},"bugs":{"url":"https://github.com/credufy/credufy-voice-sdk/issues"},"license":"MIT","readme":"# @credufy/voice-sdk\n\nBrowser SDK for Credufy Voice. It takes a session URL from your backend and\nhandles the WebSocket connection, microphone capture, and audio playback so\nyou can add a real-time voice agent to a web app in a few lines of code.\n\n## Install\n\n```bash\nnpm install @credufy/voice-sdk\n```\n\n## Quick start\n\nThe SDK never sees your API key. Your backend creates a session with your\nsecret key and hands the browser a short-lived `wsUrl` — that's the only\nthing that crosses the network to the client.\n\n**Backend** (creates the session, keeps the API key secret):\n\n```ts\n// server-side only — never expose CREDUFY_API_KEY to the browser\nconst res = await fetch('https://voice.credufy.com/api/v1/sessions/create', {\n  method: 'POST',\n  headers: {\n    Authorization: `Bearer ${process.env.CREDUFY_API_KEY}`,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({ agentId: 'agent_123', userId: 'user_456' }),\n})\n\nconst session = await res.json()\n// send the whole session object to the browser, e.g. as part\n// of your page's initial data. When your account has the\n// WebRTC transport enabled it contains `livekit` credentials;\n// otherwise the SDK falls back to the legacy `wsUrl` gateway —\n// your frontend code is identical either way.\n```\n\n**Frontend** (uses only the session object your backend gave it):\n\n```ts\nimport { CredufyVoice } from '@credufy/voice-sdk'\n\nconst voice = new CredufyVoice({\n  session,   // the JSON response from /v1/sessions/create, verbatim\n  onReady:      (e) => console.log('Session ready:', e.sessionId),\n  onTranscript: (t) => console.log(t.final ? 'You said:' : 'Listening...', t.text),\n  onStatus:     (s) => console.log('Status:', s),\n  onAudio:      (s) => console.log('Audio:', s),\n  onEnd:        (e) => console.log('Call ended, duration:', e.duration),\n  onError:      (err) => console.error(err),\n})\n\nawait voice.start()   // opens the mic, connects, and begins the call\n\n// Later:\nvoice.interrupt()     // cut the agent off mid-sentence\nvoice.stop()          // end the call\n```\n\n## Config reference\n\n| Option | Type | Required | Description |\n|---|---|---|---|\n| `session` | `CreateSessionResponse` | One of the three | The JSON response from `POST /v1/sessions/create`, passed verbatim. Preferred: the SDK picks WebRTC (LiveKit) when present, gateway otherwise. |\n| `livekit` | `{ url, token }` | One of the three | Explicit LiveKit credentials, if you'd rather not pass the whole session object. |\n| `wsUrl` | `string` | One of the three | Legacy WebSocket gateway URL. Contains a short-lived JWT and expires 5 minutes after issue. |\n| `onReady` | `(e: ReadyEvent) => void` | No | Fired once the gateway confirms the session, with `sessionId` and the agent's `firstMessage`. |\n| `onTranscript` | `(e: TranscriptEvent) => void` | No | Fired as the caller's speech is transcribed. `final` is `false` for interim results. |\n| `onStatus` | `(s: VoiceStatus) => void` | No | Fired on every state change: `connecting`, `listening`, `thinking`, `speaking`, `ended`. |\n| `onToken` | `(token: string) => void` | No | Fired per LLM token as the agent's reply streams in — useful for a live caption UI. |\n| `onAudio` | `(s: AudioStatus) => void` | No | Fired as agent audio starts (`playing`) and finishes (`idle`) playing back. |\n| `onEnd` | `(s: EndSummary) => void` | No | Fired once, when the session ends, with `sessionId` and call `duration` in seconds. |\n| `onError` | `(e: Error \\| Event) => void` | No | Fired on any connection, microphone, or protocol error. |\n\n## Methods\n\n| Method | Description |\n|---|---|\n| `start()` | Requests microphone access, connects (WebRTC room or WebSocket), and begins streaming. Returns a `Promise<void>` that resolves once the connection and mic are live. Throws if called twice on the same instance. |\n| `interrupt()` | Gateway transport: stops the agent mid-sentence and returns it to `listening`. WebRTC transport: no-op — barge-in is automatic (just speak). |\n| `stop()` | Ends the session, releases the microphone, and closes the connection. Triggers `onEnd`. |\n\n## Security\n\nYour Credufy API key is a backend secret. It must **never** appear in\nbrowser code, a client-side bundle, or a public repository. Only your\nserver should call `/v1/sessions/create` — the browser only ever receives\nthe resulting `wsUrl`, which is single-use and expires in 5 minutes.\n\n## Browser support\n\nAny browser with `getUserMedia` and `WebSocket` support: Chrome, Edge,\nFirefox, and Safari 14.1+. Microphone access requires a secure context\n(HTTPS, or `localhost` during development).\n\n## Docs\n\nFull API and gateway protocol documentation: https://voice.credufy.com/docs\n","readmeFilename":"README.md","_rev":"1-1355714eab96f7e0a8822e08ace17082"}