Expose public plugin API (refs #227)

src/api.ts

@@ -0,0 +1,54 @@
+import { TFile } from 'obsidian';
+import type FolderNotesPlugin from './main';
+import { getFolderNote } from './functions/folderNoteFunctions';
+import { getDetachedFolder, getExcludedFolder } from './ExcludeFolders/functions/folderFunctions';
+
+const API_VERSION = '1.0.0';
+
+/**
+ * Public API exposed by the folder-notes plugin on its instance as `plugin.api`.
+ *
+ * External plugins can access it via:
+ *   app.plugins.plugins['folder-notes']?.api
+ *
+ * The API is available after folder-notes has finished onload (settings loaded).
+ * It is safe to call synchronously from any point after layout-ready.
+ */
+export interface FolderNotesApi {
+	/** Semver-ish version string for feature detection. */
+	version: string;
+
+	/**
+	 * Returns the folder note TFile for the given folder path only if the
+	 * folder's note is enabled — i.e., the folder is not detached and not
+	 * excluded with `disableFolderNote`. Matches the plugin's own UI
+	 * gating (the rules that decide whether `.has-folder-note` gets
+	 * applied in the file explorer).
+	 *
+	 * Returns null if:
+	 *   - the folder does not exist or has no folder note
+	 *   - the folder is detached
+	 *   - the folder is excluded with disableFolderNote
+	 */
+	getEnabledFolderNote(folderPath: string): TFile | null;
+}
+
+export function getApi(plugin: FolderNotesPlugin): FolderNotesApi {
+	return {
+		version: getVersion(),
+		getEnabledFolderNote: (folderPath) => getEnabledFolderNote(plugin, folderPath),
+	};
+}
+
+function getVersion(): string {
+	return API_VERSION;
+}
+
+function getEnabledFolderNote(plugin: FolderNotesPlugin, folderPath: string): TFile | null {
+	const note = getFolderNote(plugin, folderPath);
+	if (!note) return null;
+	if (getDetachedFolder(plugin, folderPath)) return null;
+	const excluded = getExcludedFolder(plugin, folderPath, true);
+	if (excluded?.disableFolderNote) return null;
+	return note;
+}

src/main.ts

@@ -11,6 +11,7 @@ import {
 } from './settings/SettingsTab';
 import { Commands } from './Commands';
 import type { FileExplorerWorkspaceLeaf } from './globals';
+import { getApi, type FolderNotesApi } from './api';
 import {
 	registerFileExplorerObserver, unregisterFileExplorerObserver,
 } from './events/MutationObserver';
@@ -49,10 +50,12 @@ export default class FolderNotesPlugin extends Plugin {
 	settingsOpened = false;
 	askModalCurrentlyOpen = false;
 	fvIndexDB: FvIndexDB;
+	api!: FolderNotesApi;
 
 	async onload(): Promise<void> {
 		console.log('loading folder notes plugin');
 		await this.loadSettings();
+		this.api = getApi(this);
 		this.settingsTab = new SettingsTab(this.app, this);
 		this.addSettingTab(this.settingsTab);
 		this.saveSettings();