@roam-research/roam-tools-core 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/README.md +17 -0
  2. package/dist/client.d.ts +34 -0
  3. package/dist/client.d.ts.map +1 -0
  4. package/dist/client.js +275 -0
  5. package/dist/connect.d.ts +10 -0
  6. package/dist/connect.d.ts.map +1 -0
  7. package/dist/connect.js +477 -0
  8. package/dist/graph-resolver.d.ts +54 -0
  9. package/dist/graph-resolver.d.ts.map +1 -0
  10. package/dist/graph-resolver.js +338 -0
  11. package/dist/index.d.ts +9 -0
  12. package/dist/index.d.ts.map +1 -0
  13. package/dist/index.js +10 -0
  14. package/dist/operations/blocks.d.ts +120 -0
  15. package/dist/operations/blocks.d.ts.map +1 -0
  16. package/dist/operations/blocks.js +108 -0
  17. package/dist/operations/files.d.ts +43 -0
  18. package/dist/operations/files.d.ts.map +1 -0
  19. package/dist/operations/files.js +175 -0
  20. package/dist/operations/graphs.d.ts +26 -0
  21. package/dist/operations/graphs.d.ts.map +1 -0
  22. package/dist/operations/graphs.js +214 -0
  23. package/dist/operations/navigation.d.ts +32 -0
  24. package/dist/operations/navigation.d.ts.map +1 -0
  25. package/dist/operations/navigation.js +54 -0
  26. package/dist/operations/pages.d.ts +63 -0
  27. package/dist/operations/pages.d.ts.map +1 -0
  28. package/dist/operations/pages.js +59 -0
  29. package/dist/operations/query.d.ts +34 -0
  30. package/dist/operations/query.d.ts.map +1 -0
  31. package/dist/operations/query.js +46 -0
  32. package/dist/operations/search.d.ts +37 -0
  33. package/dist/operations/search.d.ts.map +1 -0
  34. package/dist/operations/search.js +33 -0
  35. package/dist/roam-api.d.ts +32 -0
  36. package/dist/roam-api.d.ts.map +1 -0
  37. package/dist/roam-api.js +50 -0
  38. package/dist/tools.d.ts +22 -0
  39. package/dist/tools.d.ts.map +1 -0
  40. package/dist/tools.js +276 -0
  41. package/dist/types.d.ts +235 -0
  42. package/dist/types.d.ts.map +1 -0
  43. package/dist/types.js +90 -0
  44. package/package.json +41 -0
@@ -0,0 +1,235 @@
1
+ export type { CallToolResult, TextContent, ImageContent } from "@modelcontextprotocol/sdk/types.js";
2
+ import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
3
+ import { z } from "zod";
4
+ export declare function textResult(value: unknown): CallToolResult;
5
+ export declare function imageResult(data: string, mimeType: string): CallToolResult;
6
+ export declare function errorResult(message: string): CallToolResult;
7
+ export type GraphType = "hosted" | "offline";
8
+ export type AccessLevel = "read-only" | "read-append" | "full";
9
+ export declare const GraphConfigSchema: z.ZodObject<{
10
+ name: z.ZodString;
11
+ type: z.ZodDefault<z.ZodEnum<["hosted", "offline"]>>;
12
+ token: z.ZodString;
13
+ nickname: z.ZodString;
14
+ accessLevel: z.ZodOptional<z.ZodEnum<["read-only", "read-append", "full"]>>;
15
+ lastKnownTokenStatus: z.ZodOptional<z.ZodEnum<["active", "revoked"]>>;
16
+ }, "strip", z.ZodTypeAny, {
17
+ type: "hosted" | "offline";
18
+ name: string;
19
+ token: string;
20
+ nickname: string;
21
+ accessLevel?: "read-only" | "read-append" | "full" | undefined;
22
+ lastKnownTokenStatus?: "active" | "revoked" | undefined;
23
+ }, {
24
+ name: string;
25
+ token: string;
26
+ nickname: string;
27
+ type?: "hosted" | "offline" | undefined;
28
+ accessLevel?: "read-only" | "read-append" | "full" | undefined;
29
+ lastKnownTokenStatus?: "active" | "revoked" | undefined;
30
+ }>;
31
+ export type GraphConfig = z.infer<typeof GraphConfigSchema>;
32
+ export declare const RoamMcpConfigSchema: z.ZodObject<{
33
+ version: z.ZodOptional<z.ZodNumber>;
34
+ graphs: z.ZodArray<z.ZodObject<{
35
+ name: z.ZodString;
36
+ type: z.ZodDefault<z.ZodEnum<["hosted", "offline"]>>;
37
+ token: z.ZodString;
38
+ nickname: z.ZodString;
39
+ accessLevel: z.ZodOptional<z.ZodEnum<["read-only", "read-append", "full"]>>;
40
+ lastKnownTokenStatus: z.ZodOptional<z.ZodEnum<["active", "revoked"]>>;
41
+ }, "strip", z.ZodTypeAny, {
42
+ type: "hosted" | "offline";
43
+ name: string;
44
+ token: string;
45
+ nickname: string;
46
+ accessLevel?: "read-only" | "read-append" | "full" | undefined;
47
+ lastKnownTokenStatus?: "active" | "revoked" | undefined;
48
+ }, {
49
+ name: string;
50
+ token: string;
51
+ nickname: string;
52
+ type?: "hosted" | "offline" | undefined;
53
+ accessLevel?: "read-only" | "read-append" | "full" | undefined;
54
+ lastKnownTokenStatus?: "active" | "revoked" | undefined;
55
+ }>, "many">;
56
+ }, "strip", z.ZodTypeAny, {
57
+ graphs: {
58
+ type: "hosted" | "offline";
59
+ name: string;
60
+ token: string;
61
+ nickname: string;
62
+ accessLevel?: "read-only" | "read-append" | "full" | undefined;
63
+ lastKnownTokenStatus?: "active" | "revoked" | undefined;
64
+ }[];
65
+ version?: number | undefined;
66
+ }, {
67
+ graphs: {
68
+ name: string;
69
+ token: string;
70
+ nickname: string;
71
+ type?: "hosted" | "offline" | undefined;
72
+ accessLevel?: "read-only" | "read-append" | "full" | undefined;
73
+ lastKnownTokenStatus?: "active" | "revoked" | undefined;
74
+ }[];
75
+ version?: number | undefined;
76
+ }>;
77
+ export type RoamMcpConfig = z.infer<typeof RoamMcpConfigSchema>;
78
+ export interface ResolvedGraph {
79
+ name: string;
80
+ type: GraphType;
81
+ token: string;
82
+ nickname: string;
83
+ accessLevel?: AccessLevel;
84
+ lastKnownTokenStatus?: "active" | "revoked";
85
+ }
86
+ export declare const ErrorCodes: {
87
+ readonly VERSION_MISMATCH: "VERSION_MISMATCH";
88
+ readonly VALIDATION_ERROR: "VALIDATION_ERROR";
89
+ readonly MISSING_TOKEN: "MISSING_TOKEN";
90
+ readonly INVALID_TOKEN_FORMAT: "INVALID_TOKEN_FORMAT";
91
+ readonly WRONG_GRAPH_TYPE: "WRONG_GRAPH_TYPE";
92
+ readonly TOKEN_NOT_FOUND: "TOKEN_NOT_FOUND";
93
+ readonly INSUFFICIENT_SCOPE: "INSUFFICIENT_SCOPE";
94
+ readonly SCOPE_EXCEEDS_PERMISSION: "SCOPE_EXCEEDS_PERMISSION";
95
+ readonly USER_REJECTED: "USER_REJECTED";
96
+ readonly GRAPH_BLOCKED: "GRAPH_BLOCKED";
97
+ readonly TIMEOUT: "TIMEOUT";
98
+ readonly REQUEST_IN_PROGRESS: "REQUEST_IN_PROGRESS";
99
+ readonly UNKNOWN_ACTION: "UNKNOWN_ACTION";
100
+ readonly TOKEN_FILE_CORRUPTED: "TOKEN_FILE_CORRUPTED";
101
+ readonly INTERNAL_ERROR: "INTERNAL_ERROR";
102
+ readonly CONFIG_NOT_FOUND: "CONFIG_NOT_FOUND";
103
+ readonly GRAPH_NOT_CONFIGURED: "GRAPH_NOT_CONFIGURED";
104
+ readonly GRAPH_NOT_SELECTED: "GRAPH_NOT_SELECTED";
105
+ readonly CONNECTION_FAILED: "CONNECTION_FAILED";
106
+ readonly CONFIG_TOO_NEW: "CONFIG_TOO_NEW";
107
+ };
108
+ export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
109
+ export declare class RoamError extends Error {
110
+ readonly code?: ErrorCode | undefined;
111
+ readonly context?: Record<string, unknown> | undefined;
112
+ constructor(message: string, code?: ErrorCode | undefined, context?: Record<string, unknown> | undefined);
113
+ }
114
+ export declare const CONFIG_VERSION = 1;
115
+ export declare const EXPECTED_API_VERSION = "1.1.0";
116
+ export interface RoamApiError {
117
+ message: string;
118
+ code?: string;
119
+ }
120
+ export declare function getErrorMessage(error: string | RoamApiError | undefined): string;
121
+ export interface RoamResponse<T = unknown> {
122
+ success: boolean;
123
+ result?: T;
124
+ error?: string | RoamApiError;
125
+ apiVersion?: string;
126
+ expectedApiVersion?: string;
127
+ }
128
+ export interface Block {
129
+ uid: string;
130
+ string: string;
131
+ children?: Block[];
132
+ open?: boolean;
133
+ heading?: number;
134
+ "text-align"?: "left" | "center" | "right" | "justify";
135
+ "children-view-type"?: "bullet" | "numbered" | "document";
136
+ }
137
+ export interface Page {
138
+ uid: string;
139
+ title: string;
140
+ children?: Block[];
141
+ "children-view-type"?: "bullet" | "numbered" | "document";
142
+ }
143
+ export interface BlockLocation {
144
+ "parent-uid": string;
145
+ order: number | "first" | "last";
146
+ }
147
+ export type WindowType = "mentions" | "block" | "outline" | "graph" | "search-query";
148
+ export interface SidebarWindow {
149
+ type: WindowType;
150
+ "block-uid"?: string;
151
+ "search-query-str"?: string;
152
+ order?: number;
153
+ }
154
+ export interface SidebarWindowInfo {
155
+ type: WindowType;
156
+ "window-id": string;
157
+ "block-uid"?: string;
158
+ "mentions-uid"?: string;
159
+ "search-query-str"?: string;
160
+ order?: number;
161
+ "pinned-to-top?"?: boolean;
162
+ collapsed?: boolean;
163
+ }
164
+ export interface FocusedBlock {
165
+ "block-uid": string;
166
+ "window-id": string;
167
+ }
168
+ export interface SelectedBlock {
169
+ "block-uid": string;
170
+ }
171
+ export type MainWindowViewType = "outline" | "log" | "graph" | "diagram" | "pdf" | "search" | "custom";
172
+ export interface MainWindowView {
173
+ type: MainWindowViewType;
174
+ uid?: string;
175
+ title?: string;
176
+ "block-string"?: string;
177
+ id?: string;
178
+ args?: unknown[];
179
+ }
180
+ export interface SearchResultPath {
181
+ uid: string;
182
+ title: string;
183
+ }
184
+ export interface SearchResult {
185
+ uid: string;
186
+ markdown: string;
187
+ path: SearchResultPath[];
188
+ type?: "page";
189
+ }
190
+ export interface SearchResponse {
191
+ total: number;
192
+ results: SearchResult[];
193
+ }
194
+ export interface Template {
195
+ name: string;
196
+ uid: string;
197
+ content: string;
198
+ }
199
+ export interface QueryResult {
200
+ uid: string;
201
+ markdown: string;
202
+ path?: string;
203
+ type?: "page";
204
+ }
205
+ export interface QueryResponse {
206
+ total: number;
207
+ results: QueryResult[];
208
+ }
209
+ export interface TokenInfoResponse {
210
+ success: boolean;
211
+ graphName?: string;
212
+ graphType?: GraphType;
213
+ grantedAccessLevel?: string;
214
+ grantedScopes?: {
215
+ read?: boolean;
216
+ append?: boolean;
217
+ edit?: boolean;
218
+ };
219
+ description?: string;
220
+ }
221
+ export type TokenInfoResult = {
222
+ status: "active";
223
+ info: TokenInfoResponse;
224
+ } | {
225
+ status: "revoked";
226
+ } | {
227
+ status: "unknown";
228
+ };
229
+ export interface RoamClientConfig {
230
+ graphName: string;
231
+ graphType: GraphType;
232
+ token: string;
233
+ port?: number;
234
+ }
235
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
package/dist/types.js ADDED
@@ -0,0 +1,90 @@
1
+ import { z } from "zod";
2
+ // Helper to create a text result
3
+ export function textResult(value) {
4
+ const text = typeof value === "string" ? value : JSON.stringify(value, null, 2);
5
+ return { content: [{ type: "text", text }] };
6
+ }
7
+ // Helper to create an image result
8
+ export function imageResult(data, mimeType) {
9
+ return { content: [{ type: "image", data, mimeType }] };
10
+ }
11
+ // Helper to create an error result
12
+ export function errorResult(message) {
13
+ return { content: [{ type: "text", text: message }], isError: true };
14
+ }
15
+ // Config file schema for ~/.roam-tools.json
16
+ // Graph names can only contain alphanumeric characters, hyphens, and underscores
17
+ const GRAPH_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
18
+ export const GraphConfigSchema = z.object({
19
+ name: z.string().regex(GRAPH_NAME_PATTERN, "Graph name can only contain letters, numbers, hyphens, and underscores").describe("Actual graph name in Roam"),
20
+ type: z.enum(["hosted", "offline"]).default("hosted").describe("Graph type"),
21
+ token: z.string().startsWith("roam-graph-local-token-").describe("Local API token"),
22
+ nickname: z.string()
23
+ .regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, "Nickname must be lowercase letters, numbers, and hyphens")
24
+ .describe("Short identifier for the graph (lowercase, hyphens, no spaces)"),
25
+ accessLevel: z.enum(["read-only", "read-append", "full"]).optional().describe("Token access level"),
26
+ lastKnownTokenStatus: z.enum(["active", "revoked"]).optional().describe("Token validity status from last sync with Roam"),
27
+ });
28
+ export const RoamMcpConfigSchema = z.object({
29
+ version: z.number().int().positive().optional(),
30
+ graphs: z.array(GraphConfigSchema).min(1, "At least one graph must be configured"),
31
+ });
32
+ // ============================================================================
33
+ // Error Codes and Custom Errors
34
+ // ============================================================================
35
+ // Error codes from Local API and MCP-specific errors
36
+ export const ErrorCodes = {
37
+ // 400 errors
38
+ VERSION_MISMATCH: "VERSION_MISMATCH",
39
+ VALIDATION_ERROR: "VALIDATION_ERROR",
40
+ // 401 errors
41
+ MISSING_TOKEN: "MISSING_TOKEN",
42
+ INVALID_TOKEN_FORMAT: "INVALID_TOKEN_FORMAT",
43
+ WRONG_GRAPH_TYPE: "WRONG_GRAPH_TYPE",
44
+ TOKEN_NOT_FOUND: "TOKEN_NOT_FOUND",
45
+ // 403 errors
46
+ INSUFFICIENT_SCOPE: "INSUFFICIENT_SCOPE",
47
+ SCOPE_EXCEEDS_PERMISSION: "SCOPE_EXCEEDS_PERMISSION",
48
+ USER_REJECTED: "USER_REJECTED",
49
+ GRAPH_BLOCKED: "GRAPH_BLOCKED",
50
+ // Token request errors
51
+ TIMEOUT: "TIMEOUT",
52
+ REQUEST_IN_PROGRESS: "REQUEST_IN_PROGRESS",
53
+ // 404 errors
54
+ UNKNOWN_ACTION: "UNKNOWN_ACTION",
55
+ // 500 errors
56
+ TOKEN_FILE_CORRUPTED: "TOKEN_FILE_CORRUPTED",
57
+ INTERNAL_ERROR: "INTERNAL_ERROR",
58
+ // MCP-specific errors (not from Local API)
59
+ CONFIG_NOT_FOUND: "CONFIG_NOT_FOUND",
60
+ GRAPH_NOT_CONFIGURED: "GRAPH_NOT_CONFIGURED",
61
+ GRAPH_NOT_SELECTED: "GRAPH_NOT_SELECTED",
62
+ CONNECTION_FAILED: "CONNECTION_FAILED",
63
+ CONFIG_TOO_NEW: "CONFIG_TOO_NEW",
64
+ };
65
+ // Custom error class with error code and optional context
66
+ export class RoamError extends Error {
67
+ code;
68
+ context;
69
+ constructor(message, code, context) {
70
+ super(message);
71
+ this.code = code;
72
+ this.context = context;
73
+ this.name = "RoamError";
74
+ }
75
+ }
76
+ // ============================================================================
77
+ // API Types
78
+ // ============================================================================
79
+ // Config version for ~/.roam-tools.json format compatibility
80
+ export const CONFIG_VERSION = 1;
81
+ // API version this client expects (major.minor must match)
82
+ export const EXPECTED_API_VERSION = "1.1.0";
83
+ // Helper to extract error message from RoamResponse
84
+ export function getErrorMessage(error) {
85
+ if (!error)
86
+ return "Unknown error";
87
+ if (typeof error === "string")
88
+ return error;
89
+ return error.message;
90
+ }
package/package.json ADDED
@@ -0,0 +1,41 @@
1
+ {
2
+ "name": "@roam-research/roam-tools-core",
3
+ "version": "0.4.0",
4
+ "description": "Core library for Roam Research tools",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/Roam-Research/roam-tools.git",
8
+ "directory": "packages/core"
9
+ },
10
+ "type": "module",
11
+ "main": "dist/index.js",
12
+ "types": "dist/index.d.ts",
13
+ "exports": {
14
+ ".": {
15
+ "types": "./dist/index.d.ts",
16
+ "development": "./src/index.ts",
17
+ "import": "./dist/index.js"
18
+ },
19
+ "./connect": {
20
+ "types": "./dist/connect.d.ts",
21
+ "development": "./src/connect.ts",
22
+ "import": "./dist/connect.js"
23
+ }
24
+ },
25
+ "files": [
26
+ "dist/",
27
+ "README.md"
28
+ ],
29
+ "publishConfig": {
30
+ "access": "public"
31
+ },
32
+ "engines": {
33
+ "node": ">=18"
34
+ },
35
+ "dependencies": {
36
+ "@inquirer/prompts": "^8.2.0",
37
+ "@modelcontextprotocol/sdk": "^1.0.0",
38
+ "open": "^11.0.0",
39
+ "zod": "^3.25.76"
40
+ }
41
+ }