granola-toolkit 0.2.0 → 0.4.0

package/README.md

@@ -58,12 +58,14 @@ Export notes:
 
 ```bash
 node dist/cli.js notes --supabase "$HOME/Library/Application Support/Granola/supabase.json"
+node dist/cli.js notes --format json --output ./notes-json
 ```
 
 Export transcripts:
 
 ```bash
 node dist/cli.js transcripts --cache "$HOME/Library/Application Support/Granola/cache-v3.json"
+node dist/cli.js transcripts --format yaml --output ./transcripts-yaml
 ```
 
 ## How It Works
@@ -77,9 +79,10 @@ The flow is:
 1. read your local `supabase.json`
 2. extract the WorkOS access token from it
 3. call Granola's paginated documents API
-4. choose the best available note content for each document
-5. convert ProseMirror content into Markdown
-6. write one Markdown file per document into the output directory
+4. normalise each document into a structured note export
+5. choose the best available note content for each document
+6. render that export as Markdown, JSON, YAML, or raw JSON
+7. write one file per document into the output directory
 
 Content is chosen in this order:
 
@@ -88,7 +91,7 @@ Content is chosen in this order:
 3. `last_viewed_panel.original_content`
 4. raw `content`
 
-Each note file includes:
+Markdown note files include:
 
 - YAML frontmatter with the document id, created timestamp, updated timestamp, and tags
 - a top-level heading from the note title
@@ -102,15 +105,18 @@ The flow is:
 
 1. read Granola's cache JSON from disk
 2. parse the cache payload, whether it is double-encoded or already an object
-3. match transcript segments to documents by document id
-4. format segments as `[HH:MM:SS] Speaker: Text`
-5. write one `.txt` file per document into the output directory
+3. normalise transcript data into a structured export per document
+4. match transcript segments to documents by document id
+5. render each export as text, JSON, YAML, or raw JSON
+6. write one file per document into the output directory
 
 Speaker labels are currently normalised to:
 
 - `You` for `microphone`
 - `System` for everything else
 
+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.
+
 ### Incremental Writes
 
 Both commands are incremental. They only rewrite an export file when the source document appears newer than the file already on disk.

package/dist/cli.js

@@ -171,10 +171,56 @@ function transcriptSpeakerLabel(segment) {
 	return segment.source === "microphone" ? "You" : "System";
 }
 //#endregion
-//#region src/api.ts
-const USER_AGENT = "Granola/5.354.0";
-const CLIENT_VERSION = "5.354.0";
-const DOCUMENTS_URL = "https://api.granola.ai/v2/get-documents";
+//#region src/client/auth.ts
+function getAccessTokenFromSupabaseContents(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;
+}
+var SupabaseFileTokenSource = class {
+	constructor(filePath) {
+		this.filePath = filePath;
+	}
+	async loadAccessToken() {
+		return getAccessTokenFromSupabaseContents(await readFile(this.filePath, "utf8"));
+	}
+};
+var NoopTokenStore = class {
+	async clearToken() {}
+	async readToken() {}
+	async writeToken(_token) {}
+};
+var CachedTokenProvider = class {
+	#token;
+	constructor(source, store = new NoopTokenStore()) {
+		this.source = source;
+		this.store = store;
+	}
+	async getAccessToken() {
+		if (this.#token) return this.#token;
+		const storedToken = await this.store.readToken();
+		if (storedToken?.trim()) {
+			this.#token = storedToken;
+			return storedToken;
+		}
+		const token = await this.source.loadAccessToken();
+		this.#token = token;
+		await this.store.writeToken(token);
+		return token;
+	}
+	async invalidate() {
+		this.#token = void 0;
+		await this.store.clearToken();
+	}
+};
+//#endregion
+//#region src/client/parsers.ts
 function parseProseMirrorDoc(value, options = {}) {
 	if (value == null) return;
 	if (typeof value === "string") {
@@ -209,17 +255,6 @@ function parseLastViewedPanel(value) {
 		updatedAt: stringValue(panel.updated_at)
 	};
 }
-function getAccessToken(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;
-}
 function parseDocument(value) {
 	const record = asRecord(value);
 	if (!record) throw new Error("document payload is not an object");
@@ -235,44 +270,93 @@ function parseDocument(value) {
 		updatedAt: stringValue(record.updated_at)
 	};
 }
-async function fetchDocuments(options) {
-	const fetchImpl = options.fetchImpl ?? fetch;
-	const accessToken = getAccessToken(options.supabaseContents);
-	const documents = [];
-	const url = options.url ?? DOCUMENTS_URL;
-	const limit = 100;
-	let offset = 0;
-	for (;;) {
-		const signal = AbortSignal.timeout(options.timeoutMs);
-		const response = await fetchImpl(url, {
-			body: JSON.stringify({
+//#endregion
+//#region src/client/granola.ts
+const USER_AGENT = "Granola/5.354.0";
+const CLIENT_VERSION = "5.354.0";
+const DOCUMENTS_URL = "https://api.granola.ai/v2/get-documents";
+var GranolaApiClient = class {
+	constructor(httpClient, documentsUrl = DOCUMENTS_URL) {
+		this.httpClient = httpClient;
+		this.documentsUrl = documentsUrl;
+	}
+	async listDocuments(options) {
+		const documents = [];
+		const limit = options.limit ?? 100;
+		let offset = 0;
+		for (;;) {
+			const response = await this.httpClient.postJson(this.documentsUrl, {
 				include_last_viewed_panel: true,
 				limit,
 				offset
-			}),
+			}, {
+				headers: {
+					"User-Agent": USER_AGENT,
+					"X-Client-Version": CLIENT_VERSION
+				},
+				timeoutMs: options.timeoutMs
+			});
+			if (!response.ok) {
+				const body = (await response.text()).slice(0, 500);
+				throw new Error(`failed to get documents: ${response.status} ${response.statusText}${body ? `: ${body}` : ""}`);
+			}
+			const payload = await response.json();
+			if (!Array.isArray(payload.docs)) throw new Error("failed to parse documents response");
+			const page = payload.docs.map(parseDocument);
+			documents.push(...page);
+			if (page.length < limit) break;
+			offset += limit;
+		}
+		return documents;
+	}
+};
+//#endregion
+//#region src/client/http.ts
+var AuthenticatedHttpClient = class {
+	fetchImpl;
+	constructor(options) {
+		this.fetchImpl = options.fetchImpl ?? fetch;
+		this.logger = options.logger;
+		this.tokenProvider = options.tokenProvider;
+	}
+	logger;
+	tokenProvider;
+	async request(options) {
+		const { retryOnUnauthorized = true, timeoutMs, url } = options;
+		const accessToken = await this.tokenProvider.getAccessToken();
+		const response = await this.fetchImpl(url, {
+			body: options.body,
+			headers: {
+				...options.headers,
+				Authorization: `Bearer ${accessToken}`
+			},
+			method: options.method ?? "GET",
+			signal: AbortSignal.timeout(timeoutMs)
+		});
+		if (response.status === 401 && retryOnUnauthorized) {
+			this.logger?.warn?.("request returned 401; invalidating token provider and retrying once");
+			await this.tokenProvider.invalidate();
+			return this.request({
+				...options,
+				retryOnUnauthorized: false
+			});
+		}
+		return response;
+	}
+	async postJson(url, body, options = { timeoutMs: 3e4 }) {
+		return this.request({
+			...options,
+			body: JSON.stringify(body),
 			headers: {
 				Accept: "*/*",
-				Authorization: `Bearer ${accessToken}`,
 				"Content-Type": "application/json",
-				"User-Agent": USER_AGENT,
-				"X-Client-Version": CLIENT_VERSION
+				...options.headers
 			},
 			method: "POST",
-			signal
+			url
 		});
-		if (!response.ok) {
-			const body = (await response.text()).slice(0, 500);
-			throw new Error(`failed to get documents: ${response.status} ${response.statusText}${body ? `: ${body}` : ""}`);
-		}
-		const payload = await response.json();
-		if (!Array.isArray(payload.docs)) throw new Error("failed to parse documents response");
-		const page = payload.docs.map(parseDocument);
-		documents.push(...page);
-		if (page.length < limit) break;
-		offset += limit;
 	}
-	return documents;
-}
+};
 //#endregion
 //#region src/config.ts
 function pickString(value) {
@@ -346,6 +430,42 @@ async function loadConfig(options) {
 	};
 }
 //#endregion
+//#region src/render.ts
+function formatScalar(value) {
+	if (value == null) return "null";
+	if (typeof value === "string") return JSON.stringify(value);
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	return JSON.stringify(value);
+}
+function renderYaml(value, depth = 0) {
+	const indent = "  ".repeat(depth);
+	if (Array.isArray(value)) {
+		if (value.length === 0) return [`${indent}[]`];
+		return value.flatMap((item) => {
+			if (item && typeof item === "object" && !Array.isArray(item)) {
+				const nested = renderYaml(item, depth + 1);
+				return [`${indent}- ${(nested[0] ?? `${"  ".repeat(depth + 1)}{}`).trimStart()}`, ...nested.slice(1)];
+			}
+			return [`${indent}- ${formatScalar(item)}`];
+		});
+	}
+	if (value && typeof value === "object") {
+		const entries = Object.entries(value);
+		if (entries.length === 0) return [`${indent}{}`];
+		return entries.flatMap(([key, entryValue]) => {
+			if (Array.isArray(entryValue) || entryValue && typeof entryValue === "object") return [`${indent}${key}:`, ...renderYaml(entryValue, depth + 1)];
+			return [`${indent}${key}: ${formatScalar(entryValue)}`];
+		});
+	}
+	return [`${indent}${formatScalar(value)}`];
+}
+function toYaml(value) {
+	return `${renderYaml(value).join("\n").trimEnd()}\n`;
+}
+function toJson(value) {
+	return `${JSON.stringify(value, null, 2)}\n`;
+}
+//#endregion
 //#region src/prosemirror.ts
 function repeatIndent(level) {
 	return "  ".repeat(level);
@@ -441,35 +561,98 @@ function extractPlainText(doc) {
 }
 //#endregion
 //#region src/notes.ts
-function documentToMarkdown(document) {
+function selectNoteContent(document) {
+	const notes = convertProseMirrorToMarkdown(document.notes).trim();
+	if (notes) return {
+		content: notes,
+		source: "notes"
+	};
+	const lastViewedPanel = convertProseMirrorToMarkdown(document.lastViewedPanel?.content).trim();
+	if (lastViewedPanel) return {
+		content: lastViewedPanel,
+		source: "lastViewedPanel.content"
+	};
+	const originalContent = htmlToMarkdownFallback(document.lastViewedPanel?.originalContent ?? "").trim();
+	if (originalContent) return {
+		content: originalContent,
+		source: "lastViewedPanel.originalContent"
+	};
+	return {
+		content: document.content.trim(),
+		source: "content"
+	};
+}
+function buildNoteExport(document) {
+	const { content, source } = selectNoteContent(document);
+	return {
+		content,
+		contentSource: source,
+		createdAt: document.createdAt,
+		id: document.id,
+		raw: document,
+		tags: document.tags,
+		title: document.title,
+		updatedAt: document.updatedAt
+	};
+}
+function renderNoteExport(note, format = "markdown") {
+	switch (format) {
+		case "json": return toJson({
+			content: note.content,
+			contentSource: note.contentSource,
+			createdAt: note.createdAt,
+			id: note.id,
+			tags: note.tags,
+			title: note.title,
+			updatedAt: note.updatedAt
+		});
+		case "raw": return toJson(note.raw);
+		case "yaml": return toYaml({
+			content: note.content,
+			contentSource: note.contentSource,
+			createdAt: note.createdAt,
+			id: note.id,
+			tags: note.tags,
+			title: note.title,
+			updatedAt: note.updatedAt
+		});
+		case "markdown": break;
+	}
 	const lines = [
 		"---",
-		`id: ${quoteYamlString(document.id)}`,
-		`created: ${quoteYamlString(document.createdAt)}`,
-		`updated: ${quoteYamlString(document.updatedAt)}`
+		`id: ${quoteYamlString(note.id)}`,
+		`created: ${quoteYamlString(note.createdAt)}`,
+		`updated: ${quoteYamlString(note.updatedAt)}`
 	];
-	if (document.tags.length > 0) {
+	if (note.tags.length > 0) {
 		lines.push("tags:");
-		for (const tag of document.tags) lines.push(`  - ${quoteYamlString(tag)}`);
+		for (const tag of note.tags) lines.push(`  - ${quoteYamlString(tag)}`);
 	}
 	lines.push("---", "");
-	if (document.title.trim()) lines.push(`# ${document.title.trim()}`, "");
-	const content = convertProseMirrorToMarkdown(document.notes).trim() || convertProseMirrorToMarkdown(document.lastViewedPanel?.content).trim() || htmlToMarkdownFallback(document.lastViewedPanel?.originalContent ?? "").trim() || document.content.trim();
-	if (content) lines.push(content);
+	if (note.title.trim()) lines.push(`# ${note.title.trim()}`, "");
+	if (note.content) lines.push(note.content);
 	return `${lines.join("\n").trimEnd()}\n`;
 }
 function documentFilename(document) {
 	return sanitiseFilename(document.title || document.id, "untitled");
 }
-async function writeNotes(documents, outputDir) {
+function noteFileExtension(format) {
+	switch (format) {
+		case "json": return ".json";
+		case "raw": return ".raw.json";
+		case "yaml": return ".yaml";
+		case "markdown": return ".md";
+	}
+}
+async function writeNotes(documents, outputDir, format = "markdown") {
 	await ensureDirectory(outputDir);
 	const sorted = [...documents].sort((left, right) => compareStrings(left.title || left.id, right.title || right.id) || compareStrings(left.id, right.id));
 	const used = /* @__PURE__ */ new Map();
 	let written = 0;
 	for (const document of sorted) {
-		const filePath = join(outputDir, `${makeUniqueFilename(documentFilename(document), used)}.md`);
+		const filePath = join(outputDir, `${makeUniqueFilename(documentFilename(document), used)}${noteFileExtension(format)}`);
 		if (!await shouldWriteFile(filePath, latestDocumentTimestamp(document))) continue;
-		await writeTextFile(filePath, documentToMarkdown(document));
+		await writeTextFile(filePath, renderNoteExport(buildNoteExport(document), format));
 		written += 1;
 	}
 	return written;
@@ -488,7 +671,8 @@ Usage:
   granola notes [options]
 
 Options:
-  --output <path>     Output directory for Markdown files (default: ./notes)
+  --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
@@ -497,8 +681,9 @@ Options:
 `;
 }
 const notesCommand = {
-	description: "Export Granola notes to Markdown",
+	description: "Export Granola notes",
 	flags: {
+		format: { type: "string" },
 		help: { type: "boolean" },
 		output: { type: "string" },
 		timeout: { type: "string" }
@@ -515,18 +700,31 @@ const notesCommand = {
 		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 documents = await fetchDocuments({
-			supabaseContents: await readFile(config.supabase, "utf8"),
-			timeoutMs: config.notes.timeoutMs
-		});
+		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);
+		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) {
@@ -583,27 +781,78 @@ function parseCacheContents(contents) {
 }
 //#endregion
 //#region src/transcripts.ts
-function formatTranscript(document, segments) {
-	if (segments.length === 0) return "";
+function buildTranscriptExport(document, segments) {
+	const renderedSegments = segments.map((segment) => ({
+		endTimestamp: segment.endTimestamp,
+		id: segment.id,
+		isFinal: segment.isFinal,
+		source: segment.source,
+		speaker: transcriptSpeakerLabel(segment),
+		startTimestamp: segment.startTimestamp,
+		text: segment.text
+	}));
+	return {
+		createdAt: document.createdAt,
+		id: document.id,
+		raw: {
+			document,
+			segments
+		},
+		segments: renderedSegments,
+		title: document.title,
+		updatedAt: document.updatedAt
+	};
+}
+function renderTranscriptExport(transcript, format = "text") {
+	switch (format) {
+		case "json": return toJson({
+			createdAt: transcript.createdAt,
+			id: transcript.id,
+			segments: transcript.segments,
+			title: transcript.title,
+			updatedAt: transcript.updatedAt
+		});
+		case "raw": return toJson(transcript.raw);
+		case "yaml": return toYaml({
+			createdAt: transcript.createdAt,
+			id: transcript.id,
+			segments: transcript.segments,
+			title: transcript.title,
+			updatedAt: transcript.updatedAt
+		});
+		case "text": break;
+	}
+	return formatTranscriptText(transcript);
+}
+function formatTranscriptText(transcript) {
+	if (transcript.segments.length === 0) return "";
 	const header = [
 		"=".repeat(80),
-		document.title || document.id,
-		`ID: ${document.id}`,
-		document.createdAt ? `Created: ${document.createdAt}` : "",
-		document.updatedAt ? `Updated: ${document.updatedAt}` : "",
-		`Segments: ${segments.length}`,
+		transcript.title || transcript.id,
+		`ID: ${transcript.id}`,
+		transcript.createdAt ? `Created: ${transcript.createdAt}` : "",
+		transcript.updatedAt ? `Updated: ${transcript.updatedAt}` : "",
+		`Segments: ${transcript.segments.length}`,
 		"=".repeat(80),
 		""
 	].filter(Boolean);
-	const body = segments.map((segment) => {
-		return `[${formatTimestampForTranscript(segment.startTimestamp)}] ${transcriptSpeakerLabel(segment)}: ${segment.text}`;
+	const body = transcript.segments.map((segment) => {
+		return `[${formatTimestampForTranscript(segment.startTimestamp)}] ${segment.speaker}: ${segment.text}`;
 	});
 	return `${[...header, ...body].join("\n").trimEnd()}\n`;
 }
 function transcriptFilename(document) {
 	return sanitiseFilename(document.title || document.id, "untitled");
 }
-async function writeTranscripts(cacheData, outputDir) {
+function transcriptFileExtension(format) {
+	switch (format) {
+		case "json": return ".json";
+		case "raw": return ".raw.json";
+		case "text": return ".txt";
+		case "yaml": return ".yaml";
+	}
+}
+async function writeTranscripts(cacheData, outputDir, format = "text") {
 	await ensureDirectory(outputDir);
 	const entries = Object.entries(cacheData.transcripts).filter(([, segments]) => segments.length > 0).sort(([leftId], [rightId]) => {
 		const leftDocument = cacheData.documents[leftId];
@@ -619,9 +868,9 @@ async function writeTranscripts(cacheData, outputDir) {
 			title: documentId,
 			updatedAt: ""
 		};
-		const filePath = join(outputDir, `${makeUniqueFilename(transcriptFilename(document), used)}.txt`);
+		const filePath = join(outputDir, `${makeUniqueFilename(transcriptFilename(document), used)}${transcriptFileExtension(format)}`);
 		if (!await shouldWriteFile(filePath, document.updatedAt)) continue;
-		const content = formatTranscript(document, segments);
+		const content = renderTranscriptExport(buildTranscriptExport(document, segments), format);
 		if (!content) continue;
 		await writeTextFile(filePath, content);
 		written += 1;
@@ -638,18 +887,18 @@ Usage:
 
 Options:
   --cache <path>      Path to Granola cache JSON
+  --format <value>    Output format: text, json, yaml, raw (default: text)
   --output <path>     Output directory for transcript files (default: ./transcripts)
   --debug             Enable debug logging
   --config <path>     Path to .granola.toml
   -h, --help          Show help
 `;
 }
-//#endregion
-//#region src/commands/index.ts
-const commands = [notesCommand, {
-	description: "Export Granola transcripts to text files",
+const transcriptsCommand = {
+	description: "Export Granola transcripts",
 	flags: {
 		cache: { type: "string" },
+		format: { type: "string" },
 		help: { type: "boolean" },
 		output: { type: "string" }
 	},
@@ -664,16 +913,31 @@ const commands = [notesCommand, {
 		debug(config.debug, "using config", config.configFileUsed ?? "(none)");
 		debug(config.debug, "cacheFile", config.transcripts.cacheFile);
 		debug(config.debug, "output", config.transcripts.output);
+		const format = resolveTranscriptFormat(commandFlags.format);
+		debug(config.debug, "format", format);
 		console.log("Reading Granola cache file...");
 		const cacheData = parseCacheContents(await readFile(config.transcripts.cacheFile, "utf8"));
 		const transcriptCount = Object.values(cacheData.transcripts).filter((segments) => segments.length > 0).length;
 		console.log(`Exporting ${transcriptCount} transcripts to ${config.transcripts.output}...`);
-		const written = await writeTranscripts(cacheData, config.transcripts.output);
+		const written = await writeTranscripts(cacheData, config.transcripts.output, format);
 		console.log("✓ Export completed successfully");
 		debug(config.debug, "transcripts written", written);
 		return 0;
 	}
-}];
+};
+function resolveTranscriptFormat(value) {
+	switch (value) {
+		case void 0: return "text";
+		case "json":
+		case "raw":
+		case "text":
+		case "yaml": return value;
+		default: throw new Error("invalid transcripts format: expected text, json, yaml, or raw");
+	}
+}
+//#endregion
+//#region src/commands/index.ts
+const commands = [notesCommand, transcriptsCommand];
 const commandMap = new Map(commands.map((command) => [command.name, command]));
 //#endregion
 //#region src/flags.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "granola-toolkit",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "CLI toolkit for exporting and working with Granola notes and transcripts",
   "keywords": [
     "cli",
@@ -37,8 +37,11 @@
     "fmt": "vp fmt",
     "lint": "vp lint",
     "pack:dry-run": "npm pack --dry-run",
-    "prepublishOnly": "vp pack",
+    "prepublishOnly": "node scripts/prepublish.mjs",
     "release": "node scripts/release.mjs",
+    "release:major": "node scripts/release.mjs major",
+    "release:minor": "node scripts/release.mjs minor",
+    "release:patch": "node scripts/release.mjs patch",
     "start": "node dist/cli.js",
     "notes": "node dist/cli.js notes",
     "transcripts": "node dist/cli.js transcripts",