fix: close TTS rework fallback gaps

README.md

@@ -72,6 +72,18 @@ UPSTASH_REDIS_REST_TOKEN="cutia_redis_token"
 NODE_ENV="development"
 ```
 
+Optional TTS env values:
+
+```bash
+EXTERNAL_TTS_API_BASE_URL="https://your-tts-provider.example.com/v1"
+EXTERNAL_TTS_API_MODEL="your_tts_model"
+EXTERNAL_TTS_API_KEY="your_tts_api_key"
+```
+
+Cutia prefers `EXTERNAL_TTS_API_*` for external speech synthesis. The legacy
+`API_BASE_URL` / `API_MODEL` / `API_KEY` names are still accepted as
+compatibility aliases when the namespaced variables are absent.
+
 To enable authentication, also start PostgreSQL and add these env values:
 
 ```bash

apps/web/.env.example

@@ -16,9 +16,19 @@ UPSTASH_REDIS_REST_TOKEN=example_token_here
 FREESOUND_CLIENT_ID=your_client_id_here
 FREESOUND_API_KEY=your_api_key_here
 
+# Optional: external OpenAI-compatible TTS provider
+# Preferred namespaced variables:
+EXTERNAL_TTS_API_BASE_URL=https://your-tts-provider.example.com/v1
+EXTERNAL_TTS_API_MODEL=your_tts_model
+EXTERNAL_TTS_API_KEY=your_tts_api_key
+# Compatibility aliases used when EXTERNAL_TTS_* is absent:
+# API_BASE_URL=https://your-shared-api.example.com/v1
+# API_MODEL=your_tts_model
+# API_KEY=your_tts_api_key
+
 # Cloudflare R2 (for reference image uploads)
 R2_ACCOUNT_ID=your_r2_account_id
 R2_ACCESS_KEY_ID=your_r2_access_key_id
 R2_SECRET_ACCESS_KEY=your_r2_secret_access_key
 R2_BUCKET_NAME=your_r2_bucket_name
-R2_PUBLIC_URL=https://your-r2-public-url.example.com
+R2_PUBLIC_URL=https://your-r2-public-url.example.com

apps/web/src/app/api/tts/generate/route.test.ts

@@ -0,0 +1,113 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { TtsError } from "@/lib/tts/errors";
+import { NextRequest } from "next/server";
+
+let synthesizeImpl: typeof import("@/lib/tts/provider").synthesizeSpeechWithFallback;
+const originalConsoleError = console.error;
+
+mock.module("@cutia/env/web", () => ({
+	webEnv: {
+		API_BASE_URL: "https://example.com/v1",
+		API_MODEL: "tts-1",
+		API_KEY: "secret",
+	},
+}));
+
+mock.module("@/lib/tts/provider", () => ({
+	synthesizeSpeechWithFallback: (args: Parameters<typeof synthesizeImpl>[0]) =>
+		synthesizeImpl(args),
+}));
+
+const { POST } = await import("./route");
+
+function createRequest(body: unknown): NextRequest {
+	return new NextRequest("http://localhost/api/tts/generate", {
+		body: JSON.stringify(body),
+		headers: {
+			"content-type": "application/json",
+		},
+		method: "POST",
+	});
+}
+
+describe("POST /api/tts/generate", () => {
+	beforeEach(() => {
+		console.error = mock(() => {});
+		synthesizeImpl = async () => Uint8Array.from([1, 2, 3]).buffer;
+	});
+
+	afterEach(() => {
+		console.error = originalConsoleError;
+	});
+
+	test("returns base64 audio for successful synthesis", async () => {
+		const response = await POST(createRequest({ text: "hello" }));
+
+		expect(response.status).toBe(200);
+		expect(await response.json()).toEqual({
+			audio: "AQID",
+		});
+	});
+
+	test("returns 502 for structured legacy upstream errors without relying on message prefixes", async () => {
+		synthesizeImpl = async () => {
+			throw new TtsError({
+				code: "LEGACY_TTS_UPSTREAM",
+				message: "legacy fallback audio download failed",
+			});
+		};
+
+		const response = await POST(createRequest({ text: "hello" }));
+
+		expect(response.status).toBe(502);
+		expect(await response.json()).toEqual({
+			error: "legacy fallback audio download failed",
+		});
+	});
+
+	test("returns 502 for structured external upstream errors without relying on message prefixes", async () => {
+		synthesizeImpl = async () => {
+			throw new TtsError({
+				code: "EXTERNAL_TTS_UPSTREAM",
+				message: "upstream gateway timeout",
+			});
+		};
+
+		const response = await POST(createRequest({ text: "hello" }));
+
+		expect(response.status).toBe(502);
+		expect(await response.json()).toEqual({
+			error: "upstream gateway timeout",
+		});
+	});
+
+	test("returns the original config error message for structured config failures", async () => {
+		synthesizeImpl = async () => {
+			throw new TtsError({
+				code: "EXTERNAL_TTS_CONFIG",
+				message: "external config missing",
+			});
+		};
+
+		const response = await POST(createRequest({ text: "hello" }));
+
+		expect(response.status).toBe(500);
+		expect(await response.json()).toEqual({
+			error: "external config missing",
+		});
+	});
+
+	test("returns 500 for unexpected non-TtsError exceptions", async () => {
+		synthesizeImpl = async () => {
+			throw new Error("unexpected failure");
+		};
+
+		const response = await POST(createRequest({ text: "hello" }));
+
+		expect(response.status).toBe(500);
+		expect(await response.json()).toEqual({
+			error: "Internal server error",
+			detail: "unexpected failure",
+		});
+	});
+});

apps/web/src/app/api/tts/generate/route.ts

@@ -1,18 +1,14 @@
+import { webEnv } from "@cutia/env/web";
 import { type NextRequest, NextResponse } from "next/server";
 import { z } from "zod";
-
-const TTS_API_BASE = "https://api.milorapart.top/apis/mbAIsc";
+import { isTtsError } from "@/lib/tts/errors";
+import { synthesizeSpeechWithFallback } from "@/lib/tts/provider";
 
 const requestSchema = z.object({
 	text: z.string().min(1, "Text is required").max(2000, "Text too long"),
 	voice: z.string().optional(),
 });
 
-const upstreamResponseSchema = z.object({
-	code: z.number(),
-	url: z.string().url(),
-});
-
 export async function POST(request: NextRequest) {
 	try {
 		const body = await request.json();
@@ -28,42 +24,33 @@ export async function POST(request: NextRequest) {
 			);
 		}
 
-		const { text } = validation.data;
-		const upstreamUrl = `${TTS_API_BASE}?${new URLSearchParams({ text, format: "mp3" })}`;
-		const upstreamResponse = await fetch(upstreamUrl);
-
-		if (!upstreamResponse.ok) {
-			return NextResponse.json(
-				{ error: `Upstream error: ${upstreamResponse.status}` },
-				{ status: 502 },
-			);
-		}
-
-		const upstreamData = await upstreamResponse.json();
-		const parsed = upstreamResponseSchema.safeParse(upstreamData);
-
-		if (!parsed.success || parsed.data.code !== 200) {
-			return NextResponse.json(
-				{ error: "TTS generation failed" },
-				{ status: 502 },
-			);
-		}
-
-		const audioResponse = await fetch(parsed.data.url);
-		if (!audioResponse.ok) {
-			return NextResponse.json(
-				{ error: `Failed to download audio: ${audioResponse.status}` },
-				{ status: 502 },
-			);
-		}
-
-		const audioArrayBuffer = await audioResponse.arrayBuffer();
+		const { text, voice } = validation.data;
+		const audioArrayBuffer = await synthesizeSpeechWithFallback({
+			env: webEnv,
+			text,
+			voice,
+		});
 		const base64 = Buffer.from(audioArrayBuffer).toString("base64");
 
 		return NextResponse.json({ audio: base64 });
 	} catch (error) {
 		const message = error instanceof Error ? error.message : "Unknown error";
 		console.error("TTS generate error:", error);
+
+		if (isTtsError(error)) {
+			switch (error.code) {
+				case "EXTERNAL_TTS_CONFIG":
+					return NextResponse.json({ error: message }, { status: 500 });
+				case "EXTERNAL_TTS_UPSTREAM":
+				case "LEGACY_TTS_UPSTREAM":
+					return NextResponse.json({ error: message }, { status: 502 });
+				default: {
+					const exhaustiveCode: never = error.code;
+					throw new Error(`Unhandled TTS error code: ${exhaustiveCode}`);
+				}
+			}
+		}
+
 		return NextResponse.json(
 			{ error: "Internal server error", detail: message },
 			{ status: 500 },

apps/web/src/constants/tts-constants.ts

@@ -3,8 +3,7 @@ export interface VoicePack {
 	name: string;
 }
 
-export const VOICE_PACKS: VoicePack[] = [
-	{ id: "default", name: "Default" },
-];
+export const VOICE_PACKS: VoicePack[] = [{ id: "default", name: "Default" }];
 
 export const DEFAULT_VOICE_PACK = "default";
+export const DEFAULT_EXTERNAL_TTS_VOICE = "alloy";

apps/web/src/lib/tts/errors.ts

@@ -0,0 +1,39 @@
+export const TTS_ERROR_CODES = [
+	"EXTERNAL_TTS_CONFIG",
+	"EXTERNAL_TTS_UPSTREAM",
+	"LEGACY_TTS_UPSTREAM",
+] as const;
+
+export type TtsErrorCode = (typeof TTS_ERROR_CODES)[number];
+
+export class TtsError extends Error {
+	code: TtsErrorCode;
+	retryable?: boolean;
+	status?: number;
+
+	constructor({
+		code,
+		message,
+		retryable,
+		status,
+	}: {
+		code: TtsErrorCode;
+		message: string;
+		retryable?: boolean;
+		status?: number;
+	}) {
+		super(message);
+		this.name = "TtsError";
+		this.code = code;
+		this.retryable = retryable;
+		this.status = status;
+	}
+}
+
+export function isTtsError(error: unknown): error is TtsError {
+	if (!(error instanceof Error)) {
+		return false;
+	}
+
+	return TTS_ERROR_CODES.includes((error as TtsError).code);
+}

apps/web/src/lib/tts/fetch-with-timeout.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+import { fetchWithTimeout } from "./fetch-with-timeout";
+
+describe("fetchWithTimeout", () => {
+	test("resolves successfully when fetch completes before the timeout", async () => {
+		let fetchCalled = false;
+
+		const response = await fetchWithTimeout({
+			fetchImpl: async () => {
+				fetchCalled = true;
+				return new Response("ok", { status: 200 });
+			},
+			input: "https://example.com",
+			timeoutMessage: "timed out",
+			timeoutMs: 50,
+		});
+
+		expect(fetchCalled).toBe(true);
+		expect(response.status).toBe(200);
+		expect(await response.text()).toBe("ok");
+	});
+
+	test("rejects immediately when the caller signal is already aborted", async () => {
+		const controller = new AbortController();
+		const callerError = new Error("caller aborted");
+		let fetchCalled = false;
+
+		controller.abort(callerError);
+
+		await expect(
+			fetchWithTimeout({
+				fetchImpl: async () => {
+					fetchCalled = true;
+					return new Response("ok");
+				},
+				init: { signal: controller.signal },
+				input: "https://example.com",
+				timeoutMessage: "timed out",
+				timeoutMs: 50,
+			}),
+		).rejects.toThrow("caller aborted");
+
+		expect(fetchCalled).toBe(false);
+	});
+
+	test("surfaces caller cancellation for in-flight requests", async () => {
+		const controller = new AbortController();
+		const callerError = new Error("caller aborted");
+
+		await expect(
+			fetchWithTimeout({
+				fetchImpl: async (_input, init) =>
+					new Promise((_resolve, reject) => {
+						setTimeout(() => controller.abort(callerError), 0);
+
+						init?.signal?.addEventListener(
+							"abort",
+							() => reject(init.signal?.reason ?? new Error("aborted")),
+							{ once: true },
+						);
+					}),
+				init: { signal: controller.signal },
+				input: "https://example.com",
+				timeoutMessage: "timed out",
+				timeoutMs: 50,
+			}),
+		).rejects.toThrow("caller aborted");
+	});
+
+	test("rejects with the timeout message when fetch exceeds timeoutMs", async () => {
+		await expect(
+			fetchWithTimeout({
+				fetchImpl: async (_input, init) =>
+					new Promise((_resolve, reject) => {
+						init?.signal?.addEventListener(
+							"abort",
+							() => reject(new Error("aborted")),
+							{ once: true },
+						);
+					}),
+				input: "https://example.com",
+				timeoutMessage: "timed out",
+				timeoutMs: 10,
+			}),
+		).rejects.toThrow("timed out");
+	});
+});