obsidian-launcher 0.3.1 → 0.4.1

package/dist/index.d.cts

@@ -11,6 +11,10 @@ type ObsidianVersionInfos = {
     };
     versions: ObsidianVersionInfo[];
 };
+/**
+ * Metadata about a specific Obsidian version, including the min/max compatible installer versions, download urls, and
+ * the internal electron version.
+ */
 type ObsidianVersionInfo = {
     version: string;
     minInstallerVersion?: string;
@@ -29,6 +33,9 @@ type ObsidianVersionInfo = {
     chromeVersion?: string;
     nodeVersion?: string;
 };
+/**
+ * Schema of entries in https://github.com/obsidianmd/obsidian-releases/HEAD/community-plugins.json
+ */
 type ObsidianCommunityPlugin = {
     id: string;
     name: string;
@@ -36,6 +43,9 @@ type ObsidianCommunityPlugin = {
     description: string;
     repo: string;
 };
+/**
+ * Schema of entries in https://github.com/obsidianmd/obsidian-releases/HEAD/community-css-themes.json
+ */
 type ObsidianCommunityTheme = {
     name: string;
     author: string;
@@ -43,25 +53,34 @@ type ObsidianCommunityTheme = {
     screenshot: string;
     modes: string[];
 };
+/** @inline */
 type BasePluginEntry = {
     /** Set false to install the plugin but start it disabled. Default true. */
     enabled?: boolean;
 };
+/** @inline */
 type LocalPluginEntry = BasePluginEntry & {
     /** Path on disk to the plugin to install. */
     path: string;
 };
-type DownloadedPluginEntry = LocalPluginEntry & {
+type DownloadedPluginEntry = {
+    /** If the plugin is enabled */
+    enabled: boolean;
+    /** Path on disk to the downloaded plugin. */
+    path: string;
+    /** Id of the plugin */
     id: string;
     /** Type of the plugin entry before downloading */
     originalType: "local" | "github" | "community";
 };
+/** @inline */
 type GitHubPluginEntry = BasePluginEntry & {
     /** Github repo of the plugin to install, e.g. "some-user/some-plugin". */
     repo: string;
     /** Version of the plugin to install. Defaults to latest. */
     version?: string;
 };
+/** @inline */
 type CommunityPluginEntry = BasePluginEntry & {
     /** Plugin ID to install from Obsidian community plugins. */
     id: string;
@@ -70,11 +89,15 @@ type CommunityPluginEntry = BasePluginEntry & {
 };
 /**
  * A plugin to install. Can be a simple string path to the local plugin to install, or an object.
- * If an object set one of `path` (to install a local plugin), `repo` (to install a plugin from github), or `id` (to
- * install a community plugin). You can also pass `enabled: false` to install the plugin, but start it disabled by
- * default.
+ * If an object set one of:
+ * - `path` to install a local plugin
+ * - `repo` to install a plugin from github
+ * - `id` to install a community plugin
+ *
+ * You can also pass `enabled: false` to install the plugin, but start it disabled by default.
  */
 type PluginEntry = string | LocalPluginEntry | GitHubPluginEntry | CommunityPluginEntry;
+/** @inline */
 type BaseThemeEntry = {
     /**
      * Set false to install the theme but not enable it. Defaults to true.
@@ -82,84 +105,111 @@ type BaseThemeEntry = {
      */
     enabled?: boolean;
 };
+/** @inline */
 type LocalThemeEntry = BaseThemeEntry & {
     /** Path on disk to the theme to install. */
     path: string;
 };
-type DownloadedThemeEntry = LocalPluginEntry & {
+type DownloadedThemeEntry = {
+    /** If the theme is enabled */
+    enabled: boolean;
+    /** Path on disk to the downloaded theme. */
+    path: string;
+    /** Name of the theme */
     name: string;
-    /** Type of the plugin entry before downloading */
+    /** Type of the theme entry before downloading */
     originalType: "local" | "github" | "community";
 };
+/** @inline */
 type GitHubThemeEntry = BaseThemeEntry & {
     /** Github repo of the theme to install, e.g. "some-user/some-theme". */
     repo: string;
 };
+/** @inline */
 type CommunityThemeEntry = BaseThemeEntry & {
     /** Theme name to install from Obsidian community themes. */
     name: string;
 };
 /**
  * A theme to install. Can be a simple string path to the local theme to install, or an object.
- * If an object, set one of `path` (to install a local theme), `repo` (to install a theme from github), or `name` (to
- * install a community theme). You can also pass `enabled: false` to install the theme, but start it disabled by
- * default. You can only have one enabled theme, so if you pass multiple you'll have to disable all but one.
+ * If an object, set one of:
+ * - `path` to install a local theme
+ * - `repo` to install a theme from github
+ * - `name` to install a community theme
+ *
+ * You can also pass `enabled: false` to install the theme, but start it disabled by default. You can only have one
+ * enabled theme, so if you pass multiple you need to disable all but one.
  */
 type ThemeEntry = string | LocalThemeEntry | GitHubThemeEntry | CommunityThemeEntry;
 
 /**
- * Handles downloading Obsidian versions, plugins, and themes and launching obsidian with sandboxed configuration.
+ * Helper class that handles downloading and installing Obsidian versions, plugins, and themes and launching Obsidian
+ * with sandboxed configuration directories.
  */
 declare class ObsidianLauncher {
     readonly cacheDir: string;
     readonly versionsUrl: string;
     readonly communityPluginsUrl: string;
     readonly communityThemesUrl: string;
+    readonly cacheDuration: number;
     /** Cached metadata files and requests */
     private metadataCache;
     /**
      * Construct an ObsidianLauncher.
-     * @param cacheDir Path to the cache directory. Defaults to "OBSIDIAN_CACHE" env var or ".obsidian-cache".
-     * @param versionsUrl Custom `obsidian-versions.json` url. Can be a file URL.
-     * @param communityPluginsUrl Custom `community-plugins.json` url. Can be a file URL.
-     * @param communityThemes Custom `community-css-themes.json` url. Can be a file URL.
+     * @param options.cacheDir Path to the cache directory. Defaults to "OBSIDIAN_CACHE" env var or ".obsidian-cache".
+     * @param options.versionsUrl Custom `obsidian-versions.json` url. Can be a file URL.
+     * @param options.communityPluginsUrl Custom `community-plugins.json` url. Can be a file URL.
+     * @param options.communityThemesUrl Custom `community-css-themes.json` url. Can be a file URL.
+     * @param options.cacheDuration If the cached version list is older than this (in ms), refetch it. Defaults to 30 minutes.
      */
     constructor(options?: {
         cacheDir?: string;
         versionsUrl?: string;
         communityPluginsUrl?: string;
         communityThemesUrl?: string;
+        cacheDuration?: number;
     });
     /**
      * Returns file content fetched from url as JSON. Caches content to dest and uses that cache if its more recent than
      * cacheDuration ms or if there are network errors.
      */
     private cachedFetch;
+    /**
+     * Get parsed content of the current project's manifest.json
+     */
     private getRootManifest;
-    /** Get information about all available Obsidian versions. */
+    /**
+     * Get information about all available Obsidian versions.
+     */
     getVersions(): Promise<ObsidianVersionInfo[]>;
-    /** Get information about all available community plugins. */
+    /**
+     * Get information about all available community plugins.
+     */
     getCommunityPlugins(): Promise<ObsidianCommunityPlugin[]>;
-    /** Get information about all available community themes. */
+    /**
+     * Get information about all available community themes.
+     */
     getCommunityThemes(): Promise<ObsidianCommunityTheme[]>;
     /**
      * Resolves Obsidian app and installer version strings to absolute versions.
-     * @param appVersion Obsidian version string or "latest", "latest-beta" or "earliest". "earliest" will use the
-     *     minAppVersion set in your manifest.json.
-     * @param installerVersion Obsidian version string or "latest" or "earliest". "earliest" will use the minimum
-     *     installer version compatible with the appVersion.
+     * @param appVersion Obsidian version string or one of
+     *   - "latest": Get the current latest non-beta Obsidian version
+     *   - "latest-beta": Get the current latest beta Obsidian version (or latest is there is no current beta)
+     *   - "earliest": Get the `minAppVersion` set in set in your `manifest.json`
+     * @param installerVersion Obsidian version string or one of
+     *   - "latest": Get the latest Obsidian installer
+     *   - "earliest": Get the oldest Obsidian installer compatible with the specified Obsidian app version
      * @returns [appVersion, installerVersion] with any "latest" etc. resolved to specific versions.
      */
     resolveVersions(appVersion: string, installerVersion?: string): Promise<[string, string]>;
     /**
      * Gets details about an Obsidian version.
-     * @param version Obsidian version string or "latest", "earliest", or "latest-beta". "earliest" will use the
-     *     minAppVersion set in your manifest.json.
+     * @param appVersion Obsidian app version (see {@link resolveVersions} for format)
      */
-    getVersionInfo(version: string): Promise<ObsidianVersionInfo>;
+    getVersionInfo(appVersion: string): Promise<ObsidianVersionInfo>;
     /**
      * Downloads the Obsidian installer for the given version and platform. Returns the file path.
-     * @param installerVersion Version to download.
+     * @param installerVersion Obsidian installer version to download. (see {@link resolveVersions} for format)
      */
     downloadInstaller(installerVersion: string): Promise<string>;
     /**
@@ -169,7 +219,11 @@ declare class ObsidianLauncher {
     private downloadInstallerFromVersionInfo;
     /**
      * Downloads the Obsidian asar for the given version and platform. Returns the file path.
-     * @param appVersion Version to download.
+     *
+     * To download beta versions you'll need to have an Obsidian account with Catalyst and set the `OBSIDIAN_USERNAME`
+     * and `OBSIDIAN_PASSWORD` environment variables. 2FA needs to be disabled.
+     *
+     * @param appVersion Obsidian version to download (see {@link resolveVersions} for format)
      */
     downloadApp(appVersion: string): Promise<string>;
     /**
@@ -177,10 +231,11 @@ declare class ObsidianLauncher {
      *
      * wdio will download chromedriver from the Chrome for Testing API automatically (see
      * https://github.com/GoogleChromeLabs/chrome-for-testing#json-api-endpoints). However, Google has only put
-     * chromedriver since v115.0.5763.0 in that API, so wdio can't download older versions of chromedriver. As of
-     * Obsidian v1.7.7, minInstallerVersion is v0.14.5 which runs on chromium v100.0.4896.75. Here we download
-     * chromedriver for older versions ourselves using the @electron/get package which fetches it from
-     * https://github.com/electron/electron/releases.
+     * chromedriver since v115.0.5763.0 in that API, so wdio can't automatically download older versions of chromedriver
+     * for old Electron versions. Here we download chromedriver for older versions ourselves using the @electron/get
+     * package which fetches chromedriver from https://github.com/electron/electron/releases.
+     *
+     * @param installerVersion Obsidian installer version (see {@link resolveVersions} for format)
      */
     downloadChromedriver(installerVersion: string): Promise<string>;
     /** Gets the latest version of a plugin. */
@@ -200,11 +255,13 @@ declare class ObsidianLauncher {
      */
     private downloadCommunityPlugin;
     /**
-     * Downloads a list of plugins to the cache and returns a list of LocalPluginEntry with the downloaded paths.
+     * Downloads a list of plugins to the cache and returns a list of `DownloadedPluginEntry` with the downloaded paths.
      * Also adds the `id` property to the plugins based on the manifest.
      *
      * You can download plugins from GitHub using `{repo: "org/repo"}` and community plugins using `{id: 'plugin-id'}`.
      * Local plugins will just be passed through.
+     *
+     * @param plugins List of plugins to download.
      */
     downloadPlugins(plugins: PluginEntry[]): Promise<DownloadedPluginEntry[]>;
     /** Gets the latest version of a theme. */
@@ -222,33 +279,35 @@ declare class ObsidianLauncher {
      */
     private downloadCommunityTheme;
     /**
-     * Downloads a list of themes to the cache and returns a list of LocalThemeEntry with the downloaded paths.
+     * Downloads a list of themes to the cache and returns a list of `DownloadedThemeEntry` with the downloaded paths.
      * Also adds the `name` property to the plugins based on the manifest.
      *
      * You can download themes from GitHub using `{repo: "org/repo"}` and community themes using `{name: 'theme-name'}`.
      * Local themes will just be passed through.
+     *
+     * @param themes List of themes to download
      */
     downloadThemes(themes: ThemeEntry[]): Promise<DownloadedThemeEntry[]>;
     /**
-     * Installs plugins into an Obsidian vault.
-     * @param vault Path to the vault to install the plugin in.
-     * @param plugins List plugins paths to install.
+     * Installs plugins into an Obsidian vault
+     * @param vault Path to the vault to install the plugins in
+     * @param plugins List plugins to install
      */
     installPlugins(vault: string, plugins: PluginEntry[]): Promise<void>;
     /**
-     * Installs themes into an obsidian vault.
-     * @param vault Path to the theme to install the plugin in.
-     * @param themes: List of themes to install.
+     * Installs themes into an Obsidian vault
+     * @param vault Path to the theme to install the themes in
+     * @param themes List of themes to install
      */
     installThemes(vault: string, themes: ThemeEntry[]): Promise<void>;
     /**
-     * Sets up the config dir to use for the --user-data-dir in obsidian. Returns the path to the created config dir.
+     * Sets up the config dir to use for the `--user-data-dir` in obsidian. Returns the path to the created config dir.
      *
-     * @param appVersion Obsidian version string.
-     * @param installerVersion Obsidian version string.
-     * @param appPath Path to the asar file to install. Will download if omitted.
-     * @param vault Path to the vault to open in Obsidian.
-     * @param dest Destination path for the config dir. If omitted it will create it under `/tmp`.
+     * @param params.appVersion Obsidian app version (see {@link resolveVersions} for format)
+     * @param params.installerVersion Obsidian version string.
+     * @param params.appPath Path to the asar file to install. Will download if omitted.
+     * @param params.vault Path to the vault to open in Obsidian.
+     * @param params.dest Destination path for the config dir. If omitted it will create a temporary directory.
      */
     setupConfigDir(params: {
         appVersion: string;
@@ -260,10 +319,10 @@ declare class ObsidianLauncher {
     /**
      * Sets up a vault for Obsidian, installing plugins and themes and optionally copying the vault to a temporary
      * directory first.
-     * @param vault Path to the vault to open in Obsidian.
-     * @param copy Whether to copy the vault to a tmpdir first. Default false.
-     * @param plugins List of plugins to install in the vault.
-     * @param themes List of themes to install in the vault.
+     * @param params.vault Path to the vault to open in Obsidian
+     * @param params.copy Whether to copy the vault to a tmpdir first. Default false
+     * @param params.plugins List of plugins to install in the vault
+     * @param params.themes List of themes to install in the vault
      * @returns Path to the copied vault (or just the path to the vault if copy is false)
      */
     setupVault(params: {
@@ -276,21 +335,22 @@ declare class ObsidianLauncher {
      * Downloads and launches Obsidian with a sandboxed config dir and a specifc vault open. Optionally install plugins
      * and themes first.
      *
-     * This is just a shortcut for calling downloadApp, downloadInstaller, setupVault and setupConfDir.
+     * This is just a shortcut for calling `downloadApp`, `downloadInstaller`, `setupVault` and `setupConfDir`.
      *
-     * @param appVersion Obsidian version string.
-     * @param installerVersion Obsidian version string.
-     * @param vault Path to the vault to open in Obsidian.
-     * @param copy Whether to copy the vault to a tmpdir first. Default false.
-     * @param plugins List of plugins to install in the vault.
-     * @param themes List of themes to install in the vault.
-     * @param args CLI args to pass to Obsidian
-     * @param spawnOptions Options to pass to `spawn`.
-     * @returns The launched child process and the created tmpdirs.
+     * @param params.appVersion Obsidian app version (see {@link resolveVersions} for format). Default "latest"
+     * @param params.installerVersion Obsidian installer version (see {@link resolveVersions} for format).
+     *   Default "latest"
+     * @param params.vault Path to the vault to open in Obsidian
+     * @param params.copy Whether to copy the vault to a tmpdir first. Default false
+     * @param params.plugins List of plugins to install in the vault
+     * @param params.themes List of themes to install in the vault
+     * @param params.args CLI args to pass to Obsidian
+     * @param params.spawnOptions Options to pass to `spawn`
+     * @returns The launched child process and the created tmpdirs
      */
     launch(params: {
-        appVersion: string;
-        installerVersion: string;
+        appVersion?: string;
+        installerVersion?: string;
         copy?: boolean;
         vault?: string;
         plugins?: PluginEntry[];
@@ -312,13 +372,16 @@ declare class ObsidianLauncher {
     }): Promise<ObsidianVersionInfos>;
     /**
      * Returns true if the Obsidian version is already in the cache.
+     * @param type on of "app" or "installer"
+     * @param version Obsidian app/installer version (see {@link resolveVersions} for format)
      */
     isInCache(type: "app" | "installer", version: string): Promise<boolean>;
     /**
-     * Returns true if we either have the credentails to download the version or it's already in cache.
+     * Returns true if we either have the credentials to download the version or it's already in cache.
      * This is only relevant for Obsidian beta versions, as they require Obsidian insider credentials to download.
+     * @param version Obsidian version (see {@link resolveVersions} for format)
      */
     isAvailable(version: string): Promise<boolean>;
 }
 
-export { type CommunityPluginEntry, type CommunityThemeEntry, type DownloadedPluginEntry, type DownloadedThemeEntry, type GitHubPluginEntry, type GitHubThemeEntry, type LocalPluginEntry, type LocalThemeEntry, type ObsidianCommunityPlugin, type ObsidianCommunityTheme, ObsidianLauncher, type ObsidianVersionInfo, type ObsidianVersionInfos, type PluginEntry, type ThemeEntry, ObsidianLauncher as default };
+export { type DownloadedPluginEntry, type DownloadedThemeEntry, type ObsidianCommunityPlugin, type ObsidianCommunityTheme, ObsidianLauncher, type ObsidianVersionInfo, type ObsidianVersionInfos, type PluginEntry, type ThemeEntry, ObsidianLauncher as default };