plaud 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing
+
+Thanks for your interest. This is a small, agent-first CLI and we try to keep it simple and robust.
+
+## Principles
+
+- **No secret leakage**: never include tokens, HAR files, or signed URLs in issues/PRs.
+- **Stable JSON contract**: keep `--json` output compatible with `docs/CONTRACT_V1.md`.
+- **Agent-first UX**: stdout should be machine-friendly; progress/logs go to stderr.
+- **Minimal deps**: prefer standard library; add dependencies only when they clearly improve correctness or maintainability.
+
+## Development
+
+Requirements:
+- Node.js 22+
+
+Commands:
+
+```bash
+npm install
+npm test
+```
+
+## Submitting changes
+
+- Keep PRs small and focused.
+- Add or update tests when behavior changes.
+- Update `README.md` and/or `docs/CONTRACT_V1.md` if you change CLI surface or JSON output.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Daniel Wilson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,101 @@
+# plaud (CLI)
+
+Export all your Plaud recordings with speaker-labeled transcripts and optional AI summaries.
+
+## Install (local)
+
+```bash
+cd plaud/plaud-cli
+npm install
+npm link
+```
+
+Requirements:
+- Node.js 22+ (tested on Node 24)
+
+## Auth
+
+Preferred (easy onboarding, stores token locally):
+
+```bash
+plaud auth login
+```
+
+Verify:
+
+```bash
+plaud auth status
+plaud doctor
+```
+
+Fallbacks:
+
+```bash
+plaud auth set --stdin
+plaud auth import-har /path/to/web.plaud.ai.har
+```
+
+Or via env var (no local storage):
+
+```bash
+export PLAUD_AUTH_TOKEN="eyJ..."
+```
+
+Tip (Node 22+): you can also use Node’s `--env-file` if you want to load a local `.env` without adding any dependency to the CLI:
+
+```bash
+node --env-file .env "$(command -v plaud)" auth status --json
+```
+
+## Export
+
+Create a single ZIP (default):
+
+```bash
+plaud recordings export --zip
+```
+
+Export to a directory:
+
+```bash
+plaud recordings export --out ./plaud-transcripts --formats txt,json,md
+```
+
+## Download a single recording
+
+```bash
+plaud recordings list --json --max 10
+plaud recordings download <id> --out ./plaud-download --what transcript,summary,json
+plaud recordings download <id> --out ./plaud-download --what audio --audio-format opus
+```
+
+Notes:
+- `plaud recordings export` prints a JSON summary to stdout; progress goes to stderr.
+- Tokens are stored at `~/.config/plaud/config.json` with `0600` permissions.
+
+## Agent-first JSON contract
+
+See `docs/CONTRACT_V1.md`.
+
+## Install (npm)
+
+Global (recommended for frequent use):
+
+```bash
+npm i -g plaud
+plaud auth login
+```
+
+No install (convenient for agents/one-offs):
+
+```bash
+npx -y plaud auth status --json
+```
+
+## Install (skill)
+
+Once this lives in a GitHub repo, you’ll be able to add the agent skill with:
+
+```bash
+npx -y skills add danielgwilson/plaud --skill plaud -g -y
+```

package/SECURITY.md

@@ -0,0 +1,23 @@
+# Security policy
+
+This project is an **unofficial** CLI for Plaud. It works by capturing a Plaud bearer token from an authenticated browser session and calling private endpoints.
+
+## Reporting a security issue
+
+Please **do not** open a public issue containing secrets.
+
+If you find a security issue (token leakage, unsafe file permissions, etc.), report it privately to the maintainer.
+
+## Never share secrets
+
+Do not paste any of the following into issues, PRs, logs, or screenshots:
+
+- Plaud auth tokens (`Authorization: Bearer …`, typically JWTs starting with `eyJ`)
+- HAR files (`*.har`, `*.har.gz`) — these often contain auth headers
+- Signed file URLs returned by Plaud (may embed temporary credentials)
+
+## Local storage
+
+By default the CLI stores the token at `~/.config/plaud/config.json` with file mode `0600`.
+
+If you don’t want local storage, use the `PLAUD_AUTH_TOKEN` environment variable instead.

package/dist/auth.js

@@ -0,0 +1,155 @@
+import fs from "node:fs/promises";
+import { writeConfig } from "./config.js";
+import { getMe } from "./plaud-api.js";
+function cleanToken(token) {
+    return String(token || "")
+        .trim()
+        .replace(/^bearer\s+/i, "");
+}
+function isProbablyJwt(token) {
+    const t = cleanToken(token);
+    return t.startsWith("eyJ") && t.length > 20;
+}
+function stripUrlQuery(url) {
+    try {
+        const u = new URL(String(url));
+        u.search = "";
+        return u.toString();
+    }
+    catch {
+        return "";
+    }
+}
+function sanitizeMe(me) {
+    if (!me || typeof me !== "object")
+        return null;
+    const dataUser = me.data_user && typeof me.data_user === "object" ? me.data_user : null;
+    const dataState = me.data_state && typeof me.data_state === "object" ? me.data_state : null;
+    const user = dataUser
+        ? {
+            id: dataUser.id || null,
+            email: dataUser.email || null,
+            nickname: dataUser.nickname || null,
+            country: dataUser.country || null,
+            userAreaName: dataUser.user_area_name || null,
+            avatarUrl: dataUser.avatar ? stripUrlQuery(dataUser.avatar) : null,
+        }
+        : null;
+    const state = dataState
+        ? {
+            isMembership: dataState.is_membership ?? null,
+            membershipType: dataState.membership_type ?? null,
+            membershipFlag: dataState.membership_flag ?? null,
+        }
+        : null;
+    return { status: me.status ?? null, user, state };
+}
+export async function validateToken(token) {
+    if (!token)
+        return { ok: false, reason: "missing" };
+    try {
+        const me = await getMe({ token });
+        return { ok: true, me: sanitizeMe(me) };
+    }
+    catch (error) {
+        return { ok: false, reason: error?.message || "invalid" };
+    }
+}
+export async function saveToken(token) {
+    const clean = cleanToken(token);
+    if (!isProbablyJwt(clean))
+        throw new Error("Invalid token format");
+    await writeConfig({ authToken: clean });
+    return clean;
+}
+export async function importTokenFromHar(harPath) {
+    const raw = await fs.readFile(harPath, "utf8");
+    const har = JSON.parse(raw);
+    const entries = har?.log?.entries;
+    if (!Array.isArray(entries)) {
+        throw new Error("Invalid HAR: missing log.entries");
+    }
+    for (const entry of entries) {
+        const req = entry?.request;
+        const headers = req?.headers;
+        if (!Array.isArray(headers))
+            continue;
+        const auth = headers.find((h) => String(h?.name || "").toLowerCase() === "authorization")?.value;
+        if (!auth)
+            continue;
+        if (!String(auth).toLowerCase().startsWith("bearer "))
+            continue;
+        const token = cleanToken(auth);
+        if (!isProbablyJwt(token))
+            continue;
+        return token;
+    }
+    throw new Error("No bearer token found in HAR");
+}
+export async function captureTokenFromBrowser({ url = "https://app.plaud.ai", timeoutMs = 180_000, channel = "chrome", headless = false, onStatus, }) {
+    let playwright;
+    try {
+        playwright = await import("playwright-core");
+    }
+    catch {
+        throw new Error("Missing dependency: playwright-core");
+    }
+    const { chromium } = playwright;
+    const startedAt = Date.now();
+    const status = (msg) => {
+        if (typeof onStatus === "function")
+            onStatus({ msg, elapsedMs: Date.now() - startedAt });
+    };
+    status(`Launching browser (${channel}${headless ? ", headless" : ""})`);
+    let browser;
+    try {
+        browser = await chromium.launch({ headless, channel });
+    }
+    catch {
+        throw new Error(`Failed to launch browser channel "${channel}". Install Chrome/Edge, or use \`plaud auth import-har\`.`);
+    }
+    try {
+        const context = await browser.newContext();
+        const page = await context.newPage();
+        let capturedToken = "";
+        const started = Date.now();
+        const maybeCapture = (request) => {
+            try {
+                const reqUrl = request.url();
+                if (!reqUrl.includes("api.plaud.ai"))
+                    return;
+                const headers = request.headers?.() || {};
+                const auth = headers.authorization || headers.Authorization;
+                if (!auth)
+                    return;
+                if (!String(auth).toLowerCase().startsWith("bearer "))
+                    return;
+                const token = cleanToken(auth);
+                if (isProbablyJwt(token)) {
+                    capturedToken = token;
+                    status("Captured Plaud bearer token");
+                }
+            }
+            catch {
+                // ignore
+            }
+        };
+        page.on("request", maybeCapture);
+        context.on("request", maybeCapture);
+        status("Opening Plaud login page (complete sign-in in the browser)");
+        await page.goto(url, { waitUntil: "domcontentloaded" });
+        status("Waiting for Plaud API request with auth header");
+        while (!capturedToken && Date.now() - started < timeoutMs) {
+            await page.waitForTimeout(250);
+        }
+        if (!capturedToken) {
+            throw new Error("Timed out waiting for Plaud API auth. Please complete login in the opened browser window, or use `plaud auth import-har`.");
+        }
+        return capturedToken;
+    }
+    finally {
+        status("Closing browser");
+        await browser.close();
+    }
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}