@vellumai/assistant 0.6.3 → 0.6.4

package/src/stt/__tests__/daemon-batch-transcriber.test.ts

@@ -0,0 +1,392 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { SttError } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Module mocks — must precede dynamic imports
+// ---------------------------------------------------------------------------
+
+let mockWhisperTranscribeResult: { text: string } = { text: "" };
+let mockWhisperTranscribeError: Error | null = null;
+
+mock.module("../../providers/speech-to-text/openai-whisper.js", () => ({
+  OpenAIWhisperProvider: class MockWhisperProvider {
+    constructor(_apiKey: string) {}
+    async transcribe(_audio: Buffer, _mimeType: string, _signal?: AbortSignal) {
+      if (mockWhisperTranscribeError) throw mockWhisperTranscribeError;
+      return mockWhisperTranscribeResult;
+    }
+  },
+}));
+
+let mockDeepgramTranscribeResult: { text: string } = { text: "" };
+let mockDeepgramTranscribeError: Error | null = null;
+
+mock.module("../../providers/speech-to-text/deepgram.js", () => ({
+  DeepgramProvider: class MockDeepgramProvider {
+    constructor(_apiKey: string) {}
+    async transcribe(_audio: Buffer, _mimeType: string, _signal?: AbortSignal) {
+      if (mockDeepgramTranscribeError) throw mockDeepgramTranscribeError;
+      return mockDeepgramTranscribeResult;
+    }
+  },
+}));
+
+let mockGeminiTranscribeResult: { text: string } = { text: "" };
+let mockGeminiTranscribeError: Error | null = null;
+
+mock.module("../../providers/speech-to-text/google-gemini.js", () => ({
+  GoogleGeminiProvider: class MockGoogleGeminiProvider {
+    constructor(_apiKey: string) {}
+    async transcribe(_audio: Buffer, _mimeType: string, _signal?: AbortSignal) {
+      if (mockGeminiTranscribeError) throw mockGeminiTranscribeError;
+      return mockGeminiTranscribeResult;
+    }
+  },
+}));
+
+// Dynamic import so mocks are active when the module loads.
+const { createDaemonBatchTranscriber, normalizeSttError } =
+  await import("../daemon-batch-transcriber.js");
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("createDaemonBatchTranscriber", () => {
+  beforeEach(() => {
+    mockWhisperTranscribeResult = { text: "" };
+    mockWhisperTranscribeError = null;
+    mockDeepgramTranscribeResult = { text: "" };
+    mockDeepgramTranscribeError = null;
+    mockGeminiTranscribeResult = { text: "" };
+    mockGeminiTranscribeError = null;
+  });
+
+  // -------------------------------------------------------------------------
+  // Credential resolution
+  // -------------------------------------------------------------------------
+
+  test("returns null when no API key is provided", () => {
+    expect(createDaemonBatchTranscriber(null, "openai-whisper")).toBeNull();
+    expect(
+      createDaemonBatchTranscriber(undefined, "openai-whisper"),
+    ).toBeNull();
+  });
+
+  test("returns a BatchTranscriber when API key is present", () => {
+    const transcriber = createDaemonBatchTranscriber(
+      "sk-test-key",
+      "openai-whisper",
+    );
+    expect(transcriber).not.toBeNull();
+  });
+
+  // -------------------------------------------------------------------------
+  // Provider identity — Whisper
+  // -------------------------------------------------------------------------
+
+  test("reports providerId as openai-whisper when created with openai-whisper", () => {
+    const transcriber = createDaemonBatchTranscriber(
+      "sk-test-key",
+      "openai-whisper",
+    );
+    expect(transcriber!.providerId).toBe("openai-whisper");
+  });
+
+  test("reports boundaryId as daemon-batch", () => {
+    const transcriber = createDaemonBatchTranscriber(
+      "sk-test-key",
+      "openai-whisper",
+    );
+    expect(transcriber!.boundaryId).toBe("daemon-batch");
+  });
+
+  // -------------------------------------------------------------------------
+  // Successful transcription — Whisper
+  // -------------------------------------------------------------------------
+
+  test("delegates transcription to the Whisper provider", async () => {
+    mockWhisperTranscribeResult = { text: "Hello from Whisper" };
+
+    const transcriber = createDaemonBatchTranscriber(
+      "sk-test-key",
+      "openai-whisper",
+    );
+    const result = await transcriber!.transcribe({
+      audio: Buffer.from("fake-audio"),
+      mimeType: "audio/ogg",
+    });
+
+    expect(result).toEqual({ text: "Hello from Whisper" });
+  });
+
+  // -------------------------------------------------------------------------
+  // Error propagation — raw provider errors pass through unchanged so that
+  // legacy callers (e.g. transcribe-audio.ts) can still detect AbortError.
+  // -------------------------------------------------------------------------
+
+  test("propagates AbortError unchanged", async () => {
+    const original = new DOMException(
+      "The operation was aborted",
+      "AbortError",
+    );
+    mockWhisperTranscribeError = original;
+
+    const transcriber = createDaemonBatchTranscriber(
+      "sk-test-key",
+      "openai-whisper",
+    );
+
+    try {
+      await transcriber!.transcribe({
+        audio: Buffer.from("audio"),
+        mimeType: "audio/wav",
+      });
+      expect.unreachable("should have thrown");
+    } catch (err) {
+      expect(err).toBe(original);
+      expect((err as Error).name).toBe("AbortError");
+    }
+  });
+
+  test("propagates generic errors unchanged", async () => {
+    const original = new Error("Something went wrong");
+    mockWhisperTranscribeError = original;
+
+    const transcriber = createDaemonBatchTranscriber(
+      "sk-test-key",
+      "openai-whisper",
+    );
+
+    try {
+      await transcriber!.transcribe({
+        audio: Buffer.from("audio"),
+        mimeType: "audio/wav",
+      });
+      expect.unreachable("should have thrown");
+    } catch (err) {
+      expect(err).toBe(original);
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // Provider identity — Deepgram
+  // -------------------------------------------------------------------------
+
+  test("reports providerId as deepgram when created with deepgram", () => {
+    const transcriber = createDaemonBatchTranscriber("dg-test-key", "deepgram");
+    expect(transcriber).not.toBeNull();
+    expect(transcriber!.providerId).toBe("deepgram");
+  });
+
+  test("reports boundaryId as daemon-batch for deepgram", () => {
+    const transcriber = createDaemonBatchTranscriber("dg-test-key", "deepgram");
+    expect(transcriber!.boundaryId).toBe("daemon-batch");
+  });
+
+  // -------------------------------------------------------------------------
+  // Successful transcription — Deepgram
+  // -------------------------------------------------------------------------
+
+  test("delegates transcription to the Deepgram provider", async () => {
+    mockDeepgramTranscribeResult = { text: "Hello from Deepgram" };
+
+    const transcriber = createDaemonBatchTranscriber("dg-test-key", "deepgram");
+    const result = await transcriber!.transcribe({
+      audio: Buffer.from("fake-audio"),
+      mimeType: "audio/ogg",
+    });
+
+    expect(result).toEqual({ text: "Hello from Deepgram" });
+  });
+
+  // -------------------------------------------------------------------------
+  // Error propagation — Deepgram
+  // -------------------------------------------------------------------------
+
+  test("propagates Deepgram errors unchanged", async () => {
+    const original = new Error("Deepgram API error (401): Invalid credentials");
+    mockDeepgramTranscribeError = original;
+
+    const transcriber = createDaemonBatchTranscriber("dg-test-key", "deepgram");
+
+    try {
+      await transcriber!.transcribe({
+        audio: Buffer.from("audio"),
+        mimeType: "audio/wav",
+      });
+      expect.unreachable("should have thrown");
+    } catch (err) {
+      expect(err).toBe(original);
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // Null on missing key — Deepgram
+  // -------------------------------------------------------------------------
+
+  test("returns null for deepgram when no API key is provided", () => {
+    expect(createDaemonBatchTranscriber(null, "deepgram")).toBeNull();
+    expect(createDaemonBatchTranscriber(undefined, "deepgram")).toBeNull();
+  });
+
+  // -------------------------------------------------------------------------
+  // Provider identity — Google Gemini
+  // -------------------------------------------------------------------------
+
+  test("reports providerId as google-gemini when created with google-gemini", () => {
+    const transcriber = createDaemonBatchTranscriber(
+      "gemini-test-key",
+      "google-gemini",
+    );
+    expect(transcriber).not.toBeNull();
+    expect(transcriber!.providerId).toBe("google-gemini");
+  });
+
+  test("reports boundaryId as daemon-batch for google-gemini", () => {
+    const transcriber = createDaemonBatchTranscriber(
+      "gemini-test-key",
+      "google-gemini",
+    );
+    expect(transcriber!.boundaryId).toBe("daemon-batch");
+  });
+
+  // -------------------------------------------------------------------------
+  // Successful transcription — Google Gemini
+  // -------------------------------------------------------------------------
+
+  test("delegates transcription to the Google Gemini provider", async () => {
+    mockGeminiTranscribeResult = { text: "Hello from Gemini" };
+
+    const transcriber = createDaemonBatchTranscriber(
+      "gemini-test-key",
+      "google-gemini",
+    );
+    const result = await transcriber!.transcribe({
+      audio: Buffer.from("fake-audio"),
+      mimeType: "audio/ogg",
+    });
+
+    expect(result).toEqual({ text: "Hello from Gemini" });
+  });
+
+  // -------------------------------------------------------------------------
+  // Error propagation — Google Gemini
+  // -------------------------------------------------------------------------
+
+  test("propagates Google Gemini errors unchanged", async () => {
+    const original = new Error(
+      "Google Gemini API error (401): Invalid credentials",
+    );
+    mockGeminiTranscribeError = original;
+
+    const transcriber = createDaemonBatchTranscriber(
+      "gemini-test-key",
+      "google-gemini",
+    );
+
+    try {
+      await transcriber!.transcribe({
+        audio: Buffer.from("audio"),
+        mimeType: "audio/wav",
+      });
+      expect.unreachable("should have thrown");
+    } catch (err) {
+      expect(err).toBe(original);
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // Null on missing key — Google Gemini
+  // -------------------------------------------------------------------------
+
+  test("returns null for google-gemini when no API key is provided", () => {
+    expect(createDaemonBatchTranscriber(null, "google-gemini")).toBeNull();
+    expect(createDaemonBatchTranscriber(undefined, "google-gemini")).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// normalizeSttError — callers use this explicitly when they need categories
+// ---------------------------------------------------------------------------
+
+describe("normalizeSttError", () => {
+  test("normalizes AbortError to timeout category", () => {
+    const err = new DOMException("The operation was aborted", "AbortError");
+    const result = normalizeSttError(err);
+    expect(result).toBeInstanceOf(SttError);
+    expect(result.category).toBe("timeout");
+  });
+
+  test("normalizes 401 errors to auth category", () => {
+    const result = normalizeSttError(
+      new Error("Whisper API error (401): Unauthorized"),
+    );
+    expect(result).toBeInstanceOf(SttError);
+    expect(result.category).toBe("auth");
+  });
+
+  test("normalizes 403 errors to auth category", () => {
+    const result = normalizeSttError(
+      new Error("Whisper API error (403): Forbidden"),
+    );
+    expect(result).toBeInstanceOf(SttError);
+    expect(result.category).toBe("auth");
+  });
+
+  test("normalizes 429 errors to rate-limit category", () => {
+    const result = normalizeSttError(
+      new Error("Whisper API error (429): Too Many Requests"),
+    );
+    expect(result).toBeInstanceOf(SttError);
+    expect(result.category).toBe("rate-limit");
+  });
+
+  test("normalizes rate limit text to rate-limit category", () => {
+    const result = normalizeSttError(
+      new Error("Request rate-limited by provider"),
+    );
+    expect(result).toBeInstanceOf(SttError);
+    expect(result.category).toBe("rate-limit");
+  });
+
+  test("normalizes 400 audio errors to invalid-audio category", () => {
+    const result = normalizeSttError(
+      new Error("Whisper API error (400): Invalid audio format"),
+    );
+    expect(result).toBeInstanceOf(SttError);
+    expect(result.category).toBe("invalid-audio");
+  });
+
+  test("normalizes unknown errors to provider-error category", () => {
+    const result = normalizeSttError(new Error("Something went wrong"));
+    expect(result).toBeInstanceOf(SttError);
+    expect(result.category).toBe("provider-error");
+  });
+
+  test("passes through SttError instances without re-wrapping", () => {
+    const original = new SttError("auth", "Custom auth failure");
+    const result = normalizeSttError(original);
+    expect(result).toBe(original);
+    expect(result.category).toBe("auth");
+  });
+
+  // Deepgram error normalization (same categories apply)
+
+  test("normalizes Deepgram 401 errors to auth category", () => {
+    const result = normalizeSttError(
+      new Error("Deepgram API error (401): Invalid credentials"),
+    );
+    expect(result).toBeInstanceOf(SttError);
+    expect(result.category).toBe("auth");
+  });
+
+  test("normalizes Deepgram 429 errors to rate-limit category", () => {
+    const result = normalizeSttError(
+      new Error("Deepgram API error (429): Rate limited"),
+    );
+    expect(result).toBeInstanceOf(SttError);
+    expect(result.category).toBe("rate-limit");
+  });
+});

package/src/stt/__tests__/types.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+
+import type {
+  SttStreamServerClosedEvent,
+  SttStreamServerErrorEvent,
+  SttStreamServerEvent,
+  SttStreamServerFinalEvent,
+  SttStreamServerPartialEvent,
+} from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Type-shape assertions for the streaming server event discriminated union.
+//
+// These types are TypeScript interfaces (no runtime Zod schemas), so the
+// "tests" below are primarily structural — they fail to compile if the
+// interfaces change shape in a way that breaks an existing caller. The
+// runtime assertions are intentionally light: they confirm the literal
+// values round-trip unchanged through an assignment to the union type.
+// ---------------------------------------------------------------------------
+
+describe("SttStreamServerEvent types", () => {
+  test("partial event compiles and round-trips without speakerLabel", () => {
+    const event: SttStreamServerPartialEvent = {
+      type: "partial",
+      text: "hello",
+    };
+    const asUnion: SttStreamServerEvent = event;
+    expect(asUnion.type).toBe("partial");
+    expect(event.text).toBe("hello");
+    expect(event.speakerLabel).toBeUndefined();
+  });
+
+  test("partial event accepts a speakerLabel when diarization is enabled", () => {
+    const event: SttStreamServerPartialEvent = {
+      type: "partial",
+      text: "hello",
+      speakerLabel: "0",
+    };
+    const asUnion: SttStreamServerEvent = event;
+    expect(asUnion.type).toBe("partial");
+    expect(event.speakerLabel).toBe("0");
+  });
+
+  test("final event compiles and round-trips without speakerLabel", () => {
+    const event: SttStreamServerFinalEvent = {
+      type: "final",
+      text: "world",
+    };
+    const asUnion: SttStreamServerEvent = event;
+    expect(asUnion.type).toBe("final");
+    expect(event.text).toBe("world");
+    expect(event.speakerLabel).toBeUndefined();
+  });
+
+  test("final event accepts a speakerLabel when diarization is enabled", () => {
+    const event: SttStreamServerFinalEvent = {
+      type: "final",
+      text: "world",
+      speakerLabel: "1",
+    };
+    const asUnion: SttStreamServerEvent = event;
+    expect(asUnion.type).toBe("final");
+    expect(event.speakerLabel).toBe("1");
+  });
+
+  test("error event has no speakerLabel field", () => {
+    const event: SttStreamServerErrorEvent = {
+      type: "error",
+      category: "provider-error",
+      message: "boom",
+    };
+    const asUnion: SttStreamServerEvent = event;
+    expect(asUnion.type).toBe("error");
+    // @ts-expect-error — speakerLabel is not part of SttStreamServerErrorEvent.
+    const _label: string | undefined = event.speakerLabel;
+    expect(_label).toBeUndefined();
+  });
+
+  test("closed event has no speakerLabel field", () => {
+    const event: SttStreamServerClosedEvent = {
+      type: "closed",
+    };
+    const asUnion: SttStreamServerEvent = event;
+    expect(asUnion.type).toBe("closed");
+    // @ts-expect-error — speakerLabel is not part of SttStreamServerClosedEvent.
+    const _label: string | undefined = event.speakerLabel;
+    expect(_label).toBeUndefined();
+  });
+});

package/src/stt/daemon-batch-transcriber.ts

@@ -0,0 +1,195 @@
+/**
+ * Daemon batch transcriber facade.
+ *
+ * Provides a single resolver that returns a `BatchTranscriber` implementation
+ * when provider credentials are available, or `null` when no STT backend can
+ * be configured. Callers use this instead of constructing provider classes
+ * directly.
+ *
+ * Supported daemon-batch providers:
+ * - OpenAI Whisper (`openai-whisper`)
+ * - Deepgram (`deepgram`)
+ * - Google Gemini (`google-gemini`)
+ */
+
+import type {
+  BatchTranscriber,
+  SttProviderId,
+  SttTranscribeRequest,
+  SttTranscribeResult,
+} from "./types.js";
+import { SttError } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// OpenAI Whisper adapter — implements BatchTranscriber on top of the existing
+// OpenAIWhisperProvider low-level class.
+// ---------------------------------------------------------------------------
+
+/**
+ * Wraps `OpenAIWhisperProvider` behind the `BatchTranscriber` contract.
+ *
+ * Raw provider errors propagate unchanged so that legacy callers (e.g.
+ * `transcribe-audio.ts`) can continue detecting `AbortError` by name.
+ * Callers that want normalized categories should wrap calls with
+ * {@link normalizeSttError}.
+ */
+class WhisperBatchTranscriber implements BatchTranscriber {
+  readonly providerId = "openai-whisper" as const;
+  readonly boundaryId = "daemon-batch" as const;
+
+  private readonly apiKey: string;
+
+  constructor(apiKey: string) {
+    this.apiKey = apiKey;
+  }
+
+  async transcribe(
+    request: SttTranscribeRequest,
+  ): Promise<SttTranscribeResult> {
+    // Lazy-import so the module graph stays lightweight for callers that
+    // only need the resolver, not the provider.
+    const { OpenAIWhisperProvider } =
+      await import("../providers/speech-to-text/openai-whisper.js");
+    const provider = new OpenAIWhisperProvider(this.apiKey);
+
+    return provider.transcribe(request.audio, request.mimeType, request.signal);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Deepgram adapter — implements BatchTranscriber on top of the Deepgram
+// prerecorded-audio provider.
+// ---------------------------------------------------------------------------
+
+/**
+ * Wraps `DeepgramProvider` behind the `BatchTranscriber` contract.
+ *
+ * Same error-propagation semantics as WhisperBatchTranscriber: raw provider
+ * errors pass through unchanged.
+ */
+class DeepgramBatchTranscriber implements BatchTranscriber {
+  readonly providerId = "deepgram" as const;
+  readonly boundaryId = "daemon-batch" as const;
+
+  private readonly apiKey: string;
+
+  constructor(apiKey: string) {
+    this.apiKey = apiKey;
+  }
+
+  async transcribe(
+    request: SttTranscribeRequest,
+  ): Promise<SttTranscribeResult> {
+    const { DeepgramProvider } =
+      await import("../providers/speech-to-text/deepgram.js");
+    const provider = new DeepgramProvider(this.apiKey);
+
+    return provider.transcribe(request.audio, request.mimeType, request.signal);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Google Gemini adapter — implements BatchTranscriber on top of the Google
+// Gemini multimodal provider.
+// ---------------------------------------------------------------------------
+
+/**
+ * Wraps `GoogleGeminiProvider` behind the `BatchTranscriber` contract.
+ *
+ * Same error-propagation semantics as WhisperBatchTranscriber: raw provider
+ * errors pass through unchanged.
+ */
+class GoogleGeminiBatchTranscriber implements BatchTranscriber {
+  readonly providerId = "google-gemini" as const;
+  readonly boundaryId = "daemon-batch" as const;
+
+  private readonly apiKey: string;
+
+  constructor(apiKey: string) {
+    this.apiKey = apiKey;
+  }
+
+  async transcribe(
+    request: SttTranscribeRequest,
+  ): Promise<SttTranscribeResult> {
+    const { GoogleGeminiProvider } =
+      await import("../providers/speech-to-text/google-gemini.js");
+    const provider = new GoogleGeminiProvider(this.apiKey);
+
+    return provider.transcribe(request.audio, request.mimeType, request.signal);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Error normalization
+// ---------------------------------------------------------------------------
+
+/**
+ * Map a raw provider error into an {@link SttError} with a normalized category.
+ *
+ * Callers that need structured error categories should wrap
+ * `BatchTranscriber.transcribe()` calls with this utility.
+ */
+export function normalizeSttError(err: unknown): SttError {
+  if (err instanceof SttError) return err;
+
+  const message = err instanceof Error ? err.message : String(err);
+
+  // Abort / timeout
+  if (err instanceof Error && err.name === "AbortError") {
+    return new SttError("timeout", message);
+  }
+
+  // Auth (401 / 403)
+  if (/\b40[13]\b/.test(message)) {
+    return new SttError("auth", message);
+  }
+
+  // Rate limit (429)
+  if (/\b429\b/.test(message) || /rate.?limit/i.test(message)) {
+    return new SttError("rate-limit", message);
+  }
+
+  // Invalid audio (400 with recognisable hints)
+  if (/\b400\b/.test(message) && /audio|format|file/i.test(message)) {
+    return new SttError("invalid-audio", message);
+  }
+
+  return new SttError("provider-error", message);
+}
+
+// ---------------------------------------------------------------------------
+// Public resolver / factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a `BatchTranscriber` for the daemon-batch boundary.
+ *
+ * Callers provide the API key and provider ID (obtained via the authorized
+ * secure-keys importer in `providers/speech-to-text/resolve.ts`) so that
+ * this module doesn't need to import secure-keys directly.
+ *
+ * Returns `null` when `apiKey` is falsy, signalling to the caller that
+ * batch transcription is unavailable.
+ */
+export function createDaemonBatchTranscriber(
+  apiKey: string | null | undefined,
+  providerId: SttProviderId,
+): BatchTranscriber | null {
+  if (!apiKey) return null;
+
+  switch (providerId) {
+    case "openai-whisper":
+      return new WhisperBatchTranscriber(apiKey);
+    case "deepgram":
+      return new DeepgramBatchTranscriber(apiKey);
+    case "google-gemini":
+      return new GoogleGeminiBatchTranscriber(apiKey);
+    default: {
+      // Exhaustive check — compile error if a new SttProviderId is added
+      // without a corresponding case here.
+      const _exhaustive: never = providerId;
+      return null;
+    }
+  }
+}