@roam-research/roam-tools-core 0.4.0

package/README.md

@@ -0,0 +1,17 @@
+# @roam-research/roam-tools-core
+
+Shared core library for Roam Research tools. Provides the Roam API client, tool definitions, graph resolution, and operations.
+
+> **This package is not meant to be used directly.** It is an internal dependency of [`@roam-research/roam-mcp`](https://www.npmjs.com/package/@roam-research/roam-mcp) (MCP server) and [`@roam-research/roam-cli`](https://www.npmjs.com/package/@roam-research/roam-cli) (CLI). If you want to connect an AI assistant to Roam, install `@roam-research/roam-mcp`. If you want a command-line interface, install `@roam-research/roam-cli`.
+
+## What's in here
+
+- **RoamClient** — authenticated HTTP client for Roam's local API
+- **Tool definitions** — Zod-validated tool schemas used by both MCP and CLI
+- **Operations** — page, block, search, query, file, and navigation operations
+- **Graph resolution** — config loading, graph lookup, and multi-graph support
+- **Types** — shared TypeScript types, error codes, and schemas
+
+## Documentation
+
+See the [main repository](https://github.com/Roam-Research/roam-tools) for full documentation.

package/dist/client.d.ts

@@ -0,0 +1,34 @@
+import type { RoamResponse, RoamClientConfig, TokenInfoResult } from "./types.js";
+export declare class RoamClient {
+    private graphName;
+    private graphType;
+    private token;
+    private port;
+    constructor(config: RoamClientConfig);
+    private getPort;
+    private openRoamDeepLink;
+    private sleep;
+    private isConnectionError;
+    private isVersionMismatch;
+    private handleVersionMismatch;
+    /**
+     * Get user-friendly guidance for authentication errors
+     */
+    private getAuthErrorGuidance;
+    /**
+     * Get user-friendly guidance for permission errors
+     */
+    private getPermissionErrorGuidance;
+    /**
+     * Handle API error responses based on HTTP status and error code
+     */
+    private handleApiError;
+    private checkResponse;
+    /**
+     * Query the token info endpoint for current permissions.
+     * Best-effort: returns "unknown" on any failure except confirmed revocation.
+     */
+    getTokenInfo(): Promise<TokenInfoResult>;
+    call<T = unknown>(action: string, args?: unknown[]): Promise<RoamResponse<T>>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAGhB,eAAe,EAEhB,MAAM,YAAY,CAAC;AAQpB,qBAAa,UAAU;IACrB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,IAAI,CAAuB;gBAEvB,MAAM,EAAE,gBAAgB;YAkBtB,OAAO;YAeP,gBAAgB;YAKhB,KAAK;IAInB,OAAO,CAAC,iBAAiB;IAuBzB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,qBAAqB;IAyB7B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAgC5B;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAoBlC;;OAEG;IACH,OAAO,CAAC,cAAc;IAgDtB,OAAO,CAAC,aAAa;IASrB;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,eAAe,CAAC;IA0CxC,IAAI,CAAC,CAAC,GAAG,OAAO,EACpB,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,OAAO,EAAO,GACnB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;CAuE5B"}

package/dist/client.js

@@ -0,0 +1,275 @@
+// src/core/client.ts
+// v2.0.0 - Token-authenticated Roam Local API client
+import { readFile } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+import open from "open";
+import { EXPECTED_API_VERSION, getErrorMessage, RoamError, ErrorCodes, } from "./types.js";
+export class RoamClient {
+    graphName;
+    graphType;
+    token;
+    port = null;
+    constructor(config) {
+        if (!config.graphName) {
+            throw new Error("graphName is required");
+        }
+        if (!/^[A-Za-z0-9_-]+$/.test(config.graphName)) {
+            throw new Error(`Invalid graph name "${config.graphName}". Graph names can only contain letters, numbers, hyphens, and underscores.`);
+        }
+        if (!config.token) {
+            throw new Error("token is required");
+        }
+        this.graphName = config.graphName;
+        this.graphType = config.graphType;
+        this.token = config.token;
+        if (config.port) {
+            this.port = config.port;
+        }
+    }
+    async getPort() {
+        if (this.port)
+            return this.port;
+        try {
+            const configFile = join(homedir(), ".roam-local-api.json");
+            const content = await readFile(configFile, "utf-8");
+            const config = JSON.parse(content);
+            this.port = config.port;
+            return this.port;
+        }
+        catch {
+            // Default port if file doesn't exist
+            return 3333;
+        }
+    }
+    async openRoamDeepLink() {
+        const deepLink = `roam://#/app/${this.graphName}`;
+        await open(deepLink);
+    }
+    async sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    isConnectionError(error) {
+        if (error instanceof Error) {
+            if (error.message.includes("ECONNREFUSED") ||
+                error.message.includes("fetch failed") ||
+                error.message.includes("network")) {
+                return true;
+            }
+            // Check error.cause for Node fetch network errors
+            if (error.cause && error.cause instanceof Error) {
+                const causeCode = error.cause.code;
+                return (causeCode === "ECONNREFUSED" ||
+                    causeCode === "ECONNRESET" ||
+                    causeCode === "ENOTFOUND" ||
+                    causeCode === "ETIMEDOUT");
+            }
+        }
+        return false;
+    }
+    isVersionMismatch(response) {
+        if (response.success)
+            return false;
+        const error = response.error;
+        if (typeof error === "object" && error !== null) {
+            return error.code === "VERSION_MISMATCH";
+        }
+        return false;
+    }
+    handleVersionMismatch(response) {
+        const serverVersion = response.apiVersion ?? "unknown";
+        let advice = "Please update Roam or the MCP server so versions match.";
+        if (serverVersion !== "unknown") {
+            const [serverMajor, serverMinor] = serverVersion.split(".").map(Number);
+            const [expectedMajor, expectedMinor] = EXPECTED_API_VERSION.split(".").map(Number);
+            if (serverMajor > expectedMajor ||
+                (serverMajor === expectedMajor && serverMinor > expectedMinor)) {
+                advice = "Please update the MCP server.";
+            }
+            else {
+                advice = "Please update Roam.";
+            }
+        }
+        throw new RoamError(`Roam API version mismatch! Roam API: ${serverVersion}, MCP expected: ${EXPECTED_API_VERSION}. ${advice}`, ErrorCodes.VERSION_MISMATCH);
+    }
+    /**
+     * Get user-friendly guidance for authentication errors
+     */
+    getAuthErrorGuidance(code) {
+        const baseMsg = "Authentication failed. ";
+        switch (code) {
+            case ErrorCodes.MISSING_TOKEN:
+                return (baseMsg +
+                    "No API token provided. Please ensure your ~/.roam-tools.json has a valid token.");
+            case ErrorCodes.INVALID_TOKEN_FORMAT:
+                return (baseMsg +
+                    "The token format is invalid. Tokens should start with 'roam-graph-local-token-'.");
+            case ErrorCodes.WRONG_GRAPH_TYPE:
+                return (baseMsg +
+                    "This token is for a different graph type. Check that 'type' matches in your config.");
+            case ErrorCodes.TOKEN_NOT_FOUND:
+                return (baseMsg +
+                    "The token was not recognized. It may have been revoked. Create a new token in Roam Settings > Graph > Local API Tokens.");
+            default:
+                return (baseMsg +
+                    "Please check your token in ~/.roam-tools.json. Create a token in Roam Settings > Graph > Local API Tokens.");
+        }
+    }
+    /**
+     * Get user-friendly guidance for permission errors
+     */
+    getPermissionErrorGuidance(code, error) {
+        switch (code) {
+            case ErrorCodes.INSUFFICIENT_SCOPE:
+                return (`Permission denied. ${error?.message || "This operation requires higher permissions."}\n` +
+                    "Create a token with the required scope in Roam Settings > Graph > Local API Tokens.");
+            case ErrorCodes.SCOPE_EXCEEDS_PERMISSION:
+                return ("The token has more permissions than your user account allows. " +
+                    "Please check your Roam user permissions for this graph.");
+            default:
+                return error?.message || "Access denied. Please check your permissions.";
+        }
+    }
+    /**
+     * Handle API error responses based on HTTP status and error code
+     */
+    handleApiError(status, response) {
+        const error = typeof response.error === "object" ? response.error : undefined;
+        const code = error?.code;
+        const message = getErrorMessage(response.error);
+        // Version mismatch - fatal
+        if (this.isVersionMismatch(response)) {
+            this.handleVersionMismatch(response);
+        }
+        // 401 - Authentication errors
+        if (status === 401) {
+            throw new RoamError(this.getAuthErrorGuidance(code), code);
+        }
+        // 403 - Permission errors
+        if (status === 403) {
+            throw new RoamError(this.getPermissionErrorGuidance(code, error), code);
+        }
+        // 404 - Unknown action
+        if (status === 404) {
+            throw new RoamError(`Unknown API action: ${message}`, ErrorCodes.UNKNOWN_ACTION);
+        }
+        // 500 - Server errors
+        if (status >= 500) {
+            const hint = message.toLowerCase().includes("promise error")
+                ? "\n\nThis can happen if the graph was closed before the request completed, " +
+                    "especially for encrypted graphs, when closed before the password was entered."
+                : "";
+            throw new RoamError(`Server error: ${message}${hint}`, ErrorCodes.INTERNAL_ERROR);
+        }
+        // Other errors
+        throw new RoamError(message, code);
+    }
+    checkResponse(response, httpStatus) {
+        if (!response.success) {
+            this.handleApiError(httpStatus, response);
+        }
+    }
+    /**
+     * Query the token info endpoint for current permissions.
+     * Best-effort: returns "unknown" on any failure except confirmed revocation.
+     */
+    async getTokenInfo() {
+        try {
+            const port = await this.getPort();
+            const response = await fetch(`http://127.0.0.1:${port}/api/graphs/tokens/info`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    token: this.token,
+                    graph: this.graphName,
+                    type: this.graphType,
+                }),
+            });
+            if (response.status === 401) {
+                try {
+                    const data = (await response.json());
+                    const code = typeof data.error === "object" ? data.error?.code : undefined;
+                    if (code === "TOKEN_NOT_FOUND") {
+                        return { status: "revoked" };
+                    }
+                }
+                catch {
+                    // Couldn't parse 401 body
+                }
+                return { status: "unknown" };
+            }
+            if (!response.ok)
+                return { status: "unknown" };
+            const data = (await response.json());
+            if (!data.success)
+                return { status: "unknown" };
+            return { status: "active", info: data };
+        }
+        catch {
+            return { status: "unknown" };
+        }
+    }
+    async call(action, args = []) {
+        const doRequest = async () => {
+            const port = await this.getPort();
+            // Build URL with graph name and optional type parameter
+            let url = `http://127.0.0.1:${port}/api/${this.graphName}`;
+            if (this.graphType === "offline") {
+                url += "?type=offline";
+            }
+            const response = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.token}`,
+                },
+                body: JSON.stringify({
+                    action,
+                    args,
+                    expectedApiVersion: EXPECTED_API_VERSION,
+                }),
+            });
+            const data = (await response.json());
+            return { data, status: response.status };
+        };
+        try {
+            const { data, status } = await doRequest();
+            this.checkResponse(data, status);
+            return data;
+        }
+        catch (error) {
+            // If connection failed, try opening Roam and retry
+            if (this.isConnectionError(error)) {
+                // Reset cached port so we re-read from config after Roam starts
+                this.port = null;
+                try {
+                    await this.openRoamDeepLink();
+                }
+                catch {
+                    // Best-effort — don't let deep link failure prevent retries
+                }
+                let delay = 500;
+                const maxDelay = 15000;
+                for (let attempt = 0; attempt < 8; attempt += 1) {
+                    await this.sleep(delay);
+                    try {
+                        const { data, status } = await doRequest();
+                        this.checkResponse(data, status);
+                        return data;
+                    }
+                    catch (retryError) {
+                        if (!this.isConnectionError(retryError)) {
+                            throw retryError;
+                        }
+                    }
+                    delay = Math.min(delay * 2, maxDelay);
+                }
+                // All retries exhausted
+                throw new RoamError("Could not connect to Roam Desktop after multiple attempts. " +
+                    "Please restart the Roam desktop app and also this app and then retry again. " +
+                    "If you continue having issues, please let us know at support@roamresearch.com.", ErrorCodes.CONNECTION_FAILED);
+            }
+            throw error;
+        }
+    }
+}

package/dist/connect.d.ts

@@ -0,0 +1,10 @@
+export interface ConnectOptions {
+    graph?: string;
+    nickname?: string;
+    accessLevel?: string;
+    public?: boolean;
+    type?: string;
+    remove?: boolean;
+}
+export declare function connect(options?: ConnectOptions): Promise<void>;
+//# sourceMappingURL=connect.d.ts.map

package/dist/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AA8BA,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA0CD,wBAAsB,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgiBzE"}