granola-toolkit 0.37.0 → 0.38.0

package/README.md

@@ -20,7 +20,7 @@ The published package exposes both `granola` and `granola-toolkit` as executable
 ## Quick Start
 
 ```bash
-granola auth login
+granola auth login --api-key grn_...
 granola sync
 granola sync --watch
 granola folder list
@@ -30,6 +30,9 @@ granola web
 granola tui
 ```
 
+If you prefer to reuse the desktop app session instead, `granola auth login` still imports it from
+`supabase.json`.
+
 ## Documentation
 
 The detailed documentation now lives at

package/dist/cli.js

@@ -1088,14 +1088,14 @@ function cacheDocumentForMeeting(document, cacheData) {
 	};
 }
 function buildMeetingTranscript(document, cacheData) {
-	if (!cacheData) return {
+	const rawSegments = cacheData?.transcripts[document.id] ?? document.transcriptSegments ?? [];
+	if (!(Boolean(cacheData) || Array.isArray(document.transcriptSegments))) return {
 		loaded: false,
 		segmentCount: 0,
 		transcript: null,
 		transcriptRecord: null,
 		transcriptText: null
 	};
-	const rawSegments = cacheData.transcripts[document.id] ?? [];
 	const normalisedSegments = normaliseTranscriptSegments(rawSegments);
 	if (normalisedSegments.length === 0) return {
 		loaded: true,
@@ -1383,7 +1383,7 @@ function renderGranolaTuiMeetingTab(bundle, tab) {
 	}
 }
 function buildGranolaTuiSummary(state, meetingSource) {
-	return `auth ${state.auth.mode === "stored-session" ? "stored" : "supabase"} | ${state.documents.loaded ? `${state.documents.count} docs` : "docs pending"} | ${state.folders.loaded ? `${state.folders.count} folders` : "folders pending"} | ${state.cache.loaded ? `${state.cache.transcriptCount} transcript sets` : state.cache.configured ? "cache configured" : "cache missing"} | ${state.index.loaded ? `${state.index.meetingCount} indexed` : "index pending"} | ${state.sync.running ? "sync running" : state.sync.lastError ? "sync error" : state.sync.lastCompletedAt ? `sync ${state.sync.lastCompletedAt.slice(11, 16)}` : "sync idle"} | list ${meetingSource}`;
+	return `auth ${state.auth.mode === "api-key" ? "key" : state.auth.mode === "stored-session" ? "stored" : "supabase"} | ${state.documents.loaded ? `${state.documents.count} docs` : "docs pending"} | ${state.folders.loaded ? `${state.folders.count} folders` : "folders pending"} | ${state.cache.loaded ? `${state.cache.transcriptCount} transcript sets` : state.cache.configured ? "cache configured" : "cache missing"} | ${state.index.loaded ? `${state.index.meetingCount} indexed` : "index pending"} | ${state.sync.running ? "sync running" : state.sync.lastError ? "sync error" : state.sync.lastCompletedAt ? `sync ${state.sync.lastCompletedAt.slice(11, 16)}` : "sync idle"} | list ${meetingSource}`;
 }
 //#endregion
 //#region src/tui/theme.ts
@@ -1429,13 +1429,16 @@ function actionDisabledReason(auth, actionId) {
 		case "refresh":
 			if (!auth.storedSessionAvailable) return "stored session missing";
 			return auth.refreshAvailable ? "" : "refresh unavailable";
+		case "use-api-key":
+			if (!auth.apiKeyAvailable) return "API key missing";
+			return auth.mode === "api-key" ? "already active" : "";
 		case "use-stored":
 			if (!auth.storedSessionAvailable) return "stored session missing";
 			return auth.mode === "stored-session" ? "already active" : "";
 		case "use-supabase":
 			if (!auth.supabaseAvailable) return "supabase.json unavailable";
 			return auth.mode === "supabase-file" ? "already active" : "";
-		case "logout": return auth.storedSessionAvailable ? "" : "stored session missing";
+		case "logout": return auth.apiKeyAvailable || auth.storedSessionAvailable ? "" : "no stored credentials";
 	}
 }
 function buildGranolaTuiAuthActions(auth) {
@@ -1452,22 +1455,28 @@ function buildGranolaTuiAuthActions(auth) {
 			key: "2",
 			label: "Refresh stored session"
 		},
+		{
+			description: "Switch the active auth source to the stored API key",
+			id: "use-api-key",
+			key: "3",
+			label: "Use API key"
+		},
 		{
 			description: "Switch the active auth source to the stored session",
 			id: "use-stored",
-			key: "3",
+			key: "4",
 			label: "Use stored session"
 		},
 		{
 			description: "Switch the active auth source to supabase.json",
 			id: "use-supabase",
-			key: "4",
+			key: "5",
 			label: "Use supabase.json"
 		},
 		{
-			description: "Delete the stored session and fall back to supabase.json",
+			description: "Delete stored credentials and fall back to configured sources",
 			id: "logout",
-			key: "5",
+			key: "6",
 			label: "Sign out"
 		}
 	].map((action) => {
@@ -1481,7 +1490,8 @@ function buildGranolaTuiAuthActions(auth) {
 }
 function renderGranolaTuiAuthState(auth) {
 	const lines = [
-		`Active source: ${auth.mode === "stored-session" ? "Stored session" : "supabase.json"}`,
+		`Active source: ${auth.mode === "api-key" ? "API key" : auth.mode === "stored-session" ? "Stored session" : "supabase.json"}`,
+		`API key: ${auth.apiKeyAvailable ? "available" : "missing"}`,
 		`Stored session: ${auth.storedSessionAvailable ? "available" : "missing"}`,
 		`supabase.json: ${auth.supabaseAvailable ? "available" : "missing"}`,
 		`Refresh: ${auth.refreshAvailable ? "available" : "missing"}`
@@ -1977,6 +1987,11 @@ var GranolaTuiWorkspace = class {
 					await this.app.refreshAuth();
 					successMessage = "Stored session refreshed";
 					break;
+				case "use-api-key":
+					this.setStatus("Switching to stored API key…");
+					await this.app.switchAuthMode("api-key");
+					successMessage = "Using stored API key";
+					break;
 				case "use-stored":
 					this.setStatus("Switching to stored session…");
 					await this.app.switchAuthMode("stored-session");
@@ -1990,7 +2005,7 @@ var GranolaTuiWorkspace = class {
 				case "logout":
 					this.setStatus("Signing out…");
 					await this.app.logoutAuth();
-					successMessage = "Stored session removed";
+					successMessage = "Stored credentials removed";
 					break;
 			}
 			await this.reloadAfterAuthChange();
@@ -2388,6 +2403,7 @@ function defaultGranolaToolkitPersistenceLayout(options = {}) {
 	const targetPlatform = options.platform ?? platform();
 	const dataDirectory = defaultGranolaToolkitDataDirectory(targetPlatform, options.homeDirectory ?? homedir());
 	return {
+		apiKeyFile: join(dataDirectory, "api-key.txt"),
 		dataDirectory,
 		exportJobsFile: join(dataDirectory, "export-jobs.json"),
 		meetingIndexFile: join(dataDirectory, "meeting-index.json"),
@@ -2402,6 +2418,7 @@ function defaultGranolaToolkitPersistenceLayout(options = {}) {
 const execFileAsync$1 = promisify(execFile);
 const DEFAULT_CLIENT_ID = "client_GranolaMac";
 const KEYCHAIN_SERVICE_NAME = "com.granola.toolkit";
+const KEYCHAIN_ACCOUNT_NAME_API_KEY = "api-key";
 const KEYCHAIN_ACCOUNT_NAME = "session";
 const WORKOS_AUTH_URL = "https://api.workos.com/user_management/authenticate";
 function numberValue(value) {
@@ -2486,6 +2503,32 @@ var FileSessionStore = class {
 		});
 	}
 };
+var FileApiKeyStore = class {
+	constructor(filePath = defaultApiKeyFilePath()) {
+		this.filePath = filePath;
+	}
+	async clearApiKey() {
+		try {
+			await unlink(this.filePath);
+		} catch {}
+	}
+	async readApiKey() {
+		try {
+			return (await readFile(this.filePath, "utf8")).trim() || void 0;
+		} catch {
+			return;
+		}
+	}
+	async writeApiKey(apiKey) {
+		const trimmed = apiKey.trim();
+		if (!trimmed) throw new Error("Granola API key is required");
+		await mkdir(dirname(this.filePath), { recursive: true });
+		await writeFile(this.filePath, `${trimmed}\n`, {
+			encoding: "utf8",
+			mode: 384
+		});
+	}
+};
 var KeychainSessionStore = class {
 	async clearSession() {
 		try {
@@ -2527,6 +2570,48 @@ var KeychainSessionStore = class {
 		]);
 	}
 };
+var KeychainApiKeyStore = class {
+	async clearApiKey() {
+		try {
+			await execFileAsync$1("security", [
+				"delete-generic-password",
+				"-s",
+				KEYCHAIN_SERVICE_NAME,
+				"-a",
+				KEYCHAIN_ACCOUNT_NAME_API_KEY
+			]);
+		} catch {}
+	}
+	async readApiKey() {
+		try {
+			const { stdout } = await execFileAsync$1("security", [
+				"find-generic-password",
+				"-s",
+				KEYCHAIN_SERVICE_NAME,
+				"-a",
+				KEYCHAIN_ACCOUNT_NAME_API_KEY,
+				"-w"
+			]);
+			return stdout.trim() || void 0;
+		} catch {
+			return;
+		}
+	}
+	async writeApiKey(apiKey) {
+		const trimmed = apiKey.trim();
+		if (!trimmed) throw new Error("Granola API key is required");
+		await execFileAsync$1("security", [
+			"add-generic-password",
+			"-U",
+			"-s",
+			KEYCHAIN_SERVICE_NAME,
+			"-a",
+			KEYCHAIN_ACCOUNT_NAME_API_KEY,
+			"-w",
+			trimmed
+		]);
+	}
+};
 var CachedTokenProvider = class {
 	#token;
 	constructor(source, store = new NoopTokenStore()) {
@@ -2620,33 +2705,45 @@ async function refreshGranolaSession(session, fetchImpl = fetch) {
 function defaultSessionFilePath() {
 	return defaultGranolaToolkitPersistenceLayout().sessionFile;
 }
+function defaultApiKeyFilePath() {
+	return defaultGranolaToolkitPersistenceLayout().apiKeyFile;
+}
 function createDefaultSessionStore() {
 	return defaultGranolaToolkitPersistenceLayout().sessionStoreKind === "keychain" ? new KeychainSessionStore() : new FileSessionStore();
 }
+function createDefaultApiKeyStore() {
+	return defaultGranolaToolkitPersistenceLayout().sessionStoreKind === "keychain" ? new KeychainApiKeyStore() : new FileApiKeyStore();
+}
 //#endregion
 //#region src/client/default-auth.ts
 function hasStoredSession(session) {
 	return Boolean(session?.accessToken.trim());
 }
 function resolveActiveMode(options) {
+	if (options.preferredMode === "api-key" && options.apiKeyAvailable) return "api-key";
 	if (options.preferredMode === "stored-session" && options.storedSessionAvailable) return "stored-session";
 	if (options.preferredMode === "supabase-file" && options.supabaseAvailable) return "supabase-file";
+	if (options.apiKeyAvailable) return "api-key";
 	if (options.storedSessionAvailable) return "stored-session";
-	return "supabase-file";
+	if (options.supabaseAvailable) return "supabase-file";
+	return options.preferredMode ?? "api-key";
 }
 function missingSupabaseError() {
 	return /* @__PURE__ */ new Error(`supabase.json not found. Pass --supabase or create .granola.toml. Expected locations include: ${granolaSupabaseCandidates().join(", ")}`);
 }
 function buildDefaultGranolaAuthInfo(config, options = {}) {
 	const existsSyncImpl = options.existsSyncImpl ?? existsSync;
+	const apiKeyAvailable = Boolean(options.apiKey?.trim());
 	const session = options.session;
 	const storedSessionAvailable = hasStoredSession(session);
 	const supabasePath = config.supabase || void 0;
 	const supabaseAvailable = Boolean(supabasePath && existsSyncImpl(supabasePath));
 	return {
+		apiKeyAvailable,
 		clientId: session?.clientId,
 		lastError: options.lastError,
 		mode: resolveActiveMode({
+			apiKeyAvailable,
 			preferredMode: options.preferredMode,
 			storedSessionAvailable,
 			supabaseAvailable
@@ -2659,9 +2756,12 @@ function buildDefaultGranolaAuthInfo(config, options = {}) {
 	};
 }
 async function inspectDefaultGranolaAuth(config, options = {}) {
+	const apiKeyStore = options.apiKeyStore ?? createDefaultApiKeyStore();
 	const sessionStore = options.sessionStore ?? createDefaultSessionStore();
+	const apiKey = options.apiKey ?? config.apiKey ?? await apiKeyStore.readApiKey();
 	const session = options.session ?? await sessionStore.readSession();
 	return buildDefaultGranolaAuthInfo(config, {
+		apiKey,
 		existsSyncImpl: options.existsSyncImpl,
 		lastError: options.lastError,
 		preferredMode: options.preferredMode,
@@ -2678,6 +2778,12 @@ var DefaultAuthController = class {
 	sessionStore() {
 		return this.options.sessionStore ?? createDefaultSessionStore();
 	}
+	apiKeyStore() {
+		return this.options.apiKeyStore ?? createDefaultApiKeyStore();
+	}
+	async readApiKey() {
+		return this.config.apiKey?.trim() || await this.apiKeyStore().readApiKey();
+	}
 	readSession() {
 		return this.sessionStore().readSession();
 	}
@@ -2691,8 +2797,10 @@ var DefaultAuthController = class {
 		return this.options.sessionSourceFactory?.(supabasePath) ?? new SupabaseFileSessionSource(supabasePath);
 	}
 	async inspect() {
+		const apiKey = await this.readApiKey();
 		const session = await this.readSession();
 		return buildDefaultGranolaAuthInfo(this.config, {
+			apiKey,
 			existsSyncImpl: this.options.existsSyncImpl,
 			lastError: this.#lastError,
 			preferredMode: this.#preferredMode,
@@ -2700,6 +2808,13 @@ var DefaultAuthController = class {
 		});
 	}
 	async login(options = {}) {
+		const apiKey = options.apiKey?.trim();
+		if (apiKey) {
+			await this.apiKeyStore().writeApiKey(apiKey);
+			this.#lastError = void 0;
+			this.#preferredMode = "api-key";
+			return await this.inspect();
+		}
 		const supabasePath = this.resolveSupabasePath(options.supabasePath);
 		const session = await this.sessionSource(supabasePath).loadSession();
 		await this.sessionStore().writeSession(session);
@@ -2708,6 +2823,7 @@ var DefaultAuthController = class {
 		return await this.inspect();
 	}
 	async logout() {
+		await this.apiKeyStore().clearApiKey();
 		await this.sessionStore().clearSession();
 		this.#lastError = void 0;
 		this.#preferredMode = void 0;
@@ -2732,6 +2848,10 @@ var DefaultAuthController = class {
 	}
 	async switchMode(mode) {
 		const state = await this.inspect();
+		if (mode === "api-key" && !state.apiKeyAvailable) {
+			this.#lastError = "no Granola API key found";
+			throw new Error(this.#lastError);
+		}
 		if (mode === "stored-session" && !state.storedSessionAvailable) {
 			this.#lastError = "no stored Granola session found";
 			throw new Error(this.#lastError);
@@ -2796,6 +2916,63 @@ function parseDocument(value) {
 		updatedAt: stringValue(record.updated_at)
 	};
 }
+function parseFolderMembership(value) {
+	const record = asRecord(value);
+	if (!record) return;
+	const id = stringValue(record.id);
+	const name = stringValue(record.name);
+	if (!id || !name) return;
+	return {
+		id,
+		name
+	};
+}
+function parsePublicTranscriptSegment(documentId, value, index) {
+	const record = asRecord(value);
+	if (!record) return;
+	const text = stringValue(record.text);
+	const startTimestamp = stringValue(record.start_time);
+	const endTimestamp = stringValue(record.end_time) || startTimestamp;
+	if (!text || !startTimestamp) return;
+	const speaker = asRecord(record.speaker);
+	return {
+		documentId,
+		endTimestamp,
+		id: stringValue(record.id) || `${documentId}:transcript:${index + 1}`,
+		isFinal: true,
+		source: stringValue(speaker?.name) || stringValue(speaker?.source) || "unknown",
+		startTimestamp,
+		text
+	};
+}
+function parsePublicNoteSummary(value) {
+	const record = asRecord(value);
+	if (!record) throw new Error("public note payload is not an object");
+	return {
+		createdAt: stringValue(record.created_at),
+		id: stringValue(record.id),
+		title: stringValue(record.title),
+		updatedAt: stringValue(record.updated_at)
+	};
+}
+function parsePublicNote(value) {
+	const record = asRecord(value);
+	if (!record) throw new Error("public note payload is not an object");
+	const id = stringValue(record.id);
+	const summaryMarkdown = stringValue(record.summary_markdown);
+	const summaryText = stringValue(record.summary_text);
+	return {
+		content: summaryMarkdown || summaryText,
+		createdAt: stringValue(record.created_at),
+		folderMemberships: Array.isArray(record.folder_membership) ? record.folder_membership.map(parseFolderMembership).filter((membership) => Boolean(membership)) : [],
+		id,
+		notesPlain: summaryText,
+		tags: [],
+		title: stringValue(record.title),
+		transcriptSegments: Array.isArray(record.transcript) ? record.transcript.map((segment, index) => parsePublicTranscriptSegment(id, segment, index)).filter((segment) => Boolean(segment)) : [],
+		updatedAt: stringValue(record.updated_at)
+	};
+}
 function parseFolderDocumentIds(value) {
 	if (!Array.isArray(value)) return [];
 	return value.map((item) => {
@@ -2899,6 +3076,98 @@ var GranolaApiClient = class {
 	}
 };
 //#endregion
+//#region src/client/granola-public.ts
+const PUBLIC_NOTES_URL = "https://public-api.granola.ai/v1/notes";
+const MAX_PAGE_SIZE = 30;
+const DETAIL_BATCH_SIZE = 5;
+function cloneDocument(document) {
+	return {
+		...document,
+		folderMemberships: document.folderMemberships?.map((membership) => ({ ...membership })),
+		tags: [...document.tags],
+		transcriptSegments: document.transcriptSegments?.map((segment) => ({ ...segment }))
+	};
+}
+async function mapInBatches(items, batchSize, mapper) {
+	const results = [];
+	for (let index = 0; index < items.length; index += batchSize) {
+		const batch = items.slice(index, index + batchSize);
+		results.push(...await Promise.all(batch.map((item) => mapper(item))));
+	}
+	return results;
+}
+var GranolaPublicApiClient = class {
+	#documentsById = /* @__PURE__ */ new Map();
+	constructor(httpClient) {
+		this.httpClient = httpClient;
+	}
+	async listNoteSummaries(options) {
+		const notes = [];
+		const pageSize = Math.max(1, Math.min(options.limit ?? MAX_PAGE_SIZE, MAX_PAGE_SIZE));
+		let cursor;
+		for (;;) {
+			const url = new URL(PUBLIC_NOTES_URL);
+			url.searchParams.set("page_size", String(pageSize));
+			if (cursor) url.searchParams.set("cursor", cursor);
+			const response = await this.httpClient.request({
+				headers: { Accept: "application/json" },
+				timeoutMs: options.timeoutMs,
+				url: url.toString()
+			});
+			if (!response.ok) {
+				const body = (await response.text()).slice(0, 500);
+				throw new Error(`failed to list notes: ${response.status} ${response.statusText}${body ? `: ${body}` : ""}`);
+			}
+			const payload = await response.json();
+			if (!Array.isArray(payload.notes)) throw new Error("failed to parse public notes response");
+			notes.push(...payload.notes.map(parsePublicNoteSummary));
+			cursor = payload.cursor ?? void 0;
+			if (!payload.hasMore || !cursor) break;
+		}
+		return notes;
+	}
+	async fetchNoteDetail(noteId, timeoutMs) {
+		const url = new URL(`${PUBLIC_NOTES_URL}/${noteId}`);
+		url.searchParams.append("include", "transcript");
+		const response = await this.httpClient.request({
+			headers: { Accept: "application/json" },
+			timeoutMs,
+			url: url.toString()
+		});
+		if (!response.ok) {
+			const body = (await response.text()).slice(0, 500);
+			throw new Error(`failed to get note ${noteId}: ${response.status} ${response.statusText}${body ? `: ${body}` : ""}`);
+		}
+		const document = parsePublicNote(await response.json());
+		this.#documentsById.set(document.id, cloneDocument(document));
+		return document;
+	}
+	async listDocuments(options) {
+		const summaries = await this.listNoteSummaries(options);
+		const nextDocuments = [];
+		const toFetch = [];
+		for (const summary of summaries) {
+			const cached = this.#documentsById.get(summary.id);
+			if (cached && cached.updatedAt === summary.updatedAt) {
+				nextDocuments.push(cloneDocument(cached));
+				continue;
+			}
+			toFetch.push(summary);
+		}
+		const fetchedDocuments = await mapInBatches(toFetch, DETAIL_BATCH_SIZE, async (summary) => await this.fetchNoteDetail(summary.id, options.timeoutMs));
+		const fetchedById = new Map(fetchedDocuments.map((document) => [document.id, document]));
+		const ids = /* @__PURE__ */ new Set();
+		for (const summary of summaries) {
+			const document = fetchedById.get(summary.id) ?? this.#documentsById.get(summary.id);
+			if (!document) throw new Error(`failed to load note detail: ${summary.id}`);
+			ids.add(summary.id);
+			nextDocuments.push(cloneDocument(document));
+		}
+		for (const cachedId of this.#documentsById.keys()) if (!ids.has(cachedId)) this.#documentsById.delete(cachedId);
+		return nextDocuments;
+	}
+};
+//#endregion
 //#region src/client/http.ts
 const RETRYABLE_STATUS_CODES = new Set([
 	429,
@@ -2993,8 +3262,23 @@ var AuthenticatedHttpClient = class {
 //#region src/client/default.ts
 async function createDefaultGranolaRuntime(config, logger = console, options = {}) {
 	const auth = await inspectDefaultGranolaAuth(config, { preferredMode: options.preferredMode });
-	if (!auth.storedSessionAvailable && !config.supabase) throw new Error(`supabase.json not found. Pass --supabase or create .granola.toml. Expected locations include: ${granolaSupabaseCandidates().join(", ")}`);
-	if (!auth.storedSessionAvailable && config.supabase && !existsSync(config.supabase)) throw new Error(`supabase.json not found: ${config.supabase}`);
+	if (!auth.apiKeyAvailable && !auth.storedSessionAvailable && !config.supabase) throw new Error(`Granola credentials not found. Set --api-key or GRANOLA_API_KEY, use granola auth login --api-key, or fall back to --supabase. Expected supabase locations include: ${granolaSupabaseCandidates().join(", ")}`);
+	if (config.supabase && !existsSync(config.supabase) && !auth.apiKeyAvailable && !auth.storedSessionAvailable) throw new Error(`supabase.json not found: ${config.supabase}`);
+	if (auth.mode !== "api-key" && !auth.storedSessionAvailable && config.supabase && !existsSync(config.supabase)) throw new Error(`supabase.json not found: ${config.supabase}`);
+	if (auth.mode === "api-key") {
+		const apiKeyStore = createDefaultApiKeyStore();
+		const apiKey = config.apiKey?.trim() || await apiKeyStore.readApiKey();
+		if (!apiKey) throw new Error("Granola API key not found. Set --api-key or GRANOLA_API_KEY, or run granola auth login --api-key <token>.");
+		return {
+			auth,
+			client: new GranolaPublicApiClient(new AuthenticatedHttpClient({
+				logger,
+				tokenProvider: new CachedTokenProvider({ async loadAccessToken() {
+					return apiKey;
+				} })
+			}))
+		};
+	}
 	const sessionStore = createDefaultSessionStore();
 	return {
 		auth,
@@ -3763,6 +4047,28 @@ var GranolaApp = class {
 		for (const [documentId, summaries] of byDocumentId.entries()) byDocumentId.set(documentId, summaries.slice().sort((left, right) => left.name.localeCompare(right.name)).map((folder) => cloneFolderSummary(folder)));
 		return byDocumentId;
 	}
+	deriveFoldersFromDocuments(documents) {
+		const byFolderId = /* @__PURE__ */ new Map();
+		for (const document of documents) for (const membership of document.folderMemberships ?? []) {
+			const existing = byFolderId.get(membership.id);
+			if (existing) {
+				existing.documentIds = [...new Set([...existing.documentIds, document.id])];
+				existing.updatedAt = existing.updatedAt.localeCompare(document.updatedAt) >= 0 ? existing.updatedAt : document.updatedAt;
+				if (!existing.createdAt || existing.createdAt.localeCompare(document.createdAt) > 0) existing.createdAt = document.createdAt;
+				continue;
+			}
+			byFolderId.set(membership.id, {
+				createdAt: document.createdAt,
+				documentIds: [document.id],
+				id: membership.id,
+				isFavourite: false,
+				name: membership.name,
+				updatedAt: document.updatedAt
+			});
+		}
+		if (byFolderId.size === 0) return;
+		return [...byFolderId.values()].sort((left, right) => left.name.localeCompare(right.name));
+	}
 	async loadFolders(options = {}) {
 		if (options.forceRefresh) {
 			this.resetFoldersState();
@@ -3774,6 +4080,24 @@ var GranolaApp = class {
 		}));
 		const client = await this.getGranolaClient();
 		if (!client.listFolders) {
+			const documents = await this.listDocuments({ forceRefresh: options.forceRefresh });
+			const folders = this.deriveFoldersFromDocuments(documents);
+			if (folders) {
+				this.#folders = folders.map((folder) => ({
+					...folder,
+					documentIds: [...folder.documentIds]
+				}));
+				this.#state.folders = {
+					count: folders.length,
+					loaded: true,
+					loadedAt: this.nowIso()
+				};
+				this.emitStateUpdate();
+				return this.#folders.map((folder) => ({
+					...folder,
+					documentIds: [...folder.documentIds]
+				}));
+			}
 			if (options.required) throw new Error("Granola folder API is not configured");
 			return;
 		}
@@ -4368,6 +4692,7 @@ async function loadConfig(options) {
 	const defaultCache = firstExistingPath(granolaCacheCandidates());
 	const timeoutValue = pickString(options.subcommandFlags.timeout) ?? pickString(env.TIMEOUT) ?? pickString(configValues.timeout) ?? "2m";
 	return {
+		apiKey: pickString(options.globalFlags["api-key"]) ?? pickString(env.GRANOLA_API_KEY) ?? pickString(configValues["api-key"]) ?? pickString(configValues.apiKey),
 		configFileUsed: config.path,
 		debug: pickBoolean(options.globalFlags.debug) ?? envFlag(env.DEBUG_MODE) ?? pickBoolean(configValues.debug) ?? false,
 		notes: {
@@ -4455,13 +4780,15 @@ Usage:
 
 Subcommands:
   login               Import credentials from the Granola desktop app
+                      Or store a Granola API key with --api-key
   status              Show the current Granola auth state
-  logout              Delete the stored Granola session
+  logout              Delete stored Granola credentials
   refresh             Refresh the stored Granola session
-  use <stored|supabase>
+  use <api-key|stored|supabase>
                       Switch the active auth source for this toolkit instance
 
 Options:
+  --api-key <token>   Store a Granola Personal API key
   --supabase <path>   Path to supabase.json for auth login
   --config <path>     Path to .granola.toml
   --debug             Enable debug logging
@@ -4469,10 +4796,15 @@ Options:
 `;
 }
 function formatAuthSource(mode) {
-	return mode === "stored-session" ? "stored session" : "supabase.json";
+	switch (mode) {
+		case "api-key": return "API key";
+		case "stored-session": return "stored session";
+		default: return "supabase.json";
+	}
 }
 function printAuthState(state) {
 	console.log(`Active source: ${formatAuthSource(state.mode)}`);
+	console.log(`API key: ${state.apiKeyAvailable ? "available" : "missing"}`);
 	console.log(`Stored session: ${state.storedSessionAvailable ? "available" : "missing"}`);
 	console.log(`supabase.json: ${state.supabaseAvailable ? "available" : "missing"}`);
 	if (state.supabasePath) console.log(`supabase path: ${state.supabasePath}`);
@@ -4483,10 +4815,13 @@ function printAuthState(state) {
 }
 const authCommand = {
 	description: "Manage stored Granola sessions",
-	flags: { help: { type: "boolean" } },
+	flags: {
+		"api-key": { type: "string" },
+		help: { type: "boolean" }
+	},
 	help: authHelp,
 	name: "auth",
-	async run({ commandArgs, globalFlags }) {
+	async run({ commandArgs, commandFlags, globalFlags }) {
 		const [action, value] = commandArgs;
 		const config = await loadConfig({
 			globalFlags,
@@ -4497,14 +4832,14 @@ const authCommand = {
 		const app = await createGranolaApp(config);
 		switch (action) {
 			case "login": {
-				const state = await app.loginAuth();
-				console.log(`Imported Granola session from ${state.supabasePath ?? "desktop app defaults"}`);
+				const state = await app.loginAuth({ apiKey: typeof commandFlags["api-key"] === "string" ? commandFlags["api-key"] : void 0 });
+				console.log(typeof commandFlags["api-key"] === "string" ? "Stored Granola API key" : `Imported Granola session from ${state.supabasePath ?? "desktop app defaults"}`);
 				printAuthState(state);
 				return 0;
 			}
 			case "logout": {
 				const state = await app.logoutAuth();
-				console.log("Stored Granola session deleted");
+				console.log("Stored Granola credentials deleted");
 				printAuthState(state);
 				return 0;
 			}
@@ -4517,7 +4852,7 @@ const authCommand = {
 			case "status": {
 				const state = await app.inspectAuth();
 				printAuthState(state);
-				return state.storedSessionAvailable ? 0 : 1;
+				return state.apiKeyAvailable || state.storedSessionAvailable || state.supabaseAvailable ? 0 : 1;
 			}
 			case "use": {
 				const mode = resolveAuthMode(value);
@@ -4535,11 +4870,13 @@ const authCommand = {
 };
 function resolveAuthMode(value) {
 	switch (value) {
+		case "api":
+		case "api-key": return "api-key";
 		case "stored":
 		case "stored-session": return "stored-session";
 		case "supabase":
 		case "supabase-file": return "supabase-file";
-		default: throw new Error("invalid auth mode: expected stored or supabase");
+		default: throw new Error("invalid auth mode: expected api-key, stored, or supabase");
 	}
 }
 //#endregion
@@ -4983,7 +5320,12 @@ function renderAppState() {
   }
 
   const appState = state.appState;
-  const authMode = appState.auth.mode === "stored-session" ? "Stored session" : "supabase.json";
+  const authMode =
+    appState.auth.mode === "api-key"
+      ? "API key"
+      : appState.auth.mode === "stored-session"
+        ? "Stored session"
+        : "supabase.json";
   const docs = appState.documents.loaded ? String(appState.documents.count) : "not loaded";
   const cache = appState.cache.loaded
     ? appState.cache.transcriptCount + " transcript sets"
@@ -5103,7 +5445,12 @@ function renderAuthPanel() {
     return;
   }
 
-  const activeSource = auth.mode === "stored-session" ? "Stored session" : "supabase.json";
+  const activeSource =
+    auth.mode === "api-key"
+      ? "API key"
+      : auth.mode === "stored-session"
+        ? "Stored session"
+        : "supabase.json";
   const lastError = auth.lastError
     ? '<div class="auth-card__meta auth-card__error">' + escapeHtml(auth.lastError) + "</div>"
     : "";
@@ -5112,6 +5459,7 @@ function renderAuthPanel() {
     '<div class="auth-card">',
     '<div class="status-grid">',
     '<div><span class="status-label">Active</span><strong>' + escapeHtml(activeSource) + "</strong></div>",
+    '<div><span class="status-label">API key</span><strong>' + escapeHtml(auth.apiKeyAvailable ? "available" : "missing") + "</strong></div>",
     '<div><span class="status-label">Stored</span><strong>' + escapeHtml(auth.storedSessionAvailable ? "available" : "missing") + "</strong></div>",
     '<div><span class="status-label">supabase.json</span><strong>' + escapeHtml(auth.supabaseAvailable ? "available" : "missing") + "</strong></div>",
     '<div><span class="status-label">Refresh</span><strong>' + escapeHtml(auth.refreshAvailable ? "available" : "missing") + "</strong></div>",
@@ -5126,12 +5474,16 @@ function renderAuthPanel() {
       ? '<div class="auth-card__meta">supabase path: ' + escapeHtml(auth.supabasePath) + "</div>"
       : "",
     lastError,
+    '<div class="auth-card__meta">Store a Granola Personal API key here or use <code>granola auth login --api-key &lt;token&gt;</code>.</div>',
     '<div class="auth-card__actions">',
+    '<input class="input" type="password" placeholder="grn_..." data-auth-api-key />',
+    authActionButton("Save API key", "login-api-key", false),
     authActionButton("Import desktop session", "login", !auth.supabaseAvailable),
     authActionButton("Refresh stored session", "refresh", !auth.storedSessionAvailable || !auth.refreshAvailable),
+    authModeButton("Use API key", "api-key", !auth.apiKeyAvailable || auth.mode === "api-key"),
     authModeButton("Use stored session", "stored-session", !auth.storedSessionAvailable || auth.mode === "stored-session"),
     authModeButton("Use supabase.json", "supabase-file", !auth.supabaseAvailable || auth.mode === "supabase-file"),
-    authActionButton("Sign out", "logout", !auth.storedSessionAvailable),
+    authActionButton("Sign out", "logout", !auth.apiKeyAvailable && !auth.storedSessionAvailable),
     "</div>",
     "</div>",
   ].join("");
@@ -5521,14 +5873,19 @@ async function rerunJob(id) {
   }
 }
 
-async function loginAuth() {
-  setStatus("Importing desktop session…", "busy");
+async function loginAuth(apiKey) {
+  setStatus(apiKey ? "Saving API key…" : "Importing desktop session…", "busy");
   try {
-    await fetchJson("/auth/login", { method: "POST" });
+    const body = apiKey ? { apiKey } : undefined;
+    await fetchJson("/auth/login", {
+      body: body ? JSON.stringify(body) : undefined,
+      headers: body ? { "content-type": "application/json" } : undefined,
+      method: "POST",
+    });
     await refreshAll();
   } catch (error) {
     await syncAuthState();
-    setStatus("Auth import failed", "error");
+    setStatus(apiKey ? "API key save failed" : "Auth import failed", "error");
     state.detailError = error instanceof Error ? error.message : String(error);
     renderMeetingDetail();
   }
@@ -5675,6 +6032,17 @@ els.authPanel.addEventListener("click", (event) => {
   const actionButton = event.target.closest("[data-auth-action]");
   if (actionButton) {
     switch (actionButton.dataset.authAction) {
+      case "login-api-key": {
+        const apiKeyInput = els.authPanel.querySelector("[data-auth-api-key]");
+        const apiKey =
+          apiKeyInput && "value" in apiKeyInput ? String(apiKeyInput.value || "").trim() : "";
+        if (!apiKey) {
+          setStatus("Enter a Granola API key", "error");
+          return;
+        }
+        void loginAuth(apiKey);
+        return;
+      }
       case "login":
         void loginAuth();
         return;
@@ -6542,9 +6910,10 @@ function parseMeetingSort(value) {
 }
 function parseAuthMode(value) {
 	switch (value) {
+		case "api-key":
 		case "stored-session":
 		case "supabase-file": return value;
-		default: throw new Error("invalid auth mode: expected stored-session or supabase-file");
+		default: throw new Error("invalid auth mode: expected api-key, stored-session, or supabase-file");
 	}
 }
 function folderIdFromBody(value) {
@@ -6891,8 +7260,12 @@ async function startGranolaServer(app, options = {}) {
 			}
 			if (method === "POST" && path === granolaTransportPaths.authLogin) {
 				const body = await readJsonBody(request);
+				const apiKey = typeof body.apiKey === "string" && body.apiKey.trim() ? body.apiKey.trim() : void 0;
 				const supabasePath = typeof body.supabasePath === "string" && body.supabasePath.trim() ? body.supabasePath.trim() : void 0;
-				sendJson(response, await app.loginAuth({ supabasePath }), { headers: originHeaders });
+				sendJson(response, await app.loginAuth({
+					apiKey,
+					supabasePath
+				}), { headers: originHeaders });
 				return;
 			}
 			if (method === "POST" && path === granolaTransportPaths.authLogout) {
@@ -7911,6 +8284,7 @@ Commands:
 ${commands.map((command) => `  ${command.name.padEnd(commandWidth)}  ${command.description}`).join("\n")}
 
 Global options:
+  --api-key <token>   Granola Personal API key
   --config <path>     Path to .granola.toml
   --debug             Enable debug logging
   --supabase <path>   Path to supabase.json
@@ -7928,6 +8302,7 @@ async function runCli(argv) {
 	try {
 		const { command, rest } = splitCommand(argv);
 		const global = parseFlags(rest, {
+			"api-key": { type: "string" },
 			config: { type: "string" },
 			debug: { type: "boolean" },
 			help: { type: "boolean" },

package/package.json

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