@pipedream/excalidraw 0.0.1 → 0.1.0

package/actions/create-collection/create-collection.mjs

@@ -0,0 +1,38 @@
+import app from "../../excalidraw.app.mjs";
+
+export default {
+  key: "excalidraw-create-collection",
+  name: "Create Collection",
+  description:
+    "Creates a new collection (folder) in the Excalidraw Plus workspace for organizing scenes."
+    + " Returns the new collection's ID — pass it to **Create Scene** or **Update Scene** to add scenes to this collection."
+    + " [See the documentation](https://plus.excalidraw.com/docs/api/collections/post)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: false,
+  },
+  props: {
+    app,
+    collectionName: {
+      propDefinition: [
+        app,
+        "collectionName",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const data = {
+      name: this.collectionName,
+    };
+
+    const collection = await this.app.createCollection({
+      $,
+      data,
+    });
+    $.export("$summary", `Created collection: ${collection.name || collection.id}`);
+    return collection;
+  },
+};

package/actions/create-scene/create-scene.mjs

@@ -0,0 +1,58 @@
+import app from "../../excalidraw.app.mjs";
+
+export default {
+  key: "excalidraw-create-scene",
+  name: "Create Scene",
+  description:
+    "Creates a new scene (whiteboard) in the Excalidraw Plus workspace."
+    + " The API requires a collection — if no `collectionId` is provided, the scene is placed in the default (Main) collection automatically."
+    + " Use **List Collections** to find the collection ID if the user wants the scene in a specific folder."
+    + " Returns the new scene's ID and metadata."
+    + " [See the documentation](https://plus.excalidraw.com/docs/api/scenes/post)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: false,
+  },
+  props: {
+    app,
+    sceneName: {
+      propDefinition: [
+        app,
+        "sceneName",
+      ],
+    },
+    collectionId: {
+      propDefinition: [
+        app,
+        "collectionId",
+      ],
+    },
+    pinned: {
+      type: "boolean",
+      label: "Pinned",
+      description: "Whether to pin the scene to the top of the collection.",
+      optional: true,
+      default: false,
+    },
+  },
+  async run({ $ }) {
+    const collectionId = this.collectionId
+      || await this.app.getDefaultCollectionId($);
+
+    const data = {
+      name: this.sceneName,
+      pinned: this.pinned,
+      collectionId,
+    };
+
+    const scene = await this.app.createScene({
+      $,
+      data,
+    });
+    $.export("$summary", `Created scene: ${scene.metadata?.name || scene.metadata?.id}`);
+    return scene;
+  },
+};

package/actions/delete-scene/delete-scene.mjs

@@ -0,0 +1,37 @@
+import app from "../../excalidraw.app.mjs";
+
+export default {
+  key: "excalidraw-delete-scene",
+  name: "Delete Scene",
+  description:
+    "Permanently deletes an Excalidraw scene and all its drawing content. This action cannot be undone."
+    + " Use **List Scenes** to find the scene ID before calling this tool."
+    + " [See the documentation](https://plus.excalidraw.com/docs/api/scenes/sceneId-delete)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: true,
+    openWorldHint: true,
+    readOnlyHint: false,
+  },
+  props: {
+    app,
+    sceneId: {
+      propDefinition: [
+        app,
+        "sceneId",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.app.deleteScene({
+      $,
+      sceneId: this.sceneId,
+    });
+    $.export("$summary", `Deleted scene: ${this.sceneId}`);
+    return response ?? {
+      deleted: true,
+      id: this.sceneId,
+    };
+  },
+};

package/actions/get-current-user/get-current-user.mjs

@@ -0,0 +1,25 @@
+import app from "../../excalidraw.app.mjs";
+
+export default {
+  key: "excalidraw-get-current-user",
+  name: "Get Current User",
+  description:
+    "Returns the current workspace context from Excalidraw Plus, including workspace ID, name, user IDs, and roles."
+    + " Use this when the user asks 'who am I', 'what workspace am I in', or needs the workspace ID or user role."
+    + " [See the documentation](https://plus.excalidraw.com/docs/api/workspace/workspaces-get)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    app,
+  },
+  async run({ $ }) {
+    const workspace = await this.app.getWorkspace($);
+    $.export("$summary", `Workspace: ${workspace.name} (${workspace.id})`);
+    return workspace;
+  },
+};

package/actions/get-scene/get-scene.mjs

@@ -0,0 +1,52 @@
+import app from "../../excalidraw.app.mjs";
+
+export default {
+  key: "excalidraw-get-scene",
+  name: "Get Scene",
+  description:
+    "Returns metadata for a specific Excalidraw scene, and optionally its full drawing content (elements JSON)."
+    + " Use this when the user asks to view, inspect, or read a specific scene."
+    + " Use **List Scenes** first to find the scene ID by name."
+    + " Set `includeContent` to true only when the user explicitly asks for the drawing data — the content can be large."
+    + " [See the documentation](https://plus.excalidraw.com/docs/api/scenes/sceneId-content-get)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    app,
+    sceneId: {
+      propDefinition: [
+        app,
+        "sceneId",
+      ],
+    },
+    includeContent: {
+      type: "boolean",
+      label: "Include Drawing Content",
+      description: "When true, also fetches the scene's drawing elements (the full canvas JSON). Only set this when the user explicitly asks for the drawing content.",
+      optional: true,
+      default: false,
+    },
+  },
+  async run({ $ }) {
+    const scene = await this.app.getScene({
+      $,
+      sceneId: this.sceneId,
+    });
+
+    if (this.includeContent) {
+      const content = await this.app.getSceneContent({
+        $,
+        sceneId: this.sceneId,
+      });
+      scene.content = content;
+    }
+
+    $.export("$summary", `Retrieved scene: ${scene.metadata?.name || this.sceneId}`);
+    return scene;
+  },
+};

package/actions/list-collections/list-collections.mjs

@@ -0,0 +1,47 @@
+import app from "../../excalidraw.app.mjs";
+
+export default {
+  key: "excalidraw-list-collections",
+  name: "List Collections",
+  description:
+    "Returns all collections (folders) in the Excalidraw Plus workspace."
+    + " Use this to discover available collection IDs and names before filtering scenes by collection or creating a scene in a specific collection."
+    + " Cross-reference: pass a collection ID from this result to **List Scenes** or **Create Scene**."
+    + " [See the documentation](https://plus.excalidraw.com/docs/api/collections/get)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    app,
+    limit: {
+      propDefinition: [
+        app,
+        "limit",
+      ],
+    },
+    offset: {
+      propDefinition: [
+        app,
+        "offset",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const params = {
+      limit: this.limit,
+      offset: this.offset,
+    };
+
+    const response = await this.app.listCollections({
+      $,
+      params,
+    });
+    const collections = response.data ?? [];
+    $.export("$summary", `Retrieved ${collections.length} collection(s)`);
+    return response;
+  },
+};

package/actions/list-scenes/list-scenes.mjs

@@ -0,0 +1,85 @@
+import app from "../../excalidraw.app.mjs";
+
+export default {
+  key: "excalidraw-list-scenes",
+  name: "List Scenes",
+  description:
+    "Returns scenes (whiteboards) in the Excalidraw Plus workspace."
+    + " Optionally filter by collection ID or apply a name substring filter (applied client-side, since the API has no server-side search)."
+    + " When the user says 'scenes in [collection]', use **List Collections** first to get the collection ID, then pass it as `collectionId` here."
+    + " Use `nameFilter` (and `limit`) to narrow results when the user asks for a scene by name — the tool fetches up to `limit` scenes and returns only those whose name contains the filter string."
+    + " [See the documentation](https://plus.excalidraw.com/docs/api/scenes/get)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    app,
+    collectionId: {
+      propDefinition: [
+        app,
+        "collectionId",
+      ],
+    },
+    nameFilter: {
+      type: "string",
+      label: "Name Filter",
+      description: "Filter scenes by name (case-insensitive substring match, applied client-side).",
+      optional: true,
+    },
+    limit: {
+      propDefinition: [
+        app,
+        "limit",
+      ],
+    },
+  },
+  async run({ $ }) {
+    if (!this.nameFilter) {
+      const response = await this.app.listScenes({
+        $,
+        params: {
+          collectionId: this.collectionId,
+          limit: this.limit,
+        },
+      });
+      const scenes = response.data ?? [];
+      $.export("$summary", `Retrieved ${scenes.length} scene(s)`);
+      return scenes;
+    }
+
+    // When nameFilter is active, paginate to collect enough matches.
+    // The user's limit caps how many matches to return (default 100).
+    const maxResults = this.limit ?? 100;
+    const filter = this.nameFilter.toLowerCase();
+    const matches = [];
+    let offset = 0;
+    let hasNextPage = true;
+
+    while (hasNextPage && matches.length < maxResults) {
+      const response = await this.app.listScenes({
+        $,
+        params: {
+          collectionId: this.collectionId,
+          limit: 100,
+          offset,
+        },
+      });
+      const chunk = response.data ?? [];
+      for (const scene of chunk) {
+        if (scene.metadata?.name?.toLowerCase().includes(filter)) {
+          matches.push(scene);
+          if (matches.length === maxResults) break;
+        }
+      }
+      offset += chunk.length;
+      hasNextPage = response.hasNextPage && chunk.length > 0;
+    }
+
+    $.export("$summary", `Retrieved ${matches.length} scene(s)`);
+    return matches;
+  },
+};

package/actions/update-scene/update-scene.mjs

@@ -0,0 +1,70 @@
+import { ConfigurationError } from "@pipedream/platform";
+import app from "../../excalidraw.app.mjs";
+
+export default {
+  key: "excalidraw-update-scene",
+  name: "Update Scene",
+  description:
+    "Updates an existing Excalidraw scene's name or collection membership."
+    + " Use **List Scenes** to find the scene ID, and **List Collections** to find a collection ID if moving the scene."
+    + " Only the fields you provide are updated — omitted fields remain unchanged."
+    + " Note: the Excalidraw API does not support a description field on scenes."
+    + " [See the documentation](https://plus.excalidraw.com/docs/api/scenes/sceneId-patch)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: false,
+  },
+  props: {
+    app,
+    sceneId: {
+      propDefinition: [
+        app,
+        "sceneId",
+      ],
+    },
+    sceneName: {
+      propDefinition: [
+        app,
+        "sceneName",
+      ],
+      optional: true,
+    },
+    collectionId: {
+      propDefinition: [
+        app,
+        "collectionId",
+      ],
+    },
+    pinned: {
+      type: "boolean",
+      label: "Pinned",
+      description: "Whether to pin the scene to the top of the collection.",
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const nothingProvided = this.sceneName === undefined
+      && this.collectionId === undefined
+      && this.pinned === undefined;
+    if (nothingProvided) {
+      throw new ConfigurationError("Provide at least one of: sceneName, collectionId, pinned.");
+    }
+
+    const data = {
+      name: this.sceneName,
+      collectionId: this.collectionId,
+      pinned: this.pinned,
+    };
+
+    const scene = await this.app.updateScene({
+      $,
+      sceneId: this.sceneId,
+      data,
+    });
+    $.export("$summary", `Updated scene: ${scene.metadata?.name || this.sceneId}`);
+    return scene;
+  },
+};

package/excalidraw.app.mjs

@@ -1,11 +1,162 @@
+import { axios } from "@pipedream/platform";
+
 export default {
   type: "app",
   app: "excalidraw",
-  propDefinitions: {},
+  propDefinitions: {
+    sceneId: {
+      type: "string",
+      label: "Scene ID",
+      description: "The unique identifier of the scene. Use **List Scenes** to find scene IDs. Example: `4towcktqVl9`.",
+    },
+    collectionId: {
+      type: "string",
+      label: "Collection ID",
+      description: "The unique identifier of the collection. Use **List Collections** to find collection IDs. Example: `77i8dL6qc5t`.",
+      optional: true,
+    },
+    sceneName: {
+      type: "string",
+      label: "Name",
+      description: "The name of the scene.",
+    },
+    collectionName: {
+      type: "string",
+      label: "Name",
+      description: "The name of the collection.",
+    },
+    limit: {
+      type: "integer",
+      label: "Limit",
+      description: "Maximum number of results to return.",
+      optional: true,
+      default: 100,
+    },
+    offset: {
+      type: "integer",
+      label: "Offset",
+      description: "The number of items to skip before starting to collect the result set.",
+      optional: true,
+      min: 0,
+      max: 9007199254740991,
+    },
+  },
   methods: {
-    // this.$auth contains connected account data
-    authKeys() {
-      console.log(Object.keys(this.$auth));
+    _baseUrl() {
+      return "https://api.excalidraw.com/api/v1";
+    },
+    _headers() {
+      return {
+        "Authorization": `Bearer ${this.$auth.api_key}`,
+        "Content-Type": "application/json",
+      };
+    },
+    _makeRequest({
+      $ = this,
+      method = "GET",
+      path,
+      params,
+      data,
+      ...opts
+    }) {
+      return axios($, {
+        method,
+        url: `${this._baseUrl()}${path}`,
+        headers: this._headers(),
+        params,
+        data,
+        ...opts,
+      });
+    },
+    getWorkspace($) {
+      return this._makeRequest({
+        $,
+        path: "/workspaces",
+      });
+    },
+    listScenes({
+      $, params,
+    }) {
+      return this._makeRequest({
+        $,
+        path: "/scenes",
+        params,
+      });
+    },
+    getScene({
+      $, sceneId,
+    }) {
+      return this._makeRequest({
+        $,
+        path: `/scenes/${sceneId}`,
+      });
+    },
+    getSceneContent({
+      $, sceneId,
+    }) {
+      return this._makeRequest({
+        $,
+        path: `/scenes/${sceneId}/content`,
+      });
+    },
+    listCollections({
+      $, params,
+    }) {
+      return this._makeRequest({
+        $,
+        path: "/collections",
+        params,
+      });
+    },
+    async getDefaultCollectionId($) {
+      const response = await this.listCollections({
+        $,
+        params: {
+          limit: 100,
+        },
+      });
+      const collections = response.data;
+      const defaultCol = collections.find((c) => c.isDefault) ?? collections[0];
+      return defaultCol?.id;
+    },
+    createScene({
+      $, data,
+    }) {
+      return this._makeRequest({
+        $,
+        method: "POST",
+        path: "/scenes",
+        data,
+      });
+    },
+    updateScene({
+      $, sceneId, data,
+    }) {
+      return this._makeRequest({
+        $,
+        method: "PATCH",
+        path: `/scenes/${sceneId}`,
+        data,
+      });
+    },
+    deleteScene({
+      $, sceneId,
+    }) {
+      return this._makeRequest({
+        $,
+        method: "DELETE",
+        path: `/scenes/${sceneId}`,
+      });
+    },
+    createCollection({
+      $, data,
+    }) {
+      return this._makeRequest({
+        $,
+        method: "POST",
+        path: "/collections",
+        data,
+      });
     },
   },
-};
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipedream/excalidraw",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Pipedream Excalidraw Components",
   "main": "excalidraw.app.mjs",
   "keywords": [
@@ -9,6 +9,9 @@
   ],
   "homepage": "https://pipedream.com/apps/excalidraw",
   "author": "Pipedream <support@pipedream.com> (https://pipedream.com/)",
+  "dependencies": {
+    "@pipedream/platform": "^3.1.1"
+  },
   "publishConfig": {
     "access": "public"
   }