Phase 3: client feature slices and one typed API layer

client/api/audiobook.test.ts

@@ -0,0 +1,152 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { ApiError } from './http'
+import {
+  getBookAudiobook,
+  generateAudiobook,
+  getEngineStatus,
+  installEngine,
+  listVoices,
+  revealAudiobook,
+} from './audiobook'
+
+/**
+ * The narration engine, its voices, and the audiobook generated for each
+ * book. installEngine gets the most attention here, since a 409 from that
+ * one endpoint is a success rather than a failure, and that is the one
+ * behavior in this module that is easy to get backwards.
+ */
+
+let fetchSpy: ReturnType<typeof vi.spyOn>
+
+beforeEach(() => {
+  fetchSpy = vi.spyOn(globalThis, 'fetch')
+})
+afterEach(() => {
+  fetchSpy.mockRestore()
+})
+
+describe('getBookAudiobook', () => {
+  it('requests the per-book audiobook status', async () => {
+    const payload = { exists: true, generatedChapters: [1, 2], manifest: null }
+    fetchSpy.mockResolvedValueOnce(new Response(JSON.stringify(payload), { status: 200 }))
+
+    const result = await getBookAudiobook('ada')
+
+    const [url, init] = fetchSpy.mock.calls[0]
+    expect(url).toBe('/api/books/ada/audiobook')
+    expect((init as RequestInit).method).toBeUndefined()
+    expect(result).toEqual(payload)
+  })
+
+  it('omits the trace header, since this polls on an interval while generating', async () => {
+    fetchSpy.mockResolvedValueOnce(
+      new Response(JSON.stringify({ exists: false, generatedChapters: [], manifest: null }), { status: 200 }),
+    )
+
+    await getBookAudiobook('ada')
+
+    const headers = new Headers((fetchSpy.mock.calls[0][1] as RequestInit).headers)
+    expect(headers.has('X-Trace-Id')).toBe(false)
+  })
+})
+
+describe('generateAudiobook', () => {
+  it('posts the voice, speed, and remember or replace choices', async () => {
+    fetchSpy.mockResolvedValueOnce(new Response(JSON.stringify({ taskId: 't1' }), { status: 200 }))
+    const body = { voiceId: 'am_michael', speed: 1.1, rememberAsDefault: true, confirmReplace: false }
+
+    const result = await generateAudiobook('ada', body)
+
+    const [url, init] = fetchSpy.mock.calls[0]
+    expect(url).toBe('/api/books/ada/audiobook')
+    expect((init as RequestInit).method).toBe('POST')
+    expect((init as RequestInit).body).toBe(JSON.stringify(body))
+    expect(result).toEqual({ taskId: 't1' })
+  })
+
+  it('throws an ApiError carrying the status and the reason the server gave', async () => {
+    fetchSpy.mockResolvedValueOnce(
+      new Response(JSON.stringify({ error: 'Audiobook already exists', exists: true }), { status: 409 }),
+    )
+
+    const failure = await generateAudiobook('ada', {}).catch((e: unknown) => e)
+
+    expect(failure).toBeInstanceOf(ApiError)
+    expect((failure as ApiError).status).toBe(409)
+    expect((failure as Error).message).toBe('Audiobook already exists')
+  })
+})
+
+describe('getEngineStatus', () => {
+  it('requests the narration engine status', async () => {
+    const payload = { installed: true, missing: { model: false, ffmpeg: false }, downloadSize: 0 }
+    fetchSpy.mockResolvedValueOnce(new Response(JSON.stringify(payload), { status: 200 }))
+
+    const result = await getEngineStatus()
+
+    const [url, init] = fetchSpy.mock.calls[0]
+    expect(url).toBe('/api/audiobook/status')
+    expect((init as RequestInit).method).toBeUndefined()
+    expect(result).toEqual(payload)
+  })
+})
+
+describe('installEngine', () => {
+  it('posts to the install endpoint', async () => {
+    fetchSpy.mockResolvedValueOnce(new Response(JSON.stringify({ taskId: 't1' }), { status: 200 }))
+
+    await installEngine()
+
+    const [url, init] = fetchSpy.mock.calls[0]
+    expect(url).toBe('/api/audiobook/install')
+    expect((init as RequestInit).method).toBe('POST')
+  })
+
+  it('resolves rather than throwing when the engine is already installed or installing', async () => {
+    fetchSpy.mockResolvedValueOnce(
+      new Response(JSON.stringify({ error: 'Audiobook engine already installed' }), { status: 409 }),
+    )
+
+    await expect(installEngine()).resolves.toBeUndefined()
+  })
+
+  it('still throws an ApiError for a real failure', async () => {
+    fetchSpy.mockResolvedValueOnce(new Response(JSON.stringify({ error: 'Disk full' }), { status: 500 }))
+
+    const failure = await installEngine().catch((e: unknown) => e)
+
+    expect(failure).toBeInstanceOf(ApiError)
+    expect((failure as ApiError).status).toBe(500)
+    expect((failure as Error).message).toBe('Disk full')
+  })
+})
+
+describe('listVoices', () => {
+  it('requests the voice list and unwraps it', async () => {
+    const voices = [
+      { id: 'am_michael', name: 'Michael', language: 'American English', gender: 'Male', grade: 'A' },
+    ]
+    fetchSpy.mockResolvedValueOnce(new Response(JSON.stringify({ voices }), { status: 200 }))
+
+    const result = await listVoices()
+
+    const [url, init] = fetchSpy.mock.calls[0]
+    expect(url).toBe('/api/audiobook/voices')
+    expect((init as RequestInit).method).toBeUndefined()
+    expect(result).toEqual(voices)
+  })
+})
+
+describe('revealAudiobook', () => {
+  it('posts to the reveal endpoint for one book', async () => {
+    const payload = { path: '/books/ada/audiobook/book.m4b', revealed: true }
+    fetchSpy.mockResolvedValueOnce(new Response(JSON.stringify(payload), { status: 200 }))
+
+    const result = await revealAudiobook('ada')
+
+    const [url, init] = fetchSpy.mock.calls[0]
+    expect(url).toBe('/api/books/ada/audiobook/reveal')
+    expect((init as RequestInit).method).toBe('POST')
+    expect(result).toEqual(payload)
+  })
+})

client/api/audiobook.ts

@@ -0,0 +1,88 @@
+import type { z } from 'zod'
+import type { GenerateAudiobookBodySchema } from '@shared/contracts'
+import type { AudiobookManifest } from '@shared/domain'
+import type { AudiobookStatus, VoiceInfo } from '@shared/responses'
+import { apiFetch, expectOk, request } from './http'
+
+/**
+ * Endpoints for the narration engine, the voices it offers, and the
+ * audiobook generated for each book.
+ *
+ * Request bodies are inferred from the Zod schemas the server validates
+ * against, so a body this module sends cannot drift from what the route
+ * accepts. The schemas are imported as types only and compile away, so no
+ * validator reaches the browser bundle.
+ */
+
+/** The audiobook state for one book, covering whether it exists, how far narration has gotten, and its manifest. */
+export interface BookAudiobookStatus {
+  exists: boolean
+  path?: string
+  generatedChapters: number[]
+  manifest: AudiobookManifest | null
+}
+
+/**
+ * Check whether a book has a generated audiobook and how far generation has progressed.
+ *
+ * Tracing is switched off because this call runs on a four second interval
+ * while an audiobook is generating. Adding the trace header would turn a
+ * CORS-simple GET into a preflighted one, doubling the request count for as
+ * long as the poll runs.
+ */
+export async function getBookAudiobook(bookId: string): Promise<BookAudiobookStatus> {
+  return request<BookAudiobookStatus>(`/api/books/${bookId}/audiobook`, { trace: false })
+}
+
+/** The voice, speed, and remember or replace choices generateAudiobook sends. */
+export type GenerateAudiobookBody = z.infer<typeof GenerateAudiobookBodySchema>
+
+/** What generateAudiobook resolves with once narration has been queued. */
+export interface GenerateAudiobookResult {
+  taskId: string
+}
+
+/** Start narrating a book's chapters into a single audiobook file. */
+export async function generateAudiobook(
+  bookId: string,
+  body: GenerateAudiobookBody,
+): Promise<GenerateAudiobookResult> {
+  return request<GenerateAudiobookResult>(`/api/books/${bookId}/audiobook`, { method: 'POST', body })
+}
+
+/** Check whether the narration engine, meaning the model and ffmpeg, is installed. */
+export async function getEngineStatus(): Promise<AudiobookStatus> {
+  return request<AudiobookStatus>('/api/audiobook/status')
+}
+
+/**
+ * Kick off the narration engine install.
+ *
+ * A 409 from the server means the engine is already installed or an install
+ * is already running. Either outcome is exactly what this call wants, so it
+ * resolves instead of throwing. request() would turn that response into an
+ * ApiError, so this goes through apiFetch directly and checks the status by
+ * hand.
+ */
+export async function installEngine(): Promise<void> {
+  const response = await apiFetch('/api/audiobook/install', { method: 'POST' })
+  if (response.status === 409) return
+  await expectOk(response, 'Failed to start the narrator install')
+}
+
+/** List the narrator voices available for the voice picker. */
+export async function listVoices(): Promise<VoiceInfo[]> {
+  const { voices } = await request<{ voices: VoiceInfo[] }>('/api/audiobook/voices')
+  return voices
+}
+
+/** What revealAudiobook resolves with, meaning the file path and whether the OS reveal succeeded. */
+export interface RevealAudiobookResult {
+  path: string
+  revealed: boolean
+}
+
+/** Ask the server to reveal a book's audiobook file in Finder or Explorer. */
+export async function revealAudiobook(bookId: string): Promise<RevealAudiobookResult> {
+  return request<RevealAudiobookResult>(`/api/books/${bookId}/audiobook/reveal`, { method: 'POST' })
+}