@spectratools/figma-cli 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 spectra-the-bot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { readFileSync, realpathSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+import { initTelemetry, shutdownTelemetry } from "@spectratools/cli-shared/telemetry";
+import { Cli } from "incur";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var pkg = JSON.parse(readFileSync(resolve(__dirname, "../package.json"), "utf8"));
+var cli = Cli.create("figma", {
+  version: pkg.version,
+  description: "Query Figma REST API data from the command line."
+});
+var isMain = (() => {
+  const entrypoint = process.argv[1];
+  if (!entrypoint) {
+    return false;
+  }
+  try {
+    return realpathSync(entrypoint) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+if (isMain) {
+  initTelemetry("figma");
+  process.on("beforeExit", () => shutdownTelemetry());
+  cli.serve();
+}
+export {
+  cli
+};

package/dist/index.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { readFileSync, realpathSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+import { initTelemetry, shutdownTelemetry } from "@spectratools/cli-shared/telemetry";
+import { Cli } from "incur";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var pkg = JSON.parse(readFileSync(resolve(__dirname, "../package.json"), "utf8"));
+var cli = Cli.create("figma", {
+  version: pkg.version,
+  description: "Query Figma REST API data from the command line."
+});
+var isMain = (() => {
+  const entrypoint = process.argv[1];
+  if (!entrypoint) {
+    return false;
+  }
+  try {
+    return realpathSync(entrypoint) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+if (isMain) {
+  initTelemetry("figma");
+  process.on("beforeExit", () => shutdownTelemetry());
+  cli.serve();
+}
+
+// src/api.ts
+import {
+  createHttpClient,
+  createRateLimiter,
+  withRateLimit,
+  withRetry
+} from "@spectratools/cli-shared";
+import { z } from "incur";
+var BASE_URL = "https://api.figma.com/v1";
+var RETRY_OPTIONS = { maxRetries: 3, baseMs: 1e3, maxMs: 15e3 };
+var colorSchema = z.object({
+  r: z.number(),
+  g: z.number(),
+  b: z.number(),
+  a: z.number()
+});
+var userSchema = z.object({
+  id: z.string(),
+  handle: z.string(),
+  img_url: z.string().optional()
+});
+var componentSchema = z.object({
+  key: z.string(),
+  name: z.string(),
+  description: z.string()
+});
+var styleSchema = z.object({
+  key: z.string(),
+  name: z.string(),
+  style_type: z.string(),
+  description: z.string().optional()
+});
+var commentSchema = z.object({
+  id: z.string(),
+  message: z.string(),
+  created_at: z.string(),
+  user: userSchema,
+  order_id: z.union([z.string(), z.number()]).optional()
+});
+var fileMetaSchema = z.object({
+  name: z.string(),
+  lastModified: z.string(),
+  version: z.string(),
+  role: z.string().optional()
+});
+var projectFileSchema = z.object({
+  key: z.string(),
+  name: z.string(),
+  thumbnail_url: z.string().optional(),
+  last_modified: z.string()
+});
+var getFileResponseSchema = z.object({
+  name: z.string(),
+  lastModified: z.string(),
+  version: z.string(),
+  role: z.string().optional(),
+  document: z.unknown(),
+  components: z.record(z.string(), componentSchema).optional(),
+  styles: z.record(z.string(), styleSchema).optional()
+});
+var getFileNodesResponseSchema = z.object({
+  name: z.string(),
+  lastModified: z.string(),
+  version: z.string(),
+  nodes: z.record(z.string(), z.unknown())
+});
+var getImagesResponseSchema = z.object({
+  images: z.record(z.string(), z.string().nullable()),
+  err: z.string().nullable().optional()
+});
+var getFileStylesResponseSchema = z.object({
+  meta: z.object({
+    styles: z.array(styleSchema)
+  })
+});
+var getFileComponentsResponseSchema = z.object({
+  meta: z.object({
+    components: z.array(componentSchema)
+  })
+});
+var getCommentsResponseSchema = z.object({
+  comments: z.array(commentSchema)
+});
+var postCommentResponseSchema = commentSchema;
+var getProjectFilesResponseSchema = z.object({
+  name: z.string(),
+  files: z.array(projectFileSchema)
+});
+function createFigmaClient(apiKey) {
+  const http = createHttpClient({
+    baseUrl: BASE_URL,
+    defaultHeaders: { "X-Figma-Token": apiKey }
+  });
+  const acquire = createRateLimiter({ requestsPerSecond: 2 });
+  function request(path, schema, query) {
+    const opts = query ? { query } : {};
+    return withRetry(
+      () => withRateLimit(() => http.request(path, opts), acquire),
+      RETRY_OPTIONS
+    ).then((raw) => schema.parse(raw));
+  }
+  function post(path, schema, body) {
+    return withRetry(
+      () => withRateLimit(() => http.request(path, { method: "POST", body }), acquire),
+      RETRY_OPTIONS
+    ).then((raw) => schema.parse(raw));
+  }
+  return {
+    /** Fetch a full Figma file. */
+    getFile(fileKey, opts) {
+      const query = {};
+      if (opts?.depth !== void 0) query.depth = opts.depth;
+      if (opts?.ids !== void 0) query.ids = opts.ids;
+      if (opts?.version !== void 0) query.version = opts.version;
+      if (opts?.geometry !== void 0) query.geometry = opts.geometry;
+      return request(`/files/${fileKey}`, getFileResponseSchema, query);
+    },
+    /** Fetch specific nodes from a file. */
+    getFileNodes(fileKey, nodeIds) {
+      return request(`/files/${fileKey}/nodes`, getFileNodesResponseSchema, {
+        ids: nodeIds.join(",")
+      });
+    },
+    /** Export images for the given node IDs. */
+    getImages(fileKey, nodeIds, opts) {
+      const query = {
+        ids: nodeIds.join(",")
+      };
+      if (opts?.scale !== void 0) query.scale = opts.scale;
+      if (opts?.format !== void 0) query.format = opts.format;
+      if (opts?.version !== void 0) query.version = opts.version;
+      return request(`/images/${fileKey}`, getImagesResponseSchema, query);
+    },
+    /** List published styles in a file. */
+    getFileStyles(fileKey) {
+      return request(`/files/${fileKey}/styles`, getFileStylesResponseSchema);
+    },
+    /** List published components in a file. */
+    getFileComponents(fileKey) {
+      return request(`/files/${fileKey}/components`, getFileComponentsResponseSchema);
+    },
+    /** List comments on a file. */
+    getComments(fileKey) {
+      return request(`/files/${fileKey}/comments`, getCommentsResponseSchema);
+    },
+    /** Post a comment on a file. */
+    postComment(fileKey, message, nodeId) {
+      const body = { message };
+      if (nodeId !== void 0) {
+        body.client_meta = { node_id: nodeId };
+      }
+      return post(`/files/${fileKey}/comments`, postCommentResponseSchema, body);
+    },
+    /** List files in a project. */
+    getProjectFiles(projectId) {
+      return request(`/projects/${projectId}/files`, getProjectFilesResponseSchema);
+    }
+  };
+}
+
+// src/auth.ts
+import { z as z2 } from "incur";
+var figmaEnv = z2.object({
+  FIGMA_API_KEY: z2.string().describe("Figma personal access token")
+});
+export {
+  cli,
+  createFigmaClient,
+  figmaEnv
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@spectratools/figma-cli",
+  "version": "0.2.0",
+  "description": "Figma REST API CLI for spectra-the-bot",
+  "type": "module",
+  "license": "MIT",
+  "author": "spectra-the-bot",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "figma": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "incur": "^0.3.0",
+    "@spectratools/cli-shared": "0.4.0"
+  },
+  "devDependencies": {
+    "typescript": "5.7.3",
+    "vitest": "2.1.8"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/cli.js",
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  }
+}