@mycadet/assistant 0.12.11 → 0.13.0

package/src/cloud/cloud-speech.test.ts

@@ -1,335 +0,0 @@
-import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
-
-interface MockCloudClient {
-  cloudAssistantId: string;
-  fetch: ReturnType<typeof mock>;
-}
-
-let mockClient: MockCloudClient | null = null;
-
-mock.module("./client.js", () => ({
-  CadetCloudClient: {
-    create: async () => mockClient,
-  },
-}));
-
-import {
-  managedSpeechSynthesize,
-  managedSpeechTranscribe,
-  managedSpeechVoices,
-} from "./cloud-speech.js";
-
-const AUDIO = Buffer.from([0x01, 0x02, 0x03, 0xff]);
-
-describe("managedSpeechTranscribe", () => {
-  beforeEach(() => {
-    mockClient = {
-      cloudAssistantId: "asst-123",
-      fetch: mock(
-        async () =>
-          new Response(
-            JSON.stringify({
-              text: "hello world",
-              providerId: "deepgram",
-              model: "nova-3",
-              durationSeconds: 12.5,
-            }),
-            { status: 200, headers: { "content-type": "application/json" } },
-          ),
-      ),
-    };
-  });
-
-  afterEach(() => {
-    mockClient = null;
-  });
-
-  test("posts base64 audio to the assistant's transcribe endpoint", async () => {
-    const result = await managedSpeechTranscribe({
-      audio: AUDIO,
-      mimeType: "audio/wav",
-      source: "dictation",
-    });
-
-    expect(result).toEqual({
-      ok: true,
-      value: { text: "hello world", durationSeconds: 12.5 },
-    });
-    const [path, init] = mockClient!.fetch.mock.calls[0] as [
-      string,
-      RequestInit,
-    ];
-    expect(path).toBe("/v1/assistants/asst-123/cloud-speech/stt/transcribe/");
-    expect(init.method).toBe("POST");
-    const body = JSON.parse(init.body as string);
-    expect(body).toEqual({
-      audioBase64: AUDIO.toString("base64"),
-      mimeType: "audio/wav",
-      source: "dictation",
-    });
-  });
-
-  test("omits source when not provided", async () => {
-    await managedSpeechTranscribe({ audio: AUDIO, mimeType: "audio/wav" });
-    const [, init] = mockClient!.fetch.mock.calls[0] as [string, RequestInit];
-    expect(JSON.parse(init.body as string)).not.toHaveProperty("source");
-  });
-
-  test("sends the spoken language when one is given", async () => {
-    // The cloud forwards this to Deepgram, which otherwise decodes the
-    // audio as English rather than detecting its language.
-    await managedSpeechTranscribe({
-      audio: AUDIO,
-      mimeType: "audio/wav",
-      language: "multi",
-    });
-    const [, init] = mockClient!.fetch.mock.calls[0] as [string, RequestInit];
-    expect(JSON.parse(init.body as string).language).toBe("multi");
-  });
-
-  test("omits language when not provided", async () => {
-    // An absent field and an empty one are different requests upstream, and
-    // the empty one fails the cloud serializer.
-    await managedSpeechTranscribe({ audio: AUDIO, mimeType: "audio/wav" });
-    const [, init] = mockClient!.fetch.mock.calls[0] as [string, RequestInit];
-    expect(JSON.parse(init.body as string)).not.toHaveProperty("language");
-  });
-
-  test("returns unavailable when no platform client resolves", async () => {
-    mockClient = null;
-    const result = await managedSpeechTranscribe({
-      audio: AUDIO,
-      mimeType: "audio/wav",
-    });
-    expect(result).toMatchObject({ ok: false, kind: "unavailable" });
-  });
-
-  test("returns unavailable when the assistant ID is missing", async () => {
-    mockClient!.cloudAssistantId = "";
-    const result = await managedSpeechTranscribe({
-      audio: AUDIO,
-      mimeType: "audio/wav",
-    });
-    expect(result).toMatchObject({ ok: false, kind: "unavailable" });
-  });
-
-  test("surfaces the cloud error code on 402", async () => {
-    mockClient!.fetch = mock(
-      async () =>
-        new Response(
-          JSON.stringify({
-            code: "insufficient_balance",
-            detail: "Insufficient balance. Please add funds to continue.",
-          }),
-          { status: 402, headers: { "content-type": "application/json" } },
-        ),
-    );
-    const result = await managedSpeechTranscribe({
-      audio: AUDIO,
-      mimeType: "audio/wav",
-    });
-    expect(result).toMatchObject({
-      ok: false,
-      kind: "platform-error",
-      status: 402,
-      code: "insufficient_balance",
-      message: "Insufficient balance. Please add funds to continue.",
-    });
-  });
-
-  test("treats a malformed 200 body as a cloud error", async () => {
-    mockClient!.fetch = mock(
-      async () =>
-        new Response(JSON.stringify({ unexpected: true }), {
-          status: 200,
-          headers: { "content-type": "application/json" },
-        }),
-    );
-    const result = await managedSpeechTranscribe({
-      audio: AUDIO,
-      mimeType: "audio/wav",
-    });
-    expect(result).toMatchObject({ ok: false, kind: "platform-error" });
-  });
-});
-
-describe("managedSpeechVoices", () => {
-  const CATALOG = {
-    voices: [
-      {
-        model: "aura-2-thalia-en",
-        label: "Thalia",
-        description: "American · clear, confident, energetic",
-        sampleUrl: "https://static.deepgram.com/examples/Aura-2-thalia.wav",
-        source: "deepgram",
-      },
-    ],
-    defaultModel: "aura-2-thalia-en",
-  };
-
-  beforeEach(() => {
-    mockClient = {
-      cloudAssistantId: "asst-123",
-      fetch: mock(async () => Response.json(CATALOG)),
-    };
-  });
-
-  afterEach(() => {
-    mockClient = null;
-  });
-
-  test("fetches and parses the cloud voice catalog", async () => {
-    const result = await managedSpeechVoices();
-
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.value).toEqual(CATALOG);
-    }
-    const [path, init] = mockClient!.fetch.mock.calls[0] as [
-      string,
-      RequestInit,
-    ];
-    expect(path).toBe("/v1/assistants/asst-123/cloud-speech/tts/voices/");
-    expect(init.method).toBe("GET");
-  });
-
-  test("drops malformed voice entries and tolerates a null default", async () => {
-    mockClient!.fetch = mock(async () =>
-      Response.json({
-        voices: [CATALOG.voices[0], { model: "missing-fields" }],
-        defaultModel: null,
-      }),
-    );
-    const result = await managedSpeechVoices();
-
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.value.voices).toEqual(CATALOG.voices);
-      expect(result.value.defaultModel).toBeNull();
-    }
-  });
-
-  test("treats a malformed body as a cloud error", async () => {
-    mockClient!.fetch = mock(async () => Response.json({ nope: true }));
-    const result = await managedSpeechVoices();
-    expect(result).toMatchObject({ ok: false, kind: "platform-error" });
-  });
-
-  test("propagates platform error responses", async () => {
-    mockClient!.fetch = mock(
-      async () =>
-        new Response(JSON.stringify({ code: "x", detail: "nope" }), {
-          status: 502,
-        }),
-    );
-    const result = await managedSpeechVoices();
-    expect(result).toMatchObject({
-      ok: false,
-      kind: "platform-error",
-      status: 502,
-    });
-  });
-});
-
-describe("managedSpeechSynthesize", () => {
-  const MP3_BYTES = Buffer.from([0x49, 0x44, 0x33, 0x04, 0x00]);
-
-  beforeEach(() => {
-    mockClient = {
-      cloudAssistantId: "asst-123",
-      fetch: mock(
-        async () =>
-          new Response(new Uint8Array(MP3_BYTES), {
-            status: 200,
-            headers: { "content-type": "audio/mpeg" },
-          }),
-      ),
-    };
-  });
-
-  afterEach(() => {
-    mockClient = null;
-  });
-
-  test("posts text and format, round-trips binary audio and content type", async () => {
-    const result = await managedSpeechSynthesize({
-      text: "hello",
-      format: "pcm_16000",
-    });
-
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(Buffer.compare(result.value.audio, MP3_BYTES)).toBe(0);
-      expect(result.value.contentType).toBe("audio/mpeg");
-    }
-    const [path, init] = mockClient!.fetch.mock.calls[0] as [
-      string,
-      RequestInit,
-    ];
-    expect(path).toBe("/v1/assistants/asst-123/cloud-speech/tts/synthesize/");
-    expect(JSON.parse(init.body as string)).toEqual({
-      text: "hello",
-      format: "pcm_16000",
-    });
-  });
-
-  test("includes the voice model in the body only when provided", async () => {
-    await managedSpeechSynthesize({
-      text: "hello",
-      format: "mp3",
-      model: "aura-2-zeus-en",
-    });
-    const [, init] = mockClient!.fetch.mock.calls[0] as [string, RequestInit];
-    expect(JSON.parse(init.body as string)).toEqual({
-      text: "hello",
-      format: "mp3",
-      model: "aura-2-zeus-en",
-    });
-
-    await managedSpeechSynthesize({ text: "hello", format: "mp3" });
-    const [, second] = mockClient!.fetch.mock.calls[1] as [string, RequestInit];
-    expect(JSON.parse(second.body as string)).not.toHaveProperty("model");
-  });
-
-  test("falls back to audio/mpeg when no content type is returned", async () => {
-    mockClient!.fetch = mock(
-      async () => new Response(new Uint8Array(MP3_BYTES), { status: 200 }),
-    );
-    const result = await managedSpeechSynthesize({
-      text: "hello",
-      format: "mp3",
-    });
-    expect(result.ok && result.value.contentType).toBe("audio/mpeg");
-  });
-
-  test("treats empty audio as a cloud error", async () => {
-    mockClient!.fetch = mock(
-      async () => new Response(new Uint8Array(0), { status: 200 }),
-    );
-    const result = await managedSpeechSynthesize({
-      text: "hello",
-      format: "mp3",
-    });
-    expect(result).toMatchObject({ ok: false, kind: "platform-error" });
-  });
-
-  test("surfaces insufficient_balance on 402", async () => {
-    mockClient!.fetch = mock(
-      async () =>
-        new Response(
-          JSON.stringify({ code: "insufficient_balance", detail: "Top up." }),
-          { status: 402, headers: { "content-type": "application/json" } },
-        ),
-    );
-    const result = await managedSpeechSynthesize({
-      text: "hello",
-      format: "mp3",
-    });
-    expect(result).toMatchObject({
-      ok: false,
-      kind: "platform-error",
-      status: 402,
-      code: "insufficient_balance",
-    });
-  });
-});

package/src/cloud/cloud-speech.ts

@@ -1,300 +0,0 @@
-/**
- * Client for the cloud's cloud speech endpoints: Cadet-held Deepgram
- * key, billed to the org's credits. The daemon sends complete audio (STT) or
- * text (TTS) and the cloud does the provider call — no speech credentials
- * ever live on this machine.
- *
- * Contract (mirrors `mycadet-platform` — do not change unilaterally):
- * - `POST /v1/assistants/{id}/cloud-speech/stt/transcribe/`
- *   `{audioBase64, mimeType, source?}` → 200 `{text, providerId, model,
- *   durationSeconds}`.
- * - `POST /v1/assistants/{id}/cloud-speech/tts/synthesize/`
- *   `{text, format?}` → 200 binary audio, `Content-Type` from upstream.
- * - Errors: `{code, detail}`; notable codes: `insufficient_balance` (402),
- *   `missing_price` (400), `provider_configuration_error` (500).
- *
- * Pure platform HTTP client: no provider-catalog, config-schema, or resolver
- * imports — the cadet STT/TTS providers build on top of it.
- */
-
-import { z } from "zod";
-
-import { CadetCloudClient } from "./client.js";
-
-export type CloudSpeechResult<T> =
-  | { ok: true; value: T }
-  | {
-      ok: false;
-      kind: "unavailable" | "platform-error";
-      status?: number;
-      /** Platform error code (e.g. `insufficient_balance`) when the body carried one. */
-      code?: string;
-      /**
-       * Platform-supplied human-readable message, present only when the error
-       * body carried a `detail` field. Absent when the failure fell back to a
-       * bare HTTP status. `message` mirrors this when set; callers use the
-       * presence of `detail` to distinguish real platform copy (safe to surface
-       * verbatim) from the generic status fallback.
-       */
-      detail?: string;
-      message: string;
-    };
-
-export interface CloudSpeechTranscription {
-  text: string;
-  durationSeconds: number;
-}
-
-const CloudSpeechTranscriptionSchema = z.object({
-  text: z.string(),
-  durationSeconds: z.number(),
-});
-
-export interface CloudSpeechSynthesis {
-  audio: Buffer;
-  contentType: string;
-}
-
-export type CloudSpeechTtsFormat = "mp3" | "wav_8000" | "pcm_16000";
-
-async function resolveClient(): Promise<
-  { client: CadetCloudClient } | { error: CloudSpeechResult<never> }
-> {
-  const client = await CadetCloudClient.create();
-  if (!client) {
-    return {
-      error: {
-        ok: false,
-        kind: "unavailable",
-        message: "Cloud speech is unavailable: no Cadet Cloud connection.",
-      },
-    };
-  }
-  if (!client.cloudAssistantId) {
-    return {
-      error: {
-        ok: false,
-        kind: "unavailable",
-        message:
-          "Cloud speech is unavailable: platform assistant ID is missing.",
-      },
-    };
-  }
-  return { client };
-}
-
-/**
- * Whether cloud speech can be used at all: a cloud connection whose
- * assistant identity is fully provisioned. A stored API key alone is not
- * enough — synthesis/transcription would fail before any request is made.
- */
-export async function managedSpeechAvailable(): Promise<boolean> {
-  return !("error" in (await resolveClient()));
-}
-
-export async function managedSpeechTranscribe(input: {
-  audio: Buffer;
-  mimeType: string;
-  source?: string;
-  /**
-   * Spoken language to decode: a BCP-47 code, or `"multi"` for nova-3
-   * code-switching. Omitted means the cloud sends none, which Deepgram
-   * decodes as English rather than detecting the language. Older platform
-   * builds that predate the field ignore it, so sending one is safe before
-   * the cloud side deploys.
-   */
-  language?: string;
-  signal?: AbortSignal;
-}): Promise<CloudSpeechResult<CloudSpeechTranscription>> {
-  const resolved = await resolveClient();
-  if ("error" in resolved) {
-    return resolved.error;
-  }
-  const { client } = resolved;
-
-  const response = await client.fetch(
-    `/v1/assistants/${encodeURIComponent(client.cloudAssistantId)}/cloud-speech/stt/transcribe/`,
-    {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        audioBase64: input.audio.toString("base64"),
-        mimeType: input.mimeType,
-        ...(input.source !== undefined ? { source: input.source } : {}),
-        ...(input.language ? { language: input.language } : {}),
-      }),
-      signal: input.signal,
-    },
-  );
-
-  if (!response.ok) {
-    return await platformError(response, "transcription");
-  }
-
-  const parsed = CloudSpeechTranscriptionSchema.safeParse(
-    await response.json().catch(() => null),
-  );
-  if (!parsed.success) {
-    return {
-      ok: false,
-      kind: "platform-error",
-      status: response.status,
-      message: "Cloud speech transcription returned a malformed response.",
-    };
-  }
-  return {
-    ok: true,
-    value: {
-      text: parsed.data.text,
-      durationSeconds: parsed.data.durationSeconds,
-    },
-  };
-}
-
-export async function managedSpeechSynthesize(input: {
-  text: string;
-  format: CloudSpeechTtsFormat;
-  /** Voice model (e.g. "aura-2-thalia-en"); omitted = platform default. */
-  model?: string;
-  signal?: AbortSignal;
-}): Promise<CloudSpeechResult<CloudSpeechSynthesis>> {
-  const resolved = await resolveClient();
-  if ("error" in resolved) {
-    return resolved.error;
-  }
-  const { client } = resolved;
-
-  const response = await client.fetch(
-    `/v1/assistants/${encodeURIComponent(client.cloudAssistantId)}/cloud-speech/tts/synthesize/`,
-    {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        text: input.text,
-        format: input.format,
-        ...(input.model !== undefined ? { model: input.model } : {}),
-      }),
-      signal: input.signal,
-    },
-  );
-
-  if (!response.ok) {
-    return await platformError(response, "synthesis");
-  }
-
-  const audio = Buffer.from(await response.arrayBuffer());
-  if (audio.length === 0) {
-    return {
-      ok: false,
-      kind: "platform-error",
-      status: response.status,
-      message: "Cloud speech synthesis returned empty audio.",
-    };
-  }
-  return {
-    ok: true,
-    value: {
-      audio,
-      contentType: response.headers.get("content-type") ?? "audio/mpeg",
-    },
-  };
-}
-
-export interface CloudSpeechVoice {
-  model: string;
-  label: string;
-  description: string;
-  sampleUrl: string;
-  /** Upstream provider that synthesizes this voice (e.g. "deepgram"). */
-  source: string;
-}
-
-export interface CloudSpeechVoiceCatalog {
-  /** Offered voices in display order; only currently-usable voices. */
-  voices: CloudSpeechVoice[];
-  /** Always one of `voices`; null when no voices are offered. */
-  defaultModel: string | null;
-}
-
-const CloudSpeechVoiceSchema = z.object({
-  model: z.string(),
-  label: z.string(),
-  description: z.string(),
-  sampleUrl: z.string(),
-  source: z.string(),
-});
-const CloudSpeechVoiceCatalogSchema = z.object({
-  voices: z.array(CloudSpeechVoiceSchema.nullable().catch(null)),
-  defaultModel: z.string().nullable().optional().catch(null),
-});
-const CloudSpeechErrorSchema = z.object({
-  code: z.string().optional().catch(undefined),
-  detail: z.string().optional().catch(undefined),
-});
-
-export async function managedSpeechVoices(input?: {
-  signal?: AbortSignal;
-}): Promise<CloudSpeechResult<CloudSpeechVoiceCatalog>> {
-  const resolved = await resolveClient();
-  if ("error" in resolved) {
-    return resolved.error;
-  }
-  const { client } = resolved;
-
-  const response = await client.fetch(
-    `/v1/assistants/${encodeURIComponent(client.cloudAssistantId)}/cloud-speech/tts/voices/`,
-    { method: "GET", signal: input?.signal },
-  );
-
-  if (!response.ok) {
-    return await platformError(response, "voice listing");
-  }
-
-  const parsed = CloudSpeechVoiceCatalogSchema.safeParse(
-    await response.json().catch(() => null),
-  );
-  if (!parsed.success) {
-    return {
-      ok: false,
-      kind: "platform-error",
-      status: response.status,
-      message: "Cloud speech voice listing returned a malformed response.",
-    };
-  }
-  return {
-    ok: true,
-    value: {
-      voices: parsed.data.voices.filter(
-        (voice): voice is CloudSpeechVoice => voice !== null,
-      ),
-      defaultModel: parsed.data.defaultModel ?? null,
-    },
-  };
-}
-
-async function platformError(
-  response: Response,
-  operation: string,
-): Promise<CloudSpeechResult<never>> {
-  let code: string | undefined;
-  let detail: string | undefined;
-  try {
-    const parsed = CloudSpeechErrorSchema.safeParse(await response.json());
-    if (parsed.success) {
-      code = parsed.data.code;
-      detail = parsed.data.detail;
-    }
-  } catch {
-    // Non-JSON error body; status alone will have to do.
-  }
-  return {
-    ok: false,
-    kind: "platform-error",
-    status: response.status,
-    code,
-    detail,
-    message:
-      detail ??
-      `Cloud speech ${operation} failed (platform returned ${response.status}).`,
-  };
-}