Build Dictation Session Streaming Client

// Dictation streaming tutorial (TypeScript / browser)
// Flow: login → create session → stream PCM over WebSocket → read frames to EOF → end session
// Browser WebSocket auth uses Sec-WebSocket-Protocol (not HTTP headers).
// Protocol order for Dictation: SukiAmbientAuth,<sdp_suki_token>,<transcription_session_id>
// Prefer running login / create on your backend so partner_token never ships to the client.

// ---------------------------------------------------------------------------
// Endpoints and streaming defaults
// ---------------------------------------------------------------------------
const BASE_URL = 'https://sdp.suki.ai'; // REST API host
const WS_URL = 'wss://sdp.suki.ai/ws/transcribe'; // Dictation WebSocket stream
const CHUNK_BYTES = 3200; // ~100 ms of 16 kHz mono 16-bit PCM
const WAV_HEADER_BYTES = 44; // Standard WAV header size to strip

// ---------------------------------------------------------------------------
// Replace these with your partner credentials
// ---------------------------------------------------------------------------
const partnerId = 'your-partner-id'; // Example only — replace with your partner ID
const partnerToken = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'; // Example only — replace; keep on backend only
const providerId = 'provider-123'; // Example only — optional; required for Bearer / Single Auth Token partners
const sdpProviderId = ''; // Optional. Leave empty unless your partnership requires sdp_provider_id

// ---------------------------------------------------------------------------
// Error helpers: map REST failures to the documented code / message / details shape
// ---------------------------------------------------------------------------
/** REST failure with documented { code, message, details } when present. */
class SukiApiError extends Error {
  httpStatus: number;
  url: string;
  code: unknown;
  messageText: string;
  details: unknown;
  rawBody: string;

  constructor(
    httpStatus: number,
    url: string,
    opts: { code?: unknown; message?: string; details?: unknown; rawBody?: string } = {},
  ) {
    super(
      `HTTP ${httpStatus} ${url}: code=${String(opts.code)} message=${opts.message ?? ''}`,
    );
    this.name = 'SukiApiError';
    this.httpStatus = httpStatus;
    this.url = url;
    this.code = opts.code;
    this.messageText = opts.message ?? '';
    this.details = opts.details ?? [];
    this.rawBody = opts.rawBody ?? '';
  }

  /** Match error id exactly or as a prefix (see API error messages). */
  matches(errorId: string): boolean {
    const m = this.messageText.trim();
    return m === errorId || m.startsWith(`${errorId}:`) || m.startsWith(`${errorId} `);
  }
}

function parseSukiErrorBody(raw: string): {
  code?: unknown;
  message: string;
  details: unknown;
} {
  try {
    const data = raw ? JSON.parse(raw) : {};
    if (data && typeof data === 'object' && !Array.isArray(data)) {
      return {
        code: (data as any).code,
        message: (data as any).message != null ? String((data as any).message) : '',
        details: (data as any).details ?? [],
      };
    }
  } catch {
    // non-JSON body
  }
  return { message: raw.slice(0, 500), details: [] };
}

async function expectStatus(
  response: Response,
  url: string,
  want: number,
): Promise<void> {
  if (response.status === want) return;
  const rawBody = await response.text();
  const parsed = parseSukiErrorBody(rawBody);
  throw new SukiApiError(response.status, url, {
    code: parsed.code,
    message: parsed.message,
    details: parsed.details,
    rawBody,
  });
}

function hintForError(err: SukiApiError): string {
  if (
    err.matches('invalid_sdp_token') ||
    err.messageText.toLowerCase().includes('invalid sdp token')
  ) {
    return 'Missing, expired, or invalid sdp_suki_token. Call login again.';
  }
  if (err.matches('provider_not_registered')) {
    return 'Provider is not registered. Call register once, then login again.';
  }
  if (
    err.matches('transcription_session_not_accepting') ||
    err.messageText.toLowerCase().includes('not accepting new speech')
  ) {
    return (
      'Session is not READY/IDLE. Wait until the session accepts a new speech ' +
      'session, or end the parent session if you are done.'
    );
  }
  if (err.httpStatus === 401) {
    return 'Unauthorized. Check partner credentials and sdp_suki_token.';
  }
  if (err.httpStatus === 412) {
    return 'FailedPrecondition. Open /ws/transcribe only when the session is READY or IDLE.';
  }
  if (err.httpStatus >= 500) {
    return 'Server error. Retry with backoff; see API error messages.';
  }
  return 'See /api-reference/error-messages';
}

function restHeaders(sukiToken: string): HeadersInit {
  const headers: Record<string, string> = {
    sdp_suki_token: sukiToken,
    'Content-Type': 'application/json',
  };
  // Include only when your partnership requires it (leave sdpProviderId empty otherwise).
  if (sdpProviderId) headers.sdp_provider_id = sdpProviderId;
  return headers;
}

// ---------------------------------------------------------------------------
// Authentication
// ---------------------------------------------------------------------------
/** Exchange partner credentials for a Suki token (send later as sdp_suki_token). */
async function login(
  partnerId: string,
  partnerToken: string,
  providerId?: string,
): Promise<string> {
  const url = `${BASE_URL}/api/v1/auth/login`;
  const body: Record<string, string> = {
    partner_id: partnerId,
    partner_token: partnerToken,
  };
  if (providerId) body.provider_id = providerId;

  const response = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  await expectStatus(response, url, 200);
  const data = await response.json();
  if (!data.suki_token) {
    throw new SukiApiError(200, url, { message: 'login response missing suki_token' });
  }
  return data.suki_token as string;
}

/** POST /api/v1/auth/register (one-time). */
async function registerProvider(input: {
  partnerId: string;
  partnerToken: string;
  providerName: string;
  providerOrgId: string;
  providerId?: string;
  providerSpecialty?: string;
}): Promise<void> {
  const url = `${BASE_URL}/api/v1/auth/register`;
  const response = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      partner_id: input.partnerId,
      partner_token: input.partnerToken,
      provider_name: input.providerName,
      provider_org_id: input.providerOrgId,
      provider_id: input.providerId,
      provider_specialty: input.providerSpecialty ?? 'CARDIOLOGY',
    }),
  });
  if (response.status !== 201 && response.status !== 409) {
    await expectStatus(response, url, 201);
  }
}

async function loginWithRegisterFallback(
  partnerId: string,
  partnerToken: string,
  providerId: string | undefined,
  providerName: string,
  providerOrgId: string,
): Promise<string> {
  try {
    return await login(partnerId, partnerToken, providerId);
  } catch (err) {
    if (err instanceof SukiApiError && err.matches('provider_not_registered')) {
      console.warn(hintForError(err));
      await registerProvider({
        partnerId,
        partnerToken,
        providerName,
        providerOrgId,
        providerId,
      });
      return login(partnerId, partnerToken, providerId);
    }
    if (err instanceof SukiApiError) console.warn(hintForError(err));
    throw err;
  }
}

// ---------------------------------------------------------------------------
// Dictation session setup
// ---------------------------------------------------------------------------
/** Create a Dictation session and return transcription_session_id (HTTP 201). */
async function createDictationSession(
  sukiToken: string,
  body: {
    transcription_session_id?: string;
    audio_config?: {
      audio_encoding?: string;
      audio_language?: string;
      sample_rate_hertz?: number;
    };
  } = {
    audio_config: {
      audio_encoding: 'LINEAR16',
      audio_language: 'en-US',
      sample_rate_hertz: 16000,
    },
  },
): Promise<string> {
  const url = `${BASE_URL}/api/v1/transcription/session/create`;
  const response = await fetch(url, {
    method: 'POST',
    headers: restHeaders(sukiToken),
    body: JSON.stringify(body),
  });
  await expectStatus(response, url, 201);
  const data = await response.json();
  if (!data.transcription_session_id) {
    throw new SukiApiError(201, url, {
      message: 'create response missing transcription_session_id',
    });
  }
  return data.transcription_session_id as string;
}

function bytesToBase64(u8: Uint8Array): string {
  let binary = '';
  for (let i = 0; i < u8.length; i++) binary += String.fromCharCode(u8[i]!);
  return btoa(binary);
}

/** If the file is WAV, drop the 44-byte header and keep only raw PCM bytes. */
function stripWavHeader(buf: Uint8Array): Uint8Array {
  if (
    buf.length >= 12 &&
    buf[0] === 0x52 &&
    buf[1] === 0x49 &&
    buf[2] === 0x46 &&
    buf[3] === 0x46 &&
    buf[8] === 0x57 &&
    buf[9] === 0x41 &&
    buf[10] === 0x56 &&
    buf[11] === 0x45
  ) {
    return buf.subarray(WAV_HEADER_BYTES);
  }
  return buf;
}

type TranscriptFrame = {
  transcript?: { transcript?: string; words?: unknown[] };
  is_final?: boolean;
  transcript_id?: string;
};

type EndSessionResponse = {
  transcription_session_id: string;
  status: string;
  final_transcript: string;
  duration: number;
  ended_at: string;
};

// ---------------------------------------------------------------------------
// WebSocket streaming (browser: Sec-WebSocket-Protocol auth)
// ---------------------------------------------------------------------------
/**
 * Browser stream client for Dictation.
 * Authenticate with: Sec-WebSocket-Protocol = SukiAmbientAuth,<sdp_suki_token>,<transcription_session_id>
 * (token, then session ID — same order as Ambient).
 * Sends JSON AUDIO chunks with audioData, then EVENT AUDIO_END. Collects is_final frames until EOF.
 */
function createDictationStreamClient(sukiToken: string, transcriptionSessionId: string) {
  let pcmBuffer = new Uint8Array(0);
  const pending: string[] = [];
  let closing = false;
  let sawEof = false;
  const finals: string[] = [];
  let onSocketClosed: (() => void) | undefined;
  let onEof: ((finals: string[]) => void) | undefined;
  let lastSocketError: Event | undefined;

  // Dictation protocol order: token, then transcription_session_id.
  const ws = new WebSocket(WS_URL, [
    `SukiAmbientAuth,${sukiToken},${transcriptionSessionId}`,
  ]);
  ws.binaryType = 'arraybuffer';

  function flushPending() {
    if (ws.readyState !== WebSocket.OPEN) return;
    while (pending.length > 0) ws.send(pending.shift()!);
  }

  function sendJson(obj: Record<string, unknown>) {
    pending.push(JSON.stringify(obj));
    flushPending();
  }

  function pushPcm(chunk: Uint8Array) {
    // Buffer live PCM and flush ~100 ms JSON AUDIO frames (audioData). Do not send binary frames.
    if (closing) return;
    const merged = new Uint8Array(pcmBuffer.length + chunk.length);
    merged.set(pcmBuffer, 0);
    merged.set(chunk, pcmBuffer.length);
    pcmBuffer = merged;
    while (pcmBuffer.length >= CHUNK_BYTES) {
      const frame = pcmBuffer.slice(0, CHUNK_BYTES);
      pcmBuffer = pcmBuffer.slice(CHUNK_BYTES);
      sendJson({ type: 'AUDIO', audioData: bytesToBase64(frame) });
    }
  }

  function closeWhenDrained(onClosed?: () => void) {
    onSocketClosed = onClosed;
    const tick = () => {
      if (ws.readyState === WebSocket.CLOSED) {
        const cb = onSocketClosed;
        onSocketClosed = undefined;
        cb?.();
        return;
      }
      if (ws.readyState === WebSocket.CLOSING) {
        setTimeout(tick, 20);
        return;
      }
      flushPending();
      if (
        pending.length > 0 ||
        ws.readyState === WebSocket.CONNECTING ||
        ws.bufferedAmount > 0
      ) {
        setTimeout(tick, 20);
        return;
      }
      // Prefer waiting for EOF from the server; close only if still open after drain.
      if (ws.readyState === WebSocket.OPEN && sawEof) ws.close();
      else if (ws.readyState === WebSocket.OPEN) setTimeout(tick, 50);
    };
    tick();
  }

  function endStream(onClosed?: () => void) {
    // Flush remaining PCM, then send AUDIO_END (not RU9G / Ambient data field).
    if (closing) return;
    closing = true;
    if (pcmBuffer.length > 0) {
      sendJson({ type: 'AUDIO', audioData: bytesToBase64(pcmBuffer) });
      pcmBuffer = new Uint8Array(0);
    }
    sendJson({ type: 'EVENT', event: 'AUDIO_END' });
    closeWhenDrained(onClosed);
  }

  /**
   * Stream an entire ArrayBuffer (for example from FileReader.readAsArrayBuffer).
   * Strips a RIFF/WAVE header when present, then pushes PCM and ends the stream.
   */
  function streamArrayBuffer(buffer: ArrayBuffer, onClosed?: () => void) {
    const pcm = stripWavHeader(new Uint8Array(buffer));
    for (let offset = 0; offset < pcm.byteLength; offset += CHUNK_BYTES) {
      const end = Math.min(offset + CHUNK_BYTES, pcm.byteLength);
      pushPcm(pcm.subarray(offset, end));
    }
    endStream(onClosed);
  }

  /**
   * File input helper (same pattern as the Stream Dictation Session API reference).
   * Expects <input type="file" id="audioFile" /> in the page.
   */
  function streamFromFileInput(inputId = 'audioFile', onClosed?: () => void) {
    const input = document.getElementById(inputId) as HTMLInputElement | null;
    const file = input?.files?.[0];
    if (!file) {
      console.error(`Select a file for #${inputId}`);
      ws.close();
      return;
    }
    const reader = new FileReader();
    reader.onload = () => {
      streamArrayBuffer(reader.result as ArrayBuffer, onClosed);
    };
    reader.readAsArrayBuffer(file);
  }

  ws.onopen = () => {
    flushPending();
  };

  ws.onmessage = (ev) => {
    let payload: TranscriptFrame;
    try {
      payload = JSON.parse(String(ev.data)) as TranscriptFrame;
    } catch {
      console.warn('Non-JSON frame:', ev.data);
      return;
    }
    const text = payload.transcript?.transcript;
    if (text === 'EOF') {
      sawEof = true;
      onEof?.(finals.slice());
      return;
    }
    if (payload.is_final && text) {
      finals.push(text);
      console.log('Final:', text);
    } else if (text) {
      console.log('Partial:', text);
    }
  };

  ws.onerror = (e) => {
    lastSocketError = e;
    console.error('WebSocket error', e);
  };

  ws.onclose = (ev) => {
    if (!ev.wasClean || ev.code !== 1000) {
      console.error(
        `WebSocket closed abnormally: code=${ev.code} reason=${ev.reason || '(none)'}`,
        lastSocketError,
      );
    }
    const cb = onSocketClosed;
    onSocketClosed = undefined;
    cb?.();
  };

  return {
    ws,
    pushPcm,
    endStream,
    streamArrayBuffer,
    streamFromFileInput,
    stripWavHeader,
    getFinals: () => finals.slice(),
    onEof(cb: (finals: string[]) => void) {
      onEof = cb;
    },
  };
}

// ---------------------------------------------------------------------------
// End session over REST (final_transcript is in the end response; no separate poll APIs)
// ---------------------------------------------------------------------------
async function endDictationSession(
  sukiToken: string,
  transcriptionSessionId: string,
): Promise<EndSessionResponse> {
  const url = `${BASE_URL}/api/v1/transcription/session/${transcriptionSessionId}/end`;
  const response = await fetch(url, {
    method: 'POST',
    headers: restHeaders(sukiToken),
  });
  await expectStatus(response, url, 200);
  return response.json() as Promise<EndSessionResponse>;
}

// ---------------------------------------------------------------------------
// Run the full flow end to end
// ---------------------------------------------------------------------------
async function main() {
  try {
    // 1) Authenticate (register once if the provider is new).
    const sukiToken = await loginWithRegisterFallback(
      partnerId,
      partnerToken,
      providerId,
      'Dr. John Smith', // Example only — replace with the provider's name
      'org-123', // Example only — replace with your org ID
    );
    // 2) Create the Dictation session.
    const transcriptionSessionId = await createDictationSession(sukiToken);

    // 3) Stream audio from a file input, then end the session.
    //    Add <input type="file" id="audioFile" /> to your HTML before calling main().
    const client = createDictationStreamClient(sukiToken, transcriptionSessionId);
    client.onEof((liveFinals) => {
      console.log('Live finals before EOF:', liveFinals);
    });
    // Example: expects <input type="file" id="audioFile" /> with a LINEAR16 PCM or WAV file
    client.streamFromFileInput('audioFile', async () => {
      const endBody = await endDictationSession(sukiToken, transcriptionSessionId);
      console.log('End response:', endBody);
    });

    // Live capture alternative:
    // client.pushPcm(client.stripWavHeader(pcmBytes));
    // client.endStream(async () => { ... });
  } catch (err) {
    if (err instanceof SukiApiError) console.error(hintForError(err), err);
    throw err;
  }
}

// Prefer a backend proxy for partner_token in production.
// Call main() only after credentials are set and #audioFile has a file selected.
// main();