feat(core): add new icon configuration and fetch commands; update dependencies in pnpm-lock.yaml and restructure CLI commands

Author: mrbadri

apps/docs/figmicon.config.ts

@@ -0,0 +1,24 @@
+import { defineConfig, parseFigmaUrl } from "@figmicon/core";
+
+// https://www.figma.com/design/iH0P8rAVJjqln9jiuNqY7R/VergeCloud?node-id=10806-24901&m=dev
+
+// TODO: check this URL
+// https://www.figma.com/design/B6R9BOyrbu0h3dVMhh1kkT/coolicons-%7C-Free-Iconset--Community-?node-id=30789-32015&m=dev
+
+export default defineConfig({
+  figma: {
+    token: process.env.FIGMA_TOKEN!,
+    // fileId: "iH0P8rAVJjqln9jiuNqY7R",
+    // nodeId: "10806-24901",
+    // INFO: you can use parseFigmaUrl to parse the url alternative to fileId and nodeId
+    ...parseFigmaUrl(
+      "https://www.figma.com/design/B6R9BOyrbu0h3dVMhh1kkT/coolicons-%7C-Free-Iconset--Community-?node-id=30789-32168&m=dev"
+    ),
+  },
+  fetch: {
+    // nodeTypes: ["COMPONENT", "COMPONENT_SET"],
+    generateFileName: (node, parentNode) => node.name + "--" + parentNode.name,
+    outDir: "icons/badri",
+    sanitizeName: true,
+  },
+});

apps/docs/icon.config.ts

@@ -1,5 +1,11 @@
 # @figmicon/core
 
+## 1.1.0
+
+### Minor Changes
+
+- add new icon configuration and fetch commands; update dependencies in pnpm-lock.yaml and restructure CLI commands
+
 ## 1.0.1
 
 ### Patch Changes

apps/docs/tmp/icons/sample.svg

@@ -1,6 +1,6 @@
 {
   "name": "@figmicon/core",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "sideEffects": false,
   "license": "MIT",
   "files": [
@@ -18,9 +18,13 @@
   "exports": {
     ".": {
       "import": "./dist/index.mjs",
-      "types": "./dist/index.d.mts"
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
     }
   },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
   "devDependencies": {
     "@acme/eslint-config": "workspace:*",
     "@acme/tsconfig": "workspace:*",
@@ -30,8 +34,11 @@
     "typescript": "5.5.4"
   },
   "dependencies": {
+    "@figma/rest-api-spec": "^0.33.0",
+    "c12": "^3.2.0",
     "commander": "^14.0.0",
-    "kolorist": "^1.8.0"
+    "kolorist": "^1.8.0",
+    "zod": "^4.1.5"
   },
   "publishConfig": {
     "access": "public"

packages/core/CHANGELOG.md

@@ -1,40 +1,26 @@
 import { Command } from "commander";
-import { green, cyan } from "kolorist";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { loadConfig } from "./config.js";
+
+import { fetchCommand } from "./command/fetch/index.js";
 
 const program = new Command();
 
 program
-  .name("acme")
+  .name("figmicon")
   .description(
     "Fetch icons from Figma and build React components or sprite.svg"
   )
-  .version("0.1.0");
+  .version("1.0.1");
 
-// نمونه‌ی ساده: یک فایل SVG تمرینی می‌سازد تا خروجی را تست کنی
+// fetch command
 program
   .command("fetch")
   .description("Fetch SVG icons from Figma by node IDs (demo write)")
   .option("-o, --out <dir>", "Output folder for raw SVGs", "tmp/icons")
-  .action(async ({ out }) => {
-    const outDir = path.resolve(process.cwd(), out);
-    await fs.mkdir(outDir, { recursive: true });
-
-    const sampleSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24">
-  <path d="M5 12h14" stroke="currentColor" fill="none" stroke-width="2"/>
-  <path d="M13 5l7 7-7 7" stroke="currentColor" fill="none" stroke-width="2"/>
-</svg>`;
-    const filePath = path.join(outDir, "sample.svg");
-    await fs.writeFile(filePath, sampleSvg, "utf8");
-    console.log(green("✔ fetch is working 4"));
-    const config = await loadConfig();
-    console.log("config", config);
-    console.log(cyan(`→ wrote ${filePath}`));
+  .action(async () => {
+    await fetchCommand();
   });
 
-// نمونه‌ی بسیار ساده‌ی دوم
+// hello command
 program
   .command("hello")
   .description("Prints a greeting")

packages/core/package.json

@@ -0,0 +1,89 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { type Node } from "@figma/rest-api-spec";
+import { type GenerateFileName } from "../../types";
+import { bgBlue, cyan, green } from "kolorist";
+
+export const downloadNode = async ({
+  fileId,
+  apiToken,
+  node,
+  outDir = "icons",
+  generateFileName = (node: Node, parentNode: Node) => node.name || node.id,
+  sanitizeName = true,
+  parentNode,
+}: {
+  fileId: string;
+  apiToken: string;
+  node: Node;
+  parentNode: Node;
+  outDir?: string;
+  generateFileName?: GenerateFileName;
+  sanitizeName?: boolean;
+}) => {
+  // 1) get temporary URL for SVG
+  const apiUrl = new URL(`https://api.figma.com/v1/images/${fileId}`);
+  apiUrl.searchParams.set("ids", node.id);
+  apiUrl.searchParams.set("format", "svg");
+  apiUrl.searchParams.set("svg_include_id", "true");
+
+  const res = await fetch(apiUrl, {
+    headers: { "X-Figma-Token": apiToken },
+  });
+
+  if (!res.ok) {
+    throw new Error(
+      `Failed to call Figma API: ${res.status} ${res.statusText}`
+    );
+  }
+
+  const json: { images: Record<string, string>; err?: string } =
+    await res.json();
+  if (json.err) throw new Error(`Figma API error: ${json.err}`);
+
+  const svgUrl = json.images[node.id];
+  if (!svgUrl) throw new Error(`No SVG URL returned for node ${node.id}`);
+
+  // 2) download the SVG
+  const svgRes = await fetch(svgUrl);
+  if (!svgRes.ok) {
+    throw new Error(
+      `Failed to download SVG: ${svgRes.status} ${svgRes.statusText}`
+    );
+  }
+
+  const svg = await svgRes.text();
+
+  let relPath: string;
+
+  if (sanitizeName) {
+    relPath = `${sanitizeFileName(generateFileName(node, parentNode), node.id)}.svg`;
+  } else {
+    relPath = `${generateFileName(node, parentNode)}.svg`;
+  }
+
+  const filePath = path.join(outDir, relPath);
+
+  // 4) create folders
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+
+  // 5) write file
+  await fs.writeFile(filePath, svg, "utf8");
+
+  console.log(
+    bgBlue(" Figma "),
+    green("✔"),
+    `Downloaded ${cyan(node.name || node.id)} → ${green(filePath)}`
+  );
+  return filePath;
+};
+
+function sanitizeFileName(name: string, fallback: string): string {
+  return (
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9-_]+/gi, "-")
+      .replace(/-+/g, "-")
+      .replace(/^-|-$/g, "") || fallback
+  );
+}

packages/core/src/cli.ts

@@ -0,0 +1,107 @@
+import type { GetFileNodesResponse } from "@figma/rest-api-spec";
+import { green, cyan, bgBlue } from "kolorist";
+
+/**
+ * Options for fetching a Figma document node.
+ * @interface FigmaNodeFetchOptions
+ * @property {string} fileId - The ID of the Figma file to fetch from
+ * @property {string} nodeId - The ID of the node to fetch (supports both "123-456" and "123:456" formats)
+ * @property {string} apiToken - The Figma API access token for authentication
+ */
+export interface FigmaNodeFetchOptions {
+  fileId: string;
+  nodeId: string;
+  apiToken: string;
+}
+
+/**
+ * Represents a node in the Figma document tree.
+ * This is a base type that includes all properties from the Figma API response.
+ */
+export type FigmaDocumentNode =
+  GetFileNodesResponse["nodes"][string]["document"];
+
+/**
+ * Represents a Figma node that contains child nodes.
+ * This type ensures the node has a children array containing other document nodes.
+ */
+export type FigmaParentNode = FigmaDocumentNode & {
+  children: FigmaDocumentNode[];
+};
+
+/**
+ * Type guard that checks if a node has children.
+ * @param {FigmaDocumentNode} node - The node to check
+ * @returns {boolean} True if the node has children, false otherwise
+ */
+export function isFigmaParentNode(
+  node: FigmaDocumentNode
+): node is FigmaParentNode {
+  return Array.isArray((node as any)?.children);
+}
+
+/**
+ * Fetches a Figma document node by its ID.
+ * @returns The document node if found and has children, null if not found.
+ * @throws Error if the node exists but has no children or if the API request fails.
+ */
+export const fetchFigmaDocumentNode = async ({
+  fileId,
+  nodeId,
+  apiToken,
+}: FigmaNodeFetchOptions): Promise<FigmaParentNode | null> => {
+  const formattedNodeId = nodeId.includes(":")
+    ? nodeId
+    : nodeId.replace(/-/g, ":"); // Figma IDs use ":" not "-"
+
+  // Log fetch initiation
+  console.log(
+    bgBlue(" Figma "),
+    "Fetching node:",
+    cyan(formattedNodeId),
+    "from file:",
+    green(fileId)
+  );
+
+  const url = `https://api.figma.com/v1/files/${fileId}/nodes?ids=${formattedNodeId}`;
+
+  const response = await fetch(url, {
+    headers: { "X-Figma-Token": apiToken },
+  });
+
+  // Log API response status
+  if (response.ok) {
+    console.log(bgBlue(" Figma "), green("✔"), "API request successful");
+  }
+
+  if (!response.ok) {
+    const errorMessage = `Failed to fetch Figma node (${response.status} ${response.statusText})`;
+    console.error(bgBlue(" Figma "), "❌", errorMessage);
+    throw new Error(errorMessage);
+  }
+
+  const data: GetFileNodesResponse = await response.json();
+  const nodeData = data.nodes?.[formattedNodeId];
+
+  if (!nodeData?.document) {
+    console.warn(bgBlue(" Figma "), "⚠️", `Node not found: ${formattedNodeId}`);
+    return null;
+  }
+
+  const documentNode = nodeData.document as FigmaDocumentNode;
+
+  if (isFigmaParentNode(documentNode)) {
+    console.log(
+      bgBlue(" Figma "),
+      green("✔"),
+      "Node retrieved successfully with",
+      cyan(documentNode.children.length.toString()),
+      "children"
+    );
+    return documentNode;
+  } else {
+    const errorMessage = `Selected node must have children (node type: ${documentNode.type})`;
+    console.error(bgBlue(" Figma "), "❌", errorMessage);
+    throw new Error(errorMessage);
+  }
+};