@simonpeacocks/peacockery-voice-client 0.1.2 → 0.1.4

package/README.md

@@ -19,8 +19,48 @@ 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.
 
-Run `pnpm run generate:sdk` from the repository root whenever the OpenAPI contract changes. Compiled JavaScript and declarations are checked in so a private Git installation does not need to execute package lifecycle scripts. Realtime WebSockets still use the protocol documented by `/v1/realtime`; `openapi-fetch` covers the HTTP surface.
+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.
+
+## Release
+
+Run one guarded command from a clean, synchronized `main` branch:
+
+```bash
+pnpm release:voice-client patch
+```
+
+The command regenerates the SDK, validates the TypeScript client and Swift package when Swift is available, increments the requested semantic version, commits only generated client release files, creates the matching `voice-client-vX.Y.Z` tag, atomically pushes `main` and the tag, watches the GitHub Actions publication, and verifies the new npm version.
+
+Use `minor`, `major`, or an explicit stable version in place of `patch`. Run the complete preflight while keeping the repository unchanged with:
+
+```bash
+pnpm release:voice-client patch --check
+```
+
+If GitHub Actions reports a provider-side failure after the atomic push, repair the publisher configuration and rerun that workflow. The existing version commit and release tag remain the canonical release identity.

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, 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,57 @@
+import { type PeacockeryVoiceClientOptions } from "./auth.js";
+import type { components } from "./schema.js";
+type RealtimeTerminalEvent = components["schemas"]["RealtimeSessionResult"];
+type TranscriptionArtifact = components["schemas"]["TranscriptionArtifact"];
+type TranscriptSegment = TranscriptionArtifact["content"]["segments"]["items"][number];
+type TranscriptSpeakerTurn = TranscriptionArtifact["content"]["speaker_turns"]["items"][number];
+type TranscriptWord = TranscriptionArtifact["content"]["words"]["items"][number];
+export interface PeacockeryVoiceRealtimeOptions extends PeacockeryVoiceClientOptions {
+    channels?: number;
+    encoding?: string;
+    endpointing?: string;
+    interimResults?: boolean;
+    language?: string;
+    model: string;
+    sampleRate?: number;
+    targetStreamingDelayMs?: 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 type PeacockeryVoiceRealtimeEvent = 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,130 @@
+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,
+        encoding: options.encoding,
+        endpointing: options.endpointing,
+        interim_results: options.interimResults,
+        language: options.language,
+        model: options.model,
+        sample_rate: options.sampleRate,
+        target_streaming_delay_ms: options.targetStreamingDelayMs,
+        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));
+        }
+    }
+    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 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 (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;
@@ -2029,6 +2072,7 @@ export interface components {
             completed_at: string | null;
             created_at: string;
             error: string | null;
+            error_details: components["schemas"]["ProviderFailureDiagnostic"];
             job_id: string;
             /** @enum {string} */
             kind: "transcription";
@@ -2040,6 +2084,17 @@ export interface components {
             status: "pending" | "queued" | "running" | "succeeded" | "failed";
             updated_at: string;
         };
+        ProviderFailureDiagnostic: {
+            /** @enum {string} */
+            category: "authentication" | "empty_output" | "invalid_request" | "network" | "rate_limited" | "timeout" | "unavailable" | "unknown";
+            message: string;
+            provider?: string;
+            providerCode?: string;
+            requestId?: string;
+            retryAfterMs?: number;
+            retryable: boolean;
+            statusCode?: number;
+        } | null;
         TranscriptionArtifact: {
             content: {
                 audio_events: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simonpeacocks/peacockery-voice-client",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Generated TypeScript client for the Peacockery Voice API",
   "type": "module",
   "license": "MIT",