caps-brief 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 — 2026-07-16
+
+Initial release.
+
+- `caps-brief auth` — OAuth 2.1 + PKCE browser sign-in against the Capacities API 2.0, with automatic (RFC 7591) client registration and rotating refresh tokens; `--token` for personal API tokens.
+- `caps-brief config` — manage RSS/Atom feeds and the wttr.in weather location.
+- `caps-brief run` — fetches Hacker News top 10, your feeds, and the weather; summarises with Claude (`claude-haiku-4-5`); appends the briefing to your Daily Note via `POST /blocks/daily-note/append`.
+- `caps-brief status` — auth, space, key, sources, and last-run at a glance.
+- Cron-grade reliability: once-per-day duplicate guard (`--force` to override), automatic fallback to a plain digest when Claude is transiently unavailable, per-source failure isolation, Capacities rate-limit backoff, refuses to write an empty briefing.
+- `--dry-run`, `--no-llm`, `--date YYYY-MM-DD`, `--no-timestamp` flags.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Booyaka101
+
+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,162 @@
+# caps-brief
+
+> **Status: archived, unmaintained, not published to npm.**
+>
+> caps-brief requires **Capacities Pro** — API access is a Pro-only feature (~SGD 12.99/mo), which isn't obvious from the Capacities pricing page until you look closely. I don't have Pro, so **the OAuth sign-in and the Claude summarisation path have never run against a live account.** They're implemented and unit-tested, but unproven end-to-end. Against a Basic account, `caps-brief auth` fails with a bare `notAuthenticated`.
+>
+> I'm not going to maintain a tool I can't run, so this is archived rather than deleted. It may still be useful as a **reference for building on the Capacities API 2.0** — [`src/auth.ts`](src/auth.ts) has a working RFC 7591 dynamic client registration and OAuth 2.1 + PKCE flow (registration is confirmed working: `/oauth/reg` returns 201 for a public client with a localhost redirect URI). The old Beta API shuts down 2026-09-01; this is built entirely on 2.0.
+>
+> MIT — fork it, finish it, no need to ask.
+
+A Node.js CLI that auto-populates your [Capacities](https://capacities.io) Daily Note with an AI morning briefing — Hacker News front page, your RSS feeds, and the weather — summarised by Claude and written via the **Capacities API 2.0** (launched July 2026, [developers.capacities.io](https://developers.capacities.io)).
+
+Every morning your Daily Note starts with:
+
+```
+## ☀️ Morning Briefing
+
+### Top Stories
+A 2–4 sentence synthesis of the HN front page, plus the three most notable links…
+
+### RSS Highlights
+What's new across your subscribed feeds…
+
+### Weather
+Singapore: 🌤️ +31°C
+```
+
+**BYOK (bring your own keys):** you use your own Capacities account and your own Anthropic API key. Nothing goes through anyone else's server.
+
+## Requirements
+
+- Node.js ≥ 22
+- **Capacities Pro** — API access is a Pro-only feature (~SGD 12.99/mo; there's a free trial in the app). Basic accounts can't use this tool: both the OAuth sign-in and personal tokens are gated behind Pro.
+- An Anthropic API key from [platform.claude.com](https://platform.claude.com) — optional if you run with `--no-llm`
+
+## Install
+
+Not on npm — build from source:
+
+```sh
+git clone https://github.com/Booyaka101/caps-brief.git
+cd caps-brief && npm install && npm run build && npm link
+```
+
+## 1. Authenticate with Capacities
+
+**Option A — browser sign-in (OAuth 2.1 + PKCE):**
+
+```sh
+caps-brief auth
+```
+
+Your browser opens the Capacities consent screen; approve, and tokens land in `~/.caps-brief/tokens.json`. The CLI registers itself as a public OAuth client automatically via the API's dynamic client registration endpoint — no manual app registration needed. Access tokens auto-refresh (rotating refresh tokens), so this is fire-and-forget for cron use. If you are building your own *published* integration instead, register a permanent OAuth client with the Capacities team via [developers.capacities.io](https://developers.capacities.io).
+
+**Option B — personal API token (simplest):**
+
+In the Capacities desktop app go to **Settings → Capacities API → Generate new token** (scopes: `api:read` + `api:write`), then:
+
+```sh
+caps-brief auth --token cap-api-xxxxxxxx
+```
+
+Either way, `auth` verifies the credential against `GET /space` and tells you which space it's connected to. Note: a token/OAuth grant is bound to **one space** — the briefing lands in that space's Daily Note.
+
+## 2. Configure sources
+
+```sh
+caps-brief config --add-rss https://feeds.arstechnica.com/arstechnica/index
+caps-brief config --add-rss https://www.theverge.com/rss/index.xml
+caps-brief config --weather "Singapore"     # any wttr.in location; omit for IP-based
+caps-brief config --list
+```
+
+RSS 2.0 and Atom are both supported. Hacker News (top 10 front-page stories) and weather are on by default.
+
+## 3. Set your Anthropic key and run
+
+```sh
+# macOS/Linux
+export ANTHROPIC_API_KEY=sk-ant-...
+# Windows (PowerShell)
+$env:ANTHROPIC_API_KEY = "sk-ant-..."
+
+caps-brief run --dry-run   # preview without writing
+caps-brief run             # write to today's Daily Note
+```
+
+Summarisation uses `claude-haiku-4-5` (~$0.002/day at typical volumes). No key? `caps-brief run --no-llm` writes a clean, unsummarised digest instead.
+
+Check everything at a glance any time:
+
+```sh
+caps-brief status    # auth ✔/✖, connected space, key, sources, last run
+```
+
+**Built for unattended mornings:**
+
+- Runs are **once per day** — if your scheduler fires twice, the second run is a clean no-op (`--force` overrides).
+- If Claude is transiently unreachable (rate limit, network, 5xx), the run **falls back to the plain digest** with a warning instead of leaving your note empty. Bad/missing API keys still fail loudly — config problems are never papered over.
+- Each source fails independently; the run only aborts if *everything* is unreachable (it never writes an empty briefing).
+
+Other flags: `--date 2026-07-17` (target another day's note, bypasses the once-per-day guard), `--no-timestamp` (omit the timestamp heading Capacities adds to appended blocks).
+
+## 4. Schedule it
+
+**Linux/macOS (cron):**
+
+```cron
+30 6 * * * ANTHROPIC_API_KEY=sk-ant-... /usr/local/bin/caps-brief run >> ~/.caps-brief/run.log 2>&1
+```
+
+**Windows (Task Scheduler):** — use the full path; scheduled tasks don't reliably inherit your PATH:
+
+```powershell
+$action = New-ScheduledTaskAction -Execute "$env:APPDATA\npm\caps-brief.cmd" -Argument "run"
+$trigger = New-ScheduledTaskTrigger -Daily -At 6:30am
+Register-ScheduledTask -TaskName "caps-brief" -Action $action -Trigger $trigger
+```
+
+(Set `ANTHROPIC_API_KEY` as a user environment variable first: `[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY","sk-ant-...","User")`.)
+
+Missed a morning (laptop asleep)? Just run `caps-brief run` when you're back — the once-per-day guard means double-scheduling is always safe.
+
+## How it talks to Capacities
+
+- Auth: OAuth 2.1 authorization-code + PKCE (S256) against `https://api.capacities.io/oauth/authorize` / `/oauth/token`, discovered via RFC 8414; or a `cap-api-…` bearer token.
+- Write: `POST /blocks/daily-note/append` with a `markdown` body — creates today's Daily Note if needed and appends the briefing (rate limit: 30 req/min; we make 1/day).
+- The old Capacities Beta API is **not** used anywhere — it shuts down September 1, 2026. This tool is built entirely on API 2.0.
+
+## Troubleshooting
+
+Start with `caps-brief status` — it diagnoses most of these in one shot.
+
+| Symptom | Fix |
+|---|---|
+| `Not authenticated. Run: caps-brief auth` | Token missing/revoked — re-run `caps-brief auth` |
+| `forbidden … api:write scope` | Regenerate your personal token with the **write** scope enabled |
+| `ANTHROPIC_API_KEY is not set` | Export the key, or add `--no-llm` |
+| `Already briefed today` | Working as intended — add `--force` to send another |
+| Note shows the plain digest, not the AI summary | Claude was briefly unreachable that morning; check the run log for the ⚠ line |
+| Wrong space gets the briefing | Tokens are per-space — re-auth and pick the right space |
+| All sources failed | Network/proxy issue; nothing is written on total failure |
+
+Files live in `~/.caps-brief/`: `tokens.json` (credentials, 0600), `config.json` (feeds/weather), `client.json` (OAuth client registration), `state.json` (last-run marker).
+
+## Forking
+
+This repo is archived, so issues and pull requests are closed — but it's MIT, so fork away.
+
+```sh
+npm install
+npm run build
+npm test        # unit suite (feed parsing, formatting) on Node's built-in test runner
+```
+
+If you pick this up with a Pro account, the two unverified paths are `caps-brief auth` (the OAuth browser flow — dynamic client registration works, the consent step is unproven) and [`src/llm.ts`](src/llm.ts) (Claude summarisation; `--no-llm` skips it and is exercised by the tests).
+
+Adding a source (a new feed type, a calendar, anything else) means a fetcher in [`src/sources.ts`](src/sources.ts) that fails independently of the others — the run should degrade to whatever else succeeded rather than abort.
+
+## License
+
+[MIT](LICENSE) © Booyaka101

package/SETUP.md

@@ -0,0 +1,101 @@
+# caps-brief — 10-Minute Setup Guide
+
+*By the end of this guide your Capacities Daily Note will greet you every morning with an AI-written briefing.*
+
+---
+
+## What you need
+
+| Item | Where to get it | Cost |
+|---|---|---|
+| Node.js 22+ | [nodejs.org](https://nodejs.org) | free |
+| **Capacities Pro** — API access is Pro-only | [capacities.io](https://capacities.io) | ~SGD 12.99/mo (free trial in the app) |
+| Anthropic API key | [platform.claude.com](https://platform.claude.com) → API Keys | ~$0.002/day of usage |
+
+caps-brief is **BYOK** — your keys, your data, no middleman server.
+
+## Step 1 — Install (2 min)
+
+Open a terminal in your download folder:
+
+```sh
+npm install -g ./caps-brief-0.1.0.tgz
+caps-brief --version   # → 0.1.0
+```
+
+## Step 2 — Connect Capacities (3 min)
+
+The easy path is the browser flow:
+
+```sh
+caps-brief auth
+```
+
+1. Your browser opens Capacities' sign-in/consent page.
+2. Approve access for **caps-brief CLI** (scopes: read, write, offline access).
+3. The terminal prints `✅ Signed in` and the name of your connected space.
+
+Prefer a static token? In the Capacities **desktop app**: Settings → Capacities API → *Generate new token* → tick **read** and **write** → copy it, then:
+
+```sh
+caps-brief auth --token cap-api-PASTE-YOURS-HERE
+```
+
+> ⚠️ Tokens are bound to **one space**. The briefing will be appended to the Daily Note of the space you approved.
+
+## Step 3 — Connect Claude (1 min)
+
+Create a key at platform.claude.com, then make it permanent:
+
+- **macOS/Linux** — add to `~/.zshrc` or `~/.bashrc`:
+  `export ANTHROPIC_API_KEY=sk-ant-...`
+- **Windows** — PowerShell (once):
+  `[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY","sk-ant-...","User")`
+
+*(Skip this step entirely if you're happy with an unsummarised link digest — just always run with `--no-llm`.)*
+
+## Step 4 — Pick your sources (2 min)
+
+```sh
+caps-brief config --add-rss https://feeds.arstechnica.com/arstechnica/index
+caps-brief config --add-rss https://www.theverge.com/rss/index.xml
+caps-brief config --weather "Berlin"
+```
+
+Any RSS 2.0 or Atom feed works. Hacker News top-10 and weather are included automatically.
+
+## Step 5 — Test, then go live (2 min)
+
+```sh
+caps-brief status           # everything green?
+caps-brief run --dry-run    # preview in the terminal — writes nothing
+caps-brief run              # ✨ check today's Daily Note in Capacities
+```
+
+Open Capacities → today's Daily Note. You should see **☀️ Morning Briefing** with Top Stories, RSS Highlights, and Weather.
+
+## Step 6 — Automate every morning
+
+**macOS/Linux** — `crontab -e`, then:
+
+```cron
+30 6 * * * ANTHROPIC_API_KEY=sk-ant-... /usr/local/bin/caps-brief run >> ~/.caps-brief/run.log 2>&1
+```
+
+**Windows** — PowerShell (as your user; note the full path — scheduled tasks don't reliably see your PATH):
+
+```powershell
+$action  = New-ScheduledTaskAction -Execute "$env:APPDATA\npm\caps-brief.cmd" -Argument "run"
+$trigger = New-ScheduledTaskTrigger -Daily -At 6:30am
+Register-ScheduledTask -TaskName "caps-brief" -Action $action -Trigger $trigger
+```
+
+Done. Coffee → open Capacities → your day is already summarised. ☕
+
+## FAQ
+
+**Does it duplicate if I run it twice?** No — caps-brief remembers it already briefed today and the second run is a no-op. Want a second one anyway? `caps-brief run --force`.
+**What if Claude is down at 6:30am?** Your note still gets the briefing — as a plain link digest, with a warning in the log. Bad API keys fail loudly instead (so you notice).
+**Can I write to yesterday's/tomorrow's note?** Yes: `caps-brief run --date 2026-07-17`.
+**Where are my credentials?** `~/.caps-brief/tokens.json`, file mode 0600, never sent anywhere except `api.capacities.io`.
+**Something broke?** Run the failing command again and read the `✖` line — every error tells you the fix. Note this project is archived and unmaintained: there's no issue tracker to fall back on. See the status banner in the [README](README.md).

package/dist/auth.js

@@ -0,0 +1,203 @@
+import crypto from "node:crypto";
+import http from "node:http";
+import fetch from "node-fetch";
+import open from "open";
+import { loadClient, loadTokens, saveClient, saveTokens, TOKENS_PATH, } from "./store.js";
+export const API_BASE = "https://api.capacities.io";
+const DISCOVERY_URL = `${API_BASE}/.well-known/oauth-authorization-server`;
+const SCOPES = "api:read api:write offline_access";
+/** Refresh when the access token has less than this many ms of life left. */
+const EXPIRY_SKEW_MS = 60_000;
+function b64url(buf) {
+    return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+async function discover() {
+    const res = await fetch(DISCOVERY_URL);
+    if (!res.ok) {
+        throw new Error(`OAuth discovery failed (${res.status}). Is https://api.capacities.io reachable?`);
+    }
+    return (await res.json());
+}
+/**
+ * Register caps-brief as a public OAuth client via RFC 7591 dynamic client
+ * registration, or reuse a previously registered client if the redirect URI
+ * still matches (the URI embeds the callback port, so a port change forces
+ * re-registration).
+ */
+async function getClientId(discovery, redirectUri) {
+    const cached = await loadClient();
+    if (cached && cached.redirectUri === redirectUri)
+        return cached.clientId;
+    const res = await fetch(discovery.registration_endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            client_name: "caps-brief CLI",
+            redirect_uris: [redirectUri],
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+            scope: SCOPES,
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`Dynamic client registration failed (${res.status}): ${body}\n` +
+            `You can instead use a personal API token: caps-brief auth --token cap-api-...`);
+    }
+    const reg = (await res.json());
+    await saveClient({ clientId: reg.client_id, redirectUri, registeredAt: Date.now() });
+    return reg.client_id;
+}
+/** Wait for the OAuth redirect on a local loopback server; resolve with the code. */
+function waitForCallback(server, expectedState, timeoutMs = 5 * 60_000) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error("Timed out waiting for the browser sign-in (5 minutes)."));
+        }, timeoutMs);
+        server.on("request", (req, res) => {
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (url.pathname !== "/callback") {
+                res.writeHead(404).end();
+                return;
+            }
+            const err = url.searchParams.get("error");
+            const code = url.searchParams.get("code");
+            const state = url.searchParams.get("state");
+            const finish = (ok, message) => {
+                res.writeHead(ok ? 200 : 400, { "Content-Type": "text/html; charset=utf-8" });
+                res.end(`<html><body style="font-family:sans-serif;margin:3rem auto;max-width:30rem;text-align:center">` +
+                    `<h2>${ok ? "✅ caps-brief connected" : "❌ Sign-in failed"}</h2><p>${message}</p></body></html>`);
+            };
+            if (err) {
+                finish(false, `Capacities returned: ${err}`);
+                clearTimeout(timer);
+                reject(new Error(`Authorization was denied: ${err}`));
+            }
+            else if (!code || state !== expectedState) {
+                finish(false, "Invalid callback (state mismatch). Please retry.");
+                clearTimeout(timer);
+                reject(new Error("OAuth state mismatch — possible CSRF or a stale browser tab. Retry caps-brief auth."));
+            }
+            else {
+                finish(true, "You can close this tab and return to the terminal.");
+                clearTimeout(timer);
+                resolve(code);
+            }
+        });
+    });
+}
+async function exchangeToken(tokenEndpoint, params) {
+    const res = await fetch(tokenEndpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams(params).toString(),
+    });
+    const body = await res.text();
+    if (!res.ok) {
+        throw new Error(`Token request failed (${res.status}): ${body}`);
+    }
+    return JSON.parse(body);
+}
+function toStoredTokens(t) {
+    return {
+        authMethod: "oauth",
+        accessToken: t.access_token,
+        refreshToken: t.refresh_token,
+        expiresAt: t.expires_in ? Date.now() + t.expires_in * 1000 : undefined,
+        scope: t.scope,
+        obtainedAt: Date.now(),
+    };
+}
+/** Full browser-based OAuth 2.1 PKCE flow. Stores tokens in ~/.caps-brief/tokens.json. */
+export async function oauthLogin() {
+    const discovery = await discover();
+    const server = http.createServer();
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const port = server.address().port;
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    try {
+        const clientId = await getClientId(discovery, redirectUri);
+        const verifier = b64url(crypto.randomBytes(48));
+        const challenge = b64url(crypto.createHash("sha256").update(verifier).digest());
+        const state = b64url(crypto.randomBytes(24));
+        const authUrl = new URL(discovery.authorization_endpoint);
+        authUrl.search = new URLSearchParams({
+            response_type: "code",
+            client_id: clientId,
+            redirect_uri: redirectUri,
+            scope: SCOPES,
+            resource: API_BASE,
+            code_challenge: challenge,
+            code_challenge_method: "S256",
+            state,
+        }).toString();
+        console.log("Opening your browser to sign in to Capacities…");
+        console.log(`If it does not open, visit:\n  ${authUrl.toString()}\n`);
+        await open(authUrl.toString()).catch(() => {
+            /* headless environments: the URL is already printed */
+        });
+        const code = await waitForCallback(server, state);
+        const tokens = await exchangeToken(discovery.token_endpoint, {
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: redirectUri,
+            client_id: clientId,
+            code_verifier: verifier,
+        });
+        await saveTokens(toStoredTokens(tokens));
+        console.log(`✅ Signed in. Tokens saved to ${TOKENS_PATH}`);
+    }
+    finally {
+        server.close();
+    }
+}
+/** Store a personal API token (generated in Capacities → Settings → Capacities API). */
+export async function tokenLogin(token) {
+    if (!token.startsWith("cap-api-")) {
+        console.warn("Warning: Capacities personal tokens normally start with 'cap-api-'. Storing anyway.");
+    }
+    await saveTokens({ authMethod: "token", accessToken: token, obtainedAt: Date.now() });
+    console.log(`✅ Token saved to ${TOKENS_PATH}`);
+}
+/**
+ * Return a valid access token, refreshing via the rotating refresh token if
+ * the OAuth access token is expired or about to expire.
+ */
+export async function getAccessToken() {
+    const stored = await loadTokens();
+    if (!stored) {
+        throw new Error("Not authenticated. Run: caps-brief auth   (or: caps-brief auth --token cap-api-...)");
+    }
+    if (stored.authMethod === "token")
+        return stored.accessToken;
+    const fresh = stored.expiresAt !== undefined && Date.now() < stored.expiresAt - EXPIRY_SKEW_MS;
+    if (fresh)
+        return stored.accessToken;
+    return refreshAccessToken(stored);
+}
+/** Refresh the OAuth access token. Refresh tokens rotate on every use, so persist immediately. */
+export async function refreshAccessToken(stored) {
+    const current = stored ?? (await loadTokens());
+    if (!current || current.authMethod !== "oauth") {
+        throw new Error("No OAuth session to refresh. Run: caps-brief auth");
+    }
+    if (!current.refreshToken) {
+        throw new Error("Access token expired and no refresh token was granted. Run: caps-brief auth");
+    }
+    const discovery = await discover();
+    const client = await loadClient();
+    if (!client) {
+        throw new Error("OAuth client registration missing. Run: caps-brief auth");
+    }
+    const tokens = await exchangeToken(discovery.token_endpoint, {
+        grant_type: "refresh_token",
+        refresh_token: current.refreshToken,
+        client_id: client.clientId,
+    });
+    const next = toStoredTokens(tokens);
+    // Some servers omit the rotated refresh token on error paths; keep the old one if so.
+    next.refreshToken = tokens.refresh_token ?? current.refreshToken;
+    await saveTokens(next);
+    return next.accessToken;
+}

package/dist/capacities.js

@@ -0,0 +1,70 @@
+import fetch from "node-fetch";
+import { API_BASE, getAccessToken, refreshAccessToken } from "./auth.js";
+import { loadTokens } from "./store.js";
+async function request(method, path, body, retry = true) {
+    const token = await getAccessToken();
+    const res = await fetch(`${API_BASE}${path}`, {
+        method,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+        },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    // Expired OAuth access token → refresh once and retry.
+    if (res.status === 401 && retry) {
+        const stored = await loadTokens();
+        if (stored?.authMethod === "oauth" && stored.refreshToken) {
+            await refreshAccessToken(stored);
+            return request(method, path, body, false);
+        }
+    }
+    // Rate limited → honor the RateLimit reset window once (draft-8 header, e.g. "limit=30, remaining=0, reset=12").
+    if (res.status === 429 && retry) {
+        const header = res.headers.get("ratelimit") ?? "";
+        const reset = /reset=(\d+)/.exec(header)?.[1];
+        const waitS = Math.min(reset ? parseInt(reset, 10) : 15, 60);
+        console.error(`Capacities rate limit hit; retrying in ${waitS}s…`);
+        await new Promise((r) => setTimeout(r, waitS * 1000));
+        return request(method, path, body, false);
+    }
+    return res;
+}
+async function throwApiError(res, context) {
+    let detail = "";
+    try {
+        const err = (await res.json());
+        detail = err.message ? ` — ${err.message}${err.code ? ` (${err.code})` : ""}` : "";
+    }
+    catch {
+        /* non-JSON body */
+    }
+    if (res.status === 401) {
+        throw new Error(`${context}: not authenticated${detail}. Run: caps-brief auth`);
+    }
+    if (res.status === 403) {
+        throw new Error(`${context}: forbidden${detail}. Does your token have the api:write scope?`);
+    }
+    throw new Error(`${context}: HTTP ${res.status}${detail}`);
+}
+/** Fetch the space bound to the current token — used to verify authentication. */
+export async function getSpace() {
+    const res = await request("GET", "/space");
+    if (!res.ok)
+        await throwApiError(res, "GET /space");
+    return (await res.json());
+}
+/**
+ * Append Markdown to a daily note via POST /blocks/daily-note/append
+ * (Capacities API 2.0; processed asynchronously server-side).
+ */
+export async function appendToDailyNote(markdown, options = {}) {
+    const body = { markdown };
+    if (options.date)
+        body.date = options.date;
+    if (options.noTimeStamp !== undefined)
+        body.noTimeStamp = options.noTimeStamp;
+    const res = await request("POST", "/blocks/daily-note/append", body);
+    if (!res.ok)
+        await throwApiError(res, "POST /blocks/daily-note/append");
+}

package/dist/cli.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+import { promises as fs } from "node:fs";
+import { Command } from "commander";
+import { oauthLogin, tokenLogin } from "./auth.js";
+import { appendToDailyNote, getSpace } from "./capacities.js";
+import { formatWithoutLlm, LlmTransientError, summarise } from "./llm.js";
+import { fetchAllSources } from "./sources.js";
+import { CONFIG_PATH, loadConfig, loadState, loadTokens, localDateString, saveConfig, saveState, TOKENS_PATH, } from "./store.js";
+const program = new Command();
+program
+    .name("caps-brief")
+    .description("Auto-populate your Capacities Daily Note with an AI morning briefing.")
+    .version("0.1.0");
+program
+    .command("auth")
+    .description("Sign in to Capacities (browser OAuth 2.1 PKCE flow, or --token for a personal API token)")
+    .option("--token <token>", "use a personal API token from Capacities → Settings → Capacities API")
+    .action(async (opts) => {
+    if (opts.token) {
+        await tokenLogin(opts.token);
+    }
+    else {
+        await oauthLogin();
+    }
+    try {
+        const space = await getSpace();
+        console.log(`Connected to space: "${space.title}" (${space.id})`);
+    }
+    catch (error) {
+        // Don't leave a credential on disk that the API just rejected.
+        await fs.rm(TOKENS_PATH, { force: true });
+        throw error;
+    }
+});
+program
+    .command("config")
+    .description("Manage caps-brief configuration (~/.caps-brief/config.json)")
+    .option("--add-rss <url>", "add an RSS/Atom feed URL")
+    .option("--remove-rss <url>", "remove a feed URL")
+    .option("--weather <location>", 'set the wttr.in weather location (e.g. "Singapore")')
+    .option("--list", "show the current configuration")
+    .action(async (opts) => {
+    const config = await loadConfig();
+    let changed = false;
+    if (opts.addRss) {
+        try {
+            new URL(opts.addRss);
+        }
+        catch {
+            throw new Error(`"${opts.addRss}" is not a valid URL.`);
+        }
+        if (config.rssFeeds.includes(opts.addRss)) {
+            console.log("Feed already configured.");
+        }
+        else {
+            config.rssFeeds.push(opts.addRss);
+            changed = true;
+            console.log(`Added feed: ${opts.addRss}`);
+        }
+    }
+    if (opts.removeRss) {
+        const before = config.rssFeeds.length;
+        config.rssFeeds = config.rssFeeds.filter((u) => u !== opts.removeRss);
+        changed = config.rssFeeds.length !== before;
+        console.log(changed ? `Removed feed: ${opts.removeRss}` : "Feed was not configured.");
+    }
+    if (opts.weather !== undefined) {
+        config.weatherLocation = opts.weather;
+        changed = true;
+        console.log(`Weather location set to: ${opts.weather}`);
+    }
+    if (changed)
+        await saveConfig(config);
+    if (opts.list || (!opts.addRss && !opts.removeRss && opts.weather === undefined)) {
+        console.log(`Config file: ${CONFIG_PATH}`);
+        console.log(JSON.stringify(config, null, 2));
+    }
+});
+program
+    .command("status")
+    .description("Show auth state, connected space, sources, and last run")
+    .action(async () => {
+    const [tokens, config, state] = await Promise.all([loadTokens(), loadConfig(), loadState()]);
+    if (!tokens) {
+        console.log("Auth:      ✖ not signed in — run: caps-brief auth");
+    }
+    else {
+        const method = tokens.authMethod === "oauth" ? "OAuth (auto-refreshing)" : "personal API token";
+        console.log(`Auth:      ✔ ${method}`);
+        try {
+            const space = await getSpace();
+            console.log(`Space:     "${space.title}" (${space.id})`);
+        }
+        catch (error) {
+            console.log(`Space:     ✖ credential check failed — ${error instanceof Error ? error.message : error}`);
+        }
+    }
+    console.log(`Claude:    ${process.env.ANTHROPIC_API_KEY ? "✔ ANTHROPIC_API_KEY is set" : "✖ ANTHROPIC_API_KEY not set (runs need --no-llm)"}`);
+    console.log(`Sources:   Hacker News top 10 (always on)`);
+    if (config.rssFeeds.length === 0) {
+        console.log("           no RSS feeds — add one: caps-brief config --add-rss <url>");
+    }
+    else {
+        for (const feed of config.rssFeeds)
+            console.log(`           RSS: ${feed}`);
+    }
+    console.log(`           Weather: ${config.weatherLocation || "(IP-based location)"}`);
+    console.log(`Last run:  ${state.lastRunDate ? `${state.lastRunDate}${state.lastRunUsedLlm === false ? " (plain digest)" : ""}` : "never"}`);
+});
+program
+    .command("run")
+    .description("Fetch sources, build the briefing, and append it to today's Capacities Daily Note")
+    .option("--dry-run", "print the briefing instead of writing to Capacities")
+    .option("--no-llm", "skip Claude summarisation; write a plain formatted digest")
+    .option("--date <iso-date>", "target daily note date (YYYY-MM-DD, defaults to today)")
+    .option("--no-timestamp", "omit the timestamp heading Capacities adds to appended blocks")
+    .option("--force", "write even if a briefing was already sent today")
+    .action(async (opts) => {
+    if (opts.date && !/^\d{4}-\d{2}-\d{2}$/.test(opts.date)) {
+        throw new Error(`--date must be YYYY-MM-DD (got "${opts.date}").`);
+    }
+    // Once-per-day guard so an over-eager cron/Task Scheduler can't spam the note.
+    const today = localDateString();
+    const state = await loadState();
+    if (!opts.dryRun && !opts.force && !opts.date && state.lastRunDate === today) {
+        console.log(`Already briefed today (${today}) — nothing written. Use --force to send another.`);
+        return;
+    }
+    const config = await loadConfig();
+    console.error("Fetching sources (Hacker News, RSS, weather)…");
+    const data = await fetchAllSources(config.rssFeeds, config.weatherLocation);
+    for (const w of data.warnings)
+        console.error(`⚠ ${w}`);
+    if (data.hackerNews.length === 0 && data.rss.length === 0 && !data.weather) {
+        throw new Error("All sources failed — refusing to write an empty briefing. Check your network.");
+    }
+    console.error(`Fetched: ${data.hackerNews.length} HN stories, ${data.rss.length} RSS items, weather ${data.weather ? "OK" : "unavailable"}.`);
+    let briefing;
+    let usedLlm = false;
+    if (opts.llm) {
+        console.error("Summarising with Claude (claude-haiku-4-5)…");
+        try {
+            briefing = await summarise(data);
+            usedLlm = true;
+        }
+        catch (error) {
+            if (error instanceof LlmTransientError) {
+                // Cron reliability beats purity: deliver the plain digest rather than nothing.
+                console.error(`⚠ ${error.message} Falling back to the plain digest for today.`);
+                briefing = formatWithoutLlm(data);
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    else {
+        briefing = formatWithoutLlm(data);
+    }
+    const content = `## ☀️ Morning Briefing\n\n${briefing}`;
+    if (opts.dryRun) {
+        console.log(content);
+        console.error("\n(dry run — nothing was written to Capacities)");
+        return;
+    }
+    console.error("Appending to your Capacities Daily Note…");
+    await appendToDailyNote(content, {
+        date: opts.date,
+        noTimeStamp: opts.timestamp ? undefined : true,
+    });
+    if (!opts.date) {
+        await saveState({ lastRunDate: today, lastRunUsedLlm: usedLlm });
+    }
+    const spaceTitle = await getSpace()
+        .then((s) => ` in "${s.title}"`)
+        .catch(() => "");
+    console.log(`✅ Briefing appended to ${opts.date ?? "today"}'s Daily Note${spaceTitle}.`);
+});
+program.parseAsync().catch((error) => {
+    console.error(`\n✖ ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+});

package/dist/llm.js

@@ -0,0 +1,104 @@
+import Anthropic from "@anthropic-ai/sdk";
+const MODEL = "claude-haiku-4-5";
+/** Setup problem (missing/invalid key) — the user must act; never silently degrade. */
+export class LlmConfigError extends Error {
+}
+/** Transient problem (rate limit, network, 5xx) — safe to fall back to the plain digest. */
+export class LlmTransientError extends Error {
+}
+const SYSTEM_PROMPT = `You write a concise morning briefing (about 120 words of prose, excluding links) for a personal knowledge base.
+Output Markdown with exactly these sections, in this order:
+
+### Top Stories
+2-4 sentences synthesizing the day's Hacker News front page: the big themes, not a list. Then the three most notable stories as a Markdown bullet list of [title](url) links.
+
+### RSS Highlights
+1-3 sentences on the user's subscribed feeds, plus up to three [title](url) bullet links. If no RSS items were provided, write "No feed items today." and nothing else in this section.
+
+### Weather
+One short line based on the provided weather string. If none was provided, write "Weather unavailable."
+
+Rules: no preamble, no closing remarks, no H1/H2 headings, keep links exactly as given, never invent stories or links.`;
+/** Summarise fetched sources into a briefing via Claude Haiku. Requires ANTHROPIC_API_KEY. */
+export async function summarise(data) {
+    if (!process.env.ANTHROPIC_API_KEY) {
+        throw new LlmConfigError("ANTHROPIC_API_KEY is not set. Export it (https://platform.claude.com) or run with --no-llm for an unsummarised briefing.");
+    }
+    const client = new Anthropic();
+    const payload = {
+        hackerNews: data.hackerNews.map((s) => ({
+            title: s.title,
+            url: s.url,
+            points: s.points,
+            comments: s.comments,
+        })),
+        rss: data.rss,
+        weather: data.weather,
+    };
+    try {
+        const response = await client.messages.create({
+            model: MODEL,
+            max_tokens: 1024,
+            system: SYSTEM_PROMPT,
+            messages: [
+                {
+                    role: "user",
+                    content: `Here is today's fetched data as JSON:\n\n${JSON.stringify(payload, null, 2)}`,
+                },
+            ],
+        });
+        const text = response.content
+            .filter((b) => b.type === "text")
+            .map((b) => b.text)
+            .join("\n")
+            .trim();
+        if (!text)
+            throw new LlmTransientError("Claude returned an empty briefing.");
+        return text;
+    }
+    catch (error) {
+        if (error instanceof Anthropic.AuthenticationError) {
+            throw new LlmConfigError("Anthropic rejected the API key (401). Check ANTHROPIC_API_KEY.");
+        }
+        if (error instanceof Anthropic.PermissionDeniedError) {
+            throw new LlmConfigError("Anthropic key lacks permission (403). Check your key/plan at platform.claude.com.");
+        }
+        if (error instanceof Anthropic.RateLimitError) {
+            throw new LlmTransientError("Anthropic rate limit hit (429).");
+        }
+        if (error instanceof Anthropic.APIConnectionError) {
+            throw new LlmTransientError("Could not reach the Anthropic API (network error).");
+        }
+        if (error instanceof Anthropic.APIError) {
+            const status = error.status ?? 0;
+            const message = `Anthropic API error ${status}: ${error.message}`;
+            throw status >= 500 ? new LlmTransientError(message) : new LlmConfigError(message);
+        }
+        throw error;
+    }
+}
+/** Deterministic briefing without an LLM — used by --no-llm and as an offline fallback. */
+export function formatWithoutLlm(data) {
+    const lines = [];
+    lines.push("### Top Stories");
+    if (data.hackerNews.length === 0) {
+        lines.push("Hacker News unavailable today.");
+    }
+    else {
+        for (const s of data.hackerNews.slice(0, 10)) {
+            lines.push(`- [${s.title}](${s.url}) — ${s.points} points, ${s.comments} comments`);
+        }
+    }
+    lines.push("", "### RSS Highlights");
+    if (data.rss.length === 0) {
+        lines.push("No feed items today.");
+    }
+    else {
+        for (const item of data.rss) {
+            lines.push(`- **${item.feedTitle}**: [${item.title}](${item.link})`);
+        }
+    }
+    lines.push("", "### Weather");
+    lines.push(data.weather ?? "Weather unavailable.");
+    return lines.join("\n");
+}

package/dist/sources.js

@@ -0,0 +1,142 @@
+import fetch from "node-fetch";
+import { XMLParser } from "fast-xml-parser";
+const HN_URL = "https://hn.algolia.com/api/v1/search?tags=front_page&hitsPerPage=10";
+const FETCH_TIMEOUT_MS = 20_000;
+const ITEMS_PER_FEED = 5;
+function withTimeout() {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    return { signal: controller.signal, done: () => clearTimeout(timer) };
+}
+export async function fetchHackerNews() {
+    const t = withTimeout();
+    try {
+        const res = await fetch(HN_URL, { signal: t.signal });
+        if (!res.ok)
+            throw new Error(`HN Algolia responded ${res.status}`);
+        const data = (await res.json());
+        return data.hits.map((h) => ({
+            title: h.title ?? "(untitled)",
+            url: h.url ?? `https://news.ycombinator.com/item?id=${h.objectID}`,
+            points: h.points ?? 0,
+            comments: h.num_comments ?? 0,
+        }));
+    }
+    finally {
+        t.done();
+    }
+}
+/** Feeds often double-encode entities; decode numeric and common named ones. */
+function decodeEntities(s) {
+    const named = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " };
+    return s
+        .replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(parseInt(d, 10)))
+        .replace(/&#x([0-9a-fA-F]+);/g, (_, h) => String.fromCodePoint(parseInt(h, 16)))
+        .replace(/&([a-z]+);/g, (m, name) => named[name] ?? m);
+}
+/** Normalize a parsed value that may be a string, a { "#text": ... } node, or a CDATA node. */
+function text(v) {
+    if (typeof v === "string")
+        return decodeEntities(v.trim());
+    if (typeof v === "number")
+        return String(v);
+    if (v && typeof v === "object") {
+        const o = v;
+        if (typeof o["#text"] === "string")
+            return decodeEntities(o["#text"].trim());
+        if (typeof o["__cdata"] === "string")
+            return decodeEntities(o["__cdata"].trim());
+    }
+    return "";
+}
+/** Atom links can be a single object or an array; prefer rel="alternate". */
+function atomLink(link) {
+    const links = Array.isArray(link) ? link : [link];
+    const objs = links
+        .filter((l) => !!l && typeof l === "object")
+        .map((l) => l);
+    const alt = objs.find((l) => !l["@_rel"] || l["@_rel"] === "alternate");
+    return alt?.["@_href"] ?? objs[0]?.["@_href"] ?? "";
+}
+/** Parse RSS 2.0 or Atom XML into items. Pure function — exported for tests. */
+export function parseFeed(xml, url) {
+    const parser = new XMLParser({ ignoreAttributes: false, cdataPropName: "__cdata" });
+    const doc = parser.parse(xml);
+    // RSS 2.0
+    if (doc.rss?.channel) {
+        const channel = doc.rss.channel;
+        const feedTitle = text(channel.title) || url;
+        const items = Array.isArray(channel.item) ? channel.item : channel.item ? [channel.item] : [];
+        return items.slice(0, ITEMS_PER_FEED).map((it) => ({
+            feedTitle,
+            title: text(it.title) || "(untitled)",
+            link: text(it.link),
+        }));
+    }
+    // Atom
+    if (doc.feed) {
+        const feedTitle = text(doc.feed.title) || url;
+        const entries = Array.isArray(doc.feed.entry) ? doc.feed.entry : doc.feed.entry ? [doc.feed.entry] : [];
+        return entries.slice(0, ITEMS_PER_FEED).map((e) => ({
+            feedTitle,
+            title: text(e.title) || "(untitled)",
+            link: atomLink(e.link),
+        }));
+    }
+    throw new Error("not a recognizable RSS 2.0 or Atom feed");
+}
+export async function fetchRssFeed(url) {
+    const t = withTimeout();
+    try {
+        const res = await fetch(url, {
+            signal: t.signal,
+            headers: { "User-Agent": "caps-brief/0.1 (+https://capacities.io daily briefing CLI)" },
+        });
+        if (!res.ok)
+            throw new Error(`feed responded ${res.status}`);
+        return parseFeed(await res.text(), url);
+    }
+    finally {
+        t.done();
+    }
+}
+export async function fetchWeather(location) {
+    const t = withTimeout();
+    try {
+        const url = `https://wttr.in/${encodeURIComponent(location ?? "")}?format=3`;
+        const res = await fetch(url, { signal: t.signal, headers: { "User-Agent": "curl/8" } });
+        if (!res.ok)
+            throw new Error(`wttr.in responded ${res.status}`);
+        const line = (await res.text()).trim();
+        if (!line || line.toLowerCase().includes("unknown location")) {
+            throw new Error(`wttr.in could not resolve location "${location}"`);
+        }
+        return line;
+    }
+    finally {
+        t.done();
+    }
+}
+/** Fetch all sources concurrently; individual failures become warnings, never a crash. */
+export async function fetchAllSources(rssFeeds, weatherLocation) {
+    const warnings = [];
+    const [hnResult, weatherResult, ...rssResults] = await Promise.allSettled([
+        fetchHackerNews(),
+        fetchWeather(weatherLocation),
+        ...rssFeeds.map((u) => fetchRssFeed(u)),
+    ]);
+    const hackerNews = hnResult.status === "fulfilled" ? hnResult.value : [];
+    if (hnResult.status === "rejected")
+        warnings.push(`Hacker News: ${hnResult.reason}`);
+    const weather = weatherResult.status === "fulfilled" ? weatherResult.value : null;
+    if (weatherResult.status === "rejected")
+        warnings.push(`Weather: ${weatherResult.reason}`);
+    const rss = [];
+    rssResults.forEach((r, i) => {
+        if (r.status === "fulfilled")
+            rss.push(...r.value);
+        else
+            warnings.push(`RSS ${rssFeeds[i]}: ${r.reason}`);
+    });
+    return { hackerNews, rss, weather, warnings };
+}

package/dist/store.js

@@ -0,0 +1,47 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export const CONFIG_DIR = path.join(os.homedir(), ".caps-brief");
+export const TOKENS_PATH = path.join(CONFIG_DIR, "tokens.json");
+export const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
+export const CLIENT_PATH = path.join(CONFIG_DIR, "client.json");
+export const STATE_PATH = path.join(CONFIG_DIR, "state.json");
+async function ensureDir() {
+    await fs.mkdir(CONFIG_DIR, { recursive: true });
+}
+async function readJson(file) {
+    try {
+        // Strip a UTF-8 BOM — Notepad adds one when users hand-edit config.json.
+        const raw = (await fs.readFile(file, "utf8")).replace(/^/, "");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function writeJson(file, data) {
+    await ensureDir();
+    await fs.writeFile(file, JSON.stringify(data, null, 2) + "\n", {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+}
+export const loadTokens = () => readJson(TOKENS_PATH);
+export const saveTokens = (t) => writeJson(TOKENS_PATH, t);
+export const loadClient = () => readJson(CLIENT_PATH);
+export const saveClient = (c) => writeJson(CLIENT_PATH, c);
+export async function loadConfig() {
+    return (await readJson(CONFIG_PATH)) ?? { rssFeeds: [] };
+}
+export const saveConfig = (c) => writeJson(CONFIG_PATH, c);
+export async function loadState() {
+    return (await readJson(STATE_PATH)) ?? {};
+}
+export const saveState = (s) => writeJson(STATE_PATH, s);
+/** Today's date in the machine's local timezone as YYYY-MM-DD. */
+export function localDateString(d = new Date()) {
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${y}-${m}-${day}`;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "caps-brief",
+  "version": "0.1.0",
+  "description": "Auto-populate your Capacities Daily Note with an AI morning briefing (Hacker News, RSS, weather) via the Capacities API 2.0.",
+  "type": "module",
+  "bin": {
+    "caps-brief": "./dist/cli.js"
+  },
+  "main": "./dist/cli.js",
+  "files": [
+    "dist",
+    "README.md",
+    "SETUP.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test test/parse.test.mjs",
+    "prepack": "npm run build"
+  },
+  "author": "Booyaka101",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Booyaka101/caps-brief.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Booyaka101/caps-brief/issues"
+  },
+  "homepage": "https://github.com/Booyaka101/caps-brief#readme",
+  "keywords": [
+    "capacities",
+    "daily-note",
+    "briefing",
+    "cli",
+    "oauth",
+    "pkce",
+    "claude",
+    "hacker-news",
+    "rss"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.111.0",
+    "commander": "^12.1.0",
+    "fast-xml-parser": "^5.10.1",
+    "node-fetch": "^3.3.2",
+    "open": "^10.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  }
+}