@simonpeacocks/peacockery-voice-client 0.1.3 → 0.2.0

package/README.md

@@ -19,9 +19,31 @@ const voice = createPeacockeryVoiceClient({
 const { data, error } = await voice.GET("/v1/models");
 ```
 
-For a device-bound child, pass `authorizationScheme: "DPoP"` and a platform proof provider. The callback receives the access token, HTTP method, canonical resource URI, and current server nonce; it returns one ES256 `dpop+jwt`. The wrapper automatically retries the first `use_dpop_nonce` challenge with a new proof. A trusted parent can also remain `Bearer` while supplying `dpopProof` to bind a newly minted child.
+For a device-bound child, pass `authorizationScheme: "DPoP"` and a platform proof provider. The callback receives the access token, HTTP method, canonical resource URI, and current server nonce; it returns one ES256 `dpop+jwt`. The wrapper automatically retries the first `use_dpop_nonce` challenge with a new proof. A trusted parent can remain `Bearer` while supplying an `ath`-free `dpopBindingProof` to bind a newly minted child, keeping the parent token inside the trusted backend.
 
-Private-key creation and signing stay in platform code. On Apple hardware the intended provider uses a non-exportable Secure Enclave P-256 key; the generated client never serializes or persists that key.
+Private-key creation and signing stay in platform code. Apple clients use Secure Enclave P-256 keys; Android clients should use a non-exportable Android Keystore P-256 key. The generated client handles public proofs while private-key state stays exclusively platform-managed.
+
+For realtime PCM, build the authenticated upgrade request and parse every provider-neutral event through the package:
+
+```ts
+const request = await createPeacockeryVoiceRealtimeRequest({
+  apiKey: childToken,
+  authorizationScheme: "DPoP",
+  dpopProof: signWithAndroidKeystore,
+  encoding: "linear16",
+  interimResults: true,
+  model: "deepgram-nova-3",
+  sampleRate: 16_000,
+});
+
+const socket = createNativeWebSocket(request.url, request.headers);
+socket.addEventListener("message", ({ data }) => {
+  const event = parsePeacockeryVoiceRealtimeEvent(String(data));
+  if (event.type.startsWith("transcript.")) updateVisibleTranscript(event.text);
+});
+```
+
+Send raw PCM chunks as binary WebSocket messages. Send `{ "type": "close" }` after the final chunk and retain the terminal `session.completed` result. The React Native adapter owns the native WebSocket constructor and Android Keystore signer because those APIs live outside the generated HTTP package.
 
 Run `pnpm run generate:sdk` from the repository root whenever the OpenAPI contract changes. Compiled JavaScript and declarations are checked in, and private Git installations consume them directly. Realtime WebSockets still use the protocol documented by `/v1/realtime`; `openapi-fetch` covers the HTTP surface.
 

package/dist/auth.d.ts

@@ -0,0 +1,25 @@
+export declare const peacockeryVoiceBaseUrls: {
+    readonly lab: "https://voice-lab.peacockery.studio";
+    readonly production: "https://voice.peacockery.studio";
+};
+export type PeacockeryVoiceEnvironment = keyof typeof peacockeryVoiceBaseUrls;
+export interface PeacockeryVoiceDpopProofInput {
+    readonly accessToken: string;
+    readonly htm: string;
+    readonly htu: string;
+    readonly nonce?: string;
+}
+export type PeacockeryVoiceDpopProofProvider = (input: PeacockeryVoiceDpopProofInput) => Promise<string>;
+export type PeacockeryVoiceDpopBindingProofInput = Omit<PeacockeryVoiceDpopProofInput, "accessToken">;
+export type PeacockeryVoiceDpopBindingProofProvider = (input: PeacockeryVoiceDpopBindingProofInput) => Promise<string>;
+export interface PeacockeryVoiceClientOptions {
+    apiKey: string;
+    authorizationScheme?: "Bearer" | "DPoP";
+    baseUrl?: string;
+    dpopBindingProof?: PeacockeryVoiceDpopBindingProofProvider;
+    dpopProof?: PeacockeryVoiceDpopProofProvider;
+    environment?: PeacockeryVoiceEnvironment;
+    fetch?: typeof globalThis.fetch;
+}
+export declare const dpopHtu: (requestUrl: string) => string;
+export declare const authenticatedFetch: (options: PeacockeryVoiceClientOptions) => typeof globalThis.fetch;

package/dist/auth.js

@@ -0,0 +1,51 @@
+export const peacockeryVoiceBaseUrls = {
+    lab: "https://voice-lab.peacockery.studio",
+    production: "https://voice.peacockery.studio",
+};
+export const dpopHtu = (requestUrl) => {
+    const url = new URL(requestUrl);
+    return `${url.origin}${url.pathname}`;
+};
+export const authenticatedFetch = (options) => {
+    const scheme = options.authorizationScheme ?? "Bearer";
+    const fetchImplementation = options.fetch ?? globalThis.fetch;
+    const bindingProofProvider = options.dpopBindingProof;
+    const workloadProofProvider = options.dpopProof;
+    if (scheme === "DPoP" && !workloadProofProvider) {
+        throw new Error("DPoP authorization requires a proof provider");
+    }
+    const hasProofProvider = scheme === "DPoP"
+        ? Boolean(workloadProofProvider)
+        : Boolean(bindingProofProvider);
+    let nonce;
+    return async (input, init) => {
+        const request = new Request(input, init);
+        const send = async () => {
+            const headers = new Headers(request.headers);
+            headers.set("Authorization", `${scheme} ${options.apiKey}`);
+            const proofInput = {
+                htm: request.method,
+                htu: dpopHtu(request.url),
+                ...(nonce ? { nonce } : {}),
+            };
+            if (scheme === "DPoP" && workloadProofProvider) {
+                headers.set("DPoP", await workloadProofProvider({
+                    accessToken: options.apiKey,
+                    ...proofInput,
+                }));
+            }
+            else if (bindingProofProvider) {
+                headers.set("DPoP", await bindingProofProvider(proofInput));
+            }
+            return fetchImplementation(new Request(request.clone(), { headers }));
+        };
+        const response = await send();
+        const challengedNonce = response.headers.get("DPoP-Nonce")?.trim();
+        if (response.status !== 401 || !challengedNonce || !hasProofProvider) {
+            return response;
+        }
+        nonce = challengedNonce;
+        await response.body?.cancel();
+        return send();
+    };
+};

package/dist/index.d.ts

@@ -1,24 +1,7 @@
+import { type PeacockeryVoiceClientOptions } from "./auth.js";
 import type { paths } from "./schema.js";
+export { type PeacockeryVoiceClientOptions, type PeacockeryVoiceDpopBindingProofInput, type PeacockeryVoiceDpopBindingProofProvider, type PeacockeryVoiceDpopProofInput, type PeacockeryVoiceDpopProofProvider, type PeacockeryVoiceEnvironment, peacockeryVoiceBaseUrls, } from "./auth.js";
+export { createPeacockeryVoiceRealtimeRequest, type PeacockeryVoiceRealtimeAudioReceivedEvent, type PeacockeryVoiceRealtimeEvent, type PeacockeryVoiceRealtimeOptions, type PeacockeryVoiceRealtimePongEvent, type PeacockeryVoiceRealtimeRequest, type PeacockeryVoiceRealtimeSessionStartedEvent, type PeacockeryVoiceRealtimeTranscriptEvent, type PeacockeryVoiceRealtimeTurnEvent, parsePeacockeryVoiceRealtimeEvent, } from "./realtime.js";
 export type { components, operations, paths } from "./schema.js";
-export declare const peacockeryVoiceBaseUrls: {
-    readonly lab: "https://voice-lab.peacockery.studio";
-    readonly production: "https://voice.peacockery.studio";
-};
-export type PeacockeryVoiceEnvironment = keyof typeof peacockeryVoiceBaseUrls;
-export interface PeacockeryVoiceDpopProofInput {
-    readonly accessToken: string;
-    readonly htm: string;
-    readonly htu: string;
-    readonly nonce?: string;
-}
-export type PeacockeryVoiceDpopProofProvider = (input: PeacockeryVoiceDpopProofInput) => Promise<string>;
-export interface PeacockeryVoiceClientOptions {
-    apiKey: string;
-    authorizationScheme?: "Bearer" | "DPoP";
-    baseUrl?: string;
-    dpopProof?: PeacockeryVoiceDpopProofProvider;
-    environment?: PeacockeryVoiceEnvironment;
-    fetch?: typeof globalThis.fetch;
-}
 export declare const createPeacockeryVoiceClient: (options: PeacockeryVoiceClientOptions) => import("openapi-fetch").Client<paths, `${string}/${string}`>;
 export type PeacockeryVoiceClient = ReturnType<typeof createPeacockeryVoiceClient>;

package/dist/index.js

@@ -1,44 +1,8 @@
 import createClient from "openapi-fetch";
-export const peacockeryVoiceBaseUrls = {
-    lab: "https://voice-lab.peacockery.studio",
-    production: "https://voice.peacockery.studio",
-};
-const dpopHtu = (requestUrl) => {
-    const url = new URL(requestUrl);
-    return `${url.origin}${url.pathname}`;
-};
-const authenticatedFetch = (options) => {
-    const scheme = options.authorizationScheme ?? "Bearer";
-    const fetchImplementation = options.fetch ?? globalThis.fetch;
-    if (scheme === "DPoP" && !options.dpopProof) {
-        throw new Error("DPoP authorization requires a proof provider");
-    }
-    let nonce;
-    return async (input, init) => {
-        const request = new Request(input, init);
-        const send = async () => {
-            const headers = new Headers(request.headers);
-            headers.set("Authorization", `${scheme} ${options.apiKey}`);
-            if (options.dpopProof) {
-                headers.set("DPoP", await options.dpopProof({
-                    accessToken: options.apiKey,
-                    htm: request.method,
-                    htu: dpopHtu(request.url),
-                    ...(nonce ? { nonce } : {}),
-                }));
-            }
-            return fetchImplementation(new Request(request.clone(), { headers }));
-        };
-        const response = await send();
-        const challengedNonce = response.headers.get("DPoP-Nonce")?.trim();
-        if (response.status !== 401 || !challengedNonce || !options.dpopProof) {
-            return response;
-        }
-        nonce = challengedNonce;
-        await response.body?.cancel();
-        return send();
-    };
-};
+import { authenticatedFetch, peacockeryVoiceBaseUrls, } from "./auth.js";
+// biome-ignore lint/performance/noBarrelFile: The public package entrypoint intentionally exposes the supported auth surface.
+export { peacockeryVoiceBaseUrls, } from "./auth.js";
+export { createPeacockeryVoiceRealtimeRequest, parsePeacockeryVoiceRealtimeEvent, } from "./realtime.js";
 export const createPeacockeryVoiceClient = (options) => {
     const environment = options.environment ?? "production";
     return createClient({

package/dist/realtime.d.ts

@@ -0,0 +1,86 @@
+import { type PeacockeryVoiceClientOptions } from "./auth.js";
+import type { components } from "./schema.js";
+type RealtimeTerminalEvent = components["schemas"]["RealtimeSessionResult"];
+interface TranscriptSegment {
+    endSeconds: number | null;
+    scores?: {
+        confidence?: number;
+        logProbability?: number;
+        probability?: number;
+        score?: number;
+        speakerConfidence?: number;
+    };
+    speaker?: string | number;
+    startSeconds: number | null;
+    text: string;
+}
+type TranscriptSpeakerTurn = Omit<TranscriptSegment, "scores">;
+type TranscriptWord = TranscriptSegment & {
+    startSeconds: number;
+    endSeconds: number;
+};
+export interface PeacockeryVoiceRealtimeOptions extends PeacockeryVoiceClientOptions {
+    channels?: number;
+    contextBias?: string[];
+    diarize?: boolean;
+    encoding?: string;
+    endpointing?: string;
+    interimResults?: boolean;
+    language?: string;
+    model: string;
+    sampleRate?: number;
+    speakerReferences?: Record<string, string>;
+    targetStreamingDelayMs?: number;
+    turnDetection?: {
+        start_threshold?: number;
+        eager_end_threshold?: number;
+        end_threshold?: number;
+        min_silence_ms?: number;
+        end_timeout_ms?: number;
+    };
+    utteranceEndMs?: number;
+    vadEvents?: boolean;
+}
+export interface PeacockeryVoiceRealtimeRequest {
+    headers: Readonly<Record<string, string>>;
+    url: string;
+}
+interface RealtimeEventBase {
+    protocol_version: 1;
+    sequence: number;
+    session_id: string;
+}
+export interface PeacockeryVoiceRealtimeSessionStartedEvent extends RealtimeEventBase {
+    language: string | null;
+    model: string;
+    type: "session.started";
+}
+export interface PeacockeryVoiceRealtimeTranscriptEvent extends RealtimeEventBase {
+    segments: TranscriptSegment[];
+    speaker_turns: TranscriptSpeakerTurn[];
+    speech_final?: boolean;
+    text: string;
+    type: "transcript.committed" | "transcript.delta" | "transcript.interim";
+    words: TranscriptWord[];
+}
+export interface PeacockeryVoiceRealtimeAudioReceivedEvent {
+    audio_bytes: number;
+    chunk_bytes: number;
+    message_count: number;
+    session_id: string;
+    type: "audio.received";
+}
+export interface PeacockeryVoiceRealtimePongEvent {
+    message_count: number;
+    session_id: string;
+    type: "pong";
+}
+export interface PeacockeryVoiceRealtimeTurnEvent extends RealtimeEventBase {
+    end_reason?: "threshold" | "timeout";
+    time_seconds: number;
+    type: "turn.start" | "turn.eager_end" | "turn.resume" | "turn.end";
+}
+export type PeacockeryVoiceRealtimeEvent = PeacockeryVoiceRealtimeTurnEvent | PeacockeryVoiceRealtimeAudioReceivedEvent | PeacockeryVoiceRealtimePongEvent | PeacockeryVoiceRealtimeSessionStartedEvent | PeacockeryVoiceRealtimeTranscriptEvent | RealtimeTerminalEvent;
+export declare const createPeacockeryVoiceRealtimeRequest: (options: PeacockeryVoiceRealtimeOptions) => Promise<PeacockeryVoiceRealtimeRequest>;
+export declare const parsePeacockeryVoiceRealtimeEvent: (value: string | unknown) => PeacockeryVoiceRealtimeEvent;
+export {};

package/dist/realtime.js

@@ -0,0 +1,149 @@
+import { dpopHtu, peacockeryVoiceBaseUrls, } from "./auth.js";
+const realtimeHttpUrl = (options) => {
+    const environment = options.environment ?? "production";
+    const url = new URL("/v1/realtime", options.baseUrl ?? peacockeryVoiceBaseUrls[environment]);
+    const query = {
+        channels: options.channels,
+        diarize: options.diarize,
+        encoding: options.encoding,
+        endpointing: options.endpointing,
+        interim_results: options.interimResults,
+        language: options.language,
+        model: options.model,
+        sample_rate: options.sampleRate,
+        speaker_references: options.speakerReferences
+            ? JSON.stringify(options.speakerReferences)
+            : undefined,
+        target_streaming_delay_ms: options.targetStreamingDelayMs,
+        turn_detection: options.turnDetection
+            ? JSON.stringify(options.turnDetection)
+            : undefined,
+        utterance_end_ms: options.utteranceEndMs,
+        vad_events: options.vadEvents,
+    };
+    for (const [name, value] of Object.entries(query)) {
+        if (value !== undefined) {
+            url.searchParams.set(name, String(value));
+        }
+    }
+    for (const term of options.contextBias ?? []) {
+        url.searchParams.append("context_bias", term);
+    }
+    return url;
+};
+const headersRecord = (headers) => {
+    const record = {};
+    for (const [name, value] of headers) {
+        record[name] = value;
+    }
+    return record;
+};
+export const createPeacockeryVoiceRealtimeRequest = async (options) => {
+    const scheme = options.authorizationScheme ?? "Bearer";
+    const url = realtimeHttpUrl(options);
+    const headers = new Headers({
+        Authorization: `${scheme} ${options.apiKey}`,
+    });
+    if (scheme === "DPoP") {
+        const proofProvider = options.dpopProof;
+        if (!proofProvider) {
+            throw new Error("DPoP authorization requires a proof provider");
+        }
+        let nonce;
+        const fetchImplementation = options.fetch ?? globalThis.fetch;
+        const nonceUrl = new URL("/v1/auth/dpop-nonce", url);
+        const prime = async () => {
+            const primeHeaders = new Headers({
+                Authorization: `DPoP ${options.apiKey}`,
+                DPoP: await proofProvider({
+                    accessToken: options.apiKey,
+                    htm: "POST",
+                    htu: dpopHtu(nonceUrl.href),
+                    ...(nonce ? { nonce } : {}),
+                }),
+            });
+            return fetchImplementation(nonceUrl, {
+                headers: primeHeaders,
+                method: "POST",
+            });
+        };
+        let response = await prime();
+        const challengedNonce = response.headers.get("DPoP-Nonce")?.trim();
+        if (response.status === 401 && challengedNonce) {
+            nonce = challengedNonce;
+            await response.body?.cancel();
+            response = await prime();
+        }
+        if (response.status !== 204 || !nonce) {
+            throw new Error(`Peacockery Voice DPoP nonce bootstrap returned ${response.status}`);
+        }
+        await response.body?.cancel();
+        headers.set("DPoP", await proofProvider({
+            accessToken: options.apiKey,
+            htm: "GET",
+            htu: dpopHtu(url.href),
+            nonce,
+        }));
+    }
+    url.protocol = url.protocol === "http:" ? "ws:" : "wss:";
+    return { headers: headersRecord(headers), url: url.href };
+};
+const isRecord = (value) => typeof value === "object" && value !== null;
+const isTurnEvent = (value) => typeof value.time_seconds === "number" &&
+    Number.isFinite(value.time_seconds) &&
+    value.time_seconds >= 0 &&
+    (value.end_reason === undefined ||
+        value.end_reason === "threshold" ||
+        value.end_reason === "timeout");
+const isRealtimeEvent = (value) => {
+    if (!isRecord(value) || typeof value.type !== "string") {
+        return false;
+    }
+    if (value.type === "audio.received") {
+        return (typeof value.audio_bytes === "number" &&
+            typeof value.chunk_bytes === "number" &&
+            typeof value.message_count === "number" &&
+            typeof value.session_id === "string");
+    }
+    if (value.type === "pong") {
+        return (typeof value.message_count === "number" &&
+            typeof value.session_id === "string");
+    }
+    const hasProtocolBase = value.protocol_version === 1 &&
+        typeof value.sequence === "number" &&
+        typeof value.session_id === "string";
+    if (!hasProtocolBase) {
+        return false;
+    }
+    if (["turn.start", "turn.eager_end", "turn.resume", "turn.end"].includes(value.type)) {
+        return isTurnEvent(value);
+    }
+    if (value.type === "session.started") {
+        return ((typeof value.language === "string" || value.language === null) &&
+            typeof value.model === "string");
+    }
+    if (value.type === "transcript.committed" ||
+        value.type === "transcript.delta" ||
+        value.type === "transcript.interim") {
+        return (Array.isArray(value.segments) &&
+            Array.isArray(value.speaker_turns) &&
+            typeof value.text === "string" &&
+            Array.isArray(value.words));
+    }
+    if (value.type === "session.completed") {
+        return value.status === "succeeded" && isRecord(value.result);
+    }
+    if (value.type === "session.failed") {
+        return (value.status === "failed" &&
+            isRecord(value.error) &&
+            isRecord(value.result));
+    }
+    return false;
+};
+export const parsePeacockeryVoiceRealtimeEvent = (value) => {
+    const parsed = typeof value === "string" ? JSON.parse(value) : value;
+    if (!isRealtimeEvent(parsed)) {
+        throw new Error("Peacockery Voice returned an invalid realtime event");
+    }
+    return parsed;
+};

package/dist/schema.d.ts

@@ -1245,6 +1245,49 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/auth/dpop-nonce": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Prime a DPoP nonce before a WebSocket upgrade */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description DPoP nonce is current for this credential. */
+                204: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description Unauthorized. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/jobs/{job_id}": {
         parameters: {
             query?: never;
@@ -1359,6 +1402,7 @@ export interface paths {
                 query?: {
                     audio_format?: string;
                     channels?: number;
+                    context_bias?: string;
                     detect_entities?: "true" | "false";
                     diarize?: "true" | "false";
                     diarize_model?: "latest" | "v1";
@@ -1382,8 +1426,12 @@ export interface paths {
                     sample_rate?: number;
                     search?: string;
                     smart_format?: "true" | "false";
+                    /** @description JSON object mapping speaker names to completed upload input_key values */
+                    speaker_references?: string;
                     tag?: string;
                     target_streaming_delay_ms?: number;
+                    /** @description JSON turn-detection configuration; {} uses provider defaults */
+                    turn_detection?: string;
                     utterance_end_ms?: number;
                     vad_events?: "true" | "false";
                     version?: string;
@@ -2071,7 +2119,7 @@ export interface components {
                     /** @enum {string|null} */
                     source: "derived" | "provider" | null;
                     items: {
-                        end_seconds: number;
+                        end_seconds: number | null;
                         scores: {
                             confidence: number | null;
                             log_probability: number | null;
@@ -2080,7 +2128,7 @@ export interface components {
                             speaker_confidence: number | null;
                         } | null;
                         speaker: string | number | null;
-                        start_seconds: number;
+                        start_seconds: number | null;
                         text: string;
                     }[];
                 };
@@ -2090,9 +2138,9 @@ export interface components {
                     /** @enum {string|null} */
                     source: "derived" | "provider" | null;
                     items: {
-                        end_seconds: number;
+                        end_seconds: number | null;
                         speaker: string | number | null;
-                        start_seconds: number;
+                        start_seconds: number | null;
                         text: string;
                         scores: null;
                     }[];

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@simonpeacocks/peacockery-voice-client",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Generated TypeScript client for the Peacockery Voice API",
-  "type": "module",
-  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/chikingsley/peacockery-voice.git",
     "directory": "clients/typescript"
   },
+  "license": "MIT",
+  "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -18,10 +18,6 @@
   "files": [
     "dist"
   ],
-  "publishConfig": {
-    "access": "public",
-    "provenance": false
-  },
   "scripts": {
     "build": "tsc",
     "check": "tsc --noEmit",
@@ -32,5 +28,9 @@
   },
   "devDependencies": {
     "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
   }
 }