voxsheild 1.0.0

package/README.md

@@ -0,0 +1,66 @@
+<!-- Generated by tools/gen_sdk.py from the VoxVerify OpenAPI document.
+     Do not edit: `python tools/gen_sdk.py` overwrites it, and tests/test_sdk.py fails
+     first. An HTML comment because the registries render this file. -->
+# voxsheild
+
+Client for the **VoxVerify** voice-authenticity API — batch file analysis, the
+pre-action risk gate, and live-call scoring over a WebSocket.
+
+The classes keep the service's name, because that is what they are a client of: the API
+paths, the environment variables and the OpenAPI document all say VoxVerify. `voxsheild`
+is what you install and import.
+
+```bash
+npm install voxsheild
+```
+
+Node 22.6 or newer. No build step — the package ships as the TypeScript it was generated as, and the modules import each other with `.ts` on the specifier so Node's type-stripping runs them directly.
+
+## Analyse a recording
+
+```ts
+import { VoxVerify } from "voxsheild";
+
+const vx = new VoxVerify({ baseUrl: "", apiKey: KEY });  // "" = same origin
+const verdict = await vx.analyze(file);
+```
+
+Three verdicts, never two: `LIKELY_HUMAN`, `LIKELY_AI`, `INCONCLUSIVE`. The service
+abstains rather than guessing when the fused score does not clear a validation-selected
+threshold, or when the fusion weight behind it is split. Treat the estimate as evidence,
+not proof — the absence of a synthesis cue is not evidence of human origin.
+
+## Score a live call
+
+```ts
+import { LiveCall } from "voxsheild/stream";
+
+const call = new LiveCall({ apiKey: KEY, sampleRate: 16000, codec: "opus" });
+call.onRisk = (e) => console.warn(e.state, e.confidence, e.reason);
+await call.open();
+call.send(pcmFrame);                     // Int16Array, LE
+const summary = await call.stop();
+```
+
+`call.droppedFrames` counts what the client refused to queue when the socket's send buffer was already backed up. A tab that buffers thirty seconds of audio is not monitoring a call, it is recording one late.
+
+Frames are capped at 1,048,576 bytes, and both clients split at the cap rather than
+let an oversized frame close the socket and cost the call every window it had
+accumulated. The caps are generated from the document, so a deployment that tunes them
+does not need this package patched.
+
+## Auth
+
+Keys are per-tenant and scoped, and the tenant comes off the key — no request body may
+name one. 10 of the 18 documented operations require a scope; the batch
+forensic routes are open by design. A 403 carrying `scope` means the key is real but
+provisioned for a different surface, which is a different fix from a bad key.
+
+## Version
+
+`1.0.0`, which is the API document's version rather than a number this package
+maintains separately. The request methods are generated from that document; the
+live-call client is hand-written, because OpenAPI 3.1 has no vocabulary for a socket.
+
+Prototype for research and evaluation. Do not present any output of the service as proof
+of origin, and do not use it as the sole basis for an accusation.

package/client.ts

@@ -0,0 +1,307 @@
+// Generated by tools/gen_sdk.py from the VoxVerify OpenAPI document.
+// Do not edit: your changes will be overwritten on the next run.
+//
+// The streaming client beside this file is hand-written -- OpenAPI cannot
+// describe a WebSocket, so it is written against x-websocket-endpoints.
+
+/**
+ * The VoxVerify request client.
+ *
+ * Method names are the server's operation ids in camelCase; parameter names that
+ * travel on the wire (query keys, body fields) keep the server's spelling exactly,
+ * because those are the strings the API reads.
+ *
+ * ```ts
+ * const vx = new VoxVerify({ baseUrl: "http://127.0.0.1:8000", apiKey: "..." });
+ * const verdict = await vx.analyze(file);
+ * ```
+ *
+ * For live calls use `./stream.ts`, which is hand-written: this file only covers what
+ * OpenAPI can describe.
+ */
+
+// The `.ts` on the specifier is deliberate. This SDK ships without a build step, to
+// match the frontend it sits beside, so the file a caller imports is the file on disk:
+// Node's own type-stripping resolves `./models.ts` and refuses `./models`. tsc accepts
+// it under `allowImportingTsExtensions`, which the emitted tsconfig.json sets.
+import type * as models from "./models.ts";
+
+/** Where the key goes -- taken from the document's securitySchemes. */
+export const API_KEY_HEADER = "X-API-Key";
+export const API_KEY_QUERY = "api_key";
+
+export type FileArg = Blob | File;
+
+export interface VoxVerifyOptions {
+  baseUrl?: string;
+  apiKey?: string;
+  /** Injected for tests and for runtimes whose fetch is not global. */
+  fetch?: typeof globalThis.fetch;
+}
+
+/** A non-2xx response, carrying the scope the operation wanted. */
+export class VoxVerifyError extends Error {
+  readonly status: number;
+  readonly detail: string;
+  readonly scope?: string;
+
+  constructor(status: number, detail: string, scope?: string) {
+    const needs = scope && (status === 401 || status === 403)
+      ? ` (this operation requires the '${scope}' scope)` : "";
+    super(`HTTP ${status}: ${detail}${needs}`);
+    this.name = "VoxVerifyError";
+    this.status = status;
+    this.detail = detail;
+    this.scope = scope;
+  }
+}
+
+
+interface CallOptions {
+  query?: Record<string, unknown>;
+  json?: unknown;
+  /** The scalar half of a multipart body, beside the uploads. */
+  form?: Record<string, unknown>;
+  files?: [string, FileArg | FileArg[]][];
+  scope?: string;
+}
+
+export class VoxVerify {
+  readonly baseUrl: string;
+  apiKey?: string;
+  private readonly doFetch: typeof globalThis.fetch;
+
+  constructor(options: VoxVerifyOptions = {}) {
+    this.baseUrl = (options.baseUrl ?? "").replace(/\/$/, "");
+    this.apiKey = options.apiKey;
+    this.doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+
+  private async call<T>(verb: string, path: string, options: CallOptions = {}): Promise<T> {
+    const url = new URL(this.baseUrl + path, globalThis.location?.href ?? "http://127.0.0.1:8000");
+    for (const [key, value] of Object.entries(options.query ?? {})) {
+      if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
+    }
+    const headers: Record<string, string> = {};
+    if (this.apiKey) headers[API_KEY_HEADER] = this.apiKey;
+
+    let body: BodyInit | undefined;
+    if (options.files?.length || options.form) {
+      const form = new FormData();
+      // Unset fields are omitted rather than sent empty: the server applies its own
+      // default, and `replace=""` would ask it to parse "" as a bool.
+      for (const [field, value] of Object.entries(options.form ?? {})) {
+        if (value !== undefined && value !== null) form.append(field, String(value));
+      }
+      for (const [field, value] of options.files ?? []) {
+        for (const one of Array.isArray(value) ? value : [value]) {
+          form.append(field, one, (one as File).name ?? "clip.wav");
+        }
+      }
+      body = form;                       // no content-type: the browser sets the boundary
+    } else if (options.json !== undefined) {
+      headers["Content-Type"] = "application/json";
+      body = JSON.stringify(options.json);
+    }
+
+    const response = await this.doFetch(url.toString(), { method: verb, headers, body });
+    if (!response.ok) {
+      let detail = await response.text();
+      try {
+        const parsed = JSON.parse(detail);
+        if (parsed?.detail) {
+          detail = Array.isArray(parsed.detail)
+            ? parsed.detail.map((e: any) => `${(e.loc ?? []).join(".")}: ${e.msg}`).join("; ")
+            : String(parsed.detail);
+        }
+      } catch { /* not JSON: the text is the detail */ }
+      throw new VoxVerifyError(response.status, detail, options.scope);
+    }
+    if (response.status === 204) return undefined as T;
+    return (await response.json()) as T;
+  }
+
+  /**
+   * Upload and analyse one recording.
+   *
+   * `POST /api/v1/analyze`
+   * Open by design: Batch forensic analysis of a file the caller uploads.
+   */
+  async analyze(audio: FileArg, query: { visuals?: boolean; segments?: boolean } = {}): Promise<models.AnalysisResponse> {
+    return this.call("POST", `/api/v1/analyze`, { query, files: [["audio", audio]] });
+  }
+
+  /**
+   * Compare 2-4 recordings side by side.
+   *
+   * `POST /api/v1/compare`
+   * Open by design: Two files the caller uploads, compared against each other.
+   */
+  async compare(audio: FileArg[], query: { visuals?: boolean; segments?: boolean; labels?: string } = {}): Promise<models.backend__schemas__analysis__CompareResponse> {
+    return this.call("POST", `/api/v1/compare`, { query, files: [["audio", audio]] });
+  }
+
+  /**
+   * Names of every extracted forensic feature.
+   *
+   * `GET /api/v1/features`
+   * Open by design: The detector list and what each one measures — documentation about the model, identical for every caller.
+   */
+  async featureList(): Promise<Record<string, unknown>> {
+    return this.call("GET", `/api/v1/features`);
+  }
+
+  /**
+   * Service and model health.
+   *
+   * `GET /api/v1/health`
+   * Open by design: Liveness and configuration, including whether a generated dev key is in use.
+   */
+  async health(): Promise<models.HealthResponse> {
+    return this.call("GET", `/api/v1/health`);
+  }
+
+  /**
+   * Recent analyses, newest first.
+   *
+   * `GET /api/v1/history`
+   * Open by design: Recent batch analyses on this deployment.
+   */
+  async history(query: { limit?: number } = {}): Promise<models.HistoryItem[]> {
+    return this.call("GET", `/api/v1/history`, { query });
+  }
+
+  /**
+   * Measured accuracy of this deployment.
+   *
+   * `GET /api/v1/report`
+   * Open by design: The measured evaluation: thresholds, operating points, and the held-out numbers behind every accuracy claim.
+   */
+  async report(): Promise<Record<string, unknown>> {
+    return this.call("GET", `/api/v1/report`);
+  }
+
+  /**
+   * Retrieve a stored analysis.
+   *
+   * `GET /api/v1/results/{analysis_id}`
+   * Open by design: Reads back one batch analysis by its opaque id.
+   */
+  async getResult(analysisId: string): Promise<models.AnalysisResponse> {
+    return this.call("GET", `/api/v1/results/${analysisId}`);
+  }
+
+  /**
+   * Delete a stored analysis.
+   *
+   * `DELETE /api/v1/results/{analysis_id}`
+   * Open by design: Deletes one batch analysis.
+   */
+  async deleteResult(analysisId: string): Promise<Record<string, unknown>> {
+    return this.call("DELETE", `/api/v1/results/${analysisId}`);
+  }
+
+  /**
+   * List Sessions.
+   *
+   * `GET /api/v1/stream/sessions`
+   * Requires an API key scoped `admin`.
+   */
+  async listSessions(): Promise<Record<string, unknown>> {
+    return this.call("GET", `/api/v1/stream/sessions`, { scope: "admin" });
+  }
+
+  /**
+   * Compare a recording against a contact's enrolled voice.
+   *
+   * `POST /api/v1/speaker/compare`
+   * Requires an API key scoped `enrol`.
+   */
+  async compareToEnrolment(contactId: string, audio: FileArg): Promise<models.backend__schemas__speaker__CompareResponse> {
+    return this.call("POST", `/api/v1/speaker/compare`, { form: { contact_id: contactId }, files: [["audio", audio]], scope: "enrol" });
+  }
+
+  /**
+   * The reference voices this tenant holds.
+   *
+   * `GET /api/v1/speaker/contacts`
+   * Requires an API key scoped `enrol`.
+   */
+  async contacts(): Promise<models.ContactListResponse> {
+    return this.call("GET", `/api/v1/speaker/contacts`, { scope: "enrol" });
+  }
+
+  /**
+   * Enrol a reference voice sample for a contact.
+   *
+   * `POST /api/v1/speaker/enrol`
+   * Requires an API key scoped `enrol`.
+   */
+  async enrol(contactId: string, audio: FileArg, form: { replace?: boolean } = {}): Promise<models.EnrolResponse> {
+    return this.call("POST", `/api/v1/speaker/enrol`, { form: { contact_id: contactId, ...form }, files: [["audio", audio]], scope: "enrol" });
+  }
+
+  /**
+   * Delete a contact's enrolled voice.
+   *
+   * `DELETE /api/v1/speaker/enrolment`
+   * Requires an API key scoped `enrol`.
+   */
+  async deleteEnrolment(query: { contact_id: string }): Promise<models.DeleteResponse> {
+    return this.call("DELETE", `/api/v1/speaker/enrolment`, { query, scope: "enrol" });
+  }
+
+  /**
+   * Decide whether an action may proceed, given the voice on the call.
+   *
+   * `POST /api/v1/risk/check`
+   * Requires an API key scoped `risk`.
+   */
+  async riskCheck(body: models.RiskCheckRequest): Promise<models.RiskDecisionResponse> {
+    return this.call("POST", `/api/v1/risk/check`, { json: body, scope: "risk" });
+  }
+
+  /**
+   * This tenant's recent gate decisions.
+   *
+   * `GET /api/v1/risk/decisions`
+   * Requires an API key scoped `risk`.
+   */
+  async riskHistory(query: { limit?: number } = {}): Promise<models.RiskHistoryResponse> {
+    return this.call("GET", `/api/v1/risk/decisions`, { query, scope: "risk" });
+  }
+
+  /**
+   * One recorded decision, in full.
+   *
+   * `GET /api/v1/risk/decisions/{decision_id}`
+   * Requires an API key scoped `risk`.
+   */
+  async riskDecision(decisionId: string): Promise<models.RiskDecisionResponse> {
+    return this.call("GET", `/api/v1/risk/decisions/${decisionId}`, { scope: "risk" });
+  }
+
+  /**
+   * The policies this deployment will enforce, and any that will not load.
+   *
+   * `GET /api/v1/risk/policies`
+   * Requires an API key scoped `risk`.
+   */
+  async riskPolicies(): Promise<models.PolicyListResponse> {
+    return this.call("GET", `/api/v1/risk/policies`, { scope: "risk" });
+  }
+
+  /**
+   * Evaluate a policy without alerting or recording.
+   *
+   * `POST /api/v1/risk/preview`
+   * Requires an API key scoped `risk`.
+   */
+  async riskPreview(body: models.RiskCheckRequest): Promise<models.RiskDecisionResponse> {
+    return this.call("POST", `/api/v1/risk/preview`, { json: body, scope: "risk" });
+  }
+
+}
+
+// Documented but deliberately absent from this client:
+//   POST /api/v1/twilio/twiml -- signed by Twilio, not callable with an API key

package/models.ts

@@ -0,0 +1,439 @@
+// Generated by tools/gen_sdk.py from the VoxVerify OpenAPI document.
+// Do not edit: your changes will be overwritten on the next run.
+//
+// The streaming client beside this file is hand-written -- OpenAPI cannot
+// describe a WebSocket, so it is written against x-websocket-endpoints.
+
+/** Response and request shapes for the VoxVerify API. */
+
+/** AudioInfo */
+export interface AudioInfo {
+  format?: string | null;
+  subtype?: string | null;
+  source_sample_rate?: number | null;
+  source_channels?: number | null;
+  analysis_sample_rate: number;
+  transcoded?: boolean;
+  speech_ratio: number;
+}
+
+/** Thresholds */
+export interface Thresholds {
+  /** Scores under this read as LIKELY_HUMAN */
+  human_below: number;
+  /** Scores over this read as LIKELY_AI */
+  ai_above: number;
+  /** Where these thresholds came from */
+  source: string;
+}
+
+/** DecisionBlock */
+export interface DecisionBlock {
+  verdict: "LIKELY_HUMAN" | "LIKELY_AI" | "INCONCLUSIVE";
+  label: string;
+  /** Why this verdict, in plain language */
+  reason: string;
+  confidence: "low" | "moderate" | "high";
+  thresholds: Thresholds;
+}
+
+/** FusionBlock */
+export interface FusionBlock {
+  ai_score: number;
+  human_score: number;
+  /** Fusion weights after re-normalising over available streams */
+  weights_used: Record<string, number>;
+  /** Where those weights came from: a validation search, or configured priors */
+  weights_source: string;
+  available_streams: string[];
+  unavailable_streams: Record<string, string>;
+  /** max - min across detector scores */
+  detector_spread: number;
+  /** Share of the fusion *weight* carried by detectors on the same side of 0.5 as the fused score */
+  detector_agreement: number;
+  /** Plain count of detectors agreeing with the fused score, for display */
+  streams_agreeing?: number;
+  /** How many detectors produced a score at all */
+  streams_scoring?: number;
+  /** True only when every contributing detector was fitted on labelled data */
+  calibrated: boolean;
+  score_label: string;
+  provenance_override: boolean;
+}
+
+/** Indicator */
+export interface Indicator {
+  detector: string;
+  title: string;
+  subtitle: string;
+  status: string;
+  score: number | null;
+  lean: "ai" | "human" | "neutral" | "unavailable";
+  text: string;
+  cues?: string[];
+  provenance?: string | null;
+}
+
+/** ModelStatus */
+export interface ModelStatus {
+  status: "OK" | "UNAVAILABLE" | "ERROR";
+  detail: string;
+  provenance: string;
+}
+
+/** Segment */
+export interface Segment {
+  start: number;
+  end: number;
+  ai_score: number | null;
+  human_score: number | null;
+  verdict: string;
+  speech_ratio: number;
+  detectors?: Record<string, number>;
+}
+
+/** SegmentConsistency */
+export interface SegmentConsistency {
+  scored_windows: number;
+  std: number;
+  min?: number | null;
+  max?: number | null;
+  hybrid_risk: "low" | "elevated" | "unknown";
+}
+
+/** SuspiciousRegion */
+export interface SuspiciousRegion {
+  start: number;
+  end: number;
+  peak_ai_score: number;
+  window_count: number;
+}
+
+/** Watermark */
+export interface Watermark {
+  /** Provenance check outcome */
+  status: "DETECTED" | "NOT_DETECTED" | "UNAVAILABLE" | "ERROR";
+  /** Provider that answered, if any */
+  provider?: string | null;
+  /** Human-readable, non-implicative wording */
+  message?: string;
+  confidence?: number | null;
+}
+
+/** AnalysisResponse */
+export interface AnalysisResponse {
+  analysis_id: string;
+  filename: string;
+  /** Analysed duration in seconds */
+  duration: number;
+  verdict: "LIKELY_HUMAN" | "LIKELY_AI" | "INCONCLUSIVE";
+  label: string;
+  /** Fused AI likelihood in [0, 1] */
+  ai_score: number;
+  human_score: number;
+  summary: string;
+  decision: DecisionBlock;
+  fusion: FusionBlock;
+  watermark: Watermark;
+  /** Per-detector AI likelihood; null when the detector did not run */
+  models: Record<string, number | null>;
+  model_status: Record<string, ModelStatus>;
+  indicators: Indicator[];
+  /** Caveats that must be shown alongside this result */
+  limitations: string[];
+  segments: Segment[];
+  suspicious_regions: SuspiciousRegion[];
+  segment_consistency: SegmentConsistency;
+  audio: AudioInfo;
+  /** Raw named forensic features */
+  features: Record<string, number>;
+  /** Waveform, spectrogram, average spectrum and pitch arrays */
+  visuals?: Record<string, unknown> | null;
+  model_version: string;
+  feature_version: string;
+  elapsed_ms: number;
+}
+
+/** Body_analyze */
+export interface Body_analyze {
+  /** WAV, MP3, FLAC, OGG, AIFF or M4A */
+  audio: string;
+}
+
+/** Body_compare */
+export interface Body_compare {
+  /** Between 2 and 4 audio files */
+  audio: string[];
+}
+
+/** Body_compare_to_enrolment */
+export interface Body_compare_to_enrolment {
+  contact_id: string;
+  audio: string;
+}
+
+/** Body_enrol */
+export interface Body_enrol {
+  /** The caller's own reference for this contact */
+  contact_id: string;
+  /** At least 3 s of the contact speaking */
+  audio: string;
+  /** Discard any existing reference for this contact instead of adding to it */
+  replace?: boolean;
+}
+
+/** CompareItem */
+export interface CompareItem {
+  /** Display label, e.g */
+  label: string;
+  analysis?: AnalysisResponse | null;
+  error?: string | null;
+}
+
+/** What is stored for a contact */
+export interface EnrolmentSummary {
+  /** `sha256(tenant | contact_id)`, truncated */
+  contact_ref: string;
+  /** Reference recordings folded into this voice */
+  samples: number;
+  /** Embedding windows across those recordings */
+  windows: number;
+  /** Total reference audio seen, in seconds */
+  seconds: number;
+  /** Dimensions of the stored voice direction */
+  dims: number;
+  /** `lda` for the measured projection, else `cosine` */
+  scoring: string;
+  created_at: number;
+  updated_at: number;
+  /** Always false */
+  audio_retained: boolean;
+}
+
+/** ContactListResponse */
+export interface ContactListResponse {
+  count: number;
+  contacts: EnrolmentSummary[];
+  note: string;
+}
+
+/** DeleteResponse */
+export interface DeleteResponse {
+  deleted: boolean;
+  contact_id: string;
+  contact_ref: string;
+}
+
+/** EnrolResponse */
+export interface EnrolResponse {
+  /** Echoed back from the request */
+  contact_id: string;
+  enrolled: boolean;
+  enrolment: EnrolmentSummary;
+  /** The operating point a later comparison will use, and whether it was measured on held-out… */
+  thresholds: Record<string, unknown>;
+  /** What these numbers do not cover */
+  caveats: string[];
+}
+
+/** ErrorResponse */
+export interface ErrorResponse {
+  detail: string;
+}
+
+/** EvidenceBlock */
+export interface EvidenceBlock {
+  /** SYNTHETIC | GENUINE | UNDECIDED */
+  state: string;
+  confidence: "low" | "moderate" | "high";
+  speech_sec: number;
+  windows: number;
+  band: string | null;
+  /** False means the verdict was reached against a configured prior rather than a threshold fitted… */
+  operating_point_measured: boolean;
+  ai_score: number | null;
+  session_id: string | null;
+  direction: string | null;
+}
+
+/** ValidationError */
+export interface ValidationError {
+  loc: (string | number)[];
+  msg: string;
+  type: string;
+  input?: unknown;
+  ctx?: Record<string, unknown>;
+}
+
+/** HTTPValidationError */
+export interface HTTPValidationError {
+  detail?: ValidationError[];
+}
+
+/** HealthResponse */
+export interface HealthResponse {
+  status: "ok" | "degraded";
+  model_version: string;
+  feature_version: string;
+  detectors: Record<string, unknown>;
+  provenance_providers: string[];
+  thresholds: Thresholds;
+  limits: Record<string, unknown>;
+  database: Record<string, unknown>;
+  /** Shape of the API-key configuration; never the keys themselves */
+  auth?: Record<string, unknown>;
+  /** Live-call window/hop, SPRT error targets and per-band operating points */
+  streaming?: Record<string, unknown>;
+  /** Pre-action gate posture: policies loaded, policy files that will not load, webhook state, and… */
+  risk?: Record<string, unknown>;
+  /** Enrolment posture: whether the identity thresholds in force were measured on held-out… */
+  speaker?: Record<string, unknown>;
+  /** Consent posture: the mode in force, whether it is enforced at the handshake, and which tenants… */
+  consent?: Record<string, unknown>;
+  /** What a retained row is allowed to say: the filename mode and the logging mode actually in… */
+  privacy?: Record<string, unknown>;
+}
+
+/** HistoryItem */
+export interface HistoryItem {
+  id: string;
+  filename: string;
+  duration: number;
+  created_at: string;
+  verdict: "LIKELY_HUMAN" | "LIKELY_AI" | "INCONCLUSIVE";
+  ai_score: number;
+  human_score: number;
+  watermark_status: string;
+  model_version: string;
+}
+
+/** NotificationBlock */
+export interface NotificationBlock {
+  event_id: string;
+  event: string;
+  delivered: boolean;
+  status?: number | null;
+  error?: string | null;
+  /** Why nothing was sent: no URL, no signing secret, or a plaintext URL without the explicit… */
+  skipped?: string | null;
+  ms?: number | null;
+}
+
+/** PolicyBlock */
+export interface PolicyBlock {
+  name: string | null;
+  version: number | null;
+  /** File that decided, including the tenant directory when a tenant override supplied it */
+  source?: string | null;
+}
+
+/** PolicyListResponse */
+export interface PolicyListResponse {
+  default_policy: string;
+  outcomes: string[];
+  confidence_levels: string[];
+  policies: Record<string, unknown>[];
+  actions?: Record<string, unknown>;
+  /** Which file the map came from: the shared `_actions.yaml` or a tenant override that replaced it */
+  actions_source?: string;
+  /** Policy files on disk that will not load */
+  problems: string[];
+}
+
+/** One pre-action question */
+export interface RiskCheckRequest {
+  /** What the caller is about to do, e.g */
+  action: string;
+  /** A specific stream session */
+  session_id?: string | null;
+  /** SIP Call-ID */
+  call_id?: string | null;
+  /** Transaction amount, for policies with an escalation floor */
+  amount?: number | null;
+  /** ISO code for `amount` */
+  currency?: string | null;
+  /** The caller's own reference for this action, echoed into the audit record so a decision can be… */
+  reference?: string | null;
+}
+
+/** RuleBlock */
+export interface RuleBlock {
+  /** Position of the matching rule in its policy file */
+  index: number;
+  when: Record<string, unknown>;
+  then: "allow" | "step_up" | "hold" | "deny";
+  notify: boolean;
+}
+
+/** SubjectBlock */
+export interface SubjectBlock {
+  source: "live" | "stored" | "none";
+  note: string;
+  /** Matching legs, including the one weighed */
+  candidates: number;
+  /** Stored evidence only: how long ago the session closed */
+  age_sec?: number | null;
+}
+
+/** The gate's answer */
+export interface RiskDecisionResponse {
+  decision_id: string;
+  created_at: string;
+  /** allow | step_up | hold | deny */
+  outcome: "allow" | "step_up" | "hold" | "deny";
+  action: string;
+  known_action: boolean;
+  /** Why, in order: the rule's own wording, then how the evidence was found, then which policy was… */
+  reasons: string[];
+  policy: PolicyBlock;
+  selection: Record<string, unknown>;
+  rule: RuleBlock | null;
+  /** Set when an unmeasured operating point softened the outcome, so a softened deny is… */
+  downgraded_from?: "allow" | "step_up" | "hold" | "deny" | null;
+  evidence: EvidenceBlock | null;
+  evidence_source: "live" | "stored" | "none";
+  subject: SubjectBlock;
+  notification: NotificationBlock | null;
+  tenant: string | null;
+  call_id: string | null;
+  reference: string | null;
+  amount: number | null;
+  currency: string | null;
+  model_version: string;
+}
+
+/** RiskHistoryResponse */
+export interface RiskHistoryResponse {
+  count: number;
+  decisions: Record<string, unknown>[];
+  stats: Record<string, unknown>;
+}
+
+/** CompareResponse */
+export interface backend__schemas__analysis__CompareResponse {
+  comparison_id: string;
+  items: CompareItem[];
+  /** Samples ordered by AI likelihood, highest first */
+  ranking: Record<string, unknown>[];
+  /** Difference between the highest and lowest score */
+  spread: number;
+  notes: string[];
+}
+
+/** An identity finding, deliberately not a score */
+export interface backend__schemas__speaker__CompareResponse {
+  /** MATCH, DRIFT or UNDECIDED against the enrolled reference; UNKNOWN_CONTACT when nothing is… */
+  state: "MATCH" | "DRIFT" | "UNDECIDED" | "UNKNOWN_CONTACT" | "UNAVAILABLE";
+  label: string;
+  /** The cosine and the threshold it was compared to */
+  reason: string;
+  /** Mean per-window cosine against the reference direction */
+  cosine?: number | null;
+  contact_ref: string | null;
+  enrolment?: EnrolmentSummary | null;
+  thresholds: Record<string, unknown>;
+  caveats: string[];
+  /** Always false */
+  affects_ai_score: boolean;
+}
+

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "voxsheild",
+  "version": "1.0.0",
+  "description": "Client for the VoxVerify voice-authenticity API: batch analysis, the risk gate, and live calls.",
+  "type": "module",
+  "exports": {
+    ".": "./client.ts",
+    "./stream": "./stream.ts",
+    "./protocol": "./protocol.ts",
+    "./models": "./models.ts"
+  },
+  "files": [
+    "client.ts",
+    "models.ts",
+    "protocol.ts",
+    "stream.ts",
+    "tsconfig.json"
+  ],
+  "engines": {
+    "node": ">=22.6"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "parse": "node --input-type=module --experimental-strip-types -e \"await import('./client.ts'); await import('./stream.ts'); console.log('ok')\""
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  },
+  "license": "MIT"
+}

package/protocol.ts

@@ -0,0 +1,67 @@
+// Generated by tools/gen_sdk.py from the VoxVerify OpenAPI document.
+// Do not edit: your changes will be overwritten on the next run.
+//
+// The streaming client beside this file is hand-written -- OpenAPI cannot
+// describe a WebSocket, so it is written against x-websocket-endpoints.
+
+/**
+ * The live-call protocol, as published in the document's `x-websocket-endpoints`.
+ *
+ * Generated. The stream clients beside this file are hand-written and import
+ * these constants rather than restating them, so a deployment that tunes its
+ * session caps re-generates one file and both clients follow.
+ */
+
+export const STREAM_PATH = "/api/v1/stream" as const;
+
+export const TWILIO_STREAM_PATH = "/api/v1/twilio/stream" as const;
+
+export const REQUIRED_SCOPE = "stream" as const;
+
+export const ENCODING = "pcm_s16le" as const;
+
+export const CAPS = {
+  "max_frame_bytes": 1048576,
+  "hello_timeout_sec": 10.0,
+  "max_session_sec": 1800.0,
+  "max_session_bytes": 125829120,
+  "note": "Per-session duration and byte caps are enforced because forked call audio is call recording: an unbounded session is a memory risk and a compliance one."
+} as const;
+
+export const CLOSE_CODES = {
+  "1000": "normal close after the summary was sent",
+  "1011": "server aborted mid-stream; the reason is sent as an error",
+  "4400": "no hello within the timeout, or a malformed one",
+  "4401": "no key",
+  "4403": "key lacks the 'stream' scope",
+  "4409": "session duration or byte cap reached",
+  "4413": "a single frame exceeded max_frame_bytes"
+} as const;
+
+export const EVENTS = [
+  "ready",
+  "window",
+  "risk",
+  "identity",
+  "error",
+  "summary",
+  "status"
+] as const;
+
+export const CONTROL_MESSAGES = {
+  "stop | close | end": "graceful close; queued audio is drained first",
+  "status | ping": "the current summary, without closing"
+} as const;
+
+export const HELLO_FIELDS = {
+  "session_id": "optional; generated when omitted",
+  "call_id": "optional SIP Call-ID, the handle the risk gate joins on",
+  "contact_id": "optional; the identifier this contact was enrolled with via POST /speaker/enrol. When present the call is also compared against that reference voice and `identity` events are emitted. Hashed on arrival and never stored; no identity result can move ai_score.",
+  "sample_rate": "integer, 4000-192000 (default 16000)",
+  "codec": "optional label, e.g. opus / pcm_mulaw \u2014 decides the band",
+  "direction": "inbound | outbound",
+  "encoding": "pcm_s16le (aliases: pcm16, l16) \u2014 transcode mu-law/A-law at the transport edge"
+} as const;
+
+export const MAX_FRAME_BYTES: number = CAPS.max_frame_bytes;
+export const HELLO_TIMEOUT_SEC: number = CAPS.hello_timeout_sec;

package/stream.ts

@@ -0,0 +1,249 @@
+/**
+ * Live-call client for `WS /api/v1/stream`, for the browser.
+ *
+ * HAND-WRITTEN, unlike `client.ts` beside it. OpenAPI 3.1 has no vocabulary for a
+ * bidirectional socket, so there is nothing for a generator to read -- and the parts
+ * that matter on a live call are not in any schema anyway: who gives way when the
+ * microphone outruns the network, and what happens to audio still in flight when the
+ * operator presses stop.
+ *
+ * Every constant enforced here comes from `protocol.ts`, which *is* generated from the
+ * server's `x-websocket-endpoints` block, so a deployment that tunes its caps
+ * regenerates one file and this client follows.
+ *
+ * ```ts
+ * const call = new LiveCall({ baseUrl: "", apiKey: key, sampleRate: 16000, codec: "opus" });
+ * call.onRisk = (e) => console.warn(e.state, e.confidence, e.reason);
+ * await call.open();
+ * call.send(pcmFrame);            // Int16Array, little-endian
+ * const summary = await call.stop();
+ * ```
+ */
+
+import { CLOSE_CODES, ENCODING, MAX_FRAME_BYTES, REQUIRED_SCOPE, STREAM_PATH } from "./protocol.ts";
+
+export interface LiveCallOptions {
+  /** Same-origin by default: the dashboard is served by the API. */
+  baseUrl?: string;
+  /** A key scoped `stream`. Required -- the socket refuses an anonymous caller. */
+  apiKey: string;
+  /** Frames must arrive at this rate; the server resamples to its own. */
+  sampleRate?: number;
+  /**
+   * Codec label, e.g. `opus` or `pcm_mulaw`. Not cosmetic: this, not the sample
+   * rate, picks the measured operating point. A G.711 leg unpacked to 16 kHz is
+   * still narrowband audio, and calling it `opus` scores it against a threshold
+   * fitted on a distribution it was not drawn from.
+   */
+  codec?: string;
+  /** SIP Call-ID, if there is one. The handle the risk gate joins on. */
+  callId?: string;
+  sessionId?: string;
+  direction?: "inbound" | "outbound";
+  /**
+   * How much unsent audio may sit in the socket's buffer before frames are dropped.
+   * The server's own queue is bounded for the same reason: a detection that arrives
+   * after the call ended is not a detection.
+   */
+  maxBufferedBytes?: number;
+}
+
+export interface StreamEvent {
+  type: "ready" | "window" | "risk" | "error" | "summary" | "status";
+  [key: string]: unknown;
+}
+
+/** The server closed the socket, with the code it closed on. */
+export class StreamClosed extends Error {
+  readonly code: number;
+  readonly reason: string;
+
+  constructor(code: number, reason?: string) {
+    const described = reason || (CLOSE_CODES as Record<string, string>)[String(code)]
+      || "closed without a reason";
+    super(`stream closed ${code}: ${described}`);
+    this.name = "StreamClosed";
+    this.code = code;
+    this.reason = described;
+  }
+}
+
+/** `http(s)://host` -> `ws(s)://host/api/v1/stream`; `""` -> same origin. */
+export function wsUrl(baseUrl: string, apiKey: string, path: string = STREAM_PATH): string {
+  const origin = baseUrl || globalThis.location?.origin || "http://127.0.0.1:8000";
+  const url = new URL(path, origin);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  // The key goes in the query string here, and only here, because the browser
+  // WebSocket API cannot set a request header on the handshake. It lands in the
+  // server's access log as a result, which is why every other call in this SDK sends
+  // it as a header instead.
+  url.searchParams.set("api_key", apiKey);
+  return url.toString();
+}
+
+export class LiveCall {
+  ready?: StreamEvent;
+  summary?: StreamEvent;
+  /** Frames this client dropped for backpressure. The server counts its own. */
+  droppedFrames = 0;
+
+  onEvent?: (event: StreamEvent) => void;
+  onWindow?: (event: StreamEvent) => void;
+  onRisk?: (event: StreamEvent) => void;
+  onSummary?: (event: StreamEvent) => void;
+  onError?: (error: StreamClosed) => void;
+
+  private socket?: WebSocket;
+  private readonly options: Required<Pick<LiveCallOptions, "sampleRate" | "direction" | "maxBufferedBytes">> & LiveCallOptions;
+  private summaryWaiters: Array<(event: StreamEvent | undefined) => void> = [];
+
+  constructor(options: LiveCallOptions) {
+    this.options = {
+      sampleRate: 16000,
+      direction: "inbound",
+      maxBufferedBytes: 8 * MAX_FRAME_BYTES,
+      ...options,
+    };
+  }
+
+  /** The server's id for this leg -- the handle `/risk/check` joins on. */
+  get sessionId(): string | undefined {
+    return this.ready?.session_id as string | undefined;
+  }
+
+  get isOpen(): boolean {
+    return this.socket?.readyState === WebSocket.OPEN;
+  }
+
+  /**
+   * Connect, send the hello, and resolve on the server's `ready`.
+   *
+   * Rejects rather than resolving on a socket that closes first, which is the case
+   * worth getting right: a key without the `stream` scope closes 4403 during what
+   * looks like a successful connection, and a client that resolved anyway would sit
+   * there sending audio into a closed socket.
+   */
+  async open(): Promise<StreamEvent> {
+    const url = wsUrl(this.options.baseUrl ?? "", this.options.apiKey);
+    const socket = new WebSocket(url);
+    socket.binaryType = "arraybuffer";
+    this.socket = socket;
+
+    const hello = {
+      sample_rate: this.options.sampleRate,
+      codec: this.options.codec,
+      call_id: this.options.callId,
+      session_id: this.options.sessionId,
+      direction: this.options.direction,
+      encoding: ENCODING,
+    };
+
+    return await new Promise<StreamEvent>((resolve, reject) => {
+      let settled = false;
+      socket.onopen = () => socket.send(JSON.stringify(
+        Object.fromEntries(Object.entries(hello).filter(([, v]) => v != null))));
+
+      socket.onmessage = (message) => {
+        const event = JSON.parse(String(message.data)) as StreamEvent;
+        this.dispatch(event);
+        if (!settled && event.type === "ready") {
+          settled = true;
+          this.ready = event;
+          resolve(event);
+        } else if (!settled && event.type === "error") {
+          settled = true;
+          reject(new StreamClosed(4400, String(event.detail ?? "the server refused the hello")));
+        }
+      };
+
+      socket.onclose = (closed) => {
+        this.releaseWaiters();
+        const failure = new StreamClosed(closed.code, closed.reason);
+        if (!settled) {
+          settled = true;
+          reject(failure);
+        } else if (closed.code !== 1000 && closed.code !== 1001) {
+          this.onError?.(failure);
+        }
+      };
+    });
+  }
+
+  private dispatch(event: StreamEvent): void {
+    this.onEvent?.(event);
+    if (event.type === "window") this.onWindow?.(event);
+    else if (event.type === "risk") this.onRisk?.(event);
+    else if (event.type === "summary") {
+      this.summary = event;
+      this.onSummary?.(event);
+      this.releaseWaiters(event);
+    }
+  }
+
+  private releaseWaiters(event?: StreamEvent): void {
+    const waiting = this.summaryWaiters;
+    this.summaryWaiters = [];
+    for (const resolve of waiting) resolve(event ?? this.summary);
+  }
+
+  /**
+   * Send one frame of 16-bit little-endian PCM.
+   *
+   * Two things happen here that the server would otherwise do less kindly. Frames
+   * larger than the published cap are split, because the server's answer to an
+   * oversized frame is to close the socket (4413) and the call loses every window it
+   * had accumulated. And when unsent audio is already piling up in the socket buffer
+   * the frame is dropped and counted, rather than queued: a tab that buffers thirty
+   * seconds of audio is not monitoring a call, it is recording one late.
+   */
+  send(pcm: Int16Array | ArrayBuffer): void {
+    const socket = this.socket;
+    if (!socket || socket.readyState !== WebSocket.OPEN) return;
+    if (socket.bufferedAmount > this.options.maxBufferedBytes) {
+      this.droppedFrames += 1;
+      return;
+    }
+    const buffer = pcm instanceof Int16Array
+      ? pcm.buffer.slice(pcm.byteOffset, pcm.byteOffset + pcm.byteLength) as ArrayBuffer
+      : pcm;
+    for (let start = 0; start < buffer.byteLength; start += MAX_FRAME_BYTES) {
+      socket.send(buffer.slice(start, Math.min(start + MAX_FRAME_BYTES, buffer.byteLength)));
+    }
+  }
+
+  /** Ask for the current summary without closing. Arrives as a `status` event. */
+  status(): void {
+    if (this.isOpen) this.socket!.send(JSON.stringify({ action: "status" }));
+  }
+
+  /**
+   * Say stop and wait for the summary.
+   *
+   * The waiting is the point: the server drains audio it has already queued before it
+   * summarises, so closing the socket on stop would discard the last few windows --
+   * on a short call, the ones that decided it. Resolves undefined if the socket dies
+   * first, which is honest: there is no verdict in that case, and returning a partial
+   * one would invent evidence.
+   */
+  async stop(timeoutMs = 30000): Promise<StreamEvent | undefined> {
+    if (this.summary) return this.summary;
+    if (!this.isOpen) return undefined;
+    this.socket!.send(JSON.stringify({ action: "stop" }));
+    return await new Promise<StreamEvent | undefined>((resolve) => {
+      const timer = setTimeout(() => resolve(this.summary), timeoutMs);
+      this.summaryWaiters.push((event) => {
+        clearTimeout(timer);
+        resolve(event);
+      });
+    });
+  }
+
+  /** Hang up without waiting. Use `stop()` unless the call is already lost. */
+  close(): void {
+    this.socket?.close(1000, "client closed");
+    this.socket = undefined;
+  }
+}
+
+/** The scope a key needs to open this socket: `stream`. */
+export const STREAM_SCOPE = REQUIRED_SCOPE;

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [
+      "ES2022",
+      "DOM"
+    ],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "strict": true,
+    "exactOptionalPropertyTypes": false,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": [
+    "*.ts"
+  ]
+}