granola-toolkit 0.17.0 → 0.18.0

package/README.md

@@ -35,6 +35,7 @@ granola --help
 granola auth login
 granola meeting --help
 granola notes --help
+granola serve --help
 granola transcripts --help
 ```
 
@@ -47,6 +48,7 @@ vp pack
 node dist/cli.js --help
 node dist/cli.js meeting --help
 node dist/cli.js notes --help
+node dist/cli.js serve --help
 node dist/cli.js transcripts --help
 ```
 
@@ -89,6 +91,14 @@ granola meeting transcript 1234abcd --format json
 granola meeting export 1234abcd --format yaml
 ```
 
+Run the local API server:
+
+```bash
+granola serve
+granola serve --port 4096
+granola serve --hostname 0.0.0.0 --port 4096
+```
+
 ## How It Works
 
 ### Notes
@@ -167,6 +177,22 @@ The machine-readable `export` command includes:
 - structured note data plus rendered Markdown
 - structured transcript data plus rendered transcript text when available
 
+### Server
+
+`serve` starts a long-lived local `Granola Toolkit` server on one shared app instance.
+
+The initial server API includes:
+
+- `GET /health`
+- `GET /state`
+- `GET /events` for server-sent state updates
+- `GET /meetings`
+- `GET /meetings/:id`
+- `POST /exports/notes`
+- `POST /exports/transcripts`
+
+This is the foundation for the future `granola web` client and any attachable TUI flows.
+
 ## Auth
 
 If you do not want to keep passing `--supabase`, import the desktop app session once:

package/dist/cli.js

@@ -7,6 +7,7 @@ import { dirname, join } from "node:path";
 import { promisify } from "node:util";
 import { NodeHtmlMarkdown } from "node-html-markdown";
 import { createHash } from "node:crypto";
+import { createServer } from "node:http";
 //#region src/utils.ts
 const INVALID_FILENAME_CHARS = /[<>:"/\\|?*]/g;
 const CONTROL_CHARACTERS = /\p{Cc}/gu;
@@ -1517,6 +1518,7 @@ var GranolaApp = class {
 	#cacheResolved = false;
 	#granolaClient;
 	#documents;
+	#listeners = /* @__PURE__ */ new Set();
 	#state;
 	constructor(config, deps, options = {}) {
 		this.config = config;
@@ -1526,16 +1528,31 @@ var GranolaApp = class {
 	getState() {
 		return cloneState(this.#state);
 	}
+	subscribe(listener) {
+		this.#listeners.add(listener);
+		return () => {
+			this.#listeners.delete(listener);
+		};
+	}
 	setUiState(patch) {
 		this.#state.ui = {
 			...this.#state.ui,
 			...patch
 		};
+		this.emitStateUpdate();
 		return this.getState();
 	}
 	nowIso() {
 		return (this.deps.now ?? (() => /* @__PURE__ */ new Date()))().toISOString();
 	}
+	emitStateUpdate() {
+		const event = {
+			state: this.getState(),
+			timestamp: this.nowIso(),
+			type: "state.updated"
+		};
+		for (const listener of this.#listeners) listener(event);
+	}
 	async getGranolaClient() {
 		if (this.#granolaClient) return this.#granolaClient;
 		if (this.deps.granolaClient) {
@@ -1546,6 +1563,7 @@ var GranolaApp = class {
 		const runtime = await this.deps.createGranolaClient();
 		this.#granolaClient = runtime.client;
 		this.#state.auth = { ...runtime.auth };
+		this.emitStateUpdate();
 		return this.#granolaClient;
 	}
 	missingCacheError() {
@@ -1560,6 +1578,7 @@ var GranolaApp = class {
 			loaded: true,
 			loadedAt: this.nowIso()
 		};
+		this.emitStateUpdate();
 		return documents;
 	}
 	async loadCache(options = {}) {
@@ -1585,6 +1604,7 @@ var GranolaApp = class {
 			loadedAt: cacheData ? this.nowIso() : void 0,
 			transcriptCount: cacheData ? transcriptCount(cacheData) : 0
 		};
+		this.emitStateUpdate();
 		if (options.required && !cacheData) throw this.missingCacheError();
 		return cacheData;
 	}
@@ -1626,6 +1646,7 @@ var GranolaApp = class {
 			ranAt: this.nowIso(),
 			written
 		};
+		this.emitStateUpdate();
 		this.setUiState({ view: "notes-export" });
 		return {
 			documentCount: documents.length,
@@ -1647,6 +1668,7 @@ var GranolaApp = class {
 			ranAt: this.nowIso(),
 			written
 		};
+		this.emitStateUpdate();
 		this.setUiState({ view: "transcripts-export" });
 		return {
 			cacheData,
@@ -2010,6 +2032,250 @@ function resolveNoteFormat(value) {
 	}
 }
 //#endregion
+//#region src/server/http.ts
+function parseInteger(value) {
+	if (!value?.trim()) return;
+	if (!/^\d+$/.test(value)) throw new Error("invalid limit: expected a positive integer");
+	const parsed = Number(value);
+	if (!Number.isInteger(parsed) || parsed < 1) throw new Error("invalid limit: expected a positive integer");
+	return parsed;
+}
+function sendJson(response, body, init = {}) {
+	const payload = `${JSON.stringify(body, null, 2)}\n`;
+	response.writeHead(init.status ?? 200, {
+		"content-length": Buffer.byteLength(payload),
+		"content-type": "application/json; charset=utf-8"
+	});
+	response.end(payload);
+}
+function sendText(response, body, status = 200) {
+	response.writeHead(status, {
+		"content-length": Buffer.byteLength(body),
+		"content-type": "text/plain; charset=utf-8"
+	});
+	response.end(body);
+}
+async function readJsonBody(request) {
+	const chunks = [];
+	for await (const chunk of request) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+	if (chunks.length === 0) return {};
+	try {
+		const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("request body must be a JSON object");
+		return parsed;
+	} catch (error) {
+		throw new Error(error instanceof Error ? error.message : "failed to parse JSON body");
+	}
+}
+function formatSseEvent(event) {
+	return `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`;
+}
+function noteFormatFromBody(value) {
+	switch (value) {
+		case void 0:
+		case "markdown": return "markdown";
+		case "json":
+		case "raw":
+		case "yaml": return value;
+		default: throw new Error("invalid notes format: expected markdown, json, yaml, or raw");
+	}
+}
+function transcriptFormatFromBody(value) {
+	switch (value) {
+		case void 0:
+		case "text": return "text";
+		case "json":
+		case "raw":
+		case "yaml": return value;
+		default: throw new Error("invalid transcript format: expected text, json, yaml, or raw");
+	}
+}
+async function startGranolaServer(app, options = {}) {
+	const hostname = options.hostname ?? "127.0.0.1";
+	const port = options.port ?? 0;
+	const server = createServer(async (request, response) => {
+		const method = request.method ?? "GET";
+		const url = new URL(request.url ?? "/", `http://${hostname}`);
+		const path = url.pathname;
+		try {
+			if (method === "GET" && path === "/health") {
+				sendJson(response, {
+					ok: true,
+					service: "granola-toolkit",
+					version: app.config ? void 0 : void 0
+				});
+				return;
+			}
+			if (method === "GET" && path === "/state") {
+				sendJson(response, app.getState());
+				return;
+			}
+			if (method === "GET" && path === "/events") {
+				response.writeHead(200, {
+					"cache-control": "no-cache, no-transform",
+					connection: "keep-alive",
+					"content-type": "text/event-stream; charset=utf-8"
+				});
+				response.write(formatSseEvent({
+					state: app.getState(),
+					timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+					type: "state.updated"
+				}));
+				const unsubscribe = app.subscribe((event) => {
+					response.write(formatSseEvent(event));
+				});
+				request.on("close", () => {
+					unsubscribe();
+					response.end();
+				});
+				return;
+			}
+			if (method === "GET" && path === "/meetings") {
+				const limit = parseInteger(url.searchParams.get("limit"));
+				const search = url.searchParams.get("search")?.trim() || void 0;
+				sendJson(response, {
+					meetings: await app.listMeetings({
+						limit,
+						search
+					}),
+					search
+				});
+				return;
+			}
+			if (method === "GET" && path.startsWith("/meetings/")) {
+				const id = decodeURIComponent(path.slice(10));
+				if (!id) throw new Error("meeting id is required");
+				sendJson(response, await app.getMeeting(id, { requireCache: url.searchParams.get("includeTranscript") === "true" }));
+				return;
+			}
+			if (method === "POST" && path === "/exports/notes") {
+				const body = await readJsonBody(request);
+				sendJson(response, await app.exportNotes(noteFormatFromBody(body.format)), { status: 202 });
+				return;
+			}
+			if (method === "POST" && path === "/exports/transcripts") {
+				const body = await readJsonBody(request);
+				sendJson(response, await app.exportTranscripts(transcriptFormatFromBody(body.format)), { status: 202 });
+				return;
+			}
+			sendText(response, "Not found\n", 404);
+		} catch (error) {
+			sendJson(response, { error: error instanceof Error ? error.message : String(error) }, { status: 400 });
+		}
+	});
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(port, hostname, () => {
+			server.off("error", reject);
+			resolve();
+		});
+	});
+	const address = server.address();
+	if (!address || typeof address === "string") throw new Error("failed to resolve server address");
+	const resolved = address;
+	const url = new URL(`http://${hostname}:${resolved.port}`);
+	return {
+		app,
+		async close() {
+			await new Promise((resolve, reject) => {
+				server.close((error) => {
+					if (error) {
+						reject(error);
+						return;
+					}
+					resolve();
+				});
+			});
+		},
+		hostname,
+		port: resolved.port,
+		server,
+		url
+	};
+}
+//#endregion
+//#region src/commands/serve.ts
+function serveHelp() {
+	return `Granola serve
+
+Usage:
+  granola serve [options]
+
+Options:
+  --hostname <value>  Hostname to bind (default: 127.0.0.1)
+  --port <value>      Port to bind (default: 0 for any available port)
+  --cache <path>      Path to Granola cache JSON
+  --timeout <value>   Request timeout, e.g. 2m, 30s, 120000 (default: 2m)
+  --supabase <path>   Path to supabase.json
+  --debug             Enable debug logging
+  --config <path>     Path to .granola.toml
+  -h, --help          Show help
+`;
+}
+function parsePort(value) {
+	if (value === void 0) return;
+	if (typeof value !== "string" || !/^\d+$/.test(value)) throw new Error("invalid port: expected a non-negative integer");
+	const port = Number(value);
+	if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error("invalid port: expected a value between 0 and 65535");
+	return port;
+}
+const serveCommand = {
+	description: "Start a local Granola API server",
+	flags: {
+		cache: { type: "string" },
+		help: { type: "boolean" },
+		hostname: { type: "string" },
+		port: { type: "string" },
+		timeout: { type: "string" }
+	},
+	help: serveHelp,
+	name: "serve",
+	async run({ commandFlags, globalFlags }) {
+		const config = await loadConfig({
+			globalFlags,
+			subcommandFlags: commandFlags
+		});
+		debug(config.debug, "using config", config.configFileUsed ?? "(none)");
+		debug(config.debug, "supabase", config.supabase);
+		debug(config.debug, "cacheFile", config.transcripts.cacheFile || "(none)");
+		debug(config.debug, "timeoutMs", config.notes.timeoutMs);
+		const server = await startGranolaServer(await createGranolaApp(config, { surface: "server" }), {
+			hostname: typeof commandFlags.hostname === "string" && commandFlags.hostname.trim() ? commandFlags.hostname.trim() : "127.0.0.1",
+			port: parsePort(commandFlags.port)
+		});
+		console.log(`Granola server listening on ${server.url.href}`);
+		console.log("Endpoints:");
+		console.log("  GET  /health");
+		console.log("  GET  /state");
+		console.log("  GET  /events");
+		console.log("  GET  /meetings");
+		console.log("  GET  /meetings/:id");
+		console.log("  POST /exports/notes");
+		console.log("  POST /exports/transcripts");
+		await new Promise((resolve, reject) => {
+			let closing = false;
+			const close = async () => {
+				if (closing) return;
+				closing = true;
+				process.off("SIGINT", handleSignal);
+				process.off("SIGTERM", handleSignal);
+				try {
+					await server.close();
+					resolve();
+				} catch (error) {
+					reject(error);
+				}
+			};
+			const handleSignal = () => {
+				close();
+			};
+			process.on("SIGINT", handleSignal);
+			process.on("SIGTERM", handleSignal);
+		});
+		return 0;
+	}
+};
+//#endregion
 //#region src/commands/transcripts.ts
 function transcriptsHelp() {
 	return `Granola transcripts
@@ -2070,6 +2336,7 @@ const commands = [
 	authCommand,
 	meetingCommand,
 	notesCommand,
+	serveCommand,
 	transcriptsCommand
 ];
 const commandMap = new Map(commands.map((command) => [command.name, command]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "granola-toolkit",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Toolkit for exporting and working with Granola meetings, notes, and transcripts",
   "keywords": [
     "cli",