Build Form Filling Session Streaming Client

// Form filling streaming tutorial (TypeScript / browser)
// Flow: login → create Form filling session → seed template context → stream PCM over WebSocket → end → poll structured data
// Browser WebSocket auth uses Sec-WebSocket-Protocol (not HTTP headers).
// Prefer running login / create / context on your backend so partner_token never ships to the client.
//
// ambient_session_id from Form filling create is the Form filling session ID (same field name as Ambient; different ID).

// ---------------------------------------------------------------------------
// Endpoints and streaming defaults
// ---------------------------------------------------------------------------
const BASE_URL = 'https://sdp.suki.ai'; // REST API host
const WS_URL = 'wss://sdp.suki.ai/ws/stream'; // Shared Ambient / Form filling 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
const KEEP_ALIVE_MS = 5000; // Send KEEP_ALIVE this often while paused

// ---------------------------------------------------------------------------
// 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

// form_template_id must come from GET /api/v1/info/suki-medical-form-templates (template_id).
// Replace this example UUID with a real template from your account.
const formTemplateId = 'YOUR_FORM_TEMPLATE_ID'; // Example placeholder — replace with template_id from the templates API

type ControlEvent = 'PAUSE' | 'RESUME' | 'KEEP_ALIVE' | 'CANCEL';

// ---------------------------------------------------------------------------
// 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.httpStatus === 401) {
    return 'Unauthorized. Check partner credentials and sdp_suki_token.';
  }
  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 (same as Ambient)
// ---------------------------------------------------------------------------
/** 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;
  }
}

// ---------------------------------------------------------------------------
// Form filling session setup
// ---------------------------------------------------------------------------
/**
 * Create a Form filling session (POST /api/v1/form-filling/session/create, HTTP 201).
 * Returns ambient_session_id: this is the Form filling session ID despite the field name.
 * Never pass an Ambient clinical-note create ID here.
 */
async function createFormFillingSession(
  sukiToken: string,
  body: { ambient_session_id?: string; encounter_id?: string } = {},
): Promise<string> {
  const url = `${BASE_URL}/api/v1/form-filling/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.ambient_session_id) {
    throw new SukiApiError(201, url, {
      message: 'create response missing ambient_session_id',
    });
  }
  return data.ambient_session_id as string;
}

/**
 * Seed Form filling context with at least one form_template_id before end.
 * form_template_id must come from GET /api/v1/info/suki-medical-form-templates (template_id).
 * Replace the example UUID with a real template from your account.
 */
async function seedFormFillingContext(
  sukiToken: string,
  ambientSessionId: string,
  formTemplateId: string,
): Promise<void> {
  const url = `${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/context`;
  const response = await fetch(url, {
    method: 'POST',
    headers: restHeaders(sukiToken),
    body: JSON.stringify({
      form_filling: {
        values: [{ form_template_id: formTemplateId }],
      },
    }),
  });
  await expectStatus(response, url, 200);
}

function utf8ToBase64(s: string): string {
  const bytes = new TextEncoder().encode(s);
  let binary = '';
  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]!);
  return btoa(binary);
}

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;
}

// ---------------------------------------------------------------------------
// WebSocket streaming (browser: Sec-WebSocket-Protocol auth; same wire format as Ambient)
// ---------------------------------------------------------------------------
/**
 * Browser stream client for Form filling (shared /ws/stream).
 * Authenticate with: Sec-WebSocket-Protocol = SukiAmbientAuth,<sdp_suki_token>,<ambient_session_id>
 * (token, then session ID). ambient_session_id must be the Form filling create ID.
 * Sends START_TIME, JSON AUDIO chunks (~100 ms), optional EVENTs, then RU9G to end the segment.
 */
function createFormFillingStreamClient(sukiToken: string, ambientSessionId: string) {
  let pcmBuffer = new Uint8Array(0);
  const pending: string[] = [];
  let startSent = false;
  let paused = false;
  let keepAliveTimer: ReturnType<typeof setInterval> | null = null;
  let closing = false;
  let onSocketClosed: (() => void) | undefined;
  let lastSocketError: Event | undefined;

  const ws = new WebSocket(WS_URL, [
    `SukiAmbientAuth,${sukiToken},${ambientSessionId}`,
  ]);
  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 ensureStartTime() {
    // Mark the start of this audio segment once (RFC3339 timestamp, base64-encoded).
    if (startSent) return;
    startSent = true;
    const rfc3339 = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
    pending.unshift(
      JSON.stringify({ type: 'START_TIME', data: utf8ToBase64(rfc3339) }),
    );
    flushPending();
  }

  function stopKeepAlive() {
    if (keepAliveTimer !== null) {
      clearInterval(keepAliveTimer);
      keepAliveTimer = null;
    }
  }

  function startKeepAlive() {
    stopKeepAlive();
    sendJson({ type: 'EVENT', event: 'KEEP_ALIVE' });
    keepAliveTimer = setInterval(() => {
      if (!paused || closing) return;
      sendJson({ type: 'EVENT', event: 'KEEP_ALIVE' });
    }, KEEP_ALIVE_MS);
  }

  function sendEvent(event: ControlEvent) {
    ensureStartTime();
    sendJson({ type: 'EVENT', event });
    if (event === 'PAUSE') {
      paused = true;
      startKeepAlive();
      return;
    }
    if (event === 'RESUME') {
      paused = false;
      stopKeepAlive();
      return;
    }
    if (event === 'CANCEL') {
      paused = false;
      stopKeepAlive();
      closing = true;
      pcmBuffer = new Uint8Array(0);
      return;
    }
  }

  function pushPcm(chunk: Uint8Array) {
    // Buffer live PCM and flush ~100 ms JSON AUDIO frames (base64). Do not send binary frames.
    if (closing) return;
    ensureStartTime();
    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', data: 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;
      }
      if (ws.readyState === WebSocket.OPEN) ws.close();
    };
    tick();
  }

  function endStream(onClosed?: () => void) {
    // Flush remaining PCM, then send the end marker (EOF as base64 text "RU9G").
    if (closing) return;
    closing = true;
    paused = false;
    stopKeepAlive();
    ensureStartTime();
    if (pcmBuffer.length > 0) {
      sendJson({ type: 'AUDIO', data: bytesToBase64(pcmBuffer) });
      pcmBuffer = new Uint8Array(0);
    }
    sendJson({ type: 'AUDIO', data: 'RU9G' });
    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. 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 LINEAR16 PCM or WAV file for #${inputId}`);
      ws.close();
      return;
    }
    const reader = new FileReader();
    reader.onload = () => {
      streamArrayBuffer(reader.result as ArrayBuffer, onClosed);
    };
    reader.readAsArrayBuffer(file);
  }

  ws.onopen = () => {
    ensureStartTime();
    flushPending();
  };
  ws.onmessage = (ev) => {
    // Final structured data is not guaranteed over WebSocket. Prefer REST.
    console.log('Received:', ev.data);
  };
  ws.onerror = (e) => {
    lastSocketError = e;
    console.error('WebSocket error', e);
  };
  ws.onclose = (ev) => {
    stopKeepAlive();
    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,
    sendEvent,
    endStream,
    streamArrayBuffer,
    streamFromFileInput,
    stripWavHeader,
  };
}

// ---------------------------------------------------------------------------
// End session and fetch structured data over REST
// ---------------------------------------------------------------------------
async function endFormFillingSession(sukiToken: string, ambientSessionId: string) {
  /** End the Form filling session after the WebSocket stream is closed. */
  const url = `${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/end`;
  const response = await fetch(url, {
    method: 'POST',
    headers: restHeaders(sukiToken),
  });
  await expectStatus(response, url, 200);
}

async function getSessionStatus(sukiToken: string, ambientSessionId: string) {
  const url = `${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/status`;
  const response = await fetch(url, { headers: restHeaders(sukiToken) });
  await expectStatus(response, url, 200);
  const body = await response.json();
  return body.status as string;
}

async function getStructuredData(sukiToken: string, ambientSessionId: string) {
  /** OpenAPI/API samples wrap the payload under the structured_data key. */
  const url = `${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/structured-data`;
  const response = await fetch(url, { headers: restHeaders(sukiToken) });
  await expectStatus(response, url, 200);
  const data = await response.json();
  if (!data || typeof data !== 'object' || !('structured_data' in data)) {
    throw new SukiApiError(200, url, { message: 'response missing structured_data key' });
  }
  return data.structured_data;
}

async function waitForResults(
  sukiToken: string,
  ambientSessionId: string,
  pollMs = 2000,
) {
  for (;;) {
    const status = await getSessionStatus(sukiToken, ambientSessionId);
    if (status === 'completed') {
      const structuredData = await getStructuredData(sukiToken, ambientSessionId);
      return { status, structured_data: structuredData };
    }
    if (status === 'failed' || status === 'aborted') {
      return { status, structured_data: null };
    }
    await new Promise((r) => setTimeout(r, pollMs));
  }
}

// ---------------------------------------------------------------------------
// 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 Form filling session and seed template context.
    //    ambientSessionId here is the Form filling session ID (not Ambient clinical create).
    const ambientSessionId = await createFormFillingSession(sukiToken);
    await seedFormFillingContext(sukiToken, ambientSessionId, formTemplateId);

    // 3) Stream audio from a file input, then end the session and poll structured data.
    //    Add <input type="file" id="audioFile" /> to your HTML before calling main().
    const client = createFormFillingStreamClient(sukiToken, ambientSessionId);
    // Example: expects <input type="file" id="audioFile" /> with a LINEAR16 PCM or WAV file
    client.streamFromFileInput('audioFile', async () => {
      await endFormFillingSession(sukiToken, ambientSessionId);
      console.log(await waitForResults(sukiToken, ambientSessionId));
    });

    // 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, template ID, and #audioFile are set.
// main();