Merge branch 'master' into vite-migration-setup

Integrate master's PR #124 changes (feed caching and UI accessibility improvements)
with strict TypeScript configuration.

Resolved conflicts by:
- Accepting master's lazy initialization for TranscriptionService via getTranscriptionService()
- Accepting master's new performance settings and feed caching features
- Accepting master's accessibility improvements to UI components
- Applying strict TypeScript fixes: definite assignment assertions (!), optional properties (?),
  and override keywords where required
- Fixing type safety: optional chaining for nullable controller cleanup
- Consolidating imports and removing unused variables to pass linting

All CI checks pass: lint, format:check, typecheck, build, and tests.

Author: chhoumann

src/constants.ts

@@ -70,4 +70,8 @@ export const DEFAULT_SETTINGS: IPodNotesSettings = {
 		template:
 			"# {{title}}\n\nPodcast: {{podcast}}\nDate: {{date}}\n\n{{transcript}}",
 	},
+	feedCache: {
+		enabled: true,
+		ttlHours: 6,
+	},
 };

src/main.ts

@@ -64,7 +64,7 @@ export default class PodNotes extends Plugin implements IPodNotes {
 	private downloadedEpisodesController?: StoreController<{
 		[podcastName: string]: DownloadedEpisode[];
 	}>;
-	private transcriptionService!: TranscriptionService;
+	private transcriptionService?: TranscriptionService;
 
 	private maxLayoutReadyAttempts = 10;
 	private layoutReadyAttempts = 0;
@@ -103,27 +103,22 @@ export default class PodNotes extends Plugin implements IPodNotes {
 			this,
 		).on();
 
-		this.transcriptionService = new TranscriptionService(this);
-
 		this.api = new API();
 
 		this.addCommand({
 			id: "podnotes-show-leaf",
 			name: "Show PodNotes",
 			icon: "podcast" as IconType,
-				checkCallback: function (this: PodNotes, checking: boolean) {
-					if (checking) {
-						return !this.app.workspace.getLeavesOfType(VIEW_TYPE).length;
-					}
-
-					const leaf = this.app.workspace.getRightLeaf(false);
-					if (leaf) {
-						leaf.setViewState({
-							type: VIEW_TYPE,
-						});
-					}
-				}.bind(this),
-			});
+			checkCallback: (checking: boolean) => {
+				if (checking) {
+					return !this.app.workspace.getLeavesOfType(VIEW_TYPE).length;
+				}
+
+				this.app.workspace.getRightLeaf(false)?.setViewState({
+					type: VIEW_TYPE,
+				});
+			},
+		});
 
 		this.addCommand({
 			id: "start-playing",
@@ -268,7 +263,18 @@ export default class PodNotes extends Plugin implements IPodNotes {
 		this.addCommand({
 			id: "podnotes-transcribe",
 			name: "Transcribe current episode",
-			callback: () => this.transcriptionService.transcribeCurrentEpisode(),
+			checkCallback: (checking) => {
+				const canTranscribe =
+					!!this.api.podcast && !!this.settings.openAIApiKey?.trim();
+
+				if (checking) {
+					return canTranscribe;
+				}
+
+				if (canTranscribe) {
+					void this.getTranscriptionService().transcribeCurrentEpisode();
+				}
+			},
 		});
 
 		this.addSettingTab(new PodNotesSettingsTab(this.app, this));
@@ -314,6 +320,14 @@ export default class PodNotes extends Plugin implements IPodNotes {
 		}
 	}
 
+	private getTranscriptionService(): TranscriptionService {
+		if (!this.transcriptionService) {
+			this.transcriptionService = new TranscriptionService(this);
+		}
+
+		return this.transcriptionService;
+	}
+
 	override onunload() {
 		this.playedEpisodeController?.off();
 		this.savedFeedsController?.off();

src/services/FeedCacheService.ts

@@ -0,0 +1,137 @@
+import type { Episode } from "src/types/Episode";
+import type { PodcastFeed } from "src/types/PodcastFeed";
+
+type SerializableEpisode = Omit<Episode, "episodeDate"> & {
+	episodeDate?: string;
+};
+
+interface CachedFeedData {
+	episodes: SerializableEpisode[];
+	updatedAt: number;
+}
+
+type FeedCache = Record<string, CachedFeedData>;
+
+const STORAGE_KEY = "podnotes:feed-cache:v1";
+const DEFAULT_TTL_MS = 1000 * 60 * 60 * 6; // 6 hours.
+const MAX_EPISODES_PER_FEED = 75;
+
+let cache: FeedCache | null = null;
+
+function getStorage(): Storage | null {
+	try {
+		return typeof localStorage === "undefined" ? null : localStorage;
+	} catch (error) {
+		console.error("Unable to access localStorage for feed cache:", error);
+		return null;
+	}
+}
+
+function loadCache(): FeedCache {
+	if (cache) {
+		return cache;
+	}
+
+	const storage = getStorage();
+	if (!storage) {
+		cache = {};
+		return cache;
+	}
+
+	try {
+		const raw = storage.getItem(STORAGE_KEY);
+		if (!raw) {
+			cache = {};
+			return cache;
+		}
+
+		const parsed = JSON.parse(raw) as FeedCache;
+		cache = parsed;
+		return cache;
+	} catch (error) {
+		console.error("Failed to parse feed cache:", error);
+		cache = {};
+		return cache;
+	}
+}
+
+function persistCache(): void {
+	const storage = getStorage();
+	if (!storage) {
+		return;
+	}
+
+	try {
+		storage.setItem(STORAGE_KEY, JSON.stringify(cache ?? {}));
+	} catch (error) {
+		console.error("Failed to persist feed cache:", error);
+	}
+}
+
+function serializeEpisode(episode: Episode): SerializableEpisode {
+	return {
+		...episode,
+		episodeDate: episode.episodeDate?.toISOString(),
+	};
+}
+
+function deserializeEpisode(episode: SerializableEpisode): Episode {
+	return {
+		...episode,
+		episodeDate: episode.episodeDate ? new Date(episode.episodeDate) : undefined,
+	};
+}
+
+function getFeedKey(feed: PodcastFeed): string {
+	return feed.url ?? feed.title;
+}
+
+export function getCachedEpisodes(
+	feed: PodcastFeed,
+	maxAgeMs: number = DEFAULT_TTL_MS,
+): Episode[] | null {
+	const store = loadCache();
+	const cacheKey = getFeedKey(feed);
+	const cachedValue = store[cacheKey];
+
+	if (!cachedValue) {
+		return null;
+	}
+
+	const isExpired = Date.now() - cachedValue.updatedAt > maxAgeMs;
+	if (isExpired) {
+		delete store[cacheKey];
+		persistCache();
+		return null;
+	}
+
+	return cachedValue.episodes.map(deserializeEpisode);
+}
+
+export function setCachedEpisodes(feed: PodcastFeed, episodes: Episode[]): void {
+	if (!episodes.length) {
+		return;
+	}
+
+	const store = loadCache();
+	const cacheKey = getFeedKey(feed);
+
+	store[cacheKey] = {
+		updatedAt: Date.now(),
+		episodes: episodes
+			.slice(0, MAX_EPISODES_PER_FEED)
+			.map(serializeEpisode),
+	};
+
+	persistCache();
+}
+
+export function clearFeedCache(): void {
+	cache = {};
+	const storage = getStorage();
+	try {
+		storage?.removeItem(STORAGE_KEY);
+	} catch (error) {
+		console.error("Failed to clear feed cache:", error);
+	}
+}

src/services/TranscriptionService.ts

@@ -1,5 +1,5 @@
 import { Notice, TFile } from "obsidian";
-import { OpenAI } from "openai";
+import type { OpenAI } from "openai";
 import type PodNotes from "../main";
 import { downloadEpisode } from "../downloadEpisode";
 import {
@@ -8,10 +8,6 @@ import {
 } from "../TemplateEngine";
 import type { Episode } from "src/types/Episode";
 
-function getErrorMessage(error: unknown): string {
-	return error instanceof Error ? error.message : String(error);
-}
-
 function TimerNotice(heading: string, initialMessage: string) {
 	let currentMessage = initialMessage;
 	const startTime = Date.now();
@@ -54,16 +50,13 @@ function formatTime(ms: number): string {
 
 export class TranscriptionService {
 	private plugin: PodNotes;
-	private client: OpenAI;
+	private client: OpenAI | null = null;
+	private cachedApiKey: string | null = null;
 	private MAX_RETRIES = 3;
 	private isTranscribing = false;
 
 	constructor(plugin: PodNotes) {
 		this.plugin = plugin;
-		this.client = new OpenAI({
-			apiKey: this.plugin.settings.openAIApiKey,
-			dangerouslyAllowBrowser: true,
-		});
 	}
 
 	async transcribeCurrentEpisode(): Promise<void> {
@@ -72,6 +65,13 @@ export class TranscriptionService {
 			return;
 		}
 
+		if (!this.plugin.settings.openAIApiKey?.trim()) {
+			new Notice(
+				"Please add your OpenAI API key in the transcript settings first.",
+			);
+			return;
+		}
+
 		const currentEpisode = this.plugin.api.podcast;
 		if (!currentEpisode) {
 			new Notice("No episode is currently playing.");
@@ -128,9 +128,10 @@ export class TranscriptionService {
 
 			notice.stop();
 			notice.update("Transcription completed and saved.");
-		} catch (error: unknown) {
+		} catch (error) {
 			console.error("Transcription error:", error);
-			notice.update(`Transcription failed: ${getErrorMessage(error)}`);
+			const message = error instanceof Error ? error.message : String(error);
+			notice.update(`Transcription failed: ${message}`);
 		} finally {
 			this.isTranscribing = false;
 			setTimeout(() => notice.hide(), 5000);
@@ -182,6 +183,7 @@ export class TranscriptionService {
 		files: File[],
 		updateNotice: (message: string) => void,
 	): Promise<string> {
+		const client = await this.getClient();
 		const transcriptions: string[] = new Array(files.length);
 		let completedChunks = 0;
 
@@ -199,15 +201,15 @@ export class TranscriptionService {
 				let retries = 0;
 				while (retries < this.MAX_RETRIES) {
 					try {
-						const result = await this.client.audio.transcriptions.create({
+						const result = await client.audio.transcriptions.create({
 							model: "whisper-1",
 							file,
 						});
 						transcriptions[index] = result.text;
 						completedChunks++;
 						updateProgress();
 						break;
-					} catch (error: unknown) {
+					} catch (error) {
 						retries++;
 						if (retries >= this.MAX_RETRIES) {
 							console.error(
@@ -265,4 +267,24 @@ export class TranscriptionService {
 			throw new Error("Expected a file but got a folder");
 		}
 	}
+
+	private async getClient(): Promise<OpenAI> {
+		const apiKey = this.plugin.settings.openAIApiKey?.trim();
+		if (!apiKey) {
+			throw new Error("Missing OpenAI API key");
+		}
+
+		if (this.client && this.cachedApiKey === apiKey) {
+			return this.client;
+		}
+
+		const { OpenAI } = await import("openai");
+		this.client = new OpenAI({
+			apiKey,
+			dangerouslyAllowBrowser: true,
+		});
+		this.cachedApiKey = apiKey;
+
+		return this.client;
+	}
 }

src/types/IPodNotesSettings.ts

@@ -36,4 +36,8 @@ export interface IPodNotesSettings {
 		path: string;
 		template: string;
 	};
+	feedCache: {
+		enabled: boolean;
+		ttlHours: number;
+	};
 }

src/ui/PodcastView/EpisodeList.svelte

@@ -50,11 +50,14 @@
 			<Icon
 				icon={hidePlayedEpisodes ? "eye-off" : "eye"}
 				size={25}
+				label={hidePlayedEpisodes ? "Show played episodes" : "Hide played episodes"}
+				pressed={hidePlayedEpisodes}
 				on:click={() => (hidePlayedEpisodes = !hidePlayedEpisodes)}
 			/>
 			<Icon
 				icon="refresh-cw"
 				size={25}
+				label="Refresh episodes"
 				on:click={() => dispatch("clickRefresh")}
 			/>
 		</div>