@alta-foundation/plaud-extractor 1.0.0

package/src/cli/commands/auth.ts

@@ -0,0 +1,27 @@
+import type { Command } from 'commander'
+import { PlaudExtractor } from '../../PlaudExtractor.js'
+import { AuthError } from '../../errors.js'
+import { authTokenPath } from '../../auth/token-store.js'
+
+export function registerAuthCommand(program: Command): void {
+  program
+    .command('auth')
+    .description('Authenticate with Plaud by launching a browser (required before first sync)')
+    .option('--headless', 'Run browser in headless mode (requires PLAUD_EMAIL + PLAUD_PASSWORD env vars)', false)
+    .option('--out <dir>', 'Data directory for logs', undefined)
+    .action(async (opts: { headless: boolean; out?: string }) => {
+      const extractor = new PlaudExtractor({ outDir: opts.out })
+
+      console.log('Launching browser to authenticate with Plaud...')
+
+      await extractor.authenticate({
+        headless: opts.headless,
+        email: process.env['PLAUD_EMAIL'],
+        password: process.env['PLAUD_PASSWORD'],
+      })
+
+      console.log(`\nAuthentication successful!`)
+      console.log(`Credentials saved to: ${authTokenPath()}`)
+      console.log(`\nYou can now run: alta-plaud sync`)
+    })
+}

package/src/cli/commands/backfill.ts

@@ -0,0 +1,77 @@
+import type { Command } from 'commander'
+import { PlaudExtractor } from '../../PlaudExtractor.js'
+import { defaultOutDir } from '../../storage/paths.js'
+import type { TranscriptFormat } from '../../storage/recording-store.js'
+
+export function registerBackfillCommand(program: Command): void {
+  program
+    .command('backfill')
+    .description('Download all recordings from scratch (ignores incremental state)')
+    .option('--out <dir>', 'Output directory', defaultOutDir())
+    .option('--since <iso>', 'Only backfill recordings after this ISO date')
+    .option('--limit <n>', 'Max number of recordings to process', parseInt)
+    .option('--concurrency <n>', 'Parallel downloads (default: 3)', parseInt, 3)
+    .option('--formats <list>', 'Transcript formats: json,txt,md (default: all)', 'json,txt,md')
+    .option('--dataset', 'Append to datasets/plaud_transcripts.jsonl (default: on)', true)
+    .option('--no-dataset', 'Skip dataset output')
+    .option('--dry-run', 'Print plan without downloading', false)
+    .option('--verbose', 'Verbose logging', false)
+    .option('--yes', 'Skip confirmation prompt', false)
+    .action(async (opts: {
+      out: string
+      since?: string
+      limit?: number
+      concurrency: number
+      formats: string
+      dataset: boolean
+      dryRun: boolean
+      verbose: boolean
+      yes: boolean
+    }) => {
+      if (!opts.yes && !opts.dryRun) {
+        const confirmed = await confirm(
+          'Backfill will re-evaluate all recordings and may overwrite existing files. Continue? (y/N) '
+        )
+        if (!confirmed) {
+          console.log('Aborted.')
+          return
+        }
+      }
+
+      const extractor = new PlaudExtractor({ outDir: opts.out, verbose: opts.verbose })
+      const formats = parseFormats(opts.formats)
+
+      const result = await extractor.backfill({
+        since: opts.since ? new Date(opts.since) : undefined,
+        limit: opts.limit,
+        concurrency: opts.concurrency,
+        formats,
+        includeDataset: opts.dataset,
+        dryRun: opts.dryRun,
+      })
+
+      const durationSec = (result.durationMs / 1000).toFixed(1)
+      console.log(`\nBackfill complete (${durationSec}s)`)
+      console.log(`  Downloaded:  ${result.succeeded}`)
+      console.log(`  Skipped:     ${result.skipped}`)
+      console.log(`  Failed:      ${result.failed}`)
+      if (result.datasetPath) console.log(`  Dataset:     ${result.datasetPath}`)
+    })
+}
+
+function parseFormats(str: string): TranscriptFormat[] {
+  const valid: TranscriptFormat[] = ['json', 'txt', 'md']
+  return str.split(',').filter((f): f is TranscriptFormat => valid.includes(f as TranscriptFormat))
+}
+
+async function confirm(message: string): Promise<boolean> {
+  const { createInterface } = await import('node:readline')
+  process.stdout.write(message)
+  return new Promise(resolve => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout })
+    rl.once('line', (answer: string) => {
+      rl.close()
+      resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes')
+    })
+  })
+}

package/src/cli/commands/sync.ts

@@ -0,0 +1,71 @@
+import type { Command } from 'commander'
+import { PlaudExtractor } from '../../PlaudExtractor.js'
+import { defaultOutDir } from '../../storage/paths.js'
+import type { TranscriptFormat } from '../../storage/recording-store.js'
+
+export function registerSyncCommand(program: Command): void {
+  program
+    .command('sync')
+    .description('Pull new or updated recordings from Plaud (incremental)')
+    .option('--out <dir>', 'Output directory', defaultOutDir())
+    .option('--since <iso>', 'Only sync recordings after this ISO date (overrides last-sync state)')
+    .option('--limit <n>', 'Max number of recordings to process', parseInt)
+    .option('--concurrency <n>', 'Parallel downloads (default: 3)', parseInt, 3)
+    .option('--formats <list>', 'Transcript formats: json,txt,md (default: all)', 'json,txt,md')
+    .option('--dataset', 'Append to datasets/plaud_transcripts.jsonl (default: on)', true)
+    .option('--no-dataset', 'Skip dataset output')
+    .option('--dry-run', 'Print plan without downloading', false)
+    .option('--verbose', 'Verbose logging', false)
+    .option('--redact', 'Redact tokens from logs', false)
+    .action(async (opts: {
+      out: string
+      since?: string
+      limit?: number
+      concurrency: number
+      formats: string
+      dataset: boolean
+      dryRun: boolean
+      verbose: boolean
+      redact: boolean
+    }) => {
+      const extractor = new PlaudExtractor({
+        outDir: opts.out,
+        verbose: opts.verbose,
+        redact: opts.redact,
+      })
+
+      const formats = parseFormats(opts.formats)
+      const result = await extractor.sync({
+        since: opts.since ? new Date(opts.since) : undefined,
+        limit: opts.limit,
+        concurrency: opts.concurrency,
+        formats,
+        includeDataset: opts.dataset,
+        dryRun: opts.dryRun,
+      })
+
+      printSyncSummary(result)
+    })
+}
+
+function parseFormats(str: string): TranscriptFormat[] {
+  const valid: TranscriptFormat[] = ['json', 'txt', 'md']
+  return str.split(',').filter((f): f is TranscriptFormat => valid.includes(f as TranscriptFormat))
+}
+
+function printSyncSummary(result: import('../../sync/types.js').SyncResult): void {
+  const durationSec = (result.durationMs / 1000).toFixed(1)
+  console.log(`\nSync complete (${durationSec}s)`)
+  console.log(`  Downloaded:  ${result.succeeded}`)
+  console.log(`  Skipped:     ${result.skipped}`)
+  console.log(`  Failed:      ${result.failed}`)
+  if (result.datasetPath) {
+    console.log(`  Dataset:     ${result.datasetPath}`)
+  }
+  if (result.errors.length > 0) {
+    console.error(`\nFailed recordings:`)
+    for (const { recordingId, error } of result.errors) {
+      console.error(`  ${recordingId}: ${error.message}`)
+    }
+  }
+}

package/src/cli/commands/verify.ts

@@ -0,0 +1,31 @@
+import type { Command } from 'commander'
+import { PlaudExtractor } from '../../PlaudExtractor.js'
+import { defaultOutDir } from '../../storage/paths.js'
+
+export function registerVerifyCommand(program: Command): void {
+  program
+    .command('verify')
+    .description('Verify checksums for all downloaded recordings')
+    .option('--out <dir>', 'Output directory', defaultOutDir())
+    .option('--repair', 'Re-download files with checksum mismatches', false)
+    .option('--verbose', 'Verbose logging', false)
+    .action(async (opts: { out: string; repair: boolean; verbose: boolean }) => {
+      const extractor = new PlaudExtractor({ outDir: opts.out, verbose: opts.verbose })
+
+      console.log(`Verifying recordings in ${opts.out}...`)
+      const result = await extractor.verify({ repair: opts.repair })
+
+      console.log(`\nVerify complete`)
+      console.log(`  Scanned:  ${result.scanned}`)
+      console.log(`  OK:       ${result.ok}`)
+      console.log(`  Failed:   ${result.failed}`)
+      if (opts.repair) console.log(`  Repaired: ${result.repaired}`)
+
+      if (result.issues.length > 0) {
+        console.error(`\nIssues found:`)
+        for (const issue of result.issues) {
+          console.error(`  ${issue.recordingId}/${issue.file}: ${issue.issue}`)
+        }
+      }
+    })
+}

package/src/cli/exit-codes.ts

@@ -0,0 +1,14 @@
+import { AuthError, StorageError } from '../errors.js'
+
+export enum ExitCode {
+  Success = 0,
+  PartialFailure = 1,
+  AuthFailure = 2,
+  StorageError = 3,
+}
+
+export function toExitCode(err: unknown): ExitCode {
+  if (err instanceof AuthError) return ExitCode.AuthFailure
+  if (err instanceof StorageError) return ExitCode.StorageError
+  return ExitCode.PartialFailure
+}

package/src/cli/options.ts

@@ -0,0 +1,10 @@
+// Shared option definitions (reused across commands if needed in future)
+export const COMMON_OPTIONS = {
+  out: { flags: '--out <dir>', description: 'Output directory' },
+  verbose: { flags: '--verbose', description: 'Verbose logging' },
+  redact: { flags: '--redact', description: 'Redact auth tokens from logs' },
+  dryRun: { flags: '--dry-run', description: 'Print plan without downloading' },
+  concurrency: { flags: '--concurrency <n>', description: 'Parallel downloads (default: 3)' },
+  formats: { flags: '--formats <list>', description: 'Transcript formats: json,txt,md' },
+  limit: { flags: '--limit <n>', description: 'Max number of recordings to process' },
+}

package/src/client/endpoints.ts

@@ -0,0 +1,62 @@
+import type { EndpointMap } from '../auth/types.js'
+
+export type { EndpointMap }
+
+// ---------------------------------------------------------------------------
+// Real Plaud API paths (discovered from arbuzmell/plaud-api reference client)
+// The user's account lives on a regional endpoint (e.g. api-euc1.plaud.ai for EU).
+// Hit api.plaud.ai/user/me to discover the correct regional base URL.
+// ---------------------------------------------------------------------------
+
+const API_BASE = (map: EndpointMap) => map.apiBaseUrl ?? 'https://api.plaud.ai'
+
+/**
+ * Build list URL using skip/limit pagination.
+ * GET /file/simple/web?skip=N&limit=50&is_trash=0&sort_by=start_time&is_desc=true
+ */
+export function buildListUrl(map: EndpointMap, skip: number, limit = 50): string {
+  const base = map.listRecordings ?? `${API_BASE(map)}/file/simple/web`
+  const url = new URL(base.replace('/{id}', ''))
+  url.searchParams.set('skip', String(skip))
+  url.searchParams.set('limit', String(limit))
+  url.searchParams.set('is_trash', '0')
+  url.searchParams.set('sort_by', 'start_time')
+  url.searchParams.set('is_desc', 'true')
+  return url.toString()
+}
+
+/**
+ * Build URL for POST /file/list — batch detail fetch that includes trans_result.
+ * Body: ["file_id_1", "file_id_2"]
+ * Response: { data_file_list: [...full recording objects with trans_result...] }
+ */
+export function buildBatchDetailUrl(map: EndpointMap): string {
+  return map.batchDetail ?? `${API_BASE(map)}/file/list`
+}
+
+/**
+ * Build URL for GET /file/temp-url/<id> — returns a presigned S3 audio download URL.
+ * Response: { temp_url: "https://s3.amazonaws.com/...?X-Amz-..." }
+ */
+export function buildAudioTempUrl(map: EndpointMap, id: string): string {
+  const base = map.getAudioUrl ?? `${API_BASE(map)}/file/temp-url`
+  return `${base.replace('/{id}', '')}/${id}`
+}
+
+export function buildProfileUrl(map: EndpointMap): string {
+  return map.userProfile ?? `${API_BASE(map)}/user/me`
+}
+
+/**
+ * Discover the correct regional API base URL by hitting the global endpoint.
+ * The global api.plaud.ai returns a region-redirect response:
+ *   { status: -302, data: { domains: { api: "https://api-euc1.plaud.ai" } } }
+ */
+export function extractRegionalBaseUrl(response: unknown): string | null {
+  const r = response as Record<string, unknown>
+  if (r?.status === -302) {
+    const api = (r?.data as Record<string, unknown>)?.domains as Record<string, unknown>
+    if (typeof api?.api === 'string') return api.api
+  }
+  return null
+}

package/src/client/http.ts

@@ -0,0 +1,110 @@
+import { fetch, type RequestInit, type Response } from 'undici'
+import { ApiError, AuthError } from '../errors.js'
+import { getLogger } from '../logger.js'
+import type { StoredCredentials } from '../auth/types.js'
+import { cookieHeader } from '../auth/token-store.js'
+
+// Browser-like headers that Plaud's API validates.
+// app-platform and edit-from are required custom headers.
+const STATIC_HEADERS = {
+  'Accept': 'application/json, */*',
+  'Accept-Language': 'en-GB,en-US;q=0.9,en;q=0.8',
+  'Origin': 'https://web.plaud.ai',
+  'Referer': 'https://web.plaud.ai/',
+  'app-platform': 'web',
+  'edit-from': 'web',
+  'User-Agent':
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36',
+}
+
+export class HttpClient {
+  constructor(private readonly creds: StoredCredentials) {}
+
+  private buildHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      ...STATIC_HEADERS,
+      'Cookie': cookieHeader(this.creds),
+    }
+    if (this.creds.authToken) {
+      // Plaud API expects lowercase 'bearer' (per arbuzmell/plaud-api reference client)
+      headers['Authorization'] = `bearer ${this.creds.authToken}`
+    }
+    return headers
+  }
+
+  async get<T>(url: string, init?: RequestInit): Promise<T> {
+    const log = getLogger()
+    log.debug({ url }, 'GET')
+
+    const res = await fetch(url, {
+      ...init,
+      method: 'GET',
+      headers: { ...this.buildHeaders(), ...(init?.headers as Record<string, string> | undefined) },
+    })
+
+    await this.assertOk(res, url)
+    return res.json() as Promise<T>
+  }
+
+  async post<T>(url: string, body: unknown, init?: RequestInit): Promise<T> {
+    const log = getLogger()
+    log.debug({ url }, 'POST')
+
+    const res = await fetch(url, {
+      ...init,
+      method: 'POST',
+      headers: { ...this.buildHeaders(), ...(init?.headers as Record<string, string> | undefined) },
+      body: JSON.stringify(body),
+    })
+
+    await this.assertOk(res, url)
+    return res.json() as Promise<T>
+  }
+
+  async getStream(url: string): Promise<AsyncIterable<Uint8Array>> {
+    const log = getLogger()
+    log.debug({ url }, 'GET (stream)')
+
+    const res = await fetch(url, {
+      method: 'GET',
+      headers: this.buildHeaders(),
+    })
+
+    await this.assertOk(res, url)
+
+    if (!res.body) {
+      throw new ApiError(`No response body from ${url}`, res.status)
+    }
+
+    return res.body as unknown as AsyncIterable<Uint8Array>
+  }
+
+  /**
+   * Download from an external URL (e.g. presigned S3) without Plaud auth headers.
+   * S3 presigned URLs sign only the `host` header — sending extra headers breaks the request.
+   */
+  async downloadExternalUrl(url: string): Promise<AsyncIterable<Uint8Array>> {
+    const log = getLogger()
+    log.debug({ url: url.split('?')[0] }, 'GET (external)')
+
+    const res = await fetch(url, { method: 'GET' })
+    await this.assertOk(res, url)
+
+    if (!res.body) {
+      throw new ApiError(`No response body from external URL`, res.status)
+    }
+
+    return res.body as unknown as AsyncIterable<Uint8Array>
+  }
+
+  private async assertOk(res: Response, url: string): Promise<void> {
+    if (res.ok) return
+
+    if (res.status === 401 || res.status === 403) {
+      throw new AuthError(`Auth failed for ${url} (${res.status}) — run 'alta-plaud auth' to re-authenticate`)
+    }
+
+    throw new ApiError(`HTTP ${res.status} for ${url}`, res.status)
+  }
+}

package/src/client/plaud-client.ts

@@ -0,0 +1,268 @@
+import { ApiError, AuthError } from '../errors.js'
+import { getLogger } from '../logger.js'
+import type { StoredCredentials } from '../auth/types.js'
+import {
+  buildListUrl,
+  buildBatchDetailUrl,
+  buildAudioTempUrl,
+  buildProfileUrl,
+  extractRegionalBaseUrl,
+  type EndpointMap,
+} from './endpoints.js'
+import { HttpClient } from './http.js'
+import {
+  PlaudRecordingSchema,
+  PlaudTranscriptSchema,
+  type PlaudRecording,
+  type PlaudTranscript,
+  type ListOptions,
+  type PlaudClient,
+} from './types.js'
+
+export class PlaudApiClient implements PlaudClient {
+  private readonly http: HttpClient
+  private endpoints: EndpointMap
+
+  constructor(creds: StoredCredentials) {
+    this.http = new HttpClient(creds)
+    this.endpoints = {
+      ...creds.endpointMap,
+      apiBaseUrl: creds.apiBaseUrl,
+    }
+  }
+
+  async isAuthenticated(): Promise<boolean> {
+    try {
+      const profileUrl = buildProfileUrl(this.endpoints)
+      const raw = await this.http.get<unknown>(profileUrl)
+      // A region-redirect response still means we're authenticated
+      if (extractRegionalBaseUrl(raw) !== null) return true
+      // Check for error status in response body
+      const r = raw as Record<string, unknown>
+      return r?.status === 0 || r?.data_user != null
+    } catch (err) {
+      if (err instanceof AuthError) return false
+      if (err instanceof ApiError && (err.statusCode === 401 || err.statusCode === 403)) return false
+      return false
+    }
+  }
+
+  async *listRecordings(opts?: ListOptions): AsyncGenerator<PlaudRecording> {
+    const log = getLogger()
+    let skip = 0
+    const limit = 50
+    let count = 0
+
+    while (true) {
+      const url = buildListUrl(this.endpoints, skip, limit)
+      const raw = await this.http.get<unknown>(url)
+      const items = extractFileList(raw)
+
+      if (items.length === 0) break
+
+      for (const item of items) {
+        const recording = normalizeRecording(item)
+        const parsed = PlaudRecordingSchema.parse(recording)
+
+        // Apply since filter (no server-side date filtering)
+        if (opts?.since && new Date(parsed.recordedAt) < opts.since) continue
+
+        yield parsed
+        count++
+
+        if (opts?.limit && count >= opts.limit) return
+      }
+
+      log.debug({ skip, fetched: items.length }, 'Fetched recording page')
+
+      // Stop when we get fewer items than the limit (last page)
+      if (items.length < limit) break
+      skip += items.length
+    }
+  }
+
+  async getTranscript(recordingId: string): Promise<PlaudTranscript> {
+    // Transcript data lives inside the recording object (trans_result field).
+    // Fetch it via POST /file/list with the single recording ID.
+    const url = buildBatchDetailUrl(this.endpoints)
+    const raw = await this.http.post<unknown>(url, [recordingId])
+    const items = extractFileList(raw)
+
+    if (items.length === 0) {
+      throw new ApiError(`Recording ${recordingId} not found`, 404)
+    }
+
+    const recording = items[0] as Record<string, unknown>
+    const normalized = normalizeTranscript(recording, recordingId)
+    return PlaudTranscriptSchema.parse(normalized)
+  }
+
+  async getAudioDownloadUrl(recordingId: string): Promise<string | null> {
+    try {
+      const url = buildAudioTempUrl(this.endpoints, recordingId)
+      const raw = await this.http.get<unknown>(url)
+      return extractTempUrl(raw)
+    } catch (err) {
+      getLogger().debug({ recordingId, err }, 'Could not get audio download URL')
+      return null
+    }
+  }
+
+  getHttpClient(): HttpClient {
+    return this.http
+  }
+}
+
+// ─── Adaptation Layer ─────────────────────────────────────────────────────────
+//
+// Real Plaud API shapes (from arbuzmell/plaud-api reference client):
+//
+// GET /file/simple/web response:
+//   { data_file_list: [{ id, filename, duration_ms, created_at, has_transcription,
+//                         filesize, filetag_id_list, has_summary }] }
+//
+// POST /file/list response (full detail):
+//   { data_file_list: [{ ...above... + trans_result: [...segments...], ai_content: {...} }] }
+//
+// trans_result segment shape:
+//   { speaker: string, text: string, start_time_ms: number, end_time_ms: number }
+//
+// GET /file/temp-url/<id> response:
+//   { temp_url: "https://s3.amazonaws.com/...?X-Amz-..." }
+
+type AnyObject = Record<string, unknown>
+
+function extractFileList(raw: unknown): unknown[] {
+  const obj = raw as AnyObject
+  // Primary response shape: { data_file_list: [...] }
+  if (Array.isArray(obj?.data_file_list)) return obj.data_file_list as unknown[]
+  // Fallback shapes
+  if (Array.isArray(obj?.data)) return obj.data as unknown[]
+  if (Array.isArray(obj?.list)) return obj.list as unknown[]
+  if (Array.isArray(raw)) return raw as unknown[]
+  return []
+}
+
+function normalizeRecording(raw: unknown): Omit<PlaudRecording, 'mimeType'> & { mimeType?: string } {
+  const r = raw as AnyObject
+
+  // duration is in milliseconds — convert to seconds
+  const durationMs = Number(r['duration'] ?? r['duration_ms'] ?? 0)
+  const duration = durationMs / 1000
+
+  // start_time is Unix milliseconds (the actual recording start time)
+  const startTimeMs = Number(r['start_time'] ?? 0)
+  const recordedAt = startTimeMs > 0 ? new Date(startTimeMs).toISOString() : new Date().toISOString()
+
+  // version_ms is when the record was last synced; edit_time is seconds
+  const versionMs = Number(r['version_ms'] ?? 0)
+  const editTimeSec = Number(r['edit_time'] ?? 0)
+  const updatedAt = versionMs > 0 ? new Date(versionMs).toISOString() : recordedAt
+  const createdAt = editTimeSec > 0 ? new Date(editTimeSec * 1000).toISOString() : recordedAt
+
+  // Determine mime type from the fullname file extension
+  const fullname = String(r['fullname'] ?? '')
+  const ext = fullname.split('.').pop()?.toLowerCase()
+  const mimeType =
+    ext === 'ogg' ? 'audio/ogg' :
+    ext === 'm4a' ? 'audio/m4a' :
+    ext === 'mp3' ? 'audio/mpeg' :
+    ext === 'opus' ? 'audio/ogg; codecs=opus' :
+    'audio/mp4'
+
+  return {
+    id: String(r['id'] ?? ''),
+    title: stringOrUndefined(r['filename'] ?? r['name'] ?? r['title']),
+    duration,
+    recordedAt,
+    createdAt,
+    updatedAt,
+    fileSize: numberOrUndefined(r['filesize'] ?? r['file_size']),
+    mimeType,
+    hasTranscript: Boolean(r['is_trans'] ?? r['has_transcription'] ?? r['hasNote']),
+    transcriptStatus: r['is_trans'] ? 'completed' : undefined,
+    language: stringOrUndefined(r['language'] ?? r['lang']),
+    deviceId: stringOrUndefined(r['serial_number'] ?? r['device_id'] ?? r['deviceId']),
+    tags: arrayOfStrings(r['filetag_id_list'] ?? r['tags']),
+    folderId: undefined,
+    summary: extractSummaryText(r['ai_content']),
+    _raw: r,
+  }
+}
+
+function normalizeTranscript(raw: unknown, recordingId: string): PlaudTranscript {
+  const r = raw as AnyObject
+  const transResult = r['trans_result']
+  const segmentsRaw = Array.isArray(transResult) ? transResult as AnyObject[] : []
+
+  const segments = segmentsRaw.map((s, i) => ({
+    index: i,
+    startMs: Number(s['start_time_ms'] ?? s['startMs'] ?? s['startTime'] ?? 0),
+    endMs: Number(s['end_time_ms'] ?? s['endMs'] ?? s['endTime'] ?? 0),
+    speaker: stringOrUndefined(s['speaker']),
+    text: String(s['text'] ?? '').trim(),
+    confidence: undefined,
+  }))
+
+  const fullText = segments.map(s => s.text).filter(Boolean).join('\n\n')
+  // duration field from POST /file/list is in milliseconds — convert to seconds
+  const durationMs = Number(r['duration_ms'] ?? r['duration'] ?? 0)
+  const duration = durationMs / 1000
+
+  return {
+    recordingId,
+    language: stringOrUndefined(r['language'] ?? r['lang']),
+    duration,
+    segments,
+    fullText,
+    createdAt: stringOrUndefined(r['created_at'] ?? r['createTime']) ? toIso(r['created_at'] ?? r['createTime']) : undefined,
+    _raw: r as Record<string, unknown>,
+  }
+}
+
+function extractTempUrl(raw: unknown): string | null {
+  const obj = raw as AnyObject
+  return stringOrUndefined(obj?.['temp_url'] ?? obj?.['url'] ?? obj?.['downloadUrl']) ?? null
+}
+
+function extractSummaryText(aiContent: unknown): string | undefined {
+  if (!aiContent || typeof aiContent !== 'object') return undefined
+  const obj = aiContent as AnyObject
+  // ai_content can have various summary fields
+  const text = obj['summary'] ?? obj['text'] ?? obj['content']
+  return stringOrUndefined(text)
+}
+
+// ─── Utilities ────────────────────────────────────────────────────────────────
+
+function toIso(val: unknown): string {
+  if (typeof val === 'string' && val.length > 0) {
+    // Already ISO string
+    if (val.includes('T') || val.includes('-')) return new Date(val).toISOString()
+    // Unix ms as string
+    const n = Number(val)
+    if (isFinite(n) && n > 0) {
+      return new Date(n > 1e12 ? n : n * 1000).toISOString()
+    }
+  }
+  if (typeof val === 'number' && val > 0) {
+    return new Date(val > 1e12 ? val : val * 1000).toISOString()
+  }
+  return new Date().toISOString()
+}
+
+function stringOrUndefined(val: unknown): string | undefined {
+  if (typeof val === 'string' && val.length > 0) return val
+  return undefined
+}
+
+function numberOrUndefined(val: unknown): number | undefined {
+  const n = Number(val)
+  return isFinite(n) && n >= 0 ? n : undefined
+}
+
+function arrayOfStrings(val: unknown): string[] | undefined {
+  if (!Array.isArray(val)) return undefined
+  const result = val.filter(v => typeof v === 'string') as string[]
+  return result.length > 0 ? result : undefined
+}