tana-mcp-codemode 0.1.0

package/src/api/tana.ts

@@ -0,0 +1,332 @@
+/**
+ * Tana API Wrapper
+ *
+ * Creates the `tana` object that gets injected into the sandbox.
+ * Maps high-level operations to Tana Local API HTTP endpoints.
+ *
+ * Types are generated from the Tana Local API OpenAPI spec.
+ * Run `bun run generate` to regenerate types from api-1.json.
+ */
+
+import type { TanaClient } from "./client";
+import type {
+  Workspace,
+  SearchQuery,
+  SearchOptions,
+  SearchResult,
+  Children,
+  EditNodeOptions,
+  Tag,
+  CreateTagOptions,
+  AddFieldOptions,
+  SetCheckboxOptions,
+  ImportResult,
+} from "./types";
+
+/**
+ * TanaAPI Interface
+ *
+ * The main interface exposed to sandbox code as the `tana` object.
+ * Provides high-level methods organized by domain (workspaces, nodes, tags, etc.)
+ */
+export interface TanaAPI {
+  /** Check API health */
+  health(): Promise<{ status: string; timestamp: string; nodeSpaceReady: boolean }>;
+
+  workspaces: {
+    /** List available workspaces */
+    list(): Promise<Workspace[]>;
+  };
+
+  nodes: {
+    /** Search for nodes */
+    search(query: SearchQuery, options?: SearchOptions): Promise<SearchResult[]>;
+    /** Read a node as markdown */
+    read(nodeId: string, maxDepth?: number): Promise<string>;
+    /** Get children of a node */
+    getChildren(
+      nodeId: string,
+      options?: { limit?: number; offset?: number }
+    ): Promise<Children>;
+    /** Edit a node's name/description */
+    edit(options: EditNodeOptions): Promise<{ success: boolean }>;
+    /** Move node to trash */
+    trash(nodeId: string): Promise<{ success: boolean }>;
+    /** Check a node's checkbox */
+    check(nodeId: string): Promise<{ success: boolean }>;
+    /** Uncheck a node's checkbox */
+    uncheck(nodeId: string): Promise<{ success: boolean }>;
+  };
+
+  tags: {
+    /** List tags in a workspace */
+    list(workspaceId: string, limit?: number): Promise<Tag[]>;
+    /** Get tag schema */
+    getSchema(tagId: string, includeEditInstructions?: boolean): Promise<string>;
+    /** Add/remove tags from a node */
+    modify(
+      nodeId: string,
+      action: "add" | "remove",
+      tagIds: string[]
+    ): Promise<{ success: boolean }>;
+    /** Create a new tag */
+    create(options: CreateTagOptions): Promise<{ tagId: string }>;
+    /** Add a field to a tag */
+    addField(options: AddFieldOptions): Promise<{ fieldId: string }>;
+    /** Configure tag checkbox */
+    setCheckbox(options: SetCheckboxOptions): Promise<{ success: boolean }>;
+  };
+
+  fields: {
+    /** Set a field to an option value */
+    setOption(
+      nodeId: string,
+      attributeId: string,
+      optionId: string
+    ): Promise<{ success: boolean }>;
+    /** Set a field to a string value */
+    setContent(
+      nodeId: string,
+      attributeId: string,
+      content: string
+    ): Promise<{ success: boolean }>;
+  };
+
+  calendar: {
+    /** Get or create a calendar node */
+    getOrCreate(
+      workspaceId: string,
+      granularity: "day" | "week" | "month" | "year",
+      date?: string
+    ): Promise<{ nodeId: string }>;
+  };
+
+  /** Import Tana Paste formatted content */
+  import(parentNodeId: string, content: string): Promise<ImportResult>;
+}
+
+export function createTanaAPI(client: TanaClient): TanaAPI {
+  return {
+    async health() {
+      return client.get<{ status: string; timestamp: string; nodeSpaceReady: boolean }>("/health");
+    },
+
+    workspaces: {
+      async list(): Promise<Workspace[]> {
+        return client.get<Workspace[]>("/workspaces");
+      },
+    },
+
+    nodes: {
+      async search(
+        query: SearchQuery,
+        options?: SearchOptions
+      ): Promise<SearchResult[]> {
+        // Build deep object query params (style: deepObject, explode: true)
+        const params: string[] = [];
+
+        function addQueryParams(obj: Record<string, unknown>, prefix: string) {
+          for (const [key, value] of Object.entries(obj)) {
+            const paramKey = prefix ? `${prefix}[${key}]` : key;
+            if (value === null || value === undefined) continue;
+            if (typeof value === "object" && !Array.isArray(value)) {
+              addQueryParams(value as Record<string, unknown>, paramKey);
+            } else if (Array.isArray(value)) {
+              value.forEach((item, i) => {
+                if (typeof item === "object") {
+                  addQueryParams(item as Record<string, unknown>, `${paramKey}[${i}]`);
+                } else {
+                  params.push(`${encodeURIComponent(`${paramKey}[${i}]`)}=${encodeURIComponent(String(item))}`);
+                }
+              });
+            } else {
+              params.push(`${encodeURIComponent(paramKey)}=${encodeURIComponent(String(value))}`);
+            }
+          }
+        }
+
+        addQueryParams(query as unknown as Record<string, unknown>, "query");
+        if (options?.limit) params.push(`limit=${options.limit}`);
+        if (options?.workspaceIds) {
+          options.workspaceIds.forEach((id, i) => {
+            params.push(`workspaceIds[${i}]=${encodeURIComponent(id)}`);
+          });
+        }
+
+        return client.get<SearchResult[]>(`/nodes/search?${params.join("&")}`);
+      },
+
+      async read(nodeId: string, maxDepth = 1): Promise<string> {
+        const result = await client.get<{ markdown: string; name?: string; description?: string }>(
+          `/nodes/${nodeId}?maxDepth=${maxDepth}`
+        );
+        return result.markdown;
+      },
+
+      async getChildren(
+        nodeId: string,
+        options?: { limit?: number; offset?: number }
+      ): Promise<Children> {
+        const params = new URLSearchParams();
+        if (options?.limit) params.set("limit", String(options.limit));
+        if (options?.offset) params.set("offset", String(options.offset));
+        const query = params.toString();
+        return client.get<Children>(
+          `/nodes/${nodeId}/children${query ? `?${query}` : ""}`
+        );
+      },
+
+      async edit(options: EditNodeOptions): Promise<{ success: boolean }> {
+        const result = await client.post<{ nodeId: string; message: string }>(
+          `/nodes/${options.nodeId}/update`,
+          {
+            name: options.name,
+            description: options.description,
+          }
+        );
+        return { success: !!result.nodeId };
+      },
+
+      async trash(nodeId: string): Promise<{ success: boolean }> {
+        const result = await client.post<{ nodeId: string; message: string }>(
+          `/nodes/${nodeId}/trash`,
+          {}
+        );
+        return { success: !!result.nodeId };
+      },
+
+      async check(nodeId: string): Promise<{ success: boolean }> {
+        const result = await client.post<{ nodeId: string; done: boolean; message: string }>(
+          `/nodes/${nodeId}/done`,
+          { done: true }
+        );
+        return { success: result.done === true };
+      },
+
+      async uncheck(nodeId: string): Promise<{ success: boolean }> {
+        const result = await client.post<{ nodeId: string; done: boolean; message: string }>(
+          `/nodes/${nodeId}/done`,
+          { done: false }
+        );
+        return { success: result.done === false };
+      },
+    },
+
+    tags: {
+      async list(workspaceId: string, limit = 50): Promise<Tag[]> {
+        return client.get<Tag[]>(
+          `/workspaces/${workspaceId}/tags?limit=${limit}`
+        );
+      },
+
+      async getSchema(
+        tagId: string,
+        includeEditInstructions = false
+      ): Promise<string> {
+        const result = await client.get<{ markdown: string }>(
+          `/tags/${tagId}/schema?includeEditInstructions=${includeEditInstructions}`
+        );
+        return result.markdown;
+      },
+
+      async modify(
+        nodeId: string,
+        action: "add" | "remove",
+        tagIds: string[]
+      ): Promise<{ success: boolean }> {
+        const result = await client.post<{ nodeId: string; action: string; results: unknown[] }>(
+          `/nodes/${nodeId}/tags`,
+          { action, tagIds }
+        );
+        return { success: !!result.nodeId };
+      },
+
+      async create(options: CreateTagOptions): Promise<{ tagId: string }> {
+        return client.post<{ tagId: string }>(
+          `/workspaces/${options.workspaceId}/tags`,
+          {
+            name: options.name,
+            description: options.description,
+            extendsTagIds: options.extendsTagIds,
+            showCheckbox: options.showCheckbox,
+          }
+        );
+      },
+
+      async addField(options: AddFieldOptions): Promise<{ fieldId: string }> {
+        return client.post<{ fieldId: string }>(
+          `/tags/${options.tagId}/fields`,
+          {
+            name: options.name,
+            dataType: options.dataType,
+            description: options.description,
+            sourceTagId: options.sourceTagId,
+            options: options.options,
+            defaultValue: options.defaultValue,
+            isMultiValue: options.isMultiValue,
+          }
+        );
+      },
+
+      async setCheckbox(
+        options: SetCheckboxOptions
+      ): Promise<{ success: boolean }> {
+        const result = await client.post<{ tagId: string; showCheckbox: boolean; message: string }>(
+          `/tags/${options.tagId}/checkbox`,
+          {
+            showCheckbox: options.showCheckbox,
+            doneStateMapping: options.doneStateMapping,
+          }
+        );
+        return { success: !!result.tagId };
+      },
+    },
+
+    fields: {
+      async setOption(
+        nodeId: string,
+        attributeId: string,
+        optionId: string
+      ): Promise<{ success: boolean }> {
+        const result = await client.post<{ nodeId: string; message: string }>(
+          `/nodes/${nodeId}/fields/${attributeId}/option`,
+          { optionId }
+        );
+        return { success: !!result.nodeId };
+      },
+
+      async setContent(
+        nodeId: string,
+        attributeId: string,
+        content: string
+      ): Promise<{ success: boolean }> {
+        const result = await client.post<{ nodeId: string; message: string }>(
+          `/nodes/${nodeId}/fields/${attributeId}/content`,
+          { content }
+        );
+        return { success: !!result.nodeId };
+      },
+    },
+
+    calendar: {
+      async getOrCreate(
+        workspaceId: string,
+        granularity: "day" | "week" | "month" | "year",
+        date?: string
+      ): Promise<{ nodeId: string }> {
+        const params = new URLSearchParams();
+        params.set("granularity", granularity);
+        if (date) params.set("date", date);
+        return client.get<{ nodeId: string }>(
+          `/workspaces/${workspaceId}/calendar/node?${params.toString()}`
+        );
+      },
+    },
+
+    async import(parentNodeId: string, content: string): Promise<ImportResult> {
+      return client.post<ImportResult>(`/nodes/${parentNodeId}/import`, {
+        content,
+      });
+    },
+  };
+}

package/src/api/types.ts

@@ -0,0 +1,207 @@
+/**
+ * API Types - Re-exports of generated OpenAPI types with friendly names
+ *
+ * These types are auto-generated from the Tana Local API OpenAPI spec.
+ * Run `bun run generate` to regenerate from api-1.json.
+ *
+ * @see ./generated/api.d.ts for the full generated types
+ */
+import type { operations } from "../generated/api";
+
+// ============================================================================
+// Response Types (extracted from operation responses)
+// ============================================================================
+
+/** Health check response */
+export type HealthResponse =
+  operations["health.ping"]["responses"]["200"]["content"]["application/json"];
+
+/** Workspace info */
+export type Workspace =
+  operations["workspaces.list"]["responses"]["200"]["content"]["application/json"][number];
+
+/** Search result node */
+export type SearchResult =
+  operations["nodes.search"]["responses"]["200"]["content"]["application/json"][number];
+
+/** Node read response (markdown content) */
+export type NodeReadResponse =
+  operations["nodes.read"]["responses"]["200"]["content"]["application/json"];
+
+/** Children list response */
+export type Children =
+  operations["nodes.getChildren"]["responses"]["200"]["content"]["application/json"];
+
+/** Child node in children response */
+export type ChildNode = Children["children"][number];
+
+/** Tag info */
+export type Tag =
+  operations["tags.list"]["responses"]["200"]["content"]["application/json"][number];
+
+/** Tag schema response (markdown) */
+export type TagSchemaResponse =
+  operations["tags.getSchema"]["responses"]["200"]["content"]["application/json"];
+
+/** Tag creation response */
+export type CreateTagResponse =
+  operations["tags.create"]["responses"]["200"]["content"]["application/json"];
+
+/** Add field response */
+export type AddFieldResponse =
+  operations["tags.addField"]["responses"]["200"]["content"]["application/json"];
+
+/** Set checkbox response */
+export type SetCheckboxResponse =
+  operations["tags.setCheckbox"]["responses"]["200"]["content"]["application/json"];
+
+/** Calendar node response */
+export type CalendarNodeResponse =
+  operations["calendar.getNodeId"]["responses"]["200"]["content"]["application/json"];
+
+/** Import response */
+export type ImportResponse =
+  operations["nodes.importTanaPaste"]["responses"]["200"]["content"]["application/json"];
+
+/** Tag modification response */
+export type ModifyTagsResponse =
+  operations["nodes.updateTags"]["responses"]["200"]["content"]["application/json"];
+
+/** Node update response */
+export type NodeUpdateResponse =
+  operations["nodes.update"]["responses"]["200"]["content"]["application/json"];
+
+/** Trash node response */
+export type TrashNodeResponse =
+  operations["nodes.trash"]["responses"]["200"]["content"]["application/json"];
+
+/** Set done response */
+export type SetDoneResponse =
+  operations["nodes.setDone"]["responses"]["200"]["content"]["application/json"];
+
+/** Set field option response */
+export type SetFieldOptionResponse =
+  operations["nodes.setFieldOption"]["responses"]["200"]["content"]["application/json"];
+
+/** Set field content response */
+export type SetFieldContentResponse =
+  operations["nodes.setFieldContent"]["responses"]["200"]["content"]["application/json"];
+
+// ============================================================================
+// Request/Query Types (extracted from operation parameters)
+// ============================================================================
+
+/** Search query structure */
+export type SearchQuery = NonNullable<
+  operations["nodes.search"]["parameters"]["query"]
+>["query"];
+
+/** Calendar granularity */
+export type CalendarGranularity = NonNullable<
+  operations["calendar.getNodeId"]["parameters"]["query"]
+>["granularity"];
+
+/** Field data type */
+export type FieldDataType = NonNullable<
+  operations["tags.addField"]["requestBody"]
+>["content"]["application/json"]["dataType"];
+
+// ============================================================================
+// Request Body Types
+// ============================================================================
+
+/** Create tag request body */
+export type CreateTagBody = NonNullable<
+  operations["tags.create"]["requestBody"]
+>["content"]["application/json"];
+
+/** Add field request body */
+export type AddFieldBody = NonNullable<
+  operations["tags.addField"]["requestBody"]
+>["content"]["application/json"];
+
+/** Set checkbox request body */
+export type SetCheckboxBody = NonNullable<
+  operations["tags.setCheckbox"]["requestBody"]
+>["content"]["application/json"];
+
+/** Update tags request body */
+export type UpdateTagsBody = NonNullable<
+  operations["nodes.updateTags"]["requestBody"]
+>["content"]["application/json"];
+
+/** Node update request body */
+export type NodeUpdateBody = NonNullable<
+  operations["nodes.update"]["requestBody"]
+>["content"]["application/json"];
+
+// ============================================================================
+// Derived Helper Types (for ergonomic API usage)
+// ============================================================================
+
+/** Options for search */
+export interface SearchOptions {
+  limit?: number;
+  workspaceIds?: string[];
+}
+
+/** Options for creating a tag */
+export interface CreateTagOptions {
+  workspaceId: string;
+  name: string;
+  description?: string;
+  extendsTagIds?: string[];
+  showCheckbox?: boolean;
+}
+
+/** Options for adding a field to a tag */
+export interface AddFieldOptions {
+  tagId: string;
+  name: string;
+  dataType: FieldDataType;
+  description?: string;
+  sourceTagId?: string;
+  options?: string[];
+  defaultValue?: string | boolean | number;
+  isMultiValue?: boolean;
+}
+
+/** Options for configuring tag checkbox */
+export interface SetCheckboxOptions {
+  tagId: string;
+  showCheckbox: boolean;
+  doneStateMapping?: {
+    fieldId: string;
+    checkedValues: string[];
+    uncheckedValues?: string[];
+  };
+}
+
+/** Options for editing a node */
+export interface EditNodeOptions {
+  nodeId: string;
+  name?: {
+    old_string: string;
+    new_string: string;
+    replace_all?: boolean;
+  };
+  description?: {
+    old_string: string;
+    new_string: string;
+    replace_all?: boolean;
+  };
+}
+
+/** Import result (simplified for API usage) */
+export interface ImportResult {
+  success: boolean;
+  nodeIds?: string[];
+  error?: string;
+}
+
+// ============================================================================
+// Re-export full generated types for escape hatch
+// ============================================================================
+
+export type { operations } from "../generated/api";
+export type { paths } from "../generated/api";