granola-toolkit 0.23.0 → 0.24.0

package/README.md

@@ -197,6 +197,7 @@ The initial server API includes:
 - `GET /state`
 - `GET /events` for server-sent state updates
 - `GET /meetings`
+- `GET /meetings?refresh=true` to bypass the local meeting index and force a live refresh
 - `GET /meetings/resolve?q=<query>`
 - `GET /meetings/:id`
 - `GET /exports/jobs`
@@ -217,6 +218,7 @@ This is the foundation for the future `granola web` client and any attachable TU
 The initial browser client includes:
 
 - a searchable meeting list
+- a fast local-index warm start for meeting browsing before live documents finish loading
 - sort and updated-date filters
 - quick open by meeting id or title
 - a focused meeting workspace with notes, transcript, metadata, and raw tabs
@@ -227,6 +229,18 @@ The initial browser client includes:
 - a recent export-jobs panel with rerun actions
 - stronger empty and error states for list/detail failures
 
+### Local Meeting Index
+
+Interactive meeting browsing now keeps a local index of meeting summaries and metadata.
+
+That index is used to:
+
+- make the web meeting list available quickly on startup
+- keep search, sort, and date filtering useful before every live document payload is fetched again
+- refresh itself after successful live loads so the next run starts warm
+
+The web client uses the index as a fast path and upgrades to live data automatically when the background refresh completes. The manual Refresh button bypasses the index and forces a live meeting fetch immediately.
+
 ### Export Jobs
 
 Exports are now tracked as jobs with:

package/dist/cli.js

@@ -1419,6 +1419,20 @@ function compareMeetingDocumentsBySort(left, right, sort) {
 		default: return compareMeetingDocuments(left, right);
 	}
 }
+function compareMeetingSummariesByUpdated(left, right) {
+	return compareTimestampsDescending(left.updatedAt, right.updatedAt) || compareTimestampsDescending(left.createdAt, right.createdAt) || compareStrings(left.title || left.id, right.title || right.id) || compareStrings(left.id, right.id);
+}
+function compareMeetingSummariesByTitle(left, right) {
+	return compareStrings(left.title || left.id, right.title || right.id) || compareTimestampsDescending(left.updatedAt, right.updatedAt) || compareStrings(left.id, right.id);
+}
+function compareMeetingSummariesBySort(left, right, sort) {
+	switch (sort) {
+		case "title-asc": return compareMeetingSummariesByTitle(left, right);
+		case "title-desc": return -compareMeetingSummariesByTitle(left, right);
+		case "updated-asc": return -compareMeetingSummariesByUpdated(left, right);
+		default: return compareMeetingSummariesByUpdated(left, right);
+	}
+}
 function serialiseNote(note) {
 	return {
 		content: note.content,
@@ -1482,6 +1496,15 @@ function matchesMeetingSearch(document, search) {
 		...document.tags
 	].some((value) => value.toLowerCase().includes(query));
 }
+function matchesMeetingSummarySearch(meeting, search) {
+	const query = search.trim().toLowerCase();
+	if (!query) return true;
+	return [
+		meeting.id,
+		meeting.title,
+		...meeting.tags
+	].some((value) => value.toLowerCase().includes(query));
+}
 function parseDateFilter(value, label) {
 	const trimmed = value?.trim();
 	if (!trimmed) return;
@@ -1499,6 +1522,15 @@ function matchesUpdatedRange(document, updatedFrom, updatedTo) {
 	if (to != null && updatedAt > to) return false;
 	return true;
 }
+function matchesMeetingSummaryUpdatedRange(meeting, updatedFrom, updatedTo) {
+	const from = parseDateFilter(updatedFrom, "updatedFrom");
+	const to = parseDateFilter(updatedTo, "updatedTo");
+	const updatedAt = parseTimestamp(meeting.updatedAt || meeting.createdAt);
+	if (updatedAt == null) return from == null && to == null;
+	if (from != null && updatedAt < from) return false;
+	if (to != null && updatedAt > to) return false;
+	return true;
+}
 function truncate(value, width) {
 	if (value.length <= width) return value.padEnd(width);
 	return `${value.slice(0, Math.max(0, width - 1))}…`;
@@ -1554,6 +1586,14 @@ function listMeetings(documents, options = {}) {
 	const sort = options.sort ?? "updated-desc";
 	return documents.filter((document) => options.search ? matchesMeetingSearch(document, options.search) : true).filter((document) => matchesUpdatedRange(document, options.updatedFrom, options.updatedTo)).sort((left, right) => compareMeetingDocumentsBySort(left, right, sort)).slice(0, limit).map((document) => buildMeetingSummary(document, options.cacheData));
 }
+function filterMeetingSummaries(meetings, options = {}) {
+	const limit = options.limit ?? 20;
+	const sort = options.sort ?? "updated-desc";
+	return meetings.filter((meeting) => options.search ? matchesMeetingSummarySearch(meeting, options.search) : true).filter((meeting) => matchesMeetingSummaryUpdatedRange(meeting, options.updatedFrom, options.updatedTo)).sort((left, right) => compareMeetingSummariesBySort(left, right, sort)).slice(0, limit).map((meeting) => ({
+		...meeting,
+		tags: [...meeting.tags]
+	}));
+}
 function resolveMeetingQuery(documents, query) {
 	const trimmed = query.trim();
 	if (!trimmed) throw new Error("meeting query is required");
@@ -1640,6 +1680,48 @@ function renderMeetingTranscript(document, cacheData, format = "text") {
 	return renderTranscriptExport(transcript, format);
 }
 //#endregion
+//#region src/meeting-index.ts
+const MEETING_INDEX_VERSION = 1;
+var FileMeetingIndexStore = class {
+	constructor(filePath = defaultMeetingIndexFilePath()) {
+		this.filePath = filePath;
+	}
+	async readIndex() {
+		try {
+			const parsed = parseJsonString(await readFile(this.filePath, "utf8"));
+			if (!parsed || parsed.version !== MEETING_INDEX_VERSION || !Array.isArray(parsed.meetings)) return [];
+			return parsed.meetings.map((meeting) => ({
+				...meeting,
+				tags: [...meeting.tags]
+			}));
+		} catch {
+			return [];
+		}
+	}
+	async writeIndex(meetings) {
+		await mkdir(dirname(this.filePath), { recursive: true });
+		const payload = {
+			meetings: meetings.map((meeting) => ({
+				...meeting,
+				tags: [...meeting.tags]
+			})),
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			version: MEETING_INDEX_VERSION
+		};
+		await writeFile(this.filePath, `${JSON.stringify(payload, null, 2)}\n`, {
+			encoding: "utf8",
+			mode: 384
+		});
+	}
+};
+function defaultMeetingIndexFilePath() {
+	const home = homedir();
+	return platform() === "darwin" ? join(home, "Library", "Application Support", "granola-toolkit", "meeting-index.json") : join(home, ".config", "granola-toolkit", "meeting-index.json");
+}
+function createDefaultMeetingIndexStore() {
+	return new FileMeetingIndexStore();
+}
+//#endregion
 //#region src/app/core.ts
 function transcriptCount(cacheData) {
 	return Object.values(cacheData.transcripts).filter((segments) => segments.length > 0).length;
@@ -1665,6 +1747,7 @@ function cloneState(state) {
 			notes: cloneExportState(state.exports.notes),
 			transcripts: cloneExportState(state.exports.transcripts)
 		},
+		index: { ...state.index },
 		ui: { ...state.ui }
 	};
 }
@@ -1688,6 +1771,12 @@ function defaultState(config, auth, surface) {
 			loaded: false
 		},
 		exports: { jobs: [] },
+		index: {
+			available: false,
+			filePath: defaultMeetingIndexFilePath(),
+			loaded: false,
+			meetingCount: 0
+		},
 		ui: {
 			surface,
 			view: "idle"
@@ -1699,13 +1788,26 @@ var GranolaApp = class {
 	#cacheResolved = false;
 	#granolaClient;
 	#documents;
+	#meetingIndex;
 	#listeners = /* @__PURE__ */ new Set();
+	#refreshingMeetingIndex;
 	#state;
 	constructor(config, deps, options = {}) {
 		this.config = config;
 		this.deps = deps;
 		this.#state = defaultState(config, deps.auth, options.surface ?? "cli");
 		this.#state.exports.jobs = (deps.exportJobs ?? []).map((job) => cloneExportJob(job));
+		this.#meetingIndex = (deps.meetingIndex ?? []).map((meeting) => ({
+			...meeting,
+			tags: [...meeting.tags]
+		}));
+		this.#state.index = {
+			available: this.#meetingIndex.length > 0,
+			filePath: defaultMeetingIndexFilePath(),
+			loaded: this.#meetingIndex.length > 0,
+			loadedAt: this.#meetingIndex.length > 0 ? this.nowIso() : void 0,
+			meetingCount: this.#meetingIndex.length
+		};
 	}
 	getState() {
 		return cloneState(this.#state);
@@ -1742,6 +1844,41 @@ var GranolaApp = class {
 		this.emitStateUpdate();
 		return { ...auth };
 	}
+	async persistMeetingIndex(meetings) {
+		this.#meetingIndex = meetings.map((meeting) => ({
+			...meeting,
+			tags: [...meeting.tags]
+		}));
+		this.#state.index = {
+			available: this.#meetingIndex.length > 0,
+			filePath: this.#state.index.filePath,
+			loaded: this.#meetingIndex.length > 0,
+			loadedAt: this.#meetingIndex.length > 0 ? this.nowIso() : void 0,
+			meetingCount: this.#meetingIndex.length
+		};
+		if (this.deps.meetingIndexStore) await this.deps.meetingIndexStore.writeIndex(this.#meetingIndex);
+		this.emitStateUpdate();
+	}
+	async refreshMeetingIndexFromLiveData() {
+		const cacheData = await this.loadCache();
+		const documents = await this.listDocuments();
+		const meetings = listMeetings(documents, {
+			cacheData,
+			limit: documents.length || 1,
+			sort: "updated-desc"
+		});
+		await this.persistMeetingIndex(meetings);
+	}
+	triggerMeetingIndexRefresh() {
+		if (this.#refreshingMeetingIndex) return;
+		this.#refreshingMeetingIndex = (async () => {
+			try {
+				await this.refreshMeetingIndexFromLiveData();
+			} catch {} finally {
+				this.#refreshingMeetingIndex = void 0;
+			}
+		})();
+	}
 	nowIso() {
 		return (this.deps.now ?? (() => /* @__PURE__ */ new Date()))().toISOString();
 	}
@@ -1875,7 +2012,16 @@ var GranolaApp = class {
 			throw error;
 		}
 	}
-	async listDocuments() {
+	async listDocuments(options = {}) {
+		if (options.forceRefresh) {
+			this.#granolaClient = void 0;
+			this.#documents = void 0;
+			this.#state.documents = {
+				count: 0,
+				loaded: false
+			};
+			this.emitStateUpdate();
+		}
 		if (this.#documents) return this.#documents;
 		const documents = await (await this.getGranolaClient()).listDocuments({ timeoutMs: this.config.notes.timeoutMs });
 		this.#documents = documents;
@@ -1915,15 +2061,41 @@ var GranolaApp = class {
 		return cacheData;
 	}
 	async listMeetings(options = {}) {
-		const meetings = listMeetings(await this.listDocuments(), {
-			cacheData: await this.loadCache(),
+		const preferIndex = options.preferIndex ?? (this.#state.ui.surface === "web" || this.#state.ui.surface === "server");
+		if (!options.forceRefresh && preferIndex && !this.#documents && this.#meetingIndex.length > 0) {
+			const meetings = filterMeetingSummaries(this.#meetingIndex, options);
+			this.setUiState({
+				meetingListSource: "index",
+				meetingSearch: options.search,
+				meetingSort: options.sort,
+				meetingUpdatedFrom: options.updatedFrom,
+				meetingUpdatedTo: options.updatedTo,
+				selectedMeetingId: void 0,
+				view: "meeting-list"
+			});
+			this.triggerMeetingIndexRefresh();
+			return {
+				meetings,
+				source: "index"
+			};
+		}
+		const cacheData = await this.loadCache();
+		const documents = await this.listDocuments({ forceRefresh: options.forceRefresh });
+		const meetings = listMeetings(documents, {
+			cacheData,
 			limit: options.limit,
 			search: options.search,
 			sort: options.sort,
 			updatedFrom: options.updatedFrom,
 			updatedTo: options.updatedTo
 		});
+		await this.persistMeetingIndex(listMeetings(documents, {
+			cacheData,
+			limit: Math.max(documents.length, 1),
+			sort: "updated-desc"
+		}));
 		this.setUiState({
+			meetingListSource: "live",
 			meetingSearch: options.search,
 			meetingSort: options.sort,
 			meetingUpdatedFrom: options.updatedFrom,
@@ -1931,7 +2103,10 @@ var GranolaApp = class {
 			selectedMeetingId: void 0,
 			view: "meeting-list"
 		});
-		return meetings;
+		return {
+			meetings,
+			source: "live"
+		};
 	}
 	async getMeeting(id, options = {}) {
 		const documents = await this.listDocuments();
@@ -2076,13 +2251,17 @@ async function createGranolaApp(config, options = {}) {
 	const auth = await inspectDefaultGranolaAuth(config);
 	const authController = createDefaultGranolaAuthController(config);
 	const exportJobStore = createDefaultExportJobStore();
+	const exportJobs = await exportJobStore.readJobs();
+	const meetingIndexStore = createDefaultMeetingIndexStore();
 	return new GranolaApp(config, {
 		auth,
 		authController,
 		cacheLoader: loadOptionalGranolaCache,
 		createGranolaClient: async (mode) => await createDefaultGranolaRuntime(config, options.logger, { preferredMode: mode }),
-		exportJobs: await exportJobStore.readJobs(),
+		exportJobs,
 		exportJobStore,
+		meetingIndex: await meetingIndexStore.readIndex(),
+		meetingIndexStore,
 		now: options.now
 	}, { surface: options.surface });
 }
@@ -2527,12 +2706,13 @@ async function list(commandFlags, globalFlags) {
 	debug(config.debug, "timeoutMs", config.notes.timeoutMs);
 	const app = await createGranolaApp(config);
 	debug(config.debug, "authMode", app.getState().auth.mode);
-	console.log("Fetching meetings from Granola API...");
-	const meetings = await app.listMeetings({
+	console.log("Loading meetings...");
+	const result = await app.listMeetings({
 		limit,
 		search
 	});
-	console.log(renderMeetingList(meetings, format).trimEnd());
+	console.log(result.source === "index" ? "Loaded meetings from the local index" : "Fetched meetings from Granola API");
+	console.log(renderMeetingList(result.meetings, format).trimEnd());
 	return 0;
 }
 async function view(id, commandFlags, globalFlags) {
@@ -2675,6 +2855,7 @@ const state = {
   selectedMeeting: null,
   selectedMeetingBundle: null,
   selectedMeetingId: null,
+  meetingSource: "live",
   sort: "updated-desc",
   updatedFrom: "",
   updatedTo: "",
@@ -2762,6 +2943,11 @@ function renderAppState() {
     : appState.cache.configured
       ? "configured"
       : "not configured";
+  const indexStatus = appState.index.loaded
+    ? appState.index.meetingCount + " meetings"
+    : appState.index.available
+      ? "available"
+      : "not built";
 
   els.appState.innerHTML = [
     '<div class="status-grid">',
@@ -2770,6 +2956,7 @@ function renderAppState() {
     '<div><span class="status-label">Auth</span><strong>' + escapeHtml(authMode) + "</strong></div>",
     '<div><span class="status-label">Documents</span><strong>' + escapeHtml(docs) + "</strong></div>",
     '<div><span class="status-label">Cache</span><strong>' + escapeHtml(cache) + "</strong></div>",
+    '<div><span class="status-label">Index</span><strong>' + escapeHtml(indexStatus) + "</strong></div>",
     "</div>",
   ].join("");
 
@@ -2999,7 +3186,7 @@ async function fetchJson(path, init) {
   return payload;
 }
 
-function buildMeetingsQuery(limit = 100) {
+function buildMeetingsQuery(limit = 100, refresh = false) {
   const params = new URLSearchParams();
   params.set("limit", String(limit));
   params.set("sort", state.sort);
@@ -3016,16 +3203,22 @@ function buildMeetingsQuery(limit = 100) {
     params.set("updatedTo", state.updatedTo);
   }
 
+  if (refresh) {
+    params.set("refresh", "true");
+  }
+
   return "?" + params.toString();
 }
 
 async function loadMeetings(options = {}) {
   const preferredMeetingId = options.preferredMeetingId || state.selectedMeetingId;
+  const refresh = options.refresh === true;
 
   try {
     state.listError = "";
-    const payload = await fetchJson("/meetings" + buildMeetingsQuery());
+    const payload = await fetchJson("/meetings" + buildMeetingsQuery(100, refresh));
     state.meetings = payload.meetings || [];
+    state.meetingSource = payload.source || "live";
 
     if (preferredMeetingId && state.meetings.some((meeting) => meeting.id === preferredMeetingId)) {
       state.selectedMeetingId = preferredMeetingId;
@@ -3094,15 +3287,19 @@ async function quickOpenMeeting() {
   }
 }
 
-async function refreshAll() {
+async function refreshAll(forceLiveMeetings = false) {
   setStatus("Refreshing…", "busy");
-  const [appState, authState] = await Promise.all([fetchJson("/state"), fetchJson("/auth/status"), loadMeetings()]);
+  const [appState, authState] = await Promise.all([
+    fetchJson("/state"),
+    fetchJson("/auth/status"),
+    loadMeetings({ refresh: forceLiveMeetings }),
+  ]);
   state.appState = {
     ...appState,
     auth: authState,
   };
   renderAppState();
-  setStatus("Connected", "ok");
+  setStatus(forceLiveMeetings ? "Live data refreshed" : state.meetingSource === "index" ? "Loaded from index" : "Connected", "ok");
 }
 
 async function syncAuthState() {
@@ -3258,7 +3455,7 @@ els.authPanel.addEventListener("click", (event) => {
 });
 
 els.refreshButton.addEventListener("click", () => {
-  void refreshAll();
+  void refreshAll(true);
 });
 
 els.noteButton.addEventListener("click", () => {
@@ -3383,9 +3580,20 @@ document.addEventListener("keydown", (event) => {
 
 const events = new EventSource("/events");
 events.addEventListener("state.updated", (event) => {
+  const previousLoadedAt = state.appState?.documents?.loadedAt;
   const payload = JSON.parse(event.data);
   state.appState = payload.state;
   renderAppState();
+
+  if (
+    state.meetingSource === "index" &&
+    payload.state.documents?.loadedAt &&
+    payload.state.documents.loadedAt !== previousLoadedAt
+  ) {
+    void loadMeetings({
+      preferredMeetingId: state.selectedMeetingId,
+    });
+  }
 });
 events.addEventListener("error", () => {
   setStatus("Disconnected", "error");
@@ -4115,19 +4323,24 @@ async function startGranolaServer(app, options = {}) {
 			}
 			if (method === "GET" && path === "/meetings") {
 				const limit = parseInteger(url.searchParams.get("limit"));
+				const refresh = url.searchParams.get("refresh") === "true";
 				const search = url.searchParams.get("search")?.trim() || void 0;
 				const sort = parseMeetingSort(url.searchParams.get("sort"));
 				const updatedFrom = url.searchParams.get("updatedFrom")?.trim() || void 0;
 				const updatedTo = url.searchParams.get("updatedTo")?.trim() || void 0;
+				const result = await app.listMeetings({
+					forceRefresh: refresh,
+					limit,
+					search,
+					sort,
+					updatedFrom,
+					updatedTo
+				});
 				sendJson(response, {
-					meetings: await app.listMeetings({
-						limit,
-						search,
-						sort,
-						updatedFrom,
-						updatedTo
-					}),
+					meetings: result.meetings,
+					refresh,
 					search,
+					source: result.source,
 					sort,
 					updatedFrom,
 					updatedTo

package/package.json

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