obsidian-mcp-server 1.5.8 → 2.0.2

package/dist/services/obsidianRestAPI/methods/activeFileMethods.js

@@ -0,0 +1,62 @@
+/**
+ * @module ActiveFileMethods
+ * @description
+ * Methods for interacting with the currently active file in Obsidian via the REST API.
+ */
+/**
+ * Gets the content of the currently active file in Obsidian.
+ * @param _request - The internal request function from the service instance.
+ * @param format - 'markdown' or 'json' (for NoteJson).
+ * @param context - Request context.
+ * @returns The file content (string) or NoteJson object.
+ */
+export async function getActiveFile(_request, format = "markdown", context) {
+    const acceptHeader = format === "json" ? "application/vnd.olrapi.note+json" : "text/markdown";
+    return _request({
+        method: "GET",
+        url: `/active/`,
+        headers: { Accept: acceptHeader },
+    }, context, "getActiveFile");
+}
+/**
+ * Updates (overwrites) the content of the currently active file.
+ * @param _request - The internal request function from the service instance.
+ * @param content - The new content.
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (204 No Content).
+ */
+export async function updateActiveFile(_request, content, context) {
+    await _request({
+        method: "PUT",
+        url: `/active/`,
+        headers: { "Content-Type": "text/markdown" },
+        data: content,
+    }, context, "updateActiveFile");
+}
+/**
+ * Appends content to the end of the currently active file.
+ * @param _request - The internal request function from the service instance.
+ * @param content - The content to append.
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (204 No Content).
+ */
+export async function appendActiveFile(_request, content, context) {
+    await _request({
+        method: "POST",
+        url: `/active/`,
+        headers: { "Content-Type": "text/markdown" },
+        data: content,
+    }, context, "appendActiveFile");
+}
+/**
+ * Deletes the currently active file.
+ * @param _request - The internal request function from the service instance.
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (204 No Content).
+ */
+export async function deleteActiveFile(_request, context) {
+    await _request({
+        method: "DELETE",
+        url: `/active/`,
+    }, context, "deleteActiveFile");
+}

package/dist/services/obsidianRestAPI/methods/commandMethods.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @module CommandMethods
+ * @description
+ * Methods for interacting with Obsidian commands via the REST API.
+ */
+import { RequestContext } from "../../../utils/index.js";
+import { ObsidianCommand, RequestFunction } from "../types.js";
+/**
+ * Executes a registered Obsidian command by its ID.
+ * @param _request - The internal request function from the service instance.
+ * @param commandId - The ID of the command (e.g., "app:go-back").
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (204 No Content).
+ */
+export declare function executeCommand(_request: RequestFunction, commandId: string, context: RequestContext): Promise<void>;
+/**
+ * Lists all available Obsidian commands.
+ * @param _request - The internal request function from the service instance.
+ * @param context - Request context.
+ * @returns A list of available commands.
+ */
+export declare function listCommands(_request: RequestFunction, context: RequestContext): Promise<ObsidianCommand[]>;

package/dist/services/obsidianRestAPI/methods/commandMethods.js

@@ -0,0 +1,31 @@
+/**
+ * @module CommandMethods
+ * @description
+ * Methods for interacting with Obsidian commands via the REST API.
+ */
+/**
+ * Executes a registered Obsidian command by its ID.
+ * @param _request - The internal request function from the service instance.
+ * @param commandId - The ID of the command (e.g., "app:go-back").
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (204 No Content).
+ */
+export async function executeCommand(_request, commandId, context) {
+    await _request({
+        method: "POST",
+        url: `/commands/${encodeURIComponent(commandId)}/`,
+    }, context, "executeCommand");
+}
+/**
+ * Lists all available Obsidian commands.
+ * @param _request - The internal request function from the service instance.
+ * @param context - Request context.
+ * @returns A list of available commands.
+ */
+export async function listCommands(_request, context) {
+    const response = await _request({
+        method: "GET",
+        url: "/commands/",
+    }, context, "listCommands");
+    return response.commands;
+}

package/dist/services/obsidianRestAPI/methods/openMethods.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @module OpenMethods
+ * @description
+ * Methods for opening files in Obsidian via the REST API.
+ */
+import { RequestContext } from "../../../utils/index.js";
+import { RequestFunction } from "../types.js";
+/**
+ * Opens a specific file in Obsidian. Creates the file if it doesn't exist.
+ * @param _request - The internal request function from the service instance.
+ * @param filePath - Vault-relative path to the file.
+ * @param newLeaf - Whether to open the file in a new editor tab (leaf).
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (200 OK, but no body expected).
+ */
+export declare function openFile(_request: RequestFunction, filePath: string, newLeaf: boolean | undefined, context: RequestContext): Promise<void>;

package/dist/services/obsidianRestAPI/methods/openMethods.js

@@ -0,0 +1,21 @@
+/**
+ * @module OpenMethods
+ * @description
+ * Methods for opening files in Obsidian via the REST API.
+ */
+/**
+ * Opens a specific file in Obsidian. Creates the file if it doesn't exist.
+ * @param _request - The internal request function from the service instance.
+ * @param filePath - Vault-relative path to the file.
+ * @param newLeaf - Whether to open the file in a new editor tab (leaf).
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (200 OK, but no body expected).
+ */
+export async function openFile(_request, filePath, newLeaf = false, context) {
+    // This endpoint returns 200 OK, not 204
+    await _request({
+        method: "POST",
+        url: `/open/${encodeURIComponent(filePath)}`,
+        params: { newLeaf },
+    }, context, "openFile");
+}

package/dist/services/obsidianRestAPI/methods/patchMethods.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @module PatchMethods
+ * @description
+ * Methods for performing granular PATCH operations within notes via the Obsidian REST API.
+ */
+import { RequestContext } from "../../../utils/index.js";
+import { PatchOptions, Period, RequestFunction } from "../types.js";
+/**
+ * Patches a specific file in the vault.
+ * @param _request - The internal request function from the service instance.
+ * @param filePath - Vault-relative path to the file.
+ * @param content - The content to insert/replace (string or JSON for tables/frontmatter).
+ * @param options - Patch operation details (operation, targetType, target, etc.).
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (200 OK).
+ */
+export declare function patchFile(_request: RequestFunction, filePath: string, content: string | object, // Allow object for JSON content type
+options: PatchOptions, context: RequestContext): Promise<void>;
+/**
+ * Patches the currently active file in Obsidian.
+ * @param _request - The internal request function from the service instance.
+ * @param content - The content to insert/replace.
+ * @param options - Patch operation details.
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (200 OK).
+ */
+export declare function patchActiveFile(_request: RequestFunction, content: string | object, options: PatchOptions, context: RequestContext): Promise<void>;
+/**
+ * Patches a periodic note.
+ * @param _request - The internal request function from the service instance.
+ * @param period - The period type ('daily', 'weekly', etc.).
+ * @param content - The content to insert/replace.
+ * @param options - Patch operation details.
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (200 OK).
+ */
+export declare function patchPeriodicNote(_request: RequestFunction, period: Period, content: string | object, options: PatchOptions, context: RequestContext): Promise<void>;

package/dist/services/obsidianRestAPI/methods/patchMethods.js

@@ -0,0 +1,94 @@
+/**
+ * @module PatchMethods
+ * @description
+ * Methods for performing granular PATCH operations within notes via the Obsidian REST API.
+ */
+import { encodeVaultPath } from "../../../utils/obsidian/obsidianApiUtils.js";
+/**
+ * Helper to construct headers for PATCH requests.
+ */
+function buildPatchHeaders(options) {
+    const headers = {
+        Operation: options.operation,
+        "Target-Type": options.targetType,
+        // Spec requires URL encoding for non-ASCII characters in Target header
+        Target: encodeURIComponent(options.target),
+    };
+    if (options.targetDelimiter) {
+        headers["Target-Delimiter"] = options.targetDelimiter;
+    }
+    if (options.trimTargetWhitespace !== undefined) {
+        headers["Trim-Target-Whitespace"] = String(options.trimTargetWhitespace);
+    }
+    // Add Create-Target-If-Missing header if provided in options
+    if (options.createTargetIfMissing !== undefined) {
+        headers["Create-Target-If-Missing"] = String(options.createTargetIfMissing);
+    }
+    if (options.contentType) {
+        headers["Content-Type"] = options.contentType;
+    }
+    else {
+        // Default to markdown if not specified, especially for non-JSON content
+        headers["Content-Type"] = "text/markdown";
+    }
+    return headers;
+}
+/**
+ * Patches a specific file in the vault.
+ * @param _request - The internal request function from the service instance.
+ * @param filePath - Vault-relative path to the file.
+ * @param content - The content to insert/replace (string or JSON for tables/frontmatter).
+ * @param options - Patch operation details (operation, targetType, target, etc.).
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (200 OK).
+ */
+export async function patchFile(_request, filePath, content, // Allow object for JSON content type
+options, context) {
+    const headers = buildPatchHeaders(options);
+    const requestData = typeof content === "object" ? JSON.stringify(content) : content;
+    const encodedPath = encodeVaultPath(filePath);
+    // PATCH returns 200 OK according to spec
+    await _request({
+        method: "PATCH",
+        url: `/vault${encodedPath}`, // Use the encoded path
+        headers: headers,
+        data: requestData,
+    }, context, "patchFile");
+}
+/**
+ * Patches the currently active file in Obsidian.
+ * @param _request - The internal request function from the service instance.
+ * @param content - The content to insert/replace.
+ * @param options - Patch operation details.
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (200 OK).
+ */
+export async function patchActiveFile(_request, content, options, context) {
+    const headers = buildPatchHeaders(options);
+    const requestData = typeof content === "object" ? JSON.stringify(content) : content;
+    await _request({
+        method: "PATCH",
+        url: `/active/`,
+        headers: headers,
+        data: requestData,
+    }, context, "patchActiveFile");
+}
+/**
+ * Patches a periodic note.
+ * @param _request - The internal request function from the service instance.
+ * @param period - The period type ('daily', 'weekly', etc.).
+ * @param content - The content to insert/replace.
+ * @param options - Patch operation details.
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (200 OK).
+ */
+export async function patchPeriodicNote(_request, period, content, options, context) {
+    const headers = buildPatchHeaders(options);
+    const requestData = typeof content === "object" ? JSON.stringify(content) : content;
+    await _request({
+        method: "PATCH",
+        url: `/periodic/${period}/`,
+        headers: headers,
+        data: requestData,
+    }, context, "patchPeriodicNote");
+}

package/dist/services/obsidianRestAPI/methods/periodicNoteMethods.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @module PeriodicNoteMethods
+ * @description
+ * Methods for interacting with periodic notes (daily, weekly, etc.) via the Obsidian REST API.
+ */
+import { RequestContext } from "../../../utils/index.js";
+import { NoteJson, Period, RequestFunction } from "../types.js";
+/**
+ * Gets the content of a periodic note (daily, weekly, etc.).
+ * @param _request - The internal request function from the service instance.
+ * @param period - The period type ('daily', 'weekly', 'monthly', 'quarterly', 'yearly').
+ * @param format - 'markdown' or 'json'.
+ * @param context - Request context.
+ * @returns The note content or NoteJson.
+ */
+export declare function getPeriodicNote(_request: RequestFunction, period: Period, format: "markdown" | "json" | undefined, context: RequestContext): Promise<string | NoteJson>;
+/**
+ * Updates (overwrites) the content of a periodic note. Creates if needed.
+ * @param _request - The internal request function from the service instance.
+ * @param period - The period type.
+ * @param content - The new content.
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (204 No Content).
+ */
+export declare function updatePeriodicNote(_request: RequestFunction, period: Period, content: string, context: RequestContext): Promise<void>;
+/**
+ * Appends content to a periodic note. Creates if needed.
+ * @param _request - The internal request function from the service instance.
+ * @param period - The period type.
+ * @param content - The content to append.
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (204 No Content).
+ */
+export declare function appendPeriodicNote(_request: RequestFunction, period: Period, content: string, context: RequestContext): Promise<void>;
+/**
+ * Deletes a periodic note.
+ * @param _request - The internal request function from the service instance.
+ * @param period - The period type.
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (204 No Content).
+ */
+export declare function deletePeriodicNote(_request: RequestFunction, period: Period, context: RequestContext): Promise<void>;

package/dist/services/obsidianRestAPI/methods/periodicNoteMethods.js

@@ -0,0 +1,66 @@
+/**
+ * @module PeriodicNoteMethods
+ * @description
+ * Methods for interacting with periodic notes (daily, weekly, etc.) via the Obsidian REST API.
+ */
+/**
+ * Gets the content of a periodic note (daily, weekly, etc.).
+ * @param _request - The internal request function from the service instance.
+ * @param period - The period type ('daily', 'weekly', 'monthly', 'quarterly', 'yearly').
+ * @param format - 'markdown' or 'json'.
+ * @param context - Request context.
+ * @returns The note content or NoteJson.
+ */
+export async function getPeriodicNote(_request, period, format = "markdown", context) {
+    const acceptHeader = format === "json" ? "application/vnd.olrapi.note+json" : "text/markdown";
+    return _request({
+        method: "GET",
+        url: `/periodic/${period}/`,
+        headers: { Accept: acceptHeader },
+    }, context, "getPeriodicNote");
+}
+/**
+ * Updates (overwrites) the content of a periodic note. Creates if needed.
+ * @param _request - The internal request function from the service instance.
+ * @param period - The period type.
+ * @param content - The new content.
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (204 No Content).
+ */
+export async function updatePeriodicNote(_request, period, content, context) {
+    await _request({
+        method: "PUT",
+        url: `/periodic/${period}/`,
+        headers: { "Content-Type": "text/markdown" },
+        data: content,
+    }, context, "updatePeriodicNote");
+}
+/**
+ * Appends content to a periodic note. Creates if needed.
+ * @param _request - The internal request function from the service instance.
+ * @param period - The period type.
+ * @param content - The content to append.
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (204 No Content).
+ */
+export async function appendPeriodicNote(_request, period, content, context) {
+    await _request({
+        method: "POST",
+        url: `/periodic/${period}/`,
+        headers: { "Content-Type": "text/markdown" },
+        data: content,
+    }, context, "appendPeriodicNote");
+}
+/**
+ * Deletes a periodic note.
+ * @param _request - The internal request function from the service instance.
+ * @param period - The period type.
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (204 No Content).
+ */
+export async function deletePeriodicNote(_request, period, context) {
+    await _request({
+        method: "DELETE",
+        url: `/periodic/${period}/`,
+    }, context, "deletePeriodicNote");
+}

package/dist/services/obsidianRestAPI/methods/searchMethods.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @module SearchMethods
+ * @description
+ * Methods for performing searches via the Obsidian REST API.
+ */
+import { RequestContext } from "../../../utils/index.js";
+import { SimpleSearchResult, ComplexSearchResult, RequestFunction } from "../types.js";
+/**
+ * Performs a simple text search across the vault.
+ * @param _request - The internal request function from the service instance.
+ * @param query - The text query string.
+ * @param contextLength - Number of characters surrounding each match (default 100).
+ * @param context - Request context.
+ * @returns An array of search results.
+ */
+export declare function searchSimple(_request: RequestFunction, query: string, contextLength: number | undefined, context: RequestContext): Promise<SimpleSearchResult[]>;
+/**
+ * Performs a complex search using Dataview DQL or JsonLogic.
+ * @param _request - The internal request function from the service instance.
+ * @param query - The query string (DQL) or JSON object (JsonLogic).
+ * @param contentType - The content type header indicating the query format.
+ * @param context - Request context.
+ * @returns An array of search results.
+ */
+export declare function searchComplex(_request: RequestFunction, query: string | object, contentType: "application/vnd.olrapi.dataview.dql+txt" | "application/vnd.olrapi.jsonlogic+json", context: RequestContext): Promise<ComplexSearchResult[]>;

package/dist/services/obsidianRestAPI/methods/searchMethods.js

@@ -0,0 +1,36 @@
+/**
+ * @module SearchMethods
+ * @description
+ * Methods for performing searches via the Obsidian REST API.
+ */
+/**
+ * Performs a simple text search across the vault.
+ * @param _request - The internal request function from the service instance.
+ * @param query - The text query string.
+ * @param contextLength - Number of characters surrounding each match (default 100).
+ * @param context - Request context.
+ * @returns An array of search results.
+ */
+export async function searchSimple(_request, query, contextLength = 100, context) {
+    return _request({
+        method: "POST",
+        url: "/search/simple/",
+        params: { query, contextLength }, // Send as query parameters
+    }, context, "searchSimple");
+}
+/**
+ * Performs a complex search using Dataview DQL or JsonLogic.
+ * @param _request - The internal request function from the service instance.
+ * @param query - The query string (DQL) or JSON object (JsonLogic).
+ * @param contentType - The content type header indicating the query format.
+ * @param context - Request context.
+ * @returns An array of search results.
+ */
+export async function searchComplex(_request, query, contentType, context) {
+    return _request({
+        method: "POST",
+        url: "/search/",
+        headers: { "Content-Type": contentType },
+        data: query,
+    }, context, "searchComplex");
+}

package/dist/services/obsidianRestAPI/methods/vaultMethods.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @module VaultMethods
+ * @description
+ * Methods for interacting with vault files and directories via the Obsidian REST API.
+ */
+import { RequestContext } from "../../../utils/index.js";
+import { NoteJson, NoteStat, RequestFunction } from "../types.js";
+/**
+ * Gets the content of a specific file in the vault.
+ * @param _request - The internal request function from the service instance.
+ * @param filePath - Vault-relative path to the file.
+ * @param format - 'markdown' or 'json' (for NoteJson).
+ * @param context - Request context.
+ * @returns The file content (string) or NoteJson object.
+ */
+export declare function getFileContent(_request: RequestFunction, filePath: string, format: "markdown" | "json" | undefined, context: RequestContext): Promise<string | NoteJson>;
+/**
+ * Updates (overwrites) the content of a file or creates it if it doesn't exist.
+ * @param _request - The internal request function from the service instance.
+ * @param filePath - Vault-relative path to the file.
+ * @param content - The new content for the file.
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (204 No Content).
+ */
+export declare function updateFileContent(_request: RequestFunction, filePath: string, content: string, context: RequestContext): Promise<void>;
+/**
+ * Appends content to the end of a file. Creates the file if it doesn't exist.
+ * @param _request - The internal request function from the service instance.
+ * @param filePath - Vault-relative path to the file.
+ * @param content - The content to append.
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (204 No Content).
+ */
+export declare function appendFileContent(_request: RequestFunction, filePath: string, content: string, context: RequestContext): Promise<void>;
+/**
+ * Deletes a specific file in the vault.
+ * @param _request - The internal request function from the service instance.
+ * @param filePath - Vault-relative path to the file.
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (204 No Content).
+ */
+export declare function deleteFile(_request: RequestFunction, filePath: string, context: RequestContext): Promise<void>;
+/**
+ * Lists files within a specified directory in the vault.
+ * @param _request - The internal request function from the service instance.
+ * @param dirPath - Vault-relative path to the directory. Use empty string "" or "/" for the root.
+ * @param context - Request context.
+ * @returns A list of file and directory names.
+ */
+export declare function listFiles(_request: RequestFunction, dirPath: string, context: RequestContext): Promise<string[]>;
+/**
+ * Gets the metadata (stat) of a specific file using a lightweight HEAD request.
+ * @param _request - The internal request function from the service instance.
+ * @param filePath - Vault-relative path to the file.
+ * @param context - Request context.
+ * @returns The file's metadata.
+ */
+export declare function getFileMetadata(_request: RequestFunction, filePath: string, context: RequestContext): Promise<NoteStat | null>;

package/dist/services/obsidianRestAPI/methods/vaultMethods.js

@@ -0,0 +1,144 @@
+/**
+ * @module VaultMethods
+ * @description
+ * Methods for interacting with vault files and directories via the Obsidian REST API.
+ */
+import { encodeVaultPath } from "../../../utils/obsidian/obsidianApiUtils.js";
+/**
+ * Gets the content of a specific file in the vault.
+ * @param _request - The internal request function from the service instance.
+ * @param filePath - Vault-relative path to the file.
+ * @param format - 'markdown' or 'json' (for NoteJson).
+ * @param context - Request context.
+ * @returns The file content (string) or NoteJson object.
+ */
+export async function getFileContent(_request, filePath, format = "markdown", context) {
+    const acceptHeader = format === "json" ? "application/vnd.olrapi.note+json" : "text/markdown";
+    const encodedPath = encodeVaultPath(filePath); // Use the new encoding function
+    return _request({
+        method: "GET",
+        url: `/vault${encodedPath}`,
+        headers: { Accept: acceptHeader },
+    }, context, "getFileContent");
+}
+/**
+ * Updates (overwrites) the content of a file or creates it if it doesn't exist.
+ * @param _request - The internal request function from the service instance.
+ * @param filePath - Vault-relative path to the file.
+ * @param content - The new content for the file.
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (204 No Content).
+ */
+export async function updateFileContent(_request, filePath, content, context) {
+    const encodedPath = encodeVaultPath(filePath); // Use the new encoding function
+    // PUT returns 204 No Content, so the expected type is void
+    await _request({
+        method: "PUT",
+        url: `/vault${encodedPath}`, // Construct URL correctly
+        headers: { "Content-Type": "text/markdown" },
+        data: content,
+    }, context, "updateFileContent");
+}
+/**
+ * Appends content to the end of a file. Creates the file if it doesn't exist.
+ * @param _request - The internal request function from the service instance.
+ * @param filePath - Vault-relative path to the file.
+ * @param content - The content to append.
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (204 No Content).
+ */
+export async function appendFileContent(_request, filePath, content, context) {
+    const encodedPath = encodeVaultPath(filePath); // Use the new encoding function
+    await _request({
+        method: "POST",
+        url: `/vault${encodedPath}`, // Construct URL correctly
+        headers: { "Content-Type": "text/markdown" },
+        data: content,
+    }, context, "appendFileContent");
+}
+/**
+ * Deletes a specific file in the vault.
+ * @param _request - The internal request function from the service instance.
+ * @param filePath - Vault-relative path to the file.
+ * @param context - Request context.
+ * @returns {Promise<void>} Resolves on success (204 No Content).
+ */
+export async function deleteFile(_request, filePath, context) {
+    const encodedPath = encodeVaultPath(filePath); // Use the new encoding function
+    await _request({
+        method: "DELETE",
+        url: `/vault${encodedPath}`, // Construct URL correctly
+    }, context, "deleteFile");
+}
+/**
+ * Lists files within a specified directory in the vault.
+ * @param _request - The internal request function from the service instance.
+ * @param dirPath - Vault-relative path to the directory. Use empty string "" or "/" for the root.
+ * @param context - Request context.
+ * @returns A list of file and directory names.
+ */
+export async function listFiles(_request, dirPath, context) {
+    // Normalize path: remove leading/trailing slashes for consistency, except for root
+    let pathSegment = dirPath.trim();
+    // Explicitly handle root path variations ('', '/') by setting pathSegment to empty.
+    // This ensures that the final URL constructed later will be '/vault/', which the API
+    // uses to list the root directory contents.
+    if (pathSegment === "" || pathSegment === "/") {
+        pathSegment = ""; // Use empty string to signify root for URL construction
+    }
+    else {
+        // For non-root paths:
+        // 1. Remove any leading/trailing slashes to prevent issues like '/vault//path/' or '/vault/path//'.
+        // 2. URI-encode *each component* of the remaining path segment to handle special characters safely.
+        pathSegment = pathSegment
+            .replace(/^\/+|\/+$/g, "")
+            .split("/")
+            .map(encodeURIComponent)
+            .join("/");
+    }
+    // Construct the final URL for the API request:
+    // - If pathSegment is not empty (i.e., it's a specific directory), format as '/vault/{encoded_path}/'.
+    // - If pathSegment IS empty (signifying the root), format as '/vault/'.
+    // The trailing slash is important for directory listing endpoints in this API.
+    const url = pathSegment ? `/vault/${pathSegment}/` : "/vault/";
+    const response = await _request({
+        method: "GET",
+        url: url, // Use the correctly constructed URL
+    }, context, "listFiles");
+    return response.files;
+}
+/**
+ * Gets the metadata (stat) of a specific file using a lightweight HEAD request.
+ * @param _request - The internal request function from the service instance.
+ * @param filePath - Vault-relative path to the file.
+ * @param context - Request context.
+ * @returns The file's metadata.
+ */
+export async function getFileMetadata(_request, filePath, context) {
+    const encodedPath = encodeVaultPath(filePath);
+    try {
+        const response = await _request({
+            method: "HEAD",
+            url: `/vault${encodedPath}`,
+        }, context, "getFileMetadata");
+        if (response && response.headers) {
+            const headers = response.headers;
+            return {
+                mtime: headers["x-obsidian-mtime"]
+                    ? parseFloat(headers["x-obsidian-mtime"]) * 1000
+                    : 0,
+                ctime: headers["x-obsidian-ctime"]
+                    ? parseFloat(headers["x-obsidian-ctime"]) * 1000
+                    : 0,
+                size: headers["content-length"]
+                    ? parseInt(headers["content-length"], 10)
+                    : 0,
+            };
+        }
+        return null;
+    }
+    catch (error) {
+        // Errors are already logged by the _request function, so we can just return null
+        return null;
+    }
+}