Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

21.0 KB
Raw Blame
const test = require("node:test");
const assert = require("node:assert/strict");

const load = () => import("../../src/helpers/providerHttpErrors.js");

const classify = async (args) =>
  (await load()).providerHttpError({ provider: "Mistral", surface: "transcription", ...args });

test("401 is an auth failure that points at Speech-to-Text settings", async () => {
  const c = await classify({ status: 401, body: '{"detail":"Invalid API Key"}' });
  assert.equal(c.code, "PROVIDER_AUTH_FAILED");
  assert.equal(c.messageKey, "providerErrors.authFailed");
  assert.deepEqual(c.messageParams, { provider: "Mistral" });
  assert.equal(c.settingsTarget, "speechToText");
  assert.equal(c.surface, "transcription");
});

test("LLM surface points fixable errors at Language Models settings", async () => {
  const c = await classify({ status: 401, body: "", surface: "llm" });
  assert.equal(c.settingsTarget, "llms");
});

test("400 or 403 carrying an invalid-key signal is an auth failure (Gemini API_KEY_INVALID)", async () => {
  const gemini = await classify({
    provider: "Gemini",
    status: 400,
    body: { error: { status: "INVALID_ARGUMENT", details: [{ reason: "API_KEY_INVALID" }] } },
  });
  assert.equal(gemini.code, "PROVIDER_AUTH_FAILED");
  const forbidden = await classify({ status: 403, body: "invalid x-api-key" });
  assert.equal(forbidden.code, "PROVIDER_AUTH_FAILED");
});

test("other 403s are access denied", async () => {
  const c = await classify({ status: 403, body: '{"error":"model not allowed for this project"}' });
  assert.equal(c.code, "PROVIDER_ACCESS_DENIED");
  assert.equal(c.settingsTarget, "speechToText");
});

test("402 and billing-flavoured 400/429 are quota exhaustion", async () => {
  assert.equal((await classify({ status: 402, body: "" })).code, "PROVIDER_QUOTA_EXHAUSTED");
  const openai = await classify({
    provider: "OpenAI",
    status: 429,
    body: {
      error: {
        message: "You exceeded your current quota, please check your plan and billing details.",
        type: "insufficient_quota",
      },
    },
  });
  assert.equal(openai.code, "PROVIDER_QUOTA_EXHAUSTED");
  const anthropic = await classify({
    provider: "Anthropic",
    status: 400,
    surface: "llm",
    body: {
      type: "error",
      error: {
        type: "invalid_request_error",
        message: "Your credit balance is too low to access the Anthropic API.",
      },
    },
  });
  assert.equal(anthropic.code, "PROVIDER_QUOTA_EXHAUSTED");
});

test("self-hosted quota exhaustion gets its own sentence instead of \"Your Your server account\"", async () => {
  const { providerHttpError } = await load();
  const err = providerHttpError({
    provider: "self-hosted",
    selfHosted: true,
    status: 402,
    body: "",
    surface: "llm",
  });
  assert.equal(err.code, "PROVIDER_QUOTA_EXHAUSTED");
  assert.equal(err.messageKey, "providerErrors.selfHosted.quotaExhausted");
  assert.equal(err.message, "Your server says the account is out of credit.");
  assert.equal(err.message.includes("Your Your server"), false);
});

// Real bodies: both mention quota and billing, but only ask the user to wait.
const GEMINI_RATE_LIMIT_BODY = {
  error: {
    code: 429,
    message:
      "You exceeded your current quota, please check your plan and billing details. For more information on this error, head to: https://ai.google.dev/gemini-api/docs/rate-limits.\n* Quota exceeded for metric: generativelanguage.googleapis.com/generate_content_free_tier_requests, limit: 10, model: gemini-3.5-flash\nPlease retry in 52.4s.",
    status: "RESOURCE_EXHAUSTED",
  },
};
const GROQ_RATE_LIMIT_BODY = {
  error: {
    message:
      "Rate limit reached for model `whisper-large-v3-turbo` in organization `org_01` service tier `on_demand` on seconds of audio per hour (ASPH): Limit 7200, Used 7190, Requested 30. Please try again in 10s. Need more tokens? Upgrade to Dev Tier today at https://console.groq.com/settings/billing",
    type: "seconds",
    code: "rate_limit_exceeded",
  },
};

test("a Gemini free-tier quota 429 stays a rate limit", async () => {
  const c = await classify({ provider: "Gemini", status: 429, body: GEMINI_RATE_LIMIT_BODY });
  assert.equal(c.code, "PROVIDER_RATE_LIMITED");
  assert.equal(c.messageKey, "hooks.audioRecording.errorDescriptions.providerRateLimited");
  assert.equal(c.settingsTarget, undefined);
});

test("a Groq 429 that links to its billing page stays a rate limit", async () => {
  const c = await classify({ provider: "Groq", status: 429, body: GROQ_RATE_LIMIT_BODY });
  assert.equal(c.code, "PROVIDER_RATE_LIMITED");
  assert.equal(c.settingsTarget, undefined);
});

test("OpenAI's real out-of-quota 429 shares Gemini's wording but is quota exhaustion", async () => {
  const c = await classify({
    provider: "OpenAI",
    status: 429,
    body: {
      error: {
        message:
          "You exceeded your current quota, please check your plan and billing details. For more information on this error, read the docs: https://platform.openai.com/docs/guides/error-codes/api-errors.",
        type: "insufficient_quota",
        param: null,
        code: "insufficient_quota",
      },
    },
  });
  assert.equal(c.code, "PROVIDER_QUOTA_EXHAUSTED");
});

test("rate-limit 429s from Gemini and Groq are still retried on the AI-model path", async () => {
  const { providerHttpError } = await load();
  const { createApiRetryStrategy } = await import("../../src/utils/retry.ts");
  const { shouldRetry } = createApiRetryStrategy();
  for (const [provider, body] of [
    ["Gemini", GEMINI_RATE_LIMIT_BODY],
    ["Groq", GROQ_RATE_LIMIT_BODY],
  ]) {
    const error = providerHttpError({ provider, status: 429, body, surface: "llm" });
    assert.equal(shouldRetry(error), true, `${provider} rate limit should retry`);
  }
});

test("404 and model-not-found 400 name the model", async () => {
  const notFound = await classify({ status: 404, body: "", model: "voxtral-max" });
  assert.equal(notFound.code, "PROVIDER_MODEL_NOT_FOUND");
  assert.equal(notFound.messageKey, "providerErrors.modelNotFound");
  assert.deepEqual(notFound.messageParams, { provider: "Mistral", model: "voxtral-max" });
  const badModel = await classify({
    provider: "OpenAI",
    status: 400,
    body: { error: { message: "The model `gpt-9` does not exist", code: "model_not_found" } },
  });
  assert.equal(badModel.code, "PROVIDER_MODEL_NOT_FOUND");
  assert.equal(badModel.messageKey, "providerErrors.modelNotFoundNoModel");
});

test("a self-hosted 404 without a model signal is a generic error, not a model error", async () => {
  const c = await classify({ status: 404, body: "<html>Not Found</html>", selfHosted: true });
  assert.equal(c.code, "PROVIDER_ERROR");
  assert.equal(c.messageKey, "providerErrors.selfHosted.unknown");
  assert.equal(c.messageParams.provider, "Your server");
});

test("a 404 for a missing conversation item doesn't blame the model", async () => {
  const c = await classify({
    provider: "OpenAI",
    surface: "llm",
    status: 404,
    model: "gpt-5-mini",
    body: {
      error: {
        message:
          "Item with id 'rs_123' not found. Items are not persisted for Zero Data Retention " +
          "organizations. Remove this item from your input and try again.",
        type: "invalid_request_error",
        code: null,
      },
    },
  });
  assert.equal(c.code, "PROVIDER_BAD_REQUEST");
  assert.equal(c.messageKey, "providerErrors.badRequest");
  assert.equal(c.settingsTarget, undefined);
});

test("413, other 4xx, timeouts, 5xx and unknown statuses", async () => {
  assert.equal((await classify({ status: 413, body: "" })).code, "PROVIDER_PAYLOAD_TOO_LARGE");
  for (const status of [400, 415, 422]) {
    assert.equal((await classify({ status, body: "bad audio" })).code, "PROVIDER_BAD_REQUEST");
  }
  for (const status of [408, 504]) {
    assert.equal((await classify({ status, body: "" })).code, "PROVIDER_TIMEOUT");
  }
  for (const status of [500, 502, 503, 529]) {
    assert.equal((await classify({ status, body: "" })).code, "PROVIDER_UNAVAILABLE");
  }
  assert.equal((await classify({ status: 418, body: "" })).code, "PROVIDER_ERROR");
});

test("technical details carry provider, status, request id and a trimmed body", async () => {
  const headers = new Headers({ "x-request-id": "req_123" });
  const c = await classify({ status: 500, body: "x".repeat(800), headers });
  assert.equal(c.technicalDetails.provider, "Mistral");
  assert.equal(c.technicalDetails.status, 500);
  assert.equal(c.technicalDetails.requestId, "req_123");
  assert.equal(c.technicalDetails.underlyingError.length, 501); // 500 chars + ellipsis
  const plain = await classify({ status: 500, body: "", headers: { "Request-Id": "abc" } });
  assert.equal(plain.technicalDetails.requestId, "abc");
  assert.equal(plain.technicalDetails.underlyingError, undefined);
});

test("HTML bodies collapse to a marker", async () => {
  const c = await classify({ status: 502, body: "<!DOCTYPE html><html><body>Bad gateway</body></html>" });
  assert.equal(c.technicalDetails.underlyingError, "<HTML response>");
});

test("keys echoed back in a body are redacted", async () => {
  const { redactProviderBody } = await load();
  const out = redactProviderBody(
    "Incorrect API key provided: sk-proj-ab***xyz. Also sk-ant-api03-zzzz gsk_abcd1234 AIzaSyA1234 xai-qwerty Authorization: Bearer eyJhbGciOi.abc"
  );
  for (const leaked of ["sk-proj-ab", "sk-ant-api03", "gsk_abcd", "AIzaSy", "xai-qwerty", "eyJhbGciOi"]) {
    assert.equal(out.includes(leaked), false, `${leaked} leaked: ${out}`);
  }
  assert.ok(out.includes("Bearer [redacted]"));
});

test("providerHttpError builds an Error carrying the classification and a short English message", async () => {
  const { providerHttpError } = await load();
  const err = providerHttpError({ provider: "Mistral", status: 401, body: "{}", surface: "transcription" });
  assert.ok(err instanceof Error);
  assert.equal(err.message, "Mistral rejected your API key.");
  assert.equal(err.code, "PROVIDER_AUTH_FAILED");
  assert.equal(err.status, 401);
  assert.equal(err.messageKey, "providerErrors.authFailed");
  assert.equal(err.settingsTarget, "speechToText");
  assert.equal(err.message.includes("{}"), false);
});

test("providerError builds key-missing errors per surface", async () => {
  const { providerError } = await load();
  const stt = providerError("API_KEY_MISSING", { provider: "Mistral", surface: "transcription" });
  assert.equal(stt.code, "API_KEY_MISSING");
  assert.equal(stt.messageKey, "hooks.audioRecording.errorDescriptions.providerKeyMissing");
  assert.equal(stt.settingsTarget, "speechToText");
  const llm = providerError("API_KEY_MISSING", { provider: "Anthropic", surface: "llm" });
  assert.equal(llm.messageKey, "providerErrors.keyMissing");
  assert.deepEqual(llm.messageParams, { provider: "Anthropic" });
  assert.equal(llm.settingsTarget, "llms");
});

test("asProviderError classifies AI SDK APICallError and RetryError", async () => {
  const { asProviderError } = await load();
  const apiCallError = Object.assign(new Error("Incorrect API key provided"), {
    name: "AI_APICallError",
    statusCode: 401,
    responseBody: '{"error":{"message":"Incorrect API key provided: sk-abcd1234"}}',
    responseHeaders: { "x-request-id": "r1" },
  });
  const direct = asProviderError(apiCallError, { provider: "OpenAI", model: "gpt-5.5", surface: "llm" });
  assert.equal(direct.code, "PROVIDER_AUTH_FAILED");
  assert.equal(direct.technicalDetails.requestId, "r1");
  assert.equal(direct.technicalDetails.underlyingError.includes("sk-abcd1234"), false);
  assert.equal(direct.cause, apiCallError);
  const retryError = Object.assign(new Error("Failed after 3 attempts"), {
    name: "AI_RetryError",
    lastError: Object.assign(new Error("overloaded"), { statusCode: 529, responseBody: "" }),
  });
  assert.equal(asProviderError(retryError, { provider: "Anthropic", surface: "llm" }).code, "PROVIDER_UNAVAILABLE");
});

test("asProviderError classifies timeouts and network failures", async () => {
  const { asProviderError } = await load();
  const ctx = { provider: "Groq", surface: "llm" };
  assert.equal(asProviderError(Object.assign(new Error("t"), { code: "LLM_REQUEST_TIMEOUT" }), ctx).code, "PROVIDER_TIMEOUT");
  assert.equal(asProviderError(Object.assign(new Error("t"), { name: "TimeoutError" }), ctx).code, "PROVIDER_TIMEOUT");
  const notFound = asProviderError(Object.assign(new Error("x"), { code: "ENOTFOUND" }), ctx);
  assert.equal(notFound.code, "PROVIDER_UNREACHABLE");
  assert.equal(notFound.technicalDetails.underlyingError, "ENOTFOUND");
  const refused = asProviderError(Object.assign(new Error("x"), { cause: { code: "ECONNREFUSED" } }), ctx);
  assert.equal(refused.code, "PROVIDER_UNREACHABLE");
  assert.equal(refused.technicalDetails.underlyingError, "ECONNREFUSED");
  const fetchFailed = asProviderError(new TypeError("fetch failed"), ctx);
  assert.equal(fetchFailed.code, "PROVIDER_UNREACHABLE");
  assert.deepEqual(fetchFailed.technicalDetails, { provider: "Groq" });
});

// Chromium reports a CORS-blocked HTTP error as "Failed to fetch" too: OpenAI's
// 401 for a bad sk- key carries no CORS header in the dictation window.
test("an online \"Failed to fetch\" points at the key and connection; offline it stays unreachable", async (t) => {
  const { asProviderError } = await load();
  const ctx = { provider: "OpenAI", surface: "transcription" };
  t.after(() => delete navigator.onLine);

  Object.defineProperty(navigator, "onLine", { configurable: true, value: true });
  const online = asProviderError(new TypeError("Failed to fetch"), ctx);
  assert.equal(online.code, "PROVIDER_NO_RESPONSE");
  assert.equal(online.message, "Couldn't get a response from OpenAI. Check your API key and connection.");
  assert.equal(online.settingsTarget, "speechToText");
  assert.deepEqual(online.technicalDetails, { provider: "OpenAI" }, "nothing beyond the message");

  Object.defineProperty(navigator, "onLine", { configurable: true, value: false });
  const offline = asProviderError(new TypeError("Failed to fetch"), ctx);
  assert.equal(offline.code, "PROVIDER_UNREACHABLE");
  assert.equal(offline.settingsTarget, undefined);
});

test("rate limits name the provider on the LLM surface and keep the dictation copy on transcription", async () => {
  const en = require("../../src/locales/en/translation.json");
  const llm = await classify({ provider: "Anthropic", status: 429, body: "", surface: "llm" });
  assert.equal(llm.code, "PROVIDER_RATE_LIMITED");
  assert.equal(llm.messageKey, "providerErrors.rateLimited");
  assert.deepEqual(llm.messageParams, { provider: "Anthropic" });
  const transcription = await classify({ status: 429, body: "", surface: "transcription" });
  assert.equal(transcription.messageKey, "hooks.audioRecording.errorDescriptions.providerRateLimited");
  const { providerHttpError } = await load();
  const error = providerHttpError({ provider: "Anthropic", status: 429, body: "", surface: "llm" });
  assert.equal(error.message, en.providerErrors.rateLimited.replace("{{provider}}", "Anthropic"));
});

test("asProviderError classifies Electron net::ERR_* rejections and leaves net::ERR_ABORTED alone", async () => {
  const { asProviderError } = await load();
  const ctx = { provider: "OpenAI", surface: "transcription" };
  for (const message of [
    "net::ERR_INTERNET_DISCONNECTED",
    "net::ERR_NAME_NOT_RESOLVED",
    "net::ERR_CONNECTION_REFUSED",
  ]) {
    const raw = new Error(message);
    const classified = asProviderError(raw, ctx);
    assert.equal(classified.code, "PROVIDER_UNREACHABLE", message);
    assert.equal(classified.messageKey, "providerErrors.unreachable");
    assert.equal(classified.cause, raw);
    // Main serialises only the message, so Copy details is the one place the code survives.
    assert.equal(classified.technicalDetails.underlyingError, message);
  }
  for (const message of ["net::ERR_TIMED_OUT", "net::ERR_CONNECTION_TIMED_OUT"]) {
    const timeout = asProviderError(new Error(message), ctx);
    assert.equal(timeout.code, "PROVIDER_TIMEOUT", message);
    assert.equal(timeout.technicalDetails.underlyingError, message);
  }
  const aborted = new Error("net::ERR_ABORTED");
  assert.equal(asProviderError(aborted, ctx), aborted);
});

test("asProviderError leaves classified, cancelled and unrelated errors untouched", async () => {
  const { asProviderError } = await load();
  const ctx = { provider: "OpenAI", surface: "llm" };
  const truncated = Object.assign(new Error("Model output was truncated"), {
    messageKey: "hooks.audioRecording.errorDescriptions.cleanupTruncated",
  });
  assert.equal(asProviderError(truncated, ctx), truncated);
  const abort = Object.assign(new Error("aborted"), { name: "AbortError" });
  assert.equal(asProviderError(abort, ctx), abort);
  const plain = new Error("something else");
  assert.equal(asProviderError(plain, ctx), plain);
  assert.equal(asProviderError(null, ctx), null);
});

test("isProviderSettingsTarget whitelists only the model settings targets", async () => {
  const { isProviderSettingsTarget } = await load();
  assert.equal(isProviderSettingsTarget("speechToText"), true);
  assert.equal(isProviderSettingsTarget("llms"), true);
  assert.equal(isProviderSettingsTarget("noteFormatting"), true);
  assert.equal(isProviderSettingsTarget("account"), false);
  assert.equal(isProviderSettingsTarget(undefined), false);
});

test("a 413 is a recording that's too large for transcription and a request that's too large for an AI model", async () => {
  const { providerHttpError } = await load();
  const recording = providerHttpError({ provider: "Mistral", status: 413, body: "", surface: "transcription" });
  assert.equal(recording.messageKey, "providerErrors.payloadTooLarge");
  assert.equal(recording.message, "This recording is too large for Mistral.");
  const request = providerHttpError({ provider: "Anthropic", status: 413, body: "", surface: "llm" });
  assert.equal(request.messageKey, "providerErrors.requestTooLarge");
  assert.equal(request.message, "This request is too large for Anthropic.");
  const selfHosted = providerHttpError({
    provider: "custom",
    selfHosted: true,
    status: 413,
    body: "",
    surface: "llm",
  });
  assert.equal(selfHosted.message, "This request is too large for your server.");
});

const en = require("../../src/locales/en/translation.json");
const LOCALES = ["en", "es", "fr", "de", "pt", "it", "ru", "zh-CN", "zh-TW", "ja", "ar"];
const lookup = (translation, key) => key.split(".").reduce((node, part) => node?.[part], translation);

// Every classification a provider failure can produce, on both surfaces, named and self-hosted.
async function everyClassification() {
  const { providerHttpError, providerError, PROVIDER_ERROR_CODES: C } = await load();
  const errors = [];
  for (const surface of ["transcription", "llm"]) {
    for (const selfHosted of [false, true]) {
      const base = { provider: "Mistral", surface, selfHosted };
      for (const status of [401, 403, 402, 429, 413, 400, 500, 504, 418]) {
        errors.push(providerHttpError({ ...base, status, body: "" }));
      }
      errors.push(providerHttpError({ ...base, status: 404, body: "model_not_found", model: "m-1" }));
      errors.push(providerHttpError({ ...base, status: 404, body: "model_not_found" }));
      for (const code of [
        C.TIMEOUT,
        C.UNREACHABLE,
        C.NO_RESPONSE,
        ...(selfHosted ? [] : [C.KEY_MISSING]),
      ]) {
        errors.push(providerError(code, base));
      }
    }
  }
  return errors;
}

test("each Error.message is the en translation of its messageKey", async () => {
  for (const error of await everyClassification()) {
    // The transcription-only hooks keys say "your transcription provider"; their twins name it.
    if (error.messageKey.startsWith("hooks.")) continue;
    const template = lookup(en, error.messageKey);
    assert.equal(typeof template, "string", `${error.messageKey} is missing from en`);
    const rendered = template.replace(/\{\{(\w+)\}\}/g, (_, name) => error.messageParams[name]);
    assert.equal(error.message, rendered, error.messageKey);
  }
});

test("self-hosted errors use sentences that name the server themselves, in every locale", async () => {
  const selfHostedKeys = new Set(
    (await everyClassification())
      .filter((error) => error.messageParams.provider === "Your server")
      .map((error) => error.messageKey)
      .filter((key) => key.startsWith("providerErrors."))
  );
  assert.ok(selfHostedKeys.size >= 10);
  for (const key of selfHostedKeys) {
    assert.match(key, /^providerErrors\.selfHosted\./);
    for (const locale of LOCALES) {
      const sentence = lookup(require(`../../src/locales/${locale}/translation.json`), key);
      assert.equal(typeof sentence, "string", `${locale}: ${key}`);
      // A substituted name can't take the case or article each sentence needs.
      assert.doesNotMatch(sentence, /\{\{provider\}\}/, `${locale}: ${key}`);
    }
  }
});

test("a model name is inserted literally, even with $ patterns", async () => {
  const { providerHttpError } = await load();
  const error = providerHttpError({
    provider: "OpenAI",
    status: 404,
    body: "",
    model: "we$&ird-$'model",
    surface: "llm",
  });
  assert.equal(error.message, "OpenAI doesn't recognize the model “we$&ird-$'model”.");
});