@alta-foundation/plaud-extractor 1.0.0

package/.env.example

@@ -0,0 +1,9 @@
+# Plaud credentials (for automated/headless login)
+PLAUD_EMAIL=you@example.com
+PLAUD_PASSWORD=your-password
+
+# Override default data directory (default: ~/alta/data/plaud)
+ALTA_DATA_DIR=
+
+# Log level: debug | info | warn | error (default: info)
+LOG_LEVEL=info

package/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    name: Typecheck & Build
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: latest
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Build
+        run: pnpm build

package/.github/workflows/publish.yml

@@ -0,0 +1,46 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    name: Build & Publish to npm
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write  # required for provenance
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: latest
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Build
+        run: pnpm build
+
+      - name: Set version from tag
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          pnpm version "$VERSION" --no-git-tag-version
+
+      - name: Publish
+        run: pnpm publish --no-git-checks --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/CLAUDE.md

@@ -0,0 +1,53 @@
+# plaud-extractor — Claude Code guide
+
+## What this project is
+SDK + CLI to pull all recordings from a Plaud account into a local-first dataset.
+Used as a building block for Alta | CORE (imported as `@alta-foundation/plaud-extractor`).
+
+## Key architecture rules
+- **SDK-first**: `PlaudExtractor` class in `src/PlaudExtractor.ts` is the public API. All core logic lives there and in sub-modules. The CLI (`src/cli/bin.ts`) is a thin wrapper — the **only** place `process.exit()` is called.
+- **No side effects at import**: library code never writes to `process.stdout` or calls `process.exit()`.
+- **Atomic writes**: all file writes go through `src/storage/atomic.ts:writeFileAtomic`.
+- **Adaptation layer**: `src/client/plaud-client.ts` contains `normalizeRecording()` and `normalizeTranscript()`. These translate raw Plaud API shapes to the canonical schema. **Update these first** when real API response shapes are observed.
+
+## Dev commands (pnpm)
+```bash
+pnpm dev -- auth                          # first-time auth (launches browser)
+pnpm dev -- sync --dry-run               # preview what would be downloaded
+pnpm dev -- sync --out ~/alta/data/plaud  # incremental sync
+pnpm dev -- backfill --limit 5           # download first 5 recordings
+pnpm dev -- verify --repair              # check + fix checksums
+pnpm build                               # compile to dist/
+pnpm typecheck                           # type-check without emitting
+```
+
+## File locations
+| Purpose | Path |
+|---|---|
+| Auth credentials | `~/.alta/plaud-auth.json` |
+| Data output (default) | `~/alta/data/plaud/` |
+| Sync state | `<out>/_state/sync_state.json` |
+| Run logs | `<out>/_state/run_logs.ndjson` |
+| Dataset | `<out>/datasets/plaud_transcripts.jsonl` |
+
+## Reading run logs
+```bash
+tail -f ~/alta/data/plaud/_state/run_logs.ndjson | jq .
+jq 'select(.recordingId == "abc123")' ~/alta/data/plaud/_state/run_logs.ndjson
+```
+
+## How Alta CORE uses this SDK
+```typescript
+import { PlaudExtractor } from '@alta-foundation/plaud-extractor'
+
+const extractor = new PlaudExtractor({ outDir: '~/alta/data/plaud' })
+const result = await extractor.sync({ since: new Date('2026-01-01') })
+console.log(result.succeeded, 'new recordings downloaded')
+```
+
+## After first real auth capture
+1. Run `pnpm dev -- auth` and log in manually
+2. Inspect `~/.alta/plaud-auth.json` → check `endpointMap`
+3. Copy a real recording JSON response into `src/client/plaud-client.ts` normalizeRecording()
+4. Copy a real transcript JSON response into normalizeTranscript()
+5. Run `pnpm dev -- sync --dry-run --limit 1` to verify parsing

package/README.md

@@ -0,0 +1,318 @@
+# @alta-foundation/plaud-extractor
+
+SDK + CLI to pull all recordings, transcripts, and metadata from a [Plaud](https://www.plaud.ai) account into a structured local-first dataset. Designed as a building block for Alta | CORE.
+
+---
+
+## Contents
+
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Authentication](#authentication)
+- [CLI](#cli)
+- [SDK](#sdk)
+- [MCP Server](#mcp-server)
+- [Output Structure](#output-structure)
+- [Environment Variables](#environment-variables)
+
+---
+
+## Prerequisites
+
+- Node.js 20+
+- pnpm (or npm/yarn)
+- Google Chrome installed on the machine (used for auth — bypasses Google's automation detection)
+
+---
+
+## Installation
+
+```bash
+# As a CLI tool
+pnpm add -g @alta-foundation/plaud-extractor
+
+# As an SDK dependency
+pnpm add @alta-foundation/plaud-extractor
+```
+
+---
+
+## Authentication
+
+Authentication is required once. It opens a real Chrome browser, you log in to Plaud, and the session is saved to `~/.alta/plaud-auth.json`.
+
+```bash
+alta-plaud auth
+```
+
+The browser closes automatically once logged in. Credentials include a JWT valid for ~1 year — you won't need to repeat this often.
+
+---
+
+## CLI
+
+### `alta-plaud sync`
+
+Incremental sync — only downloads new or changed recordings since the last run.
+
+```bash
+alta-plaud sync [options]
+
+Options:
+  --out <dir>          Output directory (default: ~/alta/data/plaud)
+  --since <iso>        Only sync recordings after this ISO date
+  --limit <n>          Max number of recordings to process
+  --concurrency <n>    Parallel downloads (default: 3)
+  --formats <list>     Transcript formats: json,txt,md (default: all)
+  --no-dataset         Skip appending to datasets/plaud_transcripts.jsonl
+  --dry-run            Print what would be downloaded without doing it
+  --verbose            Verbose logging
+  --redact             Redact tokens from logs
+```
+
+```bash
+# Preview what would sync
+alta-plaud sync --dry-run
+
+# Sync last 7 days only
+alta-plaud sync --since $(date -v-7d +%Y-%m-%d)
+
+# Sync to a custom directory
+alta-plaud sync --out ~/my-recordings
+```
+
+If the session token expires mid-sync, re-authentication is triggered automatically.
+
+---
+
+### `alta-plaud backfill`
+
+Full re-evaluation of all recordings, regardless of incremental state. Useful after a schema change or to repair gaps.
+
+```bash
+alta-plaud backfill [options]
+
+Options:
+  --out <dir>          Output directory (default: ~/alta/data/plaud)
+  --since <iso>        Only backfill recordings after this ISO date
+  --limit <n>          Max number of recordings to process
+  --concurrency <n>    Parallel downloads (default: 3)
+  --formats <list>     Transcript formats: json,txt,md (default: all)
+  --no-dataset         Skip dataset output
+  --dry-run            Print plan without downloading
+  --yes                Skip confirmation prompt
+  --verbose            Verbose logging
+```
+
+```bash
+# Backfill first 10 recordings (useful for testing)
+alta-plaud backfill --limit 10 --yes
+```
+
+---
+
+### `alta-plaud verify`
+
+Walk all downloaded recordings and verify checksums. Detects missing or corrupted files.
+
+```bash
+alta-plaud verify [options]
+
+Options:
+  --out <dir>    Output directory (default: ~/alta/data/plaud)
+  --repair       Re-download files with checksum mismatches
+  --verbose      Verbose logging
+```
+
+---
+
+### `alta-plaud auth`
+
+Launch browser for (re-)authentication.
+
+```bash
+alta-plaud auth [options]
+
+Options:
+  --out <dir>      Data directory for logs
+```
+
+---
+
+## SDK
+
+```typescript
+import { PlaudExtractor } from '@alta-foundation/plaud-extractor'
+
+const extractor = new PlaudExtractor({
+  outDir: '~/alta/data/plaud',  // default
+  verbose: false,
+  redact: false,
+})
+
+// One-time auth (opens browser)
+await extractor.authenticate()
+
+// Incremental sync
+const result = await extractor.sync({ since: new Date('2026-01-01') })
+console.log(`${result.succeeded} downloaded, ${result.failed} failed`)
+
+// Full backfill
+await extractor.backfill({ limit: 50 })
+
+// Verify checksums
+const verify = await extractor.verify({ repair: false })
+
+// Export JSONL dataset
+const datasetPath = await extractor.exportDataset()
+```
+
+**Types available:**
+
+```typescript
+import type {
+  SyncOptions,
+  SyncResult,
+  BackfillOptions,
+  VerifyResult,
+  PlaudRecording,
+  PlaudTranscript,
+  AuthSession,
+} from '@alta-foundation/plaud-extractor'
+```
+
+**Error handling:**
+
+```typescript
+import { AuthError, ApiError, StorageError } from '@alta-foundation/plaud-extractor'
+
+try {
+  await extractor.sync()
+} catch (err) {
+  if (err instanceof AuthError) {
+    // Token expired or invalid — re-authenticate
+  }
+}
+```
+
+---
+
+## MCP Server
+
+The MCP server exposes Plaud data as tools for Claude (or any MCP client). Read operations (list, transcript) are synchronous and work offline from local files. Sync/backfill run in the background and return a job ID for polling.
+
+### Tools
+
+| Tool | Type | Description |
+|---|---|---|
+| `plaud_status` | sync | Auth status, last sync time, recording count |
+| `plaud_list_recordings` | sync | List local recordings — filter by date or title |
+| `plaud_get_transcript` | sync | Full transcript by recording ID or partial title |
+| `plaud_sync` | async | Start incremental sync → returns `jobId` |
+| `plaud_backfill` | async | Start full backfill → returns `jobId` |
+| `plaud_job_status` | sync | Poll status of a background job |
+
+### Configuration
+
+Add to Claude Code settings (`~/.claude/settings.json`) or your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "alta-plaud": {
+      "command": "alta-plaud-mcp",
+      "env": {
+        "ALTA_DATA_DIR": "/Users/you/alta/data/plaud"
+      }
+    }
+  }
+}
+```
+
+If running from source:
+
+```json
+{
+  "mcpServers": {
+    "alta-plaud": {
+      "command": "node",
+      "args": ["/path/to/plaud-extractor/dist/mcp/server.js"],
+      "env": {
+        "ALTA_DATA_DIR": "/Users/you/alta/data/plaud"
+      }
+    }
+  }
+}
+```
+
+### Async job flow
+
+```
+Claude: plaud_sync({ since: "2026-02-01" })
+→ { jobId: "sync_20260226_a1b2c3", status: "running" }
+
+Claude: plaud_job_status({ jobId: "sync_20260226_a1b2c3" })
+→ { status: "completed", result: { succeeded: 12, failed: 0, ... } }
+```
+
+---
+
+## Output Structure
+
+```
+~/alta/data/plaud/
+├── recordings/
+│   └── 2026/
+│       └── 02/
+│           └── 20260224T083012Z__plaud_<id>/
+│               ├── meta.json          # Recording metadata
+│               ├── transcript.json    # Structured transcript with segments
+│               ├── transcript.txt     # Plain text transcript
+│               ├── transcript.md      # Markdown with YAML frontmatter + timestamps
+│               ├── audio.ogg          # Original audio file
+│               └── checksums.json     # SHA-256 hashes for all files
+├── datasets/
+│   └── plaud_transcripts.jsonl        # All recordings as JSONL (append-only)
+└── _state/
+    ├── sync_state.json                # Incremental sync state
+    ├── run_logs.ndjson                # Structured logs (pino NDJSON)
+    └── jobs/
+        └── sync_<id>.json             # Background job state (MCP async)
+```
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `ALTA_DATA_DIR` | Override default output directory (`~/alta/data/plaud`) |
+| `LOG_LEVEL` | Pino log level: `debug`, `info`, `warn`, `error` (default: `info`) |
+| `DEBUG` | Print full stack traces on CLI errors |
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# First-time auth
+pnpm dev -- auth
+
+# Preview sync
+pnpm dev -- sync --dry-run
+
+# Sync with verbose logging
+pnpm dev -- sync --verbose
+
+# Run MCP server locally
+pnpm dev:mcp
+
+# Build to dist/
+pnpm build
+
+# Type-check without emitting
+pnpm typecheck
+```

package/dist/PlaudExtractor.d.ts

@@ -0,0 +1,61 @@
+import { type Logger } from './logger.js';
+import { type BrowserAuthOptions } from './auth/browser-auth.js';
+import type { SyncOptions, SyncResult, BackfillOptions, VerifyResult } from './sync/types.js';
+export interface PlaudExtractorConfig {
+    /** Output directory for recordings. Default: ~/alta/data/plaud */
+    outDir?: string;
+    /** Inject a custom pino logger (e.g., from Alta CORE) */
+    logger?: Logger;
+    /** Verbose logging */
+    verbose?: boolean;
+    /** Redact tokens from logs */
+    redact?: boolean;
+}
+export declare class PlaudExtractor {
+    private readonly outDir;
+    private readonly engine;
+    constructor(config?: PlaudExtractorConfig);
+    /**
+     * Launch browser for authentication.
+     * Saves credentials to ~/.alta/plaud-auth.json.
+     */
+    authenticate(opts?: BrowserAuthOptions): Promise<void>;
+    /**
+     * Check if credentials exist and are not expired.
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Incremental sync: only download new or changed recordings since last run.
+     * If the token expires mid-sync, re-authenticates automatically and retries once.
+     */
+    sync(opts?: Partial<SyncOptions>): Promise<SyncResult>;
+    /**
+     * Full backfill: re-evaluate all recordings regardless of sync state.
+     * If the token expires mid-backfill, re-authenticates automatically and retries once.
+     */
+    backfill(opts?: Partial<BackfillOptions>): Promise<SyncResult>;
+    /**
+     * Run sync/backfill, and if a token-expired AuthError occurs mid-run,
+     * automatically re-authenticate and retry once.
+     */
+    private runWithReauth;
+    /**
+     * Walk all recording folders and verify checksums.
+     * With repair=true, re-download any file with a mismatch.
+     */
+    verify(opts?: {
+        repair?: boolean;
+    }): Promise<VerifyResult>;
+    /**
+     * Export all local recordings to a JSONL dataset file.
+     * Returns the path to the generated file.
+     */
+    exportDataset(opts?: {
+        format?: 'jsonl';
+    }): Promise<string>;
+    private walkAndExport;
+    private buildClient;
+    private buildSyncOptions;
+    get dataDir(): string;
+}
+//# sourceMappingURL=PlaudExtractor.d.ts.map

package/dist/PlaudExtractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlaudExtractor.d.ts","sourceRoot":"","sources":["../src/PlaudExtractor.ts"],"names":[],"mappings":"AAGA,OAAO,EAA2B,KAAK,MAAM,EAAE,MAAM,aAAa,CAAA;AAElE,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAQhF,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAE7F,MAAM,WAAW,oBAAoB;IACnC,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sBAAsB;IACtB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,8BAA8B;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;gBAEvB,MAAM,GAAE,oBAAyB;IAc7C;;;OAGG;IACG,YAAY,CAAC,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhE;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAOzC;;;OAGG;IACG,IAAI,CAAC,IAAI,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAIhE;;;OAGG;IACG,QAAQ,CAAC,IAAI,GAAE,OAAO,CAAC,eAAe,CAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAIxE;;;OAGG;YACW,aAAa;IAoB3B;;;OAGG;IACG,MAAM,CAAC,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,YAAY,CAAC;IA2CpE;;;OAGG;IACG,aAAa,CAAC,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,MAAM,CAAC;YAmBvD,aAAa;YA2Eb,WAAW;IAWzB,OAAO,CAAC,gBAAgB;IAYxB,IAAI,OAAO,IAAI,MAAM,CAEpB;CACF"}