[feat] get figma interaction data

src/extractors/built-in.ts

@@ -14,6 +14,7 @@ import {
   hasTextStyle,
   isTextNode,
 } from "~/transformers/text.js";
+import { buildSimplifiedInteractions } from "~/transformers/interaction.js";
 import { hasValue, isRectangleCornerRadii } from "~/utils/identity.js";
 import { generateVarId } from "~/utils/common.js";
 import type { Node as FigmaDocumentNode } from "@figma/rest-api-spec";
@@ -83,7 +84,10 @@ export const visualsExtractor: ExtractorFn = (node, result, context) => {
 
   // fills
   if (hasValue("fills", node) && Array.isArray(node.fills) && node.fills.length) {
-    const fills = node.fills.map((fill) => parsePaint(fill, hasChildren)).reverse();
+    const fills = node.fills
+      .filter((fill): fill is NonNullable<typeof fill> => fill != null)
+      .map((fill) => parsePaint(fill, hasChildren))
+      .reverse();
     const styleName = getStyleName(node, context, ["fill", "fills"]);
     if (styleName) {
       context.globalVars.styles[styleName] = fills;
@@ -158,6 +162,16 @@ export const componentExtractor: ExtractorFn = (node, result, _context) => {
   }
 };
 
+/**
+ * Extracts prototype interaction data (triggers and actions) from nodes.
+ */
+export const interactionExtractor: ExtractorFn = (node, result, _context) => {
+  const interactions = buildSimplifiedInteractions(node);
+  if (interactions) {
+    result.interactions = interactions;
+  }
+};
+
 // Helper to fetch a Figma style name for specific style keys on a node
 function getStyleName(
   node: FigmaDocumentNode,
@@ -181,7 +195,13 @@ function getStyleName(
 /**
  * All extractors - replicates the current parseNode behavior.
  */
-export const allExtractors = [layoutExtractor, textExtractor, visualsExtractor, componentExtractor];
+export const allExtractors = [
+  layoutExtractor,
+  textExtractor,
+  visualsExtractor,
+  componentExtractor,
+  interactionExtractor,
+];
 
 /**
  * Layout and text only - useful for content analysis and layout planning.

src/extractors/index.ts

@@ -19,6 +19,7 @@ export {
   textExtractor,
   visualsExtractor,
   componentExtractor,
+  interactionExtractor,
   // Convenience combinations
   allExtractors,
   layoutAndText,

src/extractors/node-walker.ts

@@ -76,6 +76,7 @@ function processNodeWithExtractors(
     // Use the same pattern as the existing parseNode function
     if (hasValue("children", node) && node.children.length > 0) {
       const children = node.children
+        .filter((child): child is NonNullable<typeof child> => child != null)
         .filter((child) => shouldProcessNode(child, options))
         .map((child) => processNodeWithExtractors(child, extractors, childContext, options))
         .filter((child): child is SimplifiedNode => child !== null);

src/extractors/types.ts

@@ -8,6 +8,7 @@ import type {
   SimplifiedComponentDefinition,
   SimplifiedComponentSetDefinition,
 } from "~/transformers/component.js";
+import type { SimplifiedInteraction } from "~/transformers/interaction.js";
 
 export type StyleTypes =
   | SimplifiedTextStyle
@@ -90,6 +91,8 @@ export interface SimplifiedNode {
   // for rect-specific strokes, etc.
   componentId?: string;
   componentProperties?: ComponentProperties[];
+  // prototype interactions
+  interactions?: SimplifiedInteraction[];
   // children
   children?: SimplifiedNode[];
 }

src/index.ts

@@ -17,6 +17,7 @@ export {
   textExtractor,
   visualsExtractor,
   componentExtractor,
+  interactionExtractor,
   allExtractors,
   layoutAndText,
   contentOnly,

src/services/figma.ts

@@ -1,5 +1,6 @@
 import path from "path";
 import type {
+  Node as FigmaDocumentNode,
   GetImagesResponse,
   GetFileResponse,
   GetFileNodesResponse,
@@ -278,21 +279,69 @@ export class FigmaService {
   }
 
   /**
-   * Get raw Figma API response for specific nodes (for use with flexible extractors)
+   * Get raw Figma API response for specific nodes (for use with flexible extractors).
+   *
+   * Fetches the full file rather than using `ids` or the `/nodes` endpoint.
+   * Both `/files?ids=` and `/files/nodes` nullify interaction destinationIds
+   * when the destination falls outside the queried subtree. Fetching the full
+   * file preserves all prototype interaction data.
+   *
+   * The `depth` parameter is NOT forwarded to the API—it is only used by the
+   * extractor pipeline to limit traversal. This ensures the target node and
+   * its interaction destinations are always present in the response.
    */
   async getRawNode(
     fileKey: string,
     nodeId: string,
     depth?: number | null,
   ): Promise<GetFileNodesResponse> {
-    const endpoint = `/files/${fileKey}/nodes?ids=${nodeId}${depth ? `&depth=${depth}` : ""}`;
+    const endpoint = `/files/${fileKey}`;
     Logger.log(
       `Retrieving raw Figma node: ${nodeId} from ${fileKey} (depth: ${depth ?? "default"})`,
     );
 
-    const response = await this.request<GetFileNodesResponse>(endpoint);
-    writeLogs("figma-raw.json", response);
+    const fileResponse = await this.request<GetFileResponse>(endpoint);
+    writeLogs("figma-raw.json", fileResponse);
 
-    return response;
+    const targetNode = findNodeInTree(fileResponse.document, nodeId);
+    if (!targetNode) {
+      throw new Error(`Node ${nodeId} not found in file ${fileKey}`);
+    }
+
+    return {
+      name: fileResponse.name,
+      role: fileResponse.role,
+      lastModified: fileResponse.lastModified,
+      editorType: fileResponse.editorType,
+      thumbnailUrl: fileResponse.thumbnailUrl ?? "",
+      version: fileResponse.version,
+      nodes: {
+        [nodeId]: {
+          document: targetNode,
+          components: fileResponse.components ?? {},
+          componentSets: fileResponse.componentSets ?? {},
+          schemaVersion: fileResponse.schemaVersion,
+          styles: fileResponse.styles ?? {},
+        },
+      },
+    };
   }
 }
+
+/**
+ * Recursively searches a Figma document tree for a node with the given ID.
+ * Guards against null/undefined entries that may appear in pruned API responses.
+ */
+function findNodeInTree(node: FigmaDocumentNode, targetId: string): FigmaDocumentNode | null {
+  if (!node || typeof node !== "object") return null;
+  if (node.id === targetId) return node;
+
+  const children = "children" in node && Array.isArray(node.children) ? node.children : [];
+  for (const child of children) {
+    if (!child) continue;
+    const found = findNodeInTree(child as FigmaDocumentNode, targetId);
+    if (found) return found;
+  }
+
+  return null;
+}