@alta-foundation/plaud-extractor 1.0.0

package/src/client/types.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod'
+
+export const TranscriptSegmentSchema = z.object({
+  index: z.number(),
+  startMs: z.number(),
+  endMs: z.number(),
+  speaker: z.string().optional(),
+  text: z.string(),
+  confidence: z.number().min(0).max(1).optional(),
+})
+
+export type TranscriptSegment = z.infer<typeof TranscriptSegmentSchema>
+
+export const PlaudRecordingSchema = z.object({
+  id: z.string(),
+  title: z.string().optional(),
+  /** Duration in seconds */
+  duration: z.number(),
+  recordedAt: z.string().datetime(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+  fileSize: z.number().optional(),
+  mimeType: z.string().default('audio/mp4'),
+  hasTranscript: z.boolean(),
+  transcriptStatus: z.enum(['pending', 'processing', 'completed', 'failed']).optional(),
+  language: z.string().optional(),
+  deviceId: z.string().optional(),
+  tags: z.array(z.string()).optional(),
+  folderId: z.string().optional(),
+  summary: z.string().optional(),
+  /** Raw API payload preserved verbatim for forward-compatibility */
+  _raw: z.record(z.unknown()),
+})
+
+export type PlaudRecording = z.infer<typeof PlaudRecordingSchema>
+
+export const PlaudTranscriptSchema = z.object({
+  recordingId: z.string(),
+  language: z.string().optional(),
+  /** Duration in seconds */
+  duration: z.number(),
+  segments: z.array(TranscriptSegmentSchema),
+  /** Concatenated full text for convenience */
+  fullText: z.string(),
+  createdAt: z.string().datetime().optional(),
+  _raw: z.record(z.unknown()),
+})
+
+export type PlaudTranscript = z.infer<typeof PlaudTranscriptSchema>
+
+export interface ListOptions {
+  since?: Date
+  limit?: number
+  cursor?: string
+}
+
+export interface PlaudClient {
+  isAuthenticated(): Promise<boolean>
+  listRecordings(options?: ListOptions): AsyncGenerator<PlaudRecording>
+  getTranscript(recordingId: string): Promise<PlaudTranscript>
+  getAudioDownloadUrl(recordingId: string): Promise<string | null>
+}

package/src/errors.ts

@@ -0,0 +1,57 @@
+export class PlaudError extends Error {
+  constructor(
+    message: string,
+    public readonly cause?: unknown,
+  ) {
+    super(message)
+    this.name = 'PlaudError'
+    if (cause instanceof Error && cause.stack) {
+      this.stack = `${this.stack}\nCaused by: ${cause.stack}`
+    }
+  }
+}
+
+export class AuthError extends PlaudError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause)
+    this.name = 'AuthError'
+  }
+}
+
+export class ApiError extends PlaudError {
+  constructor(
+    message: string,
+    public readonly statusCode: number,
+    public readonly recordingId?: string,
+    cause?: unknown,
+  ) {
+    super(message, cause)
+    this.name = 'ApiError'
+  }
+
+  get isRetryable(): boolean {
+    return this.statusCode >= 500 || this.statusCode === 429
+  }
+}
+
+export class StorageError extends PlaudError {
+  constructor(
+    message: string,
+    public readonly path: string,
+    cause?: unknown,
+  ) {
+    super(message, cause)
+    this.name = 'StorageError'
+  }
+}
+
+export class ChecksumMismatchError extends PlaudError {
+  constructor(
+    public readonly filePath: string,
+    public readonly expected: string,
+    public readonly actual: string,
+  ) {
+    super(`Checksum mismatch for ${filePath}: expected ${expected}, got ${actual}`)
+    this.name = 'ChecksumMismatchError'
+  }
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// SDK public API — what Alta CORE and other consumers import
+export { PlaudExtractor } from './PlaudExtractor.js'
+export type { PlaudExtractorConfig } from './PlaudExtractor.js'
+
+// Types
+export type { SyncOptions, SyncResult, BackfillOptions, VerifyResult } from './sync/types.js'
+export type { PlaudRecording, PlaudTranscript, TranscriptSegment, ListOptions } from './client/types.js'
+export type { AuthSession, StoredCredentials } from './auth/types.js'
+
+// Errors — consumers may need to catch these
+export {
+  PlaudError,
+  AuthError,
+  ApiError,
+  StorageError,
+  ChecksumMismatchError,
+} from './errors.js'

package/src/logger.ts

@@ -0,0 +1,49 @@
+import pino from 'pino'
+import { runLogsPath } from './storage/paths.js'
+
+export type Logger = pino.Logger
+
+let _logger: pino.Logger | null = null
+
+export function createLogger(outDir: string, opts?: { verbose?: boolean; redact?: boolean }): pino.Logger {
+  const level = process.env['LOG_LEVEL'] ?? (opts?.verbose ? 'debug' : 'info')
+
+  const targets: pino.TransportTargetOptions[] = [
+    {
+      target: 'pino/file',
+      options: { destination: runLogsPath(outDir), mkdir: true },
+      level: 'debug',
+    },
+    {
+      target: 'pino-pretty',
+      options: { colorize: true, translateTime: 'SYS:standard' },
+      level,
+    },
+  ]
+
+  const redactPaths = opts?.redact
+    ? ['authToken', 'cookies', '*.value', 'Authorization', '*.Authorization']
+    : []
+
+  _logger = pino(
+    {
+      level: 'debug',
+      redact: redactPaths.length > 0 ? { paths: redactPaths, censor: '[REDACTED]' } : undefined,
+    },
+    pino.transport({ targets }),
+  )
+
+  return _logger
+}
+
+export function getLogger(): pino.Logger {
+  if (!_logger) {
+    // Fallback: stdout-only logger for when SDK is used without init
+    _logger = pino({ level: process.env['LOG_LEVEL'] ?? 'info' })
+  }
+  return _logger
+}
+
+export function setLogger(logger: pino.Logger): void {
+  _logger = logger
+}

package/src/mcp/job-tools.ts

@@ -0,0 +1,156 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import { stateDir } from '../storage/paths.js'
+import { PlaudExtractor } from '../PlaudExtractor.js'
+import { getLogger } from '../logger.js'
+import type { SyncResult } from '../sync/types.js'
+
+// ─── Job state ─────────────────────────────────────────────────────────────────
+
+type JobStatus = 'running' | 'completed' | 'failed'
+
+interface JobState {
+  id: string
+  type: 'sync' | 'backfill'
+  status: JobStatus
+  startedAt: string
+  completedAt?: string
+  result?: Partial<SyncResult>
+  error?: string
+}
+
+function jobsDir(outDir: string): string {
+  return path.join(stateDir(outDir), 'jobs')
+}
+
+async function writeJob(outDir: string, state: JobState): Promise<void> {
+  await fs.mkdir(jobsDir(outDir), { recursive: true })
+  await fs.writeFile(
+    path.join(jobsDir(outDir), `${state.id}.json`),
+    JSON.stringify(state, null, 2),
+  )
+}
+
+async function readJob(outDir: string, jobId: string): Promise<JobState | null> {
+  try {
+    const raw = await fs.readFile(path.join(jobsDir(outDir), `${jobId}.json`), 'utf8')
+    return JSON.parse(raw) as JobState
+  } catch {
+    return null
+  }
+}
+
+function newJobId(type: string): string {
+  const ts = new Date().toISOString().replace(/[-:.TZ]/g, '').slice(0, 14)
+  const rand = crypto.randomBytes(3).toString('hex')
+  return `${type}_${ts}_${rand}`
+}
+
+// ─── Async job runner ──────────────────────────────────────────────────────────
+
+function runAsync(fn: () => Promise<void>): void {
+  fn().catch(err => getLogger().error({ err }, 'Unhandled job error'))
+}
+
+// ─── Tool registration ─────────────────────────────────────────────────────────
+
+export function registerJobTools(server: McpServer, outDir: string): void {
+
+  // ── plaud_sync ─────────────────────────────────────────────────────────────
+
+  server.tool(
+    'plaud_sync',
+    'Start an incremental sync (new/changed recordings only) in the background. Returns a jobId immediately — poll with plaud_job_status to check progress.',
+    {
+      since: z.string().optional().describe('ISO date — only sync recordings after this date'),
+      limit: z.number().int().min(1).optional().describe('Max recordings to sync'),
+      dryRun: z.boolean().default(false).describe('Preview without downloading'),
+    },
+    async ({ since, limit, dryRun }) => {
+      const jobId = newJobId('sync')
+      const job: JobState = { id: jobId, type: 'sync', status: 'running', startedAt: new Date().toISOString() }
+      await writeJob(outDir, job)
+
+      runAsync(async () => {
+        try {
+          const extractor = new PlaudExtractor({ outDir, logger: getLogger() })
+          const result = await extractor.sync({
+            since: since ? new Date(since) : undefined,
+            limit,
+            dryRun,
+          })
+          await writeJob(outDir, { ...job, status: 'completed', completedAt: new Date().toISOString(), result })
+        } catch (err) {
+          await writeJob(outDir, { ...job, status: 'failed', completedAt: new Date().toISOString(), error: String(err) })
+        }
+      })
+
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({
+            jobId,
+            status: 'running',
+            message: `Sync started. Poll with: plaud_job_status({ jobId: "${jobId}" })`,
+          }, null, 2),
+        }],
+      }
+    },
+  )
+
+  // ── plaud_backfill ─────────────────────────────────────────────────────────
+
+  server.tool(
+    'plaud_backfill',
+    'Re-evaluate and re-download all recordings in the background. Returns a jobId immediately — poll with plaud_job_status to check progress.',
+    {
+      limit: z.number().int().min(1).optional().describe('Max recordings to process'),
+    },
+    async ({ limit }) => {
+      const jobId = newJobId('backfill')
+      const job: JobState = { id: jobId, type: 'backfill', status: 'running', startedAt: new Date().toISOString() }
+      await writeJob(outDir, job)
+
+      runAsync(async () => {
+        try {
+          const extractor = new PlaudExtractor({ outDir, logger: getLogger() })
+          const result = await extractor.backfill({ limit })
+          await writeJob(outDir, { ...job, status: 'completed', completedAt: new Date().toISOString(), result })
+        } catch (err) {
+          await writeJob(outDir, { ...job, status: 'failed', completedAt: new Date().toISOString(), error: String(err) })
+        }
+      })
+
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({
+            jobId,
+            status: 'running',
+            message: `Backfill started. Poll with: plaud_job_status({ jobId: "${jobId}" })`,
+          }, null, 2),
+        }],
+      }
+    },
+  )
+
+  // ── plaud_job_status ───────────────────────────────────────────────────────
+
+  server.tool(
+    'plaud_job_status',
+    'Check the status of a background sync or backfill job.',
+    {
+      jobId: z.string().describe('The jobId returned by plaud_sync or plaud_backfill'),
+    },
+    async ({ jobId }) => {
+      const job = await readJob(outDir, jobId)
+      if (!job) {
+        return { content: [{ type: 'text' as const, text: `Job not found: ${jobId}` }] }
+      }
+      return { content: [{ type: 'text' as const, text: JSON.stringify(job, null, 2) }] }
+    },
+  )
+}

package/src/mcp/read-tools.ts

@@ -0,0 +1,204 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import { loadCredentials, isExpired } from '../auth/token-store.js'
+import { syncStatePath } from '../storage/paths.js'
+import { SyncStateSchema } from '../sync/types.js'
+
+export function registerReadTools(server: McpServer, outDir: string): void {
+
+  // ── plaud_status ──────────────────────────────────────────────────────────
+
+  server.tool(
+    'plaud_status',
+    'Check Plaud connection status, last sync time, and local recording count.',
+    {},
+    async () => {
+      const creds = await loadCredentials().catch(() => null)
+
+      let auth: string
+      if (!creds) {
+        auth = 'not authenticated — run: alta-plaud auth'
+      } else if (isExpired(creds)) {
+        auth = 'token expired — run: alta-plaud auth'
+      } else {
+        auth = 'authenticated'
+      }
+
+      let lastSync = 'never'
+      let recordingCount = 0
+      try {
+        const raw = await fs.readFile(syncStatePath(outDir), 'utf8')
+        const state = SyncStateSchema.parse(JSON.parse(raw))
+        if (state.lastSuccessfulSyncAt) lastSync = state.lastSuccessfulSyncAt
+        recordingCount = Object.keys(state.recordings).length
+      } catch { /* no state file yet */ }
+
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({ auth, lastSync, recordingCount, outDir }, null, 2),
+        }],
+      }
+    },
+  )
+
+  // ── plaud_list_recordings ─────────────────────────────────────────────────
+
+  server.tool(
+    'plaud_list_recordings',
+    'List locally synced Plaud recordings. Filter by date or search title.',
+    {
+      limit: z.number().int().min(1).max(200).default(20).describe('Max results (default 20)'),
+      since: z.string().optional().describe('ISO date — only recordings after this date'),
+      search: z.string().optional().describe('Case-insensitive title filter'),
+    },
+    async ({ limit, since, search }) => {
+      let recordings = await walkRecordingMeta(outDir)
+
+      if (since) {
+        const sinceDate = new Date(since)
+        recordings = recordings.filter(r => new Date(r.recorded_at ?? '') >= sinceDate)
+      }
+      if (search) {
+        const q = search.toLowerCase()
+        recordings = recordings.filter(r => (r.title ?? '').toLowerCase().includes(q))
+      }
+
+      recordings.sort((a, b) => (b.recorded_at ?? '').localeCompare(a.recorded_at ?? ''))
+      const page = recordings.slice(0, limit)
+
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({
+            total: recordings.length,
+            returned: page.length,
+            recordings: page.map(r => ({
+              id: r.source_recording_id,
+              title: r.title,
+              recorded_at: r.recorded_at,
+              duration_seconds: r.duration_seconds,
+              has_transcript: r.has_transcript,
+            })),
+          }, null, 2),
+        }],
+      }
+    },
+  )
+
+  // ── plaud_get_transcript ──────────────────────────────────────────────────
+
+  server.tool(
+    'plaud_get_transcript',
+    'Get the full transcript of a recording by ID or partial title match.',
+    {
+      recordingId: z.string().optional().describe('Exact recording ID'),
+      title: z.string().optional().describe('Partial title match (case-insensitive)'),
+    },
+    async ({ recordingId, title }) => {
+      if (!recordingId && !title) {
+        return { content: [{ type: 'text' as const, text: 'Error: provide recordingId or title' }] }
+      }
+
+      const recordings = await walkRecordingMeta(outDir)
+      let match: RecordingMeta | undefined
+
+      if (recordingId) {
+        match = recordings.find(r => r.source_recording_id === recordingId)
+      } else if (title) {
+        const q = title.toLowerCase()
+        match = recordings.find(r => (r.title ?? '').toLowerCase().includes(q))
+      }
+
+      if (!match) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: `No recording found matching: ${recordingId ?? title}`,
+          }],
+        }
+      }
+
+      let transcript = ''
+      try {
+        transcript = await fs.readFile(path.join(match._dir, 'transcript.txt'), 'utf8')
+      } catch {
+        try {
+          const raw = await fs.readFile(path.join(match._dir, 'transcript.json'), 'utf8')
+          const data = JSON.parse(raw) as { segments?: Array<{ text?: string }> }
+          transcript = (data.segments ?? []).map(s => s.text ?? '').filter(Boolean).join('\n\n')
+        } catch {
+          transcript = '(no transcript available)'
+        }
+      }
+
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({
+            id: match.source_recording_id,
+            title: match.title,
+            recorded_at: match.recorded_at,
+            duration_seconds: match.duration_seconds,
+            transcript,
+          }, null, 2),
+        }],
+      }
+    },
+  )
+}
+
+// ─── Filesystem helpers ────────────────────────────────────────────────────────
+
+interface RecordingMeta {
+  source_recording_id: string
+  title?: string
+  recorded_at?: string
+  duration_seconds?: number
+  has_transcript?: boolean
+  _dir: string
+}
+
+async function walkRecordingMeta(outDir: string): Promise<RecordingMeta[]> {
+  const recordingsBase = path.join(outDir, 'recordings')
+  const results: RecordingMeta[] = []
+
+  let yearDirs: string[]
+  try {
+    yearDirs = await fs.readdir(recordingsBase)
+  } catch {
+    return results
+  }
+
+  for (const year of yearDirs) {
+    let monthDirs: string[]
+    try { monthDirs = await fs.readdir(path.join(recordingsBase, year)) }
+    catch { continue }
+
+    for (const month of monthDirs) {
+      let recDirs: string[]
+      try { recDirs = await fs.readdir(path.join(recordingsBase, year, month)) }
+      catch { continue }
+
+      for (const recDir of recDirs) {
+        const dirPath = path.join(recordingsBase, year, month, recDir)
+        try {
+          const raw = await fs.readFile(path.join(dirPath, 'meta.json'), 'utf8')
+          const meta = JSON.parse(raw) as Record<string, unknown>
+          results.push({
+            source_recording_id: String(meta['source_recording_id'] ?? ''),
+            title: meta['title'] as string | undefined,
+            recorded_at: meta['recorded_at'] as string | undefined,
+            duration_seconds: meta['duration_seconds'] as number | undefined,
+            has_transcript: meta['has_transcript'] as boolean | undefined,
+            _dir: dirPath,
+          })
+        } catch { continue }
+      }
+    }
+  }
+
+  return results
+}

package/src/mcp/server.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import path from 'node:path'
+import os from 'node:os'
+import pino from 'pino'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { defaultOutDir, runLogsPath } from '../storage/paths.js'
+import { setLogger } from '../logger.js'
+import { registerReadTools } from './read-tools.js'
+import { registerJobTools } from './job-tools.js'
+
+const rawDir = process.env['ALTA_DATA_DIR']
+const outDir = rawDir
+  ? path.resolve(rawDir.replace(/^~/, os.homedir()))
+  : defaultOutDir()
+
+// MCP communicates over stdio — logs must go to file only, never stdout
+const logger = pino(
+  { level: 'debug' },
+  pino.transport({
+    targets: [{
+      target: 'pino/file',
+      options: { destination: runLogsPath(outDir), mkdir: true },
+      level: 'debug',
+    }],
+  }),
+)
+setLogger(logger)
+
+const server = new McpServer({
+  name: 'alta-plaud',
+  version: '1.0.0',
+})
+
+registerReadTools(server, outDir)
+registerJobTools(server, outDir)
+
+const transport = new StdioServerTransport()
+await server.connect(transport)

package/src/storage/atomic.ts

@@ -0,0 +1,51 @@
+import fs from 'node:fs/promises'
+import { createWriteStream } from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { StorageError } from '../errors.js'
+
+/** Write a file atomically: write to .tmp-<rand>, then rename. */
+export async function writeFileAtomic(filePath: string, data: string | Buffer): Promise<void> {
+  const tmpPath = `${filePath}.tmp-${crypto.randomBytes(4).toString('hex')}`
+  try {
+    await fs.mkdir(path.dirname(filePath), { recursive: true })
+    await fs.writeFile(tmpPath, data, { encoding: typeof data === 'string' ? 'utf8' : undefined })
+    await fs.rename(tmpPath, filePath)
+  } catch (err) {
+    // Clean up tmp file on failure
+    await fs.unlink(tmpPath).catch(() => undefined)
+    throw new StorageError(`Failed to write ${filePath}`, filePath, err)
+  }
+}
+
+/** Stream a ReadableStream to a file atomically. */
+export async function writeStreamAtomic(
+  filePath: string,
+  stream: AsyncIterable<Uint8Array> | NodeJS.ReadableStream,
+): Promise<void> {
+  const tmpPath = `${filePath}.tmp-${crypto.randomBytes(4).toString('hex')}`
+  try {
+    await fs.mkdir(path.dirname(filePath), { recursive: true })
+    await new Promise<void>((resolve, reject) => {
+      const out = createWriteStream(tmpPath)
+      out.on('finish', resolve)
+      out.on('error', reject)
+
+      if (Symbol.asyncIterator in stream) {
+        ;(async () => {
+          for await (const chunk of stream as AsyncIterable<Uint8Array>) {
+            out.write(chunk)
+          }
+          out.end()
+        })().catch(reject)
+      } else {
+        ;(stream as NodeJS.ReadableStream).pipe(out)
+        ;(stream as NodeJS.ReadableStream).on('error', reject)
+      }
+    })
+    await fs.rename(tmpPath, filePath)
+  } catch (err) {
+    await fs.unlink(tmpPath).catch(() => undefined)
+    throw new StorageError(`Failed to write stream to ${filePath}`, filePath, err)
+  }
+}