@usewax/sdk

Wax SDK — typed TypeScript client for the Wax agent API and browser voice sessions.

React shim — useConversation compatibility

Swap your ElevenLabs import in one line:

// Before:
import { useConversation } from "@elevenlabs/react";

// After:
import { useConversation } from "@usewax/sdk/react";

The hook signature and return shape are compatible. No other code changes required for the core session lifecycle.

Gap table

| EL method | Wax behavior | Notes | |---|---|---| | startSession(opts?) | Implemented | Same signature. Requires credential or tokenProvider. | | endSession() | Implemented | Graceful teardown, resets state. | | sendContextualUpdate(text) | Implemented | Sends wax.context_update over the data channel; agent injects the text as a one-shot system message on its next turn (0.3.0+). | | setDynamicVariable(name, value) | Implemented (Wax extension) | Wax-specific. Mid-session mutation of {{var_name}} template values; agent re-renders system prompt on next turn (0.3.0+). | | setMicMuted(muted) | Implemented (Wax extension) | Wax-specific. Runtime mic enable/disable. Pairs with micMuted option in useConversation. (0.3.0+). | | status | Implemented | Returns "disconnected" \| "connecting" \| "connected" \| "error". | | isSpeaking | Implemented | True while agent TTS is active. | | mode | Implemented | Returns "speaking" \| "listening". | | message | Implemented | Carries error message string when status is "error". | | sendUserMessage(text) | No-op with console.warn | Wax does not yet expose text injection on WaxSession. | | sendUserActivity() | No-op with console.warn | Inactivity timer reset not yet surfaced on WaxSession. | | sendFeedback(like) | No-op with console.warn | Feedback channel not yet available. | | sendMCPToolApprovalResult(id, approved) | No-op with console.warn | MCP tool approval not yet surfaced in this shim. | | sendMultimodalMessage(opts) | Not returned | Wax does not have a multimodal text+image channel. | | uploadFile(file) | Not returned | File upload not available in Wax. | | changeInputDevice(cfg) | Not returned | Device selection not surfaced in WaxSession. | | changeOutputDevice(cfg) | Not returned | Device selection not surfaced in WaxSession. | | setVolume(opts) | Not returned | Volume control not surfaced in WaxSession. | | setMuted(isMuted) | Mapped to setMicMuted | Use setMicMuted (Wax extension; same semantics). | | isMuted | Not returned | Mic state not tracked in this shim — read via your own React state alongside setMicMuted. | | canSendFeedback | Not returned | Feedback gating not applicable. | | getInputByteFrequencyData() | Not returned | Audio analysis not surfaced in WaxSession. | | getOutputByteFrequencyData() | Not returned | Audio analysis not surfaced in WaxSession. | | getInputVolume() | Not returned | Audio analysis not surfaced in WaxSession. | | getOutputVolume() | Not returned | Audio analysis not surfaced in WaxSession. | | getId() | Not returned | Use WaxSession.sessionId directly if needed. |

Unsupported methods that appear in the return shape emit a single console.warn on first call and then silently no-op. They will not throw.

Not-returned methods are absent from the return object entirely. TypeScript will catch any call-sites that used them at compile time.

Callback mapping

| EL callback prop | Wax equivalent | |---|---| | onConnect | WaxCallbacks.onConnect | | onDisconnect | WaxCallbacks.onDisconnect | | onError | WaxCallbacks.onError — shape changed to { message, category } | | onMessage | WaxCallbacks.onTextMessage — shape changed to { role, text } | | onModeChange | WaxCallbacks.onModeChange — mapped to "speaking" \| "listening" |

Installation

bun add @usewax/sdk
# or
npm install @usewax/sdk

Quick Start

import { WaxSession } from "@usewax/sdk";

const session = new WaxSession({
  credential: await fetchCredential(), // JWT from POST /v1/agents/{id}/sessions/credentials
  agentId: "agent-uuid",
  callbacks: {
    onConnect: () => console.log("connected"),
    onTextMessage: (msg) => console.log(msg.role, msg.text),
  },
});

await session.start();
// ... later ...
await session.end();

Package Exports

| Import path | Contents | |-------------|----------| | @usewax/sdk | Main entry — AgentsClient, WaxSession, all types | | @usewax/sdk/react | useConversation hook (ElevenLabs-compatible shim) | | @usewax/sdk/tools | ClientToolRegistry, register, attach, attachWith | | @usewax/sdk/tools/signing | DispatchEnvelope (runtime:'client'), verify, freshNonce | | @usewax/sdk/session | WaxSession, WaxCallbacks, reconnect constants |

Documentation

See docs/sdk/ in the Wax monorepo for full API reference and migration guides.