Frontend SDK
SDK overview
Run a live Athos roleplay call in your frontend with @useathos/sdk.
@useathos/sdk is a headless browser SDK. It exposes a small, domain-focused API — a roleplay
session with lifecycle events. Your code only ever works with Athos domain concepts (sessions, events, personas).
- Synchronous
create()so you register handlers before any network work starts. - A typed, discriminated event union and a stable error-code taxonomy.
- Microphone selection, mute, and automatic reconnect handling built in.
- Ships as ESM + CJS with full TypeScript types.
Install
npm install @useathos/sdkThe five-line integration
import { AthosRoleplay } from '@useathos/sdk';
const token = await getAthosToken(); // 1. your backend mints a token
const session = AthosRoleplay.create({ token, drillKey: 'ma-full-sale' }); // 2. create (sync)
session.on('ready', ({ persona }) => console.log(`${persona.name} is ready`)); // 3. handlers
session.on('ended', ({ durationSec }) => console.log(`done in ${durationSec}s`));
await session.connect(); // 4. join the callgetAthosToken() is your endpoint — it calls POST /v1/session server-side and returns the
token. The browser never sees your API key. See minting tokens.
Always register handlers before connect(). create() does no network work, so nothing is
missed; connect() is what redeems the token and joins the call.
AthosRoleplay.create(options)
Creates a session synchronously. Throws BROWSER_NOT_SUPPORTED immediately on Safari / mobile (see
Browser support).
Prop
Type
The session object
create() returns a session with these methods:
| Method | Description |
|---|---|
connect() | Redeem the token and join the call. Returns a Promise<void>. |
disconnect() | Cleanly leave the call. |
on(event, cb) | Subscribe to an event. Returns an unsubscribe function. |
off(event, cb) | Unsubscribe. |
listMicrophones() | Enumerate available mics. See Microphone & audio. |
setMicrophone(deviceId) | Switch mic mid-call without dropping. |
mute() / unmute() | Mute / unmute the local mic. |
resumeAudio() | Resume playback after AUDIO_PLAYBACK_BLOCKED (call from a user gesture). |