plaud 0.1.0

package/docs/CONTRACT_V1.md

@@ -0,0 +1,218 @@
+# Plaud CLI v1 contract (agent-first)
+
+This document defines **stable**, machine-readable behavior for agents and scripts.
+
+## Output rules
+
+- When you pass `--json`, the command prints **exactly one JSON object** to stdout.
+- Progress/status logs go to **stderr**.
+- For `plaud recordings download` and `plaud recordings export`, stdout is always JSON (even without `--json`).
+
+## JSON envelope
+
+### Success
+
+```json
+{
+  "ok": true,
+  "data": {},
+  "meta": {}
+}
+```
+
+`meta` is optional.
+
+### Failure
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "AUTH_MISSING",
+    "message": "No auth token. Run `plaud auth login`.",
+    "retryable": false,
+    "http": { "status": 401 }
+  },
+  "meta": {}
+}
+```
+
+`error.http` and `meta` are optional.
+
+## Exit codes
+
+- `0`: success
+- `1`: failure (unexpected, transient, or upstream error)
+- `2`: user action required (missing auth, invalid input, invalid HAR, etc.)
+
+## Error codes
+
+These are best-effort and may expand in the future:
+
+- `AUTH_MISSING` (exit `2`)
+- `AUTH_INVALID` (usually exit `1`)
+- `NOT_FOUND` (exit `1`)
+- `RATE_LIMITED` (exit `1`, `retryable: true`)
+- `UPSTREAM_5XX` (exit `1`, `retryable: true`)
+- `TIMEOUT` (exit `1`, `retryable: true`)
+- `VALIDATION` (exit `2`)
+- `CHECK_FAILED` (exit `1`)
+- `UNKNOWN` (exit `1`)
+
+## Commands (JSON schemas by example)
+
+### `plaud auth show --json`
+
+Success:
+```json
+{
+  "ok": true,
+  "data": { "hasToken": true, "source": "config", "tokenRedacted": "eyJhbG…abcd" }
+}
+```
+
+Failure (`exit 2`):
+```json
+{
+  "ok": false,
+  "error": { "code": "AUTH_MISSING", "message": "No token set", "retryable": false },
+  "meta": { "hasToken": false }
+}
+```
+
+### `plaud auth status --json`
+
+Success:
+```json
+{
+  "ok": true,
+  "data": {
+    "hasToken": true,
+    "source": "config",
+    "tokenRedacted": "eyJhbG…abcd",
+    "validation": { "ok": true, "me": { "status": 0, "user": { "email": "…" } } }
+  }
+}
+```
+
+### `plaud auth login --json`
+
+Success:
+```json
+{
+  "ok": true,
+  "data": { "tokenRedacted": "eyJhbG…abcd", "validation": { "ok": true, "me": { "user": { "email": "…" } } } }
+}
+```
+
+Notes:
+- This flow opens a browser and captures a Plaud bearer token from an authenticated request to `api.plaud.ai`.
+
+### `plaud auth set --json`
+
+Success:
+```json
+{ "ok": true, "data": { "saved": true, "tokenRedacted": "eyJhbG…abcd" } }
+```
+
+### `plaud auth import-har /path/to.har --json`
+
+Success:
+```json
+{ "ok": true, "data": { "imported": true, "tokenRedacted": "eyJhbG…abcd" } }
+```
+
+### `plaud auth clear --json`
+
+Success:
+```json
+{ "ok": true, "data": { "cleared": true } }
+```
+
+### `plaud whoami --json`
+
+Success:
+```json
+{ "ok": true, "data": { "me": { "user": { "email": "…" } }, "raw": false } }
+```
+
+Notes:
+- `--raw` returns the full `/user/me` response and may include signed URLs.
+
+### `plaud doctor --json`
+
+Success:
+```json
+{ "ok": true, "data": { "checks": [{ "name": "token.present", "ok": true }] } }
+```
+
+Failure:
+```json
+{
+  "ok": false,
+  "error": { "code": "CHECK_FAILED", "message": "One or more checks failed", "retryable": false },
+  "meta": { "checks": [{ "name": "api.listRecordings", "ok": false, "detail": "…" }] }
+}
+```
+
+### `plaud recordings list --json`
+
+Success:
+```json
+{
+  "ok": true,
+  "data": { "count": 2, "recordings": [{ "id": "…" }, { "id": "…" }] },
+  "meta": { "includeTrash": false, "max": 2 }
+}
+```
+
+### `plaud recordings get <id> --json`
+
+Success:
+```json
+{ "ok": true, "data": { "recording": { "id": "…", "trans_result": [] } } }
+```
+
+Failure (not found):
+```json
+{ "ok": false, "error": { "code": "NOT_FOUND", "message": "Recording not found", "retryable": false } }
+```
+
+### `plaud recordings download <id>`
+
+Success:
+```json
+{
+  "ok": true,
+  "data": {
+    "id": "…",
+    "outDir": "/abs/path",
+    "written": [{ "kind": "audio", "path": "/abs/path/file.opus", "bytes": 123 }]
+  }
+}
+```
+
+Notes:
+- `--what` supports: `transcript,summary,json,audio`
+- `--audio-format` supports: `opus` (preferred) or `original`
+
+### `plaud recordings export`
+
+Success:
+```json
+{
+  "ok": true,
+  "data": {
+    "exportDate": "2026-02-28T00:00:00.000Z",
+    "totalFiles": 10,
+    "successful": 10,
+    "failed": [],
+    "includesTrash": false,
+    "since": null,
+    "until": null,
+    "outDir": null,
+    "zipPath": "/abs/path.zip"
+  }
+}
+```
+

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "plaud",
+  "version": "0.1.0",
+  "description": "CLI to export Plaud recordings with speaker-labeled transcripts",
+  "license": "MIT",
+  "author": "Daniel G Wilson",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/danielgwilson/plaud.git"
+  },
+  "bugs": {
+    "url": "https://github.com/danielgwilson/plaud/issues"
+  },
+  "homepage": "https://github.com/danielgwilson/plaud#readme",
+  "bin": {
+    "plaud": "dist/cli.js"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.build.json && node -e \"require('node:fs').chmodSync('dist/cli.js',0o755)\"",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "npm run typecheck",
+    "pretest": "npm run build",
+    "test": "tsx --test",
+    "start": "node dist/cli.js",
+    "prepare": "npm run build"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "docs/",
+    "README.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "archiver": "^6.0.2",
+    "commander": "^12.1.0",
+    "playwright-core": "^1.51.1"
+  },
+  "devDependencies": {
+    "@types/archiver": "^7.0.0",
+    "@types/node": "^25.3.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/skills/plaud/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: plaud
+description: Export and download Plaud recordings (transcripts, summaries, audio) using the plaud CLI with safe auth handling.
+---
+
+# Plaud CLI skill
+
+Use this skill when you need to authenticate to Plaud and export/download recordings from `app.plaud.ai` / `api.plaud.ai`.
+
+## Hard constraints (security)
+
+- Never print or paste a full Plaud auth token into chat/logs.
+- Never pass tokens via CLI flags. Use `plaud auth login`, `plaud auth set --stdin`, or `PLAUD_AUTH_TOKEN`.
+- Prefer `--json` outputs and keep stdout machine-readable where available.
+
+## JSON contract
+
+- For stable machine-readable behavior, follow `docs/CONTRACT_V1.md` (in this repo).
+
+## Setup (once)
+
+- If `plaud` isn’t installed globally, use `npx -y plaud ...` (slower but zero-setup).
+- `plaud auth login`
+- Verify: `plaud auth status --json` and `plaud doctor --json`
+
+Fallbacks:
+- `plaud auth import-har /path/to/web.plaud.ai.har`
+- `plaud auth set --stdin`
+
+## Common workflows
+
+- List: `plaud recordings list --json --max 50`
+- Get one: `plaud recordings get <id> --json`
+- Download one: `plaud recordings download <id> --out ./plaud-download --what transcript,summary,json`
+- Download audio: `plaud recordings download <id> --out ./plaud-download --what audio --audio-format opus`
+- Bulk export: `plaud recordings export --zip`
+
+## Notes
+
+- `plaud recordings export` prints a JSON summary to stdout; progress goes to stderr.
+- When in doubt: run `plaud doctor --json` to confirm auth + API access.