@roam-research/roam-tools-core 0.5.1 → 0.6.1

package/dist/client.js

@@ -1,275 +0,0 @@
-// 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

@@ -1,10 +0,0 @@
-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

@@ -1 +0,0 @@
-{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AA0BA,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,CA4gBzE"}