@letterstory/cli 0.5.0 → 0.5.1

package/README.md

@@ -273,19 +273,28 @@ letterstory seers apply --file seers.json --dry-run   # print the create/update/
 letterstory seers apply --file seers.json             # apply it
 ```
 
-Connections, and one honest gap:
+Connections — both providers connect headlessly (no browser required):
 
 ```bash
 letterstory seers connections                      # GitHub + Notion status
 letterstory seers connect github --token <pat>     # org-wide token; unlocks private repos
-letterstory seers connect notion                   # prints instructions — see below
+letterstory seers connect notion                   # no token: prints how to mint one + which pages to share
+letterstory seers connect notion --token ntn_xxx   # store a Notion internal-integration secret
 ```
 
-> **Known gaps.** Notion connects via browser OAuth in the app only — the CLI/API can
-> read connection status but cannot complete the OAuth flow. `seers run` executes
-> synchronously server-side (up to ~5 minutes for web-scan providers); there is no
-> start-then-poll variant yet. And `create`'s config takes raw JSON — `seers providers`
-> is the schema reference the server validates against.
+**Connecting Notion.** Notion uses an _internal integration_ (the direct analogue of a
+GitHub PAT), so it's fully scriptable:
+
+1. Create one at [notion.so/my-integrations](https://www.notion.so/my-integrations) → **New integration → Internal**, with the **Read content** capability.
+2. Copy the **Internal Integration Secret** (`ntn_…` / `secret_…`).
+3. In Notion, open each page/database the seer should watch → **••• → Connections →** add your integration. **A Notion integration only sees pages explicitly shared with it** — this step is required, or the seer connects but detects nothing.
+4. `letterstory seers connect notion --token ntn_…`
+
+The app's browser OAuth flow (Seers tab → Connect Notion) is an equivalent alternative, not a requirement.
+
+> **Remaining gap.** `seers run` executes synchronously server-side (up to ~5 minutes for
+> web-scan providers); there is no start-then-poll variant yet. And `create`'s config takes
+> raw JSON — `seers providers` is the schema reference the server validates against.
 
 Content templates (the compose structures seers bind via `config.template_key`):
 

package/lib/cli.mjs

@@ -35,7 +35,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.5.0";
+export const VERSION = "0.5.1";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value.
@@ -245,7 +245,8 @@ Seers (event-driven signals -> drafts):
   seers release <article-id> | seers discard <article-id>
   seers connections                                    GitHub/Notion connection status
   seers connect github --token <pat>                   Store an org-wide GitHub token
-  seers connect notion                                 (browser-only OAuth — prints instructions)
+  seers connect notion --token <secret>                Store a Notion internal-integration token
+  seers connect notion                                 (no token: prints how to mint one + share pages)
   seers export [--file <path>]                         Dump the org's seers as a manifest
   seers apply --file <path> [--dry-run]                Idempotent, name-keyed upsert from a manifest
                                                        (never deletes; --dry-run prints the plan)

package/lib/commands/seers.mjs

@@ -4,11 +4,11 @@
 // `seers export` (dump the org's seers as a manifest) and `seers apply` (idempotent,
 // name-keyed diff-then-upsert from a manifest, with --dry-run).
 //
-// Known surface gaps, stated here because this is where operators hit them:
-//   - Notion connects via browser OAuth in the app only. `seers connect notion`
-//     prints instructions; there is no headless flow.
-//   - `seers run` executes synchronously server-side (news/regulation web scans can
-//     take minutes) and spends model budget — it is usage-gated per org.
+// Connections are both headless: `seers connect github --token` (a PAT) and
+// `seers connect notion --token` (a Notion internal-integration secret; run
+// `seers connect notion` with no token for how to mint one and which pages to share).
+// One thing to know: `seers run` executes synchronously server-side (news/regulation
+// web scans can take minutes) and spends model budget — it is usage-gated per org.
 
 import { readFileSync, writeFileSync } from "node:fs";
 import { CliError } from "../client.mjs";
@@ -292,7 +292,7 @@ async function seersConnections(ctx) {
 			: `GitHub: not connected${r.github.configured ? " — connect with `seers connect github --token <pat>`" : " (token storage not configured on this deployment)"}`;
 		const notion = r.notion.connected
 			? `Notion: connected to ${r.notion.workspace_name} (${r.notion.connected_at})`
-			: "Notion: not connected — connect via browser in the app (Seers tab → Connect Notion); there is no headless flow";
+			: `Notion: not connected${r.notion.configured ? " — connect with `seers connect notion --token <secret>` (run `seers connect notion` for how to get one)" : " (token storage not configured on this deployment)"}`;
 		return `${gh}\n${notion}`;
 	});
 	return 0;
@@ -310,11 +310,29 @@ async function seersConnect(ctx) {
 		return 0;
 	}
 	if (which === "notion") {
-		// Deliberate gap: Notion's OAuth flow needs a browser session; the integrations
-		// surface can read status but can't complete the dance.
-		rest.io.log("Notion connects via browser OAuth and can't be completed from the CLI.");
-		rest.io.log(`Open ${rest.config.url.replace(/\/$/, "")}/seers and use "Connect Notion", then verify with:`);
-		rest.io.log(`  ${rest.bin} seers connections`);
+		const token = flagStr(rest.flags.token);
+		if (!token) {
+			// No token yet — print how to mint one and which pages to share. Notion
+			// internal integrations only see pages explicitly shared with them, so the
+			// share step is load-bearing, not optional.
+			rest.io.log("Connect Notion with an internal-integration secret (headless — no browser needed):");
+			rest.io.log("");
+			rest.io.log("  1. Go to https://www.notion.so/my-integrations → New integration → Internal.");
+			rest.io.log("  2. Give it the 'Read content' capability, then copy the Internal Integration Secret");
+			rest.io.log("     (starts with ntn_ or secret_).");
+			rest.io.log("  3. In Notion, open each page/database the seer should watch → ••• → Connections →");
+			rest.io.log("     add your integration. (An integration only sees pages shared with it.)");
+			rest.io.log(`  4. Run:  ${rest.bin} seers connect notion --token ntn_your_secret`);
+			rest.io.log("");
+			rest.io.log(
+				"The app's browser OAuth flow (Seers tab → Connect Notion) is an alternative, not a requirement."
+			);
+			return 0;
+		}
+		const result = await rest.client.callTool("set_notion_connection", { access_token: token });
+		ok(rest, `Notion connected${result.workspace_name ? ` to ${result.workspace_name}` : ""}.`);
+		ok(rest, "Reminder: the integration only watches pages you've shared with it in Notion.");
+		printResult(rest.io, rest.flags, result);
 		return 0;
 	}
 	throw new CliError(`Unknown connect target: ${which ?? "(none)"}. Try: github, notion`);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@letterstory/cli",
-	"version": "0.5.0",
+	"version": "0.5.1",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",