@agent-native/creative-context 0.1.0

package/src/connectors/figma.ts

@@ -0,0 +1,257 @@
+import { fetchFigmaNativeContextItems } from "./figma-native.js";
+import {
+  asRecord,
+  connectorConnectionId,
+  cursorOffset,
+  executeConnectorProviderRequest,
+  positiveLimit,
+  stringArray,
+  stringValue,
+} from "./provider-response.js";
+import type {
+  ContextConnectorExecutionContext,
+  ContextConnectorFetchRequest,
+  ContextConnectorFetchResult,
+  ContextConnectorInventoryPage,
+  ContextConnectorInventoryRequest,
+  ContextImportConnector,
+} from "./types.js";
+
+interface FigmaReference {
+  key: string;
+  title: string;
+  url: string;
+  sourceModifiedAt?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export class FigmaContextConnector implements ContextImportConnector {
+  readonly kind = "figma" as const;
+  readonly label = "Figma";
+  readonly supportsIncremental = true;
+
+  async inventory(
+    request: ContextConnectorInventoryRequest,
+    context: ContextConnectorExecutionContext,
+  ): Promise<ContextConnectorInventoryPage> {
+    const connectionId = await connectorConnectionId(
+      "figma",
+      request.config,
+      context.resolveConnection,
+    );
+    const references = await figmaReferences(
+      request.config,
+      connectionId,
+      context,
+    );
+    const offset = cursorOffset(request.cursor);
+    const limit = positiveLimit(request.limit, 100, 1_000);
+    const slice = references.slice(offset, offset + limit);
+    const nextOffset = offset + slice.length;
+    return {
+      items: slice.map((file) => ({
+        externalId: file.key,
+        kind: "figma-file",
+        title: file.title,
+        canonicalUrl: file.url,
+        mimeType: "application/vnd.figma.file",
+        ...(file.sourceModifiedAt
+          ? { sourceModifiedAt: file.sourceModifiedAt }
+          : {}),
+        ...(file.metadata ? { metadata: file.metadata } : {}),
+      })),
+      nextCursor: nextOffset < references.length ? String(nextOffset) : null,
+      complete: nextOffset >= references.length,
+      coverage: {
+        inspected: slice.length,
+        returned: slice.length,
+        truncated: nextOffset < references.length,
+      },
+    };
+  }
+
+  async fetch(
+    request: ContextConnectorFetchRequest,
+    context: ContextConnectorExecutionContext,
+  ): Promise<ContextConnectorFetchResult> {
+    const connectionId = await connectorConnectionId(
+      "figma",
+      request.config,
+      context.resolveConnection,
+    );
+    const sourceUrl =
+      request.item.canonicalUrl ??
+      `https://www.figma.com/design/${encodeURIComponent(request.item.externalId)}`;
+    const result = await fetchFigmaNativeContextItems({
+      fileKey: request.item.externalId,
+      sourceTitle: request.item.title,
+      sourceUrl,
+      sourceModifiedAt: request.item.sourceModifiedAt,
+      connectionId,
+      context,
+    });
+    return {
+      items: result.items,
+      ...(result.warnings.length ? { warnings: result.warnings } : {}),
+    };
+  }
+}
+
+async function figmaReferences(
+  config: Record<string, unknown>,
+  connectionId: string | undefined,
+  context: ContextConnectorExecutionContext,
+): Promise<FigmaReference[]> {
+  const urls = stringArray(config.fileUrls);
+  const keys = stringArray(config.fileKeys);
+  const records = Array.isArray(config.files) ? config.files : [];
+  const found = new Map<string, FigmaReference>();
+  for (const key of keys) {
+    found.set(key, {
+      key,
+      title: key,
+      url: `https://www.figma.com/design/${encodeURIComponent(key)}`,
+    });
+  }
+  for (const value of urls) {
+    const key = figmaKeyFromUrl(value);
+    found.set(key, { key, title: key, url: value });
+  }
+  for (const value of records) {
+    const record = asRecord(value);
+    const url = stringValue(record?.url);
+    const key =
+      stringValue(record?.key) ?? (url ? figmaKeyFromUrl(url) : undefined);
+    if (!key) continue;
+    found.set(key, {
+      key,
+      title: stringValue(record?.title) ?? stringValue(record?.name) ?? key,
+      url: url ?? `https://www.figma.com/design/${encodeURIComponent(key)}`,
+    });
+  }
+  const projectIds = new Set([
+    ...stringArray(config.projectIds),
+    ...stringArray(config.projectUrls).map((url) =>
+      figmaContainerIdFromUrl(url, "project"),
+    ),
+  ]);
+  for (const id of stringArray(config.teamIds)) {
+    for (const projectId of await figmaProjectIdsForTeam(
+      id,
+      connectionId,
+      context,
+    )) {
+      projectIds.add(projectId);
+    }
+  }
+  for (const url of stringArray(config.teamUrls)) {
+    const id = figmaContainerIdFromUrl(url, "team");
+    for (const projectId of await figmaProjectIdsForTeam(
+      id,
+      connectionId,
+      context,
+    )) {
+      projectIds.add(projectId);
+    }
+  }
+  for (const projectId of projectIds) {
+    for (const file of await figmaFilesForProject(
+      projectId,
+      connectionId,
+      context,
+    )) {
+      found.set(file.key, file);
+    }
+  }
+  if (found.size === 0) {
+    throw new Error(
+      "Figma connector config requires explicit file, project, or team IDs/URLs. The Figma API does not provide a global file inventory.",
+    );
+  }
+  return [...found.values()];
+}
+
+export function figmaRecommendedFileKeys(
+  config: Record<string, unknown>,
+): string[] {
+  return stringArray(config.recommendedFileKeys);
+}
+
+async function figmaProjectIdsForTeam(
+  teamId: string,
+  connectionId: string | undefined,
+  context: ContextConnectorExecutionContext,
+): Promise<string[]> {
+  const payload = asRecord(
+    await executeConnectorProviderRequest(context.providerApi, {
+      provider: "figma",
+      method: "GET",
+      path: `/teams/${encodeURIComponent(teamId)}/projects`,
+      connectionId,
+    }),
+  );
+  return (Array.isArray(payload?.projects) ? payload.projects : []).flatMap(
+    (value) => {
+      const id = stringValue(asRecord(value)?.id);
+      return id ? [id] : [];
+    },
+  );
+}
+
+async function figmaFilesForProject(
+  projectId: string,
+  connectionId: string | undefined,
+  context: ContextConnectorExecutionContext,
+): Promise<FigmaReference[]> {
+  const payload = asRecord(
+    await executeConnectorProviderRequest(context.providerApi, {
+      provider: "figma",
+      method: "GET",
+      path: `/projects/${encodeURIComponent(projectId)}/files`,
+      connectionId,
+      maxBytes: 4 * 1024 * 1024,
+    }),
+  );
+  return (Array.isArray(payload?.files) ? payload.files : []).flatMap(
+    (value) => {
+      const file = asRecord(value);
+      const key = stringValue(file?.key);
+      if (!key) return [];
+      return [
+        {
+          key,
+          title: stringValue(file?.name) ?? key,
+          url: `https://www.figma.com/design/${encodeURIComponent(key)}`,
+          sourceModifiedAt: stringValue(file?.last_modified),
+          metadata: { projectId },
+        },
+      ];
+    },
+  );
+}
+
+function figmaContainerIdFromUrl(
+  value: string,
+  kind: "team" | "project",
+): string {
+  const url = new URL(value);
+  if (url.hostname !== "figma.com" && !url.hostname.endsWith(".figma.com")) {
+    throw new Error(`Figma ${kind} URL must use figma.com.`);
+  }
+  const match = url.pathname.match(new RegExp(`/files/${kind}/([^/]+)`));
+  if (!match?.[1]) {
+    throw new Error(`Could not find a Figma ${kind} ID in ${value}.`);
+  }
+  return decodeURIComponent(match[1]);
+}
+
+function figmaKeyFromUrl(value: string): string {
+  const url = new URL(value);
+  if (url.hostname !== "figma.com" && !url.hostname.endsWith(".figma.com")) {
+    throw new Error("Figma file URL must use figma.com.");
+  }
+  const match = url.pathname.match(/\/(?:file|design|board)\/([^/]+)/);
+  if (!match?.[1])
+    throw new Error(`Could not find a Figma file key in ${value}.`);
+  return decodeURIComponent(match[1]);
+}

package/src/connectors/fixtures/google-slides-native.json

@@ -0,0 +1,353 @@
+{
+  "presentationId": "fixture-deck-2026",
+  "title": "Native compiler fixture",
+  "locale": "en-US",
+  "revisionId": "revision-42",
+  "pageSize": {
+    "width": { "magnitude": 9144000, "unit": "EMU" },
+    "height": { "magnitude": 5143500, "unit": "EMU" }
+  },
+  "masters": [
+    {
+      "objectId": "master-1",
+      "pageProperties": {
+        "pageBackgroundFill": {
+          "solidFill": {
+            "color": {
+              "rgbColor": { "red": 0.04, "green": 0.06, "blue": 0.12 }
+            }
+          }
+        },
+        "colorScheme": {
+          "colors": [
+            {
+              "type": "ACCENT1",
+              "color": {
+                "rgbColor": { "red": 0.36, "green": 0.24, "blue": 0.95 }
+              }
+            },
+            {
+              "type": "TEXT1",
+              "color": { "rgbColor": { "red": 0.96, "green": 0.97, "blue": 1 } }
+            }
+          ]
+        }
+      },
+      "pageElements": [
+        {
+          "objectId": "master-title",
+          "size": {
+            "width": { "magnitude": 7315200, "unit": "EMU" },
+            "height": { "magnitude": 914400, "unit": "EMU" }
+          },
+          "transform": {
+            "scaleX": 1,
+            "scaleY": 1,
+            "translateX": 914400,
+            "translateY": 457200,
+            "unit": "EMU"
+          },
+          "shape": {
+            "shapeType": "TEXT_BOX",
+            "placeholder": { "type": "TITLE", "index": 0 },
+            "text": {
+              "textElements": [
+                { "paragraphMarker": { "style": { "alignment": "START" } } },
+                {
+                  "textRun": {
+                    "content": "Master title",
+                    "style": {
+                      "fontFamily": "Inter",
+                      "fontSize": { "magnitude": 30, "unit": "PT" }
+                    }
+                  }
+                }
+              ]
+            }
+          }
+        }
+      ]
+    }
+  ],
+  "layouts": [
+    {
+      "objectId": "layout-1",
+      "layoutProperties": { "masterObjectId": "master-1" },
+      "pageElements": [
+        {
+          "objectId": "layout-title",
+          "size": {
+            "width": { "magnitude": 7315200, "unit": "EMU" },
+            "height": { "magnitude": 914400, "unit": "EMU" }
+          },
+          "transform": {
+            "scaleX": 1,
+            "scaleY": 1,
+            "translateX": 914400,
+            "translateY": 457200,
+            "unit": "EMU"
+          },
+          "shape": {
+            "shapeType": "TEXT_BOX",
+            "placeholder": {
+              "type": "TITLE",
+              "index": 0,
+              "parentObjectId": "master-title"
+            },
+            "text": {
+              "textElements": [
+                { "paragraphMarker": { "style": { "alignment": "CENTER" } } },
+                {
+                  "textRun": {
+                    "content": "Layout title",
+                    "style": {
+                      "foregroundColor": {
+                        "opaqueColor": { "themeColor": "TEXT1" }
+                      }
+                    }
+                  }
+                }
+              ]
+            }
+          }
+        }
+      ]
+    }
+  ],
+  "slides": [
+    {
+      "objectId": "slide-1",
+      "slideProperties": {
+        "layoutObjectId": "layout-1",
+        "masterObjectId": "master-1"
+      },
+      "pageElements": [
+        {
+          "objectId": "slide-title",
+          "title": "Launch title",
+          "size": {
+            "width": { "magnitude": 7315200, "unit": "EMU" },
+            "height": { "magnitude": 914400, "unit": "EMU" }
+          },
+          "transform": {
+            "scaleX": 1,
+            "scaleY": 1,
+            "translateX": 914400,
+            "translateY": 457200,
+            "unit": "EMU"
+          },
+          "shape": {
+            "shapeType": "TEXT_BOX",
+            "placeholder": {
+              "type": "TITLE",
+              "index": 0,
+              "parentObjectId": "layout-title"
+            },
+            "text": {
+              "textElements": [
+                { "paragraphMarker": { "style": { "alignment": "CENTER" } } },
+                {
+                  "textRun": {
+                    "content": "Revenue <script>alert('x')</script>",
+                    "style": {
+                      "bold": true,
+                      "fontSize": { "magnitude": 30, "unit": "PT" },
+                      "foregroundColor": {
+                        "opaqueColor": { "themeColor": "ACCENT1" }
+                      }
+                    }
+                  }
+                },
+                {
+                  "textRun": {
+                    "content": "\n2026",
+                    "style": {
+                      "fontFamily": "Inter",
+                      "fontSize": { "magnitude": 18, "unit": "PT" }
+                    }
+                  }
+                }
+              ]
+            }
+          }
+        },
+        {
+          "objectId": "ellipse-1",
+          "size": {
+            "width": { "magnitude": 1371600, "unit": "EMU" },
+            "height": { "magnitude": 1371600, "unit": "EMU" }
+          },
+          "transform": {
+            "scaleX": 1,
+            "scaleY": 1,
+            "shearX": 0.1,
+            "translateX": 457200,
+            "translateY": 2514600,
+            "unit": "EMU"
+          },
+          "shape": {
+            "shapeType": "ELLIPSE",
+            "shapeProperties": {
+              "shapeBackgroundFill": {
+                "solidFill": { "color": { "themeColor": "ACCENT1" } }
+              },
+              "outline": {
+                "weight": { "magnitude": 1, "unit": "PT" },
+                "outlineFill": {
+                  "solidFill": {
+                    "color": { "rgbColor": { "red": 1, "green": 1, "blue": 1 } }
+                  }
+                }
+              }
+            }
+          }
+        },
+        {
+          "objectId": "image-1",
+          "size": {
+            "width": { "magnitude": 2743200, "unit": "EMU" },
+            "height": { "magnitude": 1828800, "unit": "EMU" }
+          },
+          "transform": {
+            "scaleX": 1,
+            "scaleY": 1,
+            "translateX": 5486400,
+            "translateY": 2286000,
+            "unit": "EMU"
+          },
+          "image": {
+            "contentUrl": "https://assets.example.test/photo.png?temporary=1",
+            "sourceUrl": "https://example.test/provenance/photo",
+            "imageProperties": {
+              "cropProperties": {
+                "leftOffset": 0.1,
+                "rightOffset": 0.05,
+                "topOffset": 0.15,
+                "bottomOffset": 0.05
+              }
+            }
+          }
+        },
+        {
+          "objectId": "table-1",
+          "size": {
+            "width": { "magnitude": 3657600, "unit": "EMU" },
+            "height": { "magnitude": 914400, "unit": "EMU" }
+          },
+          "transform": {
+            "scaleX": 1,
+            "scaleY": 1,
+            "translateX": 2286000,
+            "translateY": 3657600,
+            "unit": "EMU"
+          },
+          "table": {
+            "rows": 1,
+            "columns": 2,
+            "tableColumns": [
+              { "columnWidth": { "magnitude": 1371600, "unit": "EMU" } },
+              { "columnWidth": { "magnitude": 2286000, "unit": "EMU" } }
+            ],
+            "tableRows": [
+              {
+                "rowHeight": { "magnitude": 914400, "unit": "EMU" },
+                "tableCells": [
+                  {
+                    "text": {
+                      "textElements": [{ "textRun": { "content": "ARR" } }]
+                    },
+                    "tableCellProperties": {
+                      "tableCellBackgroundFill": {
+                        "solidFill": {
+                          "color": {
+                            "rgbColor": {
+                              "red": 0.1,
+                              "green": 0.12,
+                              "blue": 0.2
+                            }
+                          }
+                        }
+                      }
+                    }
+                  },
+                  {
+                    "text": {
+                      "textElements": [{ "textRun": { "content": "$12M" } }]
+                    },
+                    "tableCellProperties": {
+                      "tableCellBackgroundFill": {
+                        "solidFill": {
+                          "color": {
+                            "rgbColor": {
+                              "red": 0.1,
+                              "green": 0.12,
+                              "blue": 0.2
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "objectId": "group-1",
+          "size": {
+            "width": { "magnitude": 914400, "unit": "EMU" },
+            "height": { "magnitude": 457200, "unit": "EMU" }
+          },
+          "transform": {
+            "scaleX": 1,
+            "scaleY": 1,
+            "translateX": 7315200,
+            "translateY": 457200,
+            "unit": "EMU"
+          },
+          "elementGroup": {
+            "children": [
+              {
+                "objectId": "group-label",
+                "size": {
+                  "width": { "magnitude": 914400, "unit": "EMU" },
+                  "height": { "magnitude": 457200, "unit": "EMU" }
+                },
+                "transform": {
+                  "scaleX": 1,
+                  "scaleY": 1,
+                  "translateX": 0,
+                  "translateY": 0,
+                  "unit": "EMU"
+                },
+                "shape": {
+                  "shapeType": "ROUND_RECTANGLE",
+                  "text": {
+                    "textElements": [{ "textRun": { "content": "NEW" } }]
+                  }
+                }
+              }
+            ]
+          }
+        },
+        {
+          "objectId": "word-art-1",
+          "title": "Decorative word art",
+          "size": {
+            "width": { "magnitude": 1828800, "unit": "EMU" },
+            "height": { "magnitude": 457200, "unit": "EMU" }
+          },
+          "transform": {
+            "scaleX": 1,
+            "scaleY": 1,
+            "translateX": 3657600,
+            "translateY": 1828800,
+            "unit": "EMU"
+          },
+          "wordArt": { "renderedText": "GO" }
+        }
+      ]
+    }
+  ]
+}