granola-toolkit 0.8.0 → 0.10.0

package/README.md

@@ -31,6 +31,8 @@ Installed CLI:
 
 ```bash
 granola --help
+granola auth login
+granola meeting --help
 granola notes --help
 granola transcripts --help
 ```
@@ -40,6 +42,7 @@ Local build:
 ```bash
 vp pack
 node dist/cli.js --help
+node dist/cli.js meeting --help
 node dist/cli.js notes --help
 node dist/cli.js transcripts --help
 ```
@@ -48,6 +51,7 @@ You can also use the package scripts:
 
 ```bash
 npm run build
+npm run start -- meeting --help
 npm run notes -- --help
 npm run transcripts -- --help
 ```
@@ -57,6 +61,9 @@ npm run transcripts -- --help
 Export notes:
 
 ```bash
+granola auth login
+granola notes
+
 node dist/cli.js notes --supabase "$HOME/Library/Application Support/Granola/supabase.json"
 node dist/cli.js notes --format json --output ./notes-json
 ```
@@ -68,6 +75,15 @@ node dist/cli.js transcripts --cache "$HOME/Library/Application Support/Granola/
 node dist/cli.js transcripts --format yaml --output ./transcripts-yaml
 ```
 
+Inspect individual meetings:
+
+```bash
+granola meeting list --limit 10
+granola meeting list --search planning
+granola meeting view 1234abcd
+granola meeting export 1234abcd --format yaml
+```
+
 ## How It Works
 
 ### Notes
@@ -76,7 +92,7 @@ node dist/cli.js transcripts --format yaml --output ./transcripts-yaml
 
 The flow is:
 
-1. read your local `supabase.json`
+1. read a stored Granola session, or fall back to your local `supabase.json`
 2. extract the WorkOS access token from it
 3. call Granola's paginated documents API
 4. normalise each document into a structured note export
@@ -117,6 +133,41 @@ Speaker labels are currently normalised to:
 
 Structured output formats are useful when you want to post-process exports in scripts instead of reading the default human-oriented Markdown or text files.
 
+### Meetings
+
+`meeting` combines the API-backed notes path with the local transcript cache so you can inspect one meeting at a time.
+
+The flow is:
+
+1. read a stored Granola session, or fall back to `supabase.json`
+2. fetch documents from Granola's API
+3. optionally load the local cache for transcript data
+4. resolve a meeting by full id or unique id prefix
+5. render either a list, a human-readable meeting view, or a machine-readable export bundle
+
+The human-readable `view` command shows:
+
+- meeting metadata
+- the selected notes content
+- transcript lines when the local cache is available
+
+The machine-readable `export` command includes:
+
+- a meeting summary
+- structured note data plus rendered Markdown
+- structured transcript data plus rendered transcript text when available
+
+## Auth
+
+If you do not want to keep passing `--supabase`, import the desktop app session once:
+
+```bash
+granola auth login
+granola auth status
+```
+
+That stores a reusable Granola session locally and lets `granola notes` use it directly. `granola auth logout` deletes the stored session.
+
 ### Incremental Writes
 
 Both commands keep a small hidden state file in the output directory to track:

package/dist/cli.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 import { existsSync } from "node:fs";
-import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
+import { execFile } from "node:child_process";
+import { mkdir, readFile, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
+import { promisify } from "node:util";
 import { createHash } from "node:crypto";
 //#region src/utils.ts
 const INVALID_FILENAME_CHARS = /[<>:"/\\|?*]/g;
@@ -162,16 +164,46 @@ function transcriptSpeakerLabel(segment) {
 }
 //#endregion
 //#region src/client/auth.ts
-function getAccessTokenFromSupabaseContents(supabaseContents) {
+const execFileAsync = promisify(execFile);
+const DEFAULT_CLIENT_ID = "client_GranolaMac";
+const KEYCHAIN_SERVICE_NAME = "com.granola.toolkit";
+const KEYCHAIN_ACCOUNT_NAME = "session";
+const WORKOS_AUTH_URL = "https://api.workos.com/user_management/authenticate";
+function numberValue(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function parseSessionRecord(record) {
+	const accessToken = stringValue(record.access_token);
+	if (!accessToken.trim()) return;
+	return {
+		accessToken,
+		clientId: stringValue(record.client_id) || DEFAULT_CLIENT_ID,
+		expiresIn: numberValue(record.expires_in),
+		externalId: stringValue(record.external_id) || void 0,
+		obtainedAt: stringValue(record.obtained_at) || void 0,
+		refreshToken: stringValue(record.refresh_token) || void 0,
+		sessionId: stringValue(record.session_id) || void 0,
+		signInMethod: stringValue(record.sign_in_method) || void 0,
+		tokenType: stringValue(record.token_type) || void 0
+	};
+}
+function parseNestedRecord(value) {
+	if (typeof value === "string") return parseJsonString(value);
+	return asRecord(value);
+}
+function getSessionFromSupabaseContents(supabaseContents) {
 	const wrapper = parseJsonString(supabaseContents);
 	if (!wrapper) throw new Error("failed to parse supabase.json");
-	const workosTokens = wrapper.workos_tokens;
-	let tokenPayload;
-	if (typeof workosTokens === "string") tokenPayload = parseJsonString(workosTokens);
-	else tokenPayload = asRecord(workosTokens);
-	const accessToken = tokenPayload ? stringValue(tokenPayload.access_token) : "";
-	if (!accessToken.trim()) throw new Error("access token not found in supabase.json");
-	return accessToken;
+	const workOsSession = parseSessionRecord(parseNestedRecord(wrapper.workos_tokens) ?? {});
+	if (workOsSession) return workOsSession;
+	const cognitoSession = parseSessionRecord(parseNestedRecord(wrapper.cognito_tokens) ?? {});
+	if (cognitoSession) return cognitoSession;
+	const legacySession = parseSessionRecord(wrapper);
+	if (legacySession) return legacySession;
+	throw new Error("access token not found in supabase.json");
+}
+function getAccessTokenFromSupabaseContents(supabaseContents) {
+	return getSessionFromSupabaseContents(supabaseContents).accessToken;
 }
 var SupabaseFileTokenSource = class {
 	constructor(filePath) {
@@ -181,11 +213,85 @@ var SupabaseFileTokenSource = class {
 		return getAccessTokenFromSupabaseContents(await readFile(this.filePath, "utf8"));
 	}
 };
+var SupabaseFileSessionSource = class {
+	constructor(filePath) {
+		this.filePath = filePath;
+	}
+	async loadSession() {
+		return getSessionFromSupabaseContents(await readFile(this.filePath, "utf8"));
+	}
+};
 var NoopTokenStore = class {
 	async clearToken() {}
 	async readToken() {}
 	async writeToken(_token) {}
 };
+var FileSessionStore = class {
+	constructor(filePath = defaultSessionFilePath()) {
+		this.filePath = filePath;
+	}
+	async clearSession() {
+		try {
+			await unlink(this.filePath);
+		} catch {}
+	}
+	async readSession() {
+		try {
+			const parsed = parseJsonString(await readFile(this.filePath, "utf8"));
+			return parsed?.accessToken ? parsed : void 0;
+		} catch {
+			return;
+		}
+	}
+	async writeSession(session) {
+		await mkdir(dirname(this.filePath), { recursive: true });
+		await writeFile(this.filePath, `${JSON.stringify(session, null, 2)}\n`, {
+			encoding: "utf8",
+			mode: 384
+		});
+	}
+};
+var KeychainSessionStore = class {
+	async clearSession() {
+		try {
+			await execFileAsync("security", [
+				"delete-generic-password",
+				"-s",
+				KEYCHAIN_SERVICE_NAME,
+				"-a",
+				KEYCHAIN_ACCOUNT_NAME
+			]);
+		} catch {}
+	}
+	async readSession() {
+		try {
+			const { stdout } = await execFileAsync("security", [
+				"find-generic-password",
+				"-s",
+				KEYCHAIN_SERVICE_NAME,
+				"-a",
+				KEYCHAIN_ACCOUNT_NAME,
+				"-w"
+			]);
+			const parsed = parseJsonString(stdout.trim());
+			return parsed?.accessToken ? parsed : void 0;
+		} catch {
+			return;
+		}
+	}
+	async writeSession(session) {
+		await execFileAsync("security", [
+			"add-generic-password",
+			"-U",
+			"-s",
+			KEYCHAIN_SERVICE_NAME,
+			"-a",
+			KEYCHAIN_ACCOUNT_NAME,
+			"-w",
+			JSON.stringify(session)
+		]);
+	}
+};
 var CachedTokenProvider = class {
 	#token;
 	constructor(source, store = new NoopTokenStore()) {
@@ -209,6 +315,189 @@ var CachedTokenProvider = class {
 		await this.store.clearToken();
 	}
 };
+var StoredSessionTokenProvider = class {
+	#session;
+	constructor(store, options = {}) {
+		this.store = store;
+		this.options = options;
+	}
+	async loadSession() {
+		if (this.#session) return this.#session;
+		const storedSession = await this.store.readSession();
+		if (storedSession?.accessToken.trim()) {
+			this.#session = storedSession;
+			return storedSession;
+		}
+		if (!this.options.source) throw new Error("no stored Granola session found");
+		const sourcedSession = await this.options.source.loadSession();
+		this.#session = sourcedSession;
+		return sourcedSession;
+	}
+	async getAccessToken() {
+		return (await this.loadSession()).accessToken;
+	}
+	async invalidate() {
+		const session = await this.loadSession().catch(() => void 0);
+		if (session?.refreshToken && session.clientId) {
+			const refreshedSession = await refreshGranolaSession(session, this.options.fetchImpl);
+			this.#session = refreshedSession;
+			await this.store.writeSession(refreshedSession);
+			return;
+		}
+		if (this.options.source) {
+			this.#session = await this.options.source.loadSession();
+			return;
+		}
+		this.#session = void 0;
+		await this.store.clearSession();
+	}
+};
+async function refreshGranolaSession(session, fetchImpl = fetch) {
+	if (!session.refreshToken?.trim()) throw new Error("refresh token not available");
+	const response = await fetchImpl(WORKOS_AUTH_URL, {
+		body: JSON.stringify({
+			client_id: session.clientId,
+			grant_type: "refresh_token",
+			refresh_token: session.refreshToken
+		}),
+		headers: { "Content-Type": "application/json" },
+		method: "POST"
+	});
+	if (!response.ok) throw new Error(`failed to refresh session: ${response.status} ${response.statusText}`);
+	const refreshed = parseSessionRecord(await response.json());
+	if (!refreshed) throw new Error("failed to parse refreshed session");
+	return {
+		...session,
+		...refreshed,
+		clientId: refreshed.clientId || session.clientId,
+		obtainedAt: refreshed.obtainedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+		refreshToken: refreshed.refreshToken ?? session.refreshToken
+	};
+}
+function defaultSessionFilePath() {
+	const home = homedir();
+	return platform() === "darwin" ? join(home, "Library", "Application Support", "granola-toolkit", "session.json") : join(home, ".config", "granola-toolkit", "session.json");
+}
+function createDefaultSessionStore() {
+	return platform() === "darwin" ? new KeychainSessionStore() : new FileSessionStore();
+}
+//#endregion
+//#region src/commands/auth.ts
+function authHelp() {
+	return `Granola auth
+
+Usage:
+  granola auth <login|status|logout>
+
+Subcommands:
+  login               Import credentials from the Granola desktop app
+  status              Show whether a stored Granola session is available
+  logout              Delete the stored Granola session
+
+Options:
+  --supabase <path>   Path to supabase.json for auth login
+  -h, --help          Show help
+`;
+}
+const authCommand = {
+	description: "Manage stored Granola sessions",
+	flags: { help: { type: "boolean" } },
+	help: authHelp,
+	name: "auth",
+	async run({ commandArgs, globalFlags }) {
+		const [action] = commandArgs;
+		switch (action) {
+			case "login": return await login(globalFlags.supabase);
+			case "logout": return await logout();
+			case "status": return await status();
+			case void 0:
+				console.log(authHelp());
+				return 1;
+			default: throw new Error("invalid auth command: expected login, status, or logout");
+		}
+	}
+};
+async function login(supabaseFlag) {
+	const supabasePath = typeof supabaseFlag === "string" && supabaseFlag.trim() || firstExistingPath(granolaSupabaseCandidates());
+	if (!supabasePath) throw new Error(`supabase.json not found. Pass --supabase or create .granola.toml. Expected locations include: ${granolaSupabaseCandidates().join(", ")}`);
+	if (!existsSync(supabasePath)) throw new Error(`supabase.json not found: ${supabasePath}`);
+	const sessionStore = createDefaultSessionStore();
+	const session = await new SupabaseFileSessionSource(supabasePath).loadSession();
+	await sessionStore.writeSession(session);
+	console.log(`Imported Granola session from ${supabasePath}`);
+	return 0;
+}
+async function status() {
+	const session = await createDefaultSessionStore().readSession();
+	if (!session) {
+		console.log("No stored Granola session");
+		return 1;
+	}
+	console.log("Stored Granola session");
+	console.log(`Client ID: ${session.clientId}`);
+	console.log(`Refresh token: ${session.refreshToken ? "available" : "missing"}`);
+	console.log(`Sign-in method: ${session.signInMethod ?? "unknown"}`);
+	return 0;
+}
+async function logout() {
+	await createDefaultSessionStore().clearSession();
+	console.log("Stored Granola session deleted");
+	return 0;
+}
+//#endregion
+//#region src/cache.ts
+function parseCacheDocument(id, value) {
+	const record = asRecord(value);
+	if (!record) return;
+	return {
+		createdAt: stringValue(record.created_at),
+		id,
+		title: stringValue(record.title),
+		updatedAt: stringValue(record.updated_at)
+	};
+}
+function parseTranscriptSegments(value) {
+	if (!Array.isArray(value)) return;
+	return value.flatMap((segment) => {
+		const record = asRecord(segment);
+		if (!record) return [];
+		return [{
+			documentId: stringValue(record.document_id),
+			endTimestamp: stringValue(record.end_timestamp),
+			id: stringValue(record.id),
+			isFinal: Boolean(record.is_final),
+			source: stringValue(record.source),
+			startTimestamp: stringValue(record.start_timestamp),
+			text: stringValue(record.text)
+		}];
+	});
+}
+function parseCacheContents(contents) {
+	const outer = parseJsonString(contents);
+	if (!outer) throw new Error("failed to parse cache JSON");
+	const rawCache = outer.cache;
+	let cachePayload;
+	if (typeof rawCache === "string") cachePayload = parseJsonString(rawCache);
+	else cachePayload = asRecord(rawCache);
+	const state = cachePayload ? asRecord(cachePayload.state) : void 0;
+	if (!state) throw new Error("failed to parse cache state");
+	const rawDocuments = asRecord(state.documents) ?? {};
+	const rawTranscripts = asRecord(state.transcripts) ?? {};
+	const documents = {};
+	for (const [id, rawDocument] of Object.entries(rawDocuments)) {
+		const document = parseCacheDocument(id, rawDocument);
+		if (document) documents[id] = document;
+	}
+	const transcripts = {};
+	for (const [id, rawTranscript] of Object.entries(rawTranscripts)) {
+		const segments = parseTranscriptSegments(rawTranscript);
+		if (segments) transcripts[id] = segments;
+	}
+	return {
+		documents,
+		transcripts
+	};
+}
 //#endregion
 //#region src/client/parsers.ts
 function parseProseMirrorDoc(value, options = {}) {
@@ -348,6 +637,22 @@ var AuthenticatedHttpClient = class {
 	}
 };
 //#endregion
+//#region src/client/default.ts
+async function createDefaultGranolaApiClient(config, logger = console) {
+	const sessionStore = createDefaultSessionStore();
+	const storedSession = await sessionStore.readSession();
+	if (!storedSession && !config.supabase) throw new Error(`supabase.json not found. Pass --supabase or create .granola.toml. Expected locations include: ${granolaSupabaseCandidates().join(", ")}`);
+	if (!storedSession && config.supabase && !existsSync(config.supabase)) throw new Error(`supabase.json not found: ${config.supabase}`);
+	return new GranolaApiClient(new AuthenticatedHttpClient({
+		logger,
+		tokenProvider: storedSession ? new StoredSessionTokenProvider(sessionStore, { source: config.supabase && existsSync(config.supabase) ? new SupabaseFileSessionSource(config.supabase) : void 0 }) : new CachedTokenProvider(new SupabaseFileTokenSource(config.supabase), new NoopTokenStore())
+	}));
+}
+async function loadOptionalGranolaCache(cacheFile) {
+	if (!cacheFile || !existsSync(cacheFile)) return;
+	return parseCacheContents(await readFile(cacheFile, "utf8"));
+}
+//#endregion
 //#region src/config.ts
 function pickString(value) {
 	return typeof value === "string" && value.trim() ? value.trim() : void 0;
@@ -782,129 +1087,6 @@ async function writeNotes(documents, outputDir, format = "markdown") {
 	});
 }
 //#endregion
-//#region src/commands/shared.ts
-function debug(enabled, ...values) {
-	if (enabled) console.error("[debug]", ...values);
-}
-//#endregion
-//#region src/commands/notes.ts
-function notesHelp() {
-	return `Granola notes
-
-Usage:
-  granola notes [options]
-
-Options:
-  --format <value>    Output format: markdown, json, yaml, raw (default: markdown)
-  --output <path>     Output directory for note files (default: ./notes)
-  --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
-`;
-}
-const notesCommand = {
-	description: "Export Granola notes",
-	flags: {
-		format: { type: "string" },
-		help: { type: "boolean" },
-		output: { type: "string" },
-		timeout: { type: "string" }
-	},
-	help: notesHelp,
-	name: "notes",
-	async run({ commandFlags, globalFlags }) {
-		const config = await loadConfig({
-			globalFlags,
-			subcommandFlags: commandFlags
-		});
-		if (!config.supabase) throw new Error(`supabase.json not found. Pass --supabase or create .granola.toml. Expected locations include: ${granolaSupabaseCandidates().join(", ")}`);
-		if (!existsSync(config.supabase)) throw new Error(`supabase.json not found: ${config.supabase}`);
-		debug(config.debug, "using config", config.configFileUsed ?? "(none)");
-		debug(config.debug, "supabase", config.supabase);
-		debug(config.debug, "timeoutMs", config.notes.timeoutMs);
-		debug(config.debug, "output", config.notes.output);
-		const format = resolveNoteFormat(commandFlags.format);
-		debug(config.debug, "format", format);
-		console.log("Fetching documents from Granola API...");
-		const tokenProvider = new CachedTokenProvider(new SupabaseFileTokenSource(config.supabase), new NoopTokenStore());
-		const documents = await new GranolaApiClient(new AuthenticatedHttpClient({
-			logger: console,
-			tokenProvider
-		})).listDocuments({ timeoutMs: config.notes.timeoutMs });
-		console.log(`Exporting ${documents.length} notes to ${config.notes.output}...`);
-		const written = await writeNotes(documents, config.notes.output, format);
-		console.log("✓ Export completed successfully");
-		debug(config.debug, "notes written", written);
-		return 0;
-	}
-};
-function resolveNoteFormat(value) {
-	switch (value) {
-		case void 0: return "markdown";
-		case "json":
-		case "markdown":
-		case "raw":
-		case "yaml": return value;
-		default: throw new Error("invalid notes format: expected markdown, json, yaml, or raw");
-	}
-}
-//#endregion
-//#region src/cache.ts
-function parseCacheDocument(id, value) {
-	const record = asRecord(value);
-	if (!record) return;
-	return {
-		createdAt: stringValue(record.created_at),
-		id,
-		title: stringValue(record.title),
-		updatedAt: stringValue(record.updated_at)
-	};
-}
-function parseTranscriptSegments(value) {
-	if (!Array.isArray(value)) return;
-	return value.flatMap((segment) => {
-		const record = asRecord(segment);
-		if (!record) return [];
-		return [{
-			documentId: stringValue(record.document_id),
-			endTimestamp: stringValue(record.end_timestamp),
-			id: stringValue(record.id),
-			isFinal: Boolean(record.is_final),
-			source: stringValue(record.source),
-			startTimestamp: stringValue(record.start_timestamp),
-			text: stringValue(record.text)
-		}];
-	});
-}
-function parseCacheContents(contents) {
-	const outer = parseJsonString(contents);
-	if (!outer) throw new Error("failed to parse cache JSON");
-	const rawCache = outer.cache;
-	let cachePayload;
-	if (typeof rawCache === "string") cachePayload = parseJsonString(rawCache);
-	else cachePayload = asRecord(rawCache);
-	const state = cachePayload ? asRecord(cachePayload.state) : void 0;
-	if (!state) throw new Error("failed to parse cache state");
-	const rawDocuments = asRecord(state.documents) ?? {};
-	const rawTranscripts = asRecord(state.transcripts) ?? {};
-	const documents = {};
-	for (const [id, rawDocument] of Object.entries(rawDocuments)) {
-		const document = parseCacheDocument(id, rawDocument);
-		if (document) documents[id] = document;
-	}
-	const transcripts = {};
-	for (const [id, rawTranscript] of Object.entries(rawTranscripts)) {
-		const segments = parseTranscriptSegments(rawTranscript);
-		if (segments) transcripts[id] = segments;
-	}
-	return {
-		documents,
-		transcripts
-	};
-}
-//#endregion
 //#region src/transcripts.ts
 function transcriptSegmentKey(segment) {
 	if (segment.id) return `id:${segment.id}`;
@@ -937,7 +1119,9 @@ function normaliseTranscriptSegments(segments) {
 		const current = selected.get(key);
 		selected.set(key, preferredTranscriptSegment(current, segment));
 	}
-	return [...selected.values()].sort(compareTranscriptSegments);
+	const resolved = [...selected.values()].sort(compareTranscriptSegments);
+	if (resolved.some((segment) => segment.isFinal)) return resolved.filter((segment) => segment.isFinal);
+	return resolved;
 }
 function buildTranscriptExport(document, segments, rawSegments = segments) {
 	const renderedSegments = segments.map((segment) => ({
@@ -1038,6 +1222,398 @@ async function writeTranscripts(cacheData, outputDir, format = "text") {
 	});
 }
 //#endregion
+//#region src/meetings.ts
+function parseTimestamp(value) {
+	if (!value.trim()) return;
+	const timestamp = Date.parse(value);
+	return Number.isNaN(timestamp) ? void 0 : timestamp;
+}
+function compareTimestampsDescending(left, right) {
+	const leftTimestamp = parseTimestamp(left);
+	const rightTimestamp = parseTimestamp(right);
+	if (leftTimestamp != null && rightTimestamp != null) return rightTimestamp - leftTimestamp;
+	if (leftTimestamp != null) return -1;
+	if (rightTimestamp != null) return 1;
+	return compareStrings(right, left);
+}
+function compareMeetingDocuments(left, right) {
+	return compareTimestampsDescending(latestDocumentTimestamp(left), latestDocumentTimestamp(right)) || compareTimestampsDescending(left.createdAt, right.createdAt) || compareStrings(left.title || left.id, right.title || right.id) || compareStrings(left.id, right.id);
+}
+function serialiseNote(note) {
+	return {
+		content: note.content,
+		contentSource: note.contentSource,
+		createdAt: note.createdAt,
+		id: note.id,
+		tags: [...note.tags],
+		title: note.title,
+		updatedAt: note.updatedAt
+	};
+}
+function serialiseTranscript(transcript) {
+	return {
+		createdAt: transcript.createdAt,
+		id: transcript.id,
+		segments: transcript.segments.map((segment) => ({ ...segment })),
+		title: transcript.title,
+		updatedAt: transcript.updatedAt
+	};
+}
+function cacheDocumentForMeeting(document, cacheData) {
+	return cacheData?.documents[document.id] ?? {
+		createdAt: document.createdAt,
+		id: document.id,
+		title: document.title,
+		updatedAt: latestDocumentTimestamp(document)
+	};
+}
+function buildMeetingTranscript(document, cacheData) {
+	if (!cacheData) return {
+		loaded: false,
+		segmentCount: 0,
+		transcript: null,
+		transcriptText: null
+	};
+	const rawSegments = cacheData.transcripts[document.id] ?? [];
+	const normalisedSegments = normaliseTranscriptSegments(rawSegments);
+	if (normalisedSegments.length === 0) return {
+		loaded: true,
+		segmentCount: 0,
+		transcript: null,
+		transcriptText: null
+	};
+	const transcript = buildTranscriptExport(cacheDocumentForMeeting(document, cacheData), normalisedSegments, rawSegments);
+	return {
+		loaded: true,
+		segmentCount: transcript.segments.length,
+		transcript: serialiseTranscript(transcript),
+		transcriptText: renderTranscriptExport(transcript, "text")
+	};
+}
+function matchesMeetingSearch(document, search) {
+	const query = search.trim().toLowerCase();
+	if (!query) return true;
+	return [
+		document.id,
+		document.title,
+		...document.tags
+	].some((value) => value.toLowerCase().includes(query));
+}
+function truncate(value, width) {
+	if (value.length <= width) return value.padEnd(width);
+	return `${value.slice(0, Math.max(0, width - 1))}…`;
+}
+function formatMeetingDate(value) {
+	return value.trim().slice(0, 10) || "-";
+}
+function formatTranscriptStatus(meeting) {
+	if (!meeting.transcriptLoaded) return "n/a";
+	if (meeting.transcriptSegmentCount === 0) return "none";
+	return String(meeting.transcriptSegmentCount);
+}
+function formatTranscriptLines(transcript) {
+	if (!transcript || transcript.segments.length === 0) return "";
+	return transcript.segments.map((segment) => `[${formatTimestampForTranscript(segment.startTimestamp)}] ${segment.speaker}: ${segment.text}`).join("\n");
+}
+function buildMeetingSummary(document, cacheData) {
+	const note = buildNoteExport(document);
+	const transcript = buildMeetingTranscript(document, cacheData);
+	return {
+		createdAt: document.createdAt,
+		id: document.id,
+		noteContentSource: note.contentSource,
+		tags: [...document.tags],
+		title: document.title,
+		transcriptLoaded: transcript.loaded,
+		transcriptSegmentCount: transcript.segmentCount,
+		updatedAt: latestDocumentTimestamp(document)
+	};
+}
+function buildMeetingRecord(document, cacheData) {
+	const note = buildNoteExport(document);
+	const transcript = buildMeetingTranscript(document, cacheData);
+	return {
+		meeting: {
+			createdAt: document.createdAt,
+			id: document.id,
+			noteContentSource: note.contentSource,
+			tags: [...document.tags],
+			title: document.title,
+			transcriptLoaded: transcript.loaded,
+			transcriptSegmentCount: transcript.segmentCount,
+			updatedAt: latestDocumentTimestamp(document)
+		},
+		note: serialiseNote(note),
+		noteMarkdown: renderNoteExport(note, "markdown"),
+		transcript: transcript.transcript,
+		transcriptText: transcript.transcriptText
+	};
+}
+function listMeetings(documents, options = {}) {
+	const limit = options.limit ?? 20;
+	return documents.filter((document) => options.search ? matchesMeetingSearch(document, options.search) : true).sort(compareMeetingDocuments).slice(0, limit).map((document) => buildMeetingSummary(document, options.cacheData));
+}
+function resolveMeeting(documents, id) {
+	const exactMatch = documents.find((document) => document.id === id);
+	if (exactMatch) return exactMatch;
+	const matches = documents.filter((document) => document.id.startsWith(id));
+	if (matches.length === 1) return matches[0];
+	if (matches.length > 1) {
+		const sample = matches.slice(0, 5).map((document) => document.id.slice(0, 8)).join(", ");
+		throw new Error(`ambiguous meeting id: ${id} matches ${matches.length} meetings (${sample})`);
+	}
+	throw new Error(`meeting not found: ${id}`);
+}
+function renderMeetingList(meetings, format = "text") {
+	switch (format) {
+		case "json": return toJson(meetings);
+		case "yaml": return toYaml(meetings);
+		case "text": break;
+	}
+	if (meetings.length === 0) return "No meetings found\n";
+	const lines = [`${"ID".padEnd(10)} ${"DATE".padEnd(10)} ${"TITLE".padEnd(42)} ${"NOTE".padEnd(18)} TRANSCRIPT`, `${"-".repeat(10)} ${"-".repeat(10)} ${"-".repeat(42)} ${"-".repeat(18)} ${"-".repeat(10)}`];
+	for (const meeting of meetings) lines.push([
+		meeting.id.slice(0, 8).padEnd(10),
+		formatMeetingDate(meeting.updatedAt || meeting.createdAt).padEnd(10),
+		truncate(meeting.title || meeting.id, 42),
+		truncate(meeting.noteContentSource, 18),
+		formatTranscriptStatus(meeting)
+	].join(" "));
+	return `${lines.join("\n").trimEnd()}\n`;
+}
+function renderMeetingView(record, format = "text") {
+	switch (format) {
+		case "json": return toJson(record);
+		case "yaml": return toYaml(record);
+		case "text": break;
+	}
+	const tags = record.meeting.tags.length > 0 ? record.meeting.tags.join(", ") : "(none)";
+	const transcriptStatus = !record.meeting.transcriptLoaded ? "cache not loaded" : record.meeting.transcriptSegmentCount === 0 ? "no transcript segments" : `${record.meeting.transcriptSegmentCount} segment(s)`;
+	return `${[
+		`# ${record.meeting.title || record.meeting.id}`,
+		"",
+		`ID: ${record.meeting.id}`,
+		`Created: ${record.meeting.createdAt || "-"}`,
+		`Updated: ${record.meeting.updatedAt || "-"}`,
+		`Tags: ${tags}`,
+		`Note source: ${record.meeting.noteContentSource}`,
+		`Transcript: ${transcriptStatus}`,
+		"",
+		"## Notes",
+		"",
+		record.note.content.trim() || "(no notes)",
+		"",
+		"## Transcript",
+		"",
+		formatTranscriptLines(record.transcript) || (record.meeting.transcriptLoaded ? "(no transcript segments)" : "(Granola cache not loaded)"),
+		""
+	].join("\n").trimEnd()}\n`;
+}
+function renderMeetingExport(record, format = "json") {
+	switch (format) {
+		case "json": return toJson(record);
+		case "yaml": return toYaml(record);
+	}
+}
+//#endregion
+//#region src/commands/shared.ts
+function debug(enabled, ...values) {
+	if (enabled) console.error("[debug]", ...values);
+}
+//#endregion
+//#region src/commands/meeting.ts
+function meetingHelp() {
+	return `Granola meeting
+
+Usage:
+  granola meeting <list|view|export> [options]
+
+Subcommands:
+  list                List meetings from the Granola API
+  view <id>           Show a single meeting with notes and transcript text
+  export <id>         Export a single meeting as JSON or YAML
+
+Options:
+  --cache <path>      Path to Granola cache JSON for transcript data
+  --format <value>    list/view: text, json, yaml; export: json, yaml
+  --limit <n>         Number of meetings for list (default: 20)
+  --search <query>    Filter list by title, id, or tag
+  --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 resolveListFormat(value) {
+	switch (value) {
+		case void 0: return "text";
+		case "json":
+		case "text":
+		case "yaml": return value;
+		default: throw new Error("invalid meeting format: expected text, json, or yaml");
+	}
+}
+function resolveViewFormat(value) {
+	switch (value) {
+		case void 0: return "text";
+		case "json":
+		case "text":
+		case "yaml": return value;
+		default: throw new Error("invalid meeting format: expected text, json, or yaml");
+	}
+}
+function resolveExportFormat(value) {
+	switch (value) {
+		case void 0: return "json";
+		case "json":
+		case "yaml": return value;
+		default: throw new Error("invalid meeting export format: expected json or yaml");
+	}
+}
+function parseLimit(value) {
+	if (value === void 0) return 20;
+	if (typeof value !== "string" || !/^\d+$/.test(value)) throw new Error("invalid meeting limit: expected a positive integer");
+	const limit = Number(value);
+	if (!Number.isInteger(limit) || limit < 1) throw new Error("invalid meeting limit: expected a positive integer");
+	return limit;
+}
+const meetingCommand = {
+	description: "Inspect and export individual Granola meetings",
+	flags: {
+		cache: { type: "string" },
+		format: { type: "string" },
+		help: { type: "boolean" },
+		limit: { type: "string" },
+		search: { type: "string" },
+		timeout: { type: "string" }
+	},
+	help: meetingHelp,
+	name: "meeting",
+	async run({ commandArgs, commandFlags, globalFlags }) {
+		const [action, id] = commandArgs;
+		switch (action) {
+			case "list": return await list(commandFlags, globalFlags);
+			case "view":
+				if (!id) throw new Error("meeting view requires an id");
+				return await view(id, commandFlags, globalFlags);
+			case "export":
+				if (!id) throw new Error("meeting export requires an id");
+				return await exportMeeting(id, commandFlags, globalFlags);
+			case void 0:
+				console.log(meetingHelp());
+				return 1;
+			default: throw new Error("invalid meeting command: expected list, view, or export");
+		}
+	}
+};
+async function loadMeetingData(commandFlags, globalFlags) {
+	const config = await loadConfig({
+		globalFlags,
+		subcommandFlags: commandFlags
+	});
+	if (config.transcripts.cacheFile && !existsSync(config.transcripts.cacheFile)) throw new Error(`Granola cache file not found: ${config.transcripts.cacheFile}`);
+	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 granolaClient = await createDefaultGranolaApiClient(config);
+	return {
+		cacheData: await loadOptionalGranolaCache(config.transcripts.cacheFile),
+		config,
+		granolaClient
+	};
+}
+async function list(commandFlags, globalFlags) {
+	const format = resolveListFormat(commandFlags.format);
+	const limit = parseLimit(commandFlags.limit);
+	const search = typeof commandFlags.search === "string" ? commandFlags.search : void 0;
+	const { cacheData, config, granolaClient } = await loadMeetingData(commandFlags, globalFlags);
+	console.log("Fetching meetings from Granola API...");
+	const meetings = listMeetings(await granolaClient.listDocuments({ timeoutMs: config.notes.timeoutMs }), {
+		cacheData,
+		limit,
+		search
+	});
+	console.log(renderMeetingList(meetings, format).trimEnd());
+	return 0;
+}
+async function view(id, commandFlags, globalFlags) {
+	const format = resolveViewFormat(commandFlags.format);
+	const { cacheData, config, granolaClient } = await loadMeetingData(commandFlags, globalFlags);
+	console.log("Fetching meeting from Granola API...");
+	const meeting = buildMeetingRecord(resolveMeeting(await granolaClient.listDocuments({ timeoutMs: config.notes.timeoutMs }), id), cacheData);
+	console.log(renderMeetingView(meeting, format).trimEnd());
+	return 0;
+}
+async function exportMeeting(id, commandFlags, globalFlags) {
+	const format = resolveExportFormat(commandFlags.format);
+	const { cacheData, config, granolaClient } = await loadMeetingData(commandFlags, globalFlags);
+	console.log("Fetching meeting from Granola API...");
+	const meeting = buildMeetingRecord(resolveMeeting(await granolaClient.listDocuments({ timeoutMs: config.notes.timeoutMs }), id), cacheData);
+	console.log(renderMeetingExport(meeting, format).trimEnd());
+	return 0;
+}
+//#endregion
+//#region src/commands/notes.ts
+function notesHelp() {
+	return `Granola notes
+
+Usage:
+  granola notes [options]
+
+Options:
+  --format <value>    Output format: markdown, json, yaml, raw (default: markdown)
+  --output <path>     Output directory for note files (default: ./notes)
+  --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
+`;
+}
+const notesCommand = {
+	description: "Export Granola notes",
+	flags: {
+		format: { type: "string" },
+		help: { type: "boolean" },
+		output: { type: "string" },
+		timeout: { type: "string" }
+	},
+	help: notesHelp,
+	name: "notes",
+	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, "timeoutMs", config.notes.timeoutMs);
+		debug(config.debug, "output", config.notes.output);
+		const format = resolveNoteFormat(commandFlags.format);
+		debug(config.debug, "format", format);
+		const granolaClient = await createDefaultGranolaApiClient(config);
+		console.log("Fetching documents from Granola API...");
+		const documents = await granolaClient.listDocuments({ timeoutMs: config.notes.timeoutMs });
+		console.log(`Exporting ${documents.length} notes to ${config.notes.output}...`);
+		const written = await writeNotes(documents, config.notes.output, format);
+		console.log("✓ Export completed successfully");
+		debug(config.debug, "notes written", written);
+		return 0;
+	}
+};
+function resolveNoteFormat(value) {
+	switch (value) {
+		case void 0: return "markdown";
+		case "json":
+		case "markdown":
+		case "raw":
+		case "yaml": return value;
+		default: throw new Error("invalid notes format: expected markdown, json, yaml, or raw");
+	}
+}
+//#endregion
 //#region src/commands/transcripts.ts
 function transcriptsHelp() {
 	return `Granola transcripts
@@ -1098,7 +1674,12 @@ function resolveTranscriptFormat(value) {
 }
 //#endregion
 //#region src/commands/index.ts
-const commands = [notesCommand, transcriptsCommand];
+const commands = [
+	authCommand,
+	meetingCommand,
+	notesCommand,
+	transcriptsCommand
+];
 const commandMap = new Map(commands.map((command) => [command.name, command]));
 //#endregion
 //#region src/flags.ts
@@ -1213,6 +1794,7 @@ async function runCli(argv) {
 			return 0;
 		}
 		return await command.run({
+			commandArgs: subcommand.rest,
 			commandFlags: subcommand.values,
 			globalFlags: global.values
 		});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "granola-toolkit",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "CLI toolkit for exporting and working with Granola notes and transcripts",
   "keywords": [
     "cli",