Browser SDK - Developer Guide

npm install @sanas-ai/browser-sdk

import http from "node:http";

const SANAS_API_KEY = process.env.SANAS_API_KEY;
const SANAS_IDENTITY_URL = "https://identity.sanas.ai";
const ALLOWED_ORIGIN = process.env.ALLOWED_ORIGIN || "http://localhost:5173";

http.createServer(async (req, res) => {
  // CORS preflight
  if (req.method === "OPTIONS") {
    res.writeHead(204, corsHeaders());
    return res.end();
  }

  if (req.method === "POST" && req.url === "/token") {
    // Authenticate the calling browser session here (skipped for brevity).

    const upstream = await fetch(`${SANAS_IDENTITY_URL}/oauth2/api-key/login`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ apiKey: SANAS_API_KEY }),
    });

    const body = await upstream.text();
    res.writeHead(upstream.status, {
      "Content-Type": "application/json",
      ...corsHeaders(),
    });
    return res.end(body);
  }

  res.writeHead(404, corsHeaders());
  res.end();
}).listen(process.env.PORT || 4000);

function corsHeaders() {
  return {
    "Access-Control-Allow-Origin": ALLOWED_ORIGIN,
    "Access-Control-Allow-Methods": "POST, OPTIONS",
    "Access-Control-Allow-Headers": "Content-Type",
  };
}

import { SanasSDK, type TokenResponse } from "@sanas-ai/browser-sdk";

const sdk = new SanasSDK();

await sdk.initialize({
  tokenProvider: async (): Promise<TokenResponse> => {
    const res = await fetch("https://your-backend.example.com/token", {
      method: "POST",
      credentials: "include", // if you use cookie sessions
    });
    if (!res.ok) throw new Error(`Token request failed: ${res.status}`);
    return res.json();
  },
});

import { SanasSDK, ProcessorState } from "@sanas-ai/browser-sdk";

const sdk = new SanasSDK();

// 1. Initialize the SDK with your token provider.
await sdk.initialize({
  tokenProvider: () =>
    fetch("/token", { method: "POST" }).then((r) => r.json()),
});

// 2. Capture the microphone.
const input = await navigator.mediaDevices.getUserMedia({ audio: true });

// 3. Create a processor. RI mode with an accent-translation model:
const processor = await sdk.createAudioProcessor(
  { input, modelName: "AT5.2" },
  {
    // Drive your UI off state, not off the reason string.
    // `Initializing` — session is being set up; output is silent.
    // `Ready`        — audio is flowing through the processor.
    // `Failed`       — fatal error; the processor can't recover. Destroy it,
    //                  optionally show `reason` to the user, and create a new
    //                  one if you want to keep going.
    // `Disconnected` — you called destroyAudioProcessor(); terminal.
    onStateChange: (state, reason) => {
      if (state === ProcessorState.Ready) enableMicButton();
      if (state === ProcessorState.Failed) {
        disableMicButton();
        showBanner(reason);
      }
    },
  }
);

// 4. Attach the processed output to an <audio> element.
const audio = document.querySelector("audio")!;
audio.srcObject = processor.outputStream;
audio.play();

// 5. When you're done, tear down.
await sdk.destroyAudioProcessor(processor);
await sdk.shutdown();

const processor = await sdk.createAudioProcessor(
  {
    input: micStream,
    modelName: "AT5.2", // as shown in the Developer Console
  },
  {
    onStateChange: (state, reason) => {
      if (state === ProcessorState.Ready) console.log("live");
      if (state === ProcessorState.Failed) console.error("failed:", reason);
    },
  }
);

audioElement.srcObject = processor.outputStream;

const conversationId = crypto.randomUUID();

// Agent's mic → Spanish audio for the customer.
const outbound = await sdk.createAudioProcessor(
  {
    input: agentMicStream,
    languageIn: "en-US",
    languageOut: "es-ES",
    conversationId,
  },
  {
    onStateChange: (state, reason) => console.log("outbound", state, reason),
    onTranscript: (json) => console.log("outbound transcript", JSON.parse(json)),
    onLanguageRoute: (json) => console.log("outbound route", JSON.parse(json)),
  }
);
customerSpeakerElement.srcObject = outbound.outputStream;

// Customer's mic → English audio for the agent.
const inbound = await sdk.createAudioProcessor(
  {
    input: customerMicStream,
    languageIn: "es-ES",
    languageOut: "en-US",
    conversationId, // same UUID — shared context.
  },
  {
    onStateChange: (state, reason) => console.log("inbound", state, reason),
    onTranscript: (json) => console.log("inbound transcript", JSON.parse(json)),
    onLanguageRoute: (json) => console.log("inbound route", JSON.parse(json)),
  }
);
agentSpeakerElement.srcObject = inbound.outputStream;

const processor = await sdk.createAudioProcessor(
  {
    input: micStream,
    languageIn: "en-US",
    languageOut: "es-MX",
  },
  {
    onStateChange: (state, reason) => console.log(state, reason),
    onTranscript: (json) => console.log("transcript", JSON.parse(json)),
    onLanguageRoute: (json) => console.log("route", JSON.parse(json)),
  }
);

{
  "type": "transcription",
  "transcription": {
    "lang": "en-US",
    "utterance_idx": 0,
    "complete": [],
    "partial": [
      { "word": "Hi",      "start": 0.0, "end": 0.0, "probability": 0.900 },
      { "word": ",",       "start": 0.0, "end": 0.0, "probability": 0.881 },
      { "word": " testing","start": 0.0, "end": 0.0, "probability": 0.941 },
      { "word": " of",     "start": 0.0, "end": 0.0, "probability": 0.936 }
    ]
  }
}

const utterances = new Map<number, string>();

onTranscript: (json) => {
  const { transcription } = JSON.parse(json);
  const prev = utterances.get(transcription.utterance_idx) ?? "";
  const finalized = transcription.complete.map((w) => w.word).join("");
  const pending = transcription.partial.map((w) => w.word).join("");
  utterances.set(transcription.utterance_idx, prev + finalized);
  render(prev + finalized + pending); // finalized + current guess
};

{
  "type": "language_route_chosen",
  "language_route_chosen": {
    "utterance_idx": 1,
    "lang_in": "en-US",
    "lang_out": "es-ES",
    "is_final": true
  }
}

await processor.updateLanguageConfig({
  languageIn: "en-US",
  languageOut: "fr-FR",
});

Initializing ──► Ready ──► Disconnected (consumer destroyed)
    │              │
    │              └──► Failed (mid-call error)
    │
    └──► Failed (setup error)

class SanasSDK {
  initialize(params: InitParams): Promise<void>;
  isInitialized(): boolean;
  createAudioProcessor(
    params: AudioProcessorParams,
    callbacks?: ProcessorCallbacks
  ): Promise<IAudioProcessor>;
  destroyAudioProcessor(processor: IAudioProcessor): Promise<void>;
  getActiveProcessorCount(): number;
  shutdown(): Promise<void>;
}

interface InitParams {
  tokenProvider: () => Promise<TokenResponse>;
  logLevel?: "debug" | "info" | "warn" | "error" | "silent";
  jitterBufferTargetMs?: number;
}

interface TokenResponse {
  access_token: string;
  user_id: string;
  group_id: string;
  expires_in?: number;
  authenticated_at?: string;
  token_type?: string;
}

type AudioProcessorParams =
  | AudioProcessorModelParams
  | AudioProcessorLanguageParams;

interface AudioProcessorModelParams {
  input: MediaStream;
  modelName: string;
  sampleRate?: number;
  jitterBufferTargetMs?: number;
}

interface AudioProcessorLanguageParams {
  input: MediaStream;
  languageIn: string;
  languageOut: string;
  conversationId?: string;
  sampleRate?: number;
  jitterBufferTargetMs?: number;
}

interface ProcessorCallbacks {
  onStateChange?: (state: ProcessorState, reason: string) => void;
  onTranscript?: (json: string) => void;
  onLanguageRoute?: (json: string) => void;
}

interface IAudioProcessor {
  readonly outputStream: MediaStream;
  getState(): ProcessorState;
  updateInputStream(input: MediaStream): Promise<void>;
  updateLanguageConfig(config: {
    languageIn: string;
    languageOut: string;
    conversationId?: string;
  }): Promise<void>;
}

enum ProcessorState {
  Initializing = "initializing",
  Ready = "ready",
  Failed = "failed",
  Disconnected = "disconnected",
  Unknown = "unknown",
}

import { SdkError, InitErrorCode } from "@sanas-ai/browser-sdk";

try {
  await sdk.initialize({ tokenProvider });
} catch (err) {
  if (err instanceof SdkError && err.code === InitErrorCode.OriginNotAllowed) {
    showBanner("This origin isn't allowed. Contact your admin.");
  } else {
    throw err;
  }
}

sdk.createAudioProcessor(params, {
  onStateChange: (state, reason) => {
    if (state === ProcessorState.Failed) {
      // reason is a short user-facing string
      // e.g. "Server rejected the call (auth failure)"
      // e.g. "Media connection lost"
      // e.g. "Authentication lost: origin not allowed for this group"
      // e.g. "Entitlement revoked: language_translation is no longer available for this group"
      showErrorBanner(reason);
    }
  },
});

sdk.createAudioProcessor({ input, modelName: "...", sampleRate: 48000 }, ...);

await sdk.initialize({ tokenProvider, jitterBufferTargetMs: 200 });
// or
sdk.createAudioProcessor(
  { input, modelName: "...", jitterBufferTargetMs: 100 },
  ...
);

const newInput = await navigator.mediaDevices.getUserMedia({
  audio: { deviceId: newDeviceId },
});
await processor.updateInputStream(newInput);