@animaapp/anima-sdk 0.1.0

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@animaapp/anima-sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Anima's JavaScript utilities library",
+  "author": "Anima App, Inc.",
+  "license": "ISC",
+  "packageManager": "yarn@4.6.0",
+  "exports": {
+    "import": "./dist/index.js",
+    "require": "./dist/index.cjs"
+  },
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AnimaApp/anima-sdk.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "vite build",
+    "tests": "vitest run --dir ./tests",
+    "prepack": "yarn build"
+  },
+  "dependencies": {
+    "@animaapp/http-client-figma": "^1.0.2",
+    "@figma/rest-api-spec": "^0.23.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "vite": "^6.0.11",
+    "vite-plugin-dts": "^4.5.0",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.0.5"
+  }
+}

package/src/anima.ts

@@ -0,0 +1,240 @@
+import { CodegenError } from "./errors";
+import { validateSettings } from "./settings";
+import {
+  AnimaFiles,
+  AnimaSDKResult,
+  GetCodeHandler,
+  GetCodeParams,
+  SSECodgenMessage,
+} from "./types";
+import { convertCodegenFilesToAnimaFiles } from "./codegenToAnimaFiles";
+export type Auth =
+  | { token: string; teamId: string } // for Anima user, it's mandatory to have an associated team
+  | { token: string; userId?: string }; // for users from a 3rd-party client (e.g., Bolt) they may have optionally a user id
+
+export class Anima {
+  #auth?: Auth;
+  #apiBaseAddress: string;
+
+  constructor({
+    auth,
+    apiBaseAddress = "https://public-api.animaapp.com",
+  }: {
+    auth?: Auth;
+    apiBaseAddress?: string;
+    path?: string;
+  } = {}) {
+    this.#apiBaseAddress = apiBaseAddress;
+
+    if (auth) {
+      this.auth = auth;
+    }
+  }
+
+  protected hasAuth() {
+    return !!this.#auth;
+  }
+
+  set auth(auth: Auth) {
+    this.#auth = auth;
+  }
+
+  protected get headers() {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+
+    if (this.#auth) {
+      headers["Authorization"] = `Bearer ${this.#auth.token}`;
+
+      if ("teamId" in this.#auth) {
+        headers["X-Team-Id"] = this.#auth.teamId;
+      }
+
+      if ("userId" in this.#auth && this.#auth.userId) {
+        headers["X-User-Id"] = this.#auth.userId;
+      }
+    }
+
+    return headers;
+  }
+
+  async generateCode(params: GetCodeParams, handler: GetCodeHandler = {}) {
+    if (this.hasAuth() === false) {
+      throw new Error('It needs to set "auth" before calling this method.');
+    }
+
+    const result: Partial<AnimaSDKResult> = {};
+    const settings = validateSettings(params.settings);
+
+    const response = await fetch(`${this.#apiBaseAddress}/v1/codegen`, {
+      method: "POST",
+      headers: {
+        ...this.headers,
+        Accept: "text/event-stream",
+      },
+      body: JSON.stringify({
+        fileKey: params.fileKey,
+        figmaToken: params.figmaToken,
+        nodesId: params.nodesId,
+        language: settings.language,
+        framework: settings.framework,
+        styling: settings.styling,
+        uiLibrary: settings.uiLibrary,
+        enableTranslation: settings.enableTranslation,
+      }),
+    });
+
+    if (!response.ok) {
+      let errorMessage;
+      try {
+        const errorData = await response.json();
+        errorMessage =
+          errorData.message || `HTTP error! status: ${response.status}`;
+      } catch {
+        errorMessage = `HTTP error! status: ${response.status}`;
+      }
+      throw new CodegenError({
+        name: "HTTP Error",
+        reason: errorMessage,
+        status: response.status,
+      });
+    }
+
+    if (!response.body) {
+      throw new CodegenError({
+        name: "Stream Error",
+        reason: "Response body is null",
+        status: response.status,
+      });
+    }
+
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          break;
+        }
+
+        buffer += decoder.decode(value, { stream: true });
+
+        const lines = buffer.split("\n");
+
+        // Process all complete lines
+        buffer = lines.pop() || ""; // Keep the last incomplete line in the buffer
+
+        for (const line of lines) {
+          if (!line.trim() || line.startsWith(":")) continue;
+
+          if (line.startsWith("data: ")) {
+            let data: SSECodgenMessage;
+            try {
+              data = JSON.parse(line.slice(6));
+            } catch {
+              // ignore malformed JSON
+              continue;
+            }
+
+            switch (data.type) {
+              case "start": {
+                result.sessionId = data.sessionId;
+                typeof handler === "function"
+                  ? handler(data)
+                  : handler.onStart?.({ sessionId: data.sessionId });
+                break;
+              }
+
+              case "pre_codegen": {
+                typeof handler === "function"
+                  ? handler(data)
+                  : handler.onPreCodegen?.({ message: data.message });
+                break;
+              }
+
+              case "assets_uploaded": {
+                typeof handler === "function"
+                  ? handler(data)
+                  : handler.onAssetsUploaded?.();
+                break;
+              }
+
+              case "figma_metadata": {
+                result.figmaFileName = data.figmaFileName;
+                result.figmaSelectedFrameName = data.figmaSelectedFrameName;
+
+                typeof handler === "function"
+                  ? handler(data)
+                  : handler.onFigmaMetadata?.({
+                    figmaFileName: data.figmaFileName,
+                    figmaSelectedFrameName: data.figmaSelectedFrameName,
+                  });
+                break;
+              }
+
+              case "generating_code": {
+                const codegenFiles = data.payload.files as Record<
+                  string,
+                  { code: string; type: "code" }
+                >;
+
+                const files = convertCodegenFilesToAnimaFiles(codegenFiles);
+                
+                if (data.payload.status === "success") {
+                  result.files = files;
+                }
+
+                typeof handler === "function"
+                  ? handler(data)
+                  : handler.onGeneratingCode?.({
+                    status: data.payload.status,
+                    progress: data.payload.progress,
+                    files,
+                  });
+                break;
+              }
+
+              case "codegen_completed": {
+                typeof handler === "function"
+                  ? handler(data)
+                  : handler.onCodegenCompleted?.();
+                break;
+              }
+
+              case "error": {
+                // not sure if we want to throw on "stream" errors
+                throw new CodegenError({
+                  name: data.payload.errorName,
+                  reason: data.payload.reason,
+                });
+              }
+
+              case "done": {
+                if (!result.files) {
+                  // not sure if we want to throw on "logical" errors
+                  // I think we should throw only on "HTTP" errors
+                  throw new CodegenError({
+                    name: "Invalid response",
+                    reason: "No files found",
+                  });
+                }
+                return result as AnimaSDKResult;
+              }
+            }
+          }
+        }
+      }
+    } finally {
+      reader.cancel();
+    }
+
+    throw new CodegenError({
+      name: "Connection",
+      reason: "Connection closed before the 'done' message",
+      status: 500,
+    });
+  }
+}

package/src/codegenToAnimaFiles.ts

@@ -0,0 +1,13 @@
+import { AnimaFiles } from "./types";
+
+export const convertCodegenFilesToAnimaFiles = (
+  codegenFiles: Record<string, { code: string; type: "code" }>
+): AnimaFiles => {
+  return Object.entries(codegenFiles).reduce(
+    (acc, [fileName, file]) => {
+      acc[fileName] = { content: file.code, isBinary: false };
+      return acc;
+    },
+    {} as AnimaFiles
+  );
+};

package/src/dataStream.ts

@@ -0,0 +1,108 @@
+import type { Anima } from "./anima";
+import type { CodegenErrorReason } from "./errors";
+import type { GetCodeParams, SSECodgenMessage } from "./types";
+
+export type StreamCodgenMessage =
+  | Exclude<SSECodgenMessage, { type: "error" }>
+  | { type: "error"; payload: { message: CodegenErrorReason, status?: number } };
+
+/**
+ * Start the code generation and creates a ReadableStream to output its result.
+ *
+ * The stream is closed when the codegen ends.
+ *
+ * @param {Anima} anima - An Anima service instance to generate the code from.
+ * @param {GetCodeParams} params - Parameters required for the code generation process.
+ * @returns {ReadableStream<StreamCodgenMessage>} - A ReadableStream that emits messages related to the code generation process.
+ */
+export const createCodegenStream = (
+  anima: Anima,
+  params: GetCodeParams
+): ReadableStream<StreamCodgenMessage> => {
+  return new ReadableStream({
+    start(controller) {
+      anima
+        .generateCode(params, (message) => {
+          if (message.type === "error") {
+            console.log('NOT SURE IF THIS IS REACHABLE, ALL ERRORS ARE THROWING');
+            controller.enqueue({
+              type: "error",
+              payload: { message: message.payload.reason },
+            });
+          } else {
+            controller.enqueue(message);
+          }
+
+          if (message.type === "aborted" || message.type === "error") {
+            controller.close();
+          }
+        })
+        .then((result) => {
+          controller.enqueue({ type: "done" });
+          controller.close();
+        })
+        .catch((error) => {
+          controller.enqueue({
+            type: "error",
+            payload: {
+              message: "message" in error ? error.message : "Unknown",
+              status: "status" in error ? error.status : undefined,
+            },
+          });
+          controller.close();
+        });
+    },
+  });
+};
+
+/**
+ * Creates a Server-Sent Events (SSE) `Response` that forwards all messages from the code generation stream.
+ *
+ * But, if the first message indicates an error (e.g., connection failed), the function returns a 500 response with the error message.
+ *
+ * @param {Anima} anima - The Anima instance to use for creating the data stream.
+ * @param {GetCodeParams} params - The parameters for the code generation request.
+ * @returns {Promise<Response>} - A promise that resolves to an HTTP response.
+ */
+export const createCodegenResponseEventStream = async (
+  anima: Anima,
+  params: GetCodeParams
+): Promise<Response> => {
+  const stream = createCodegenStream(anima, params);
+
+  const [verifyStream, consumerStream] = stream.tee();
+  const firstMessage = await verifyStream.getReader().read();
+
+  if (
+    firstMessage.done ||
+    !firstMessage.value ||
+    firstMessage.value?.type === "error" && firstMessage.value?.payload?.status
+  ) {
+    return new Response(JSON.stringify(firstMessage.value), {
+      status: firstMessage.value?.type === "error" ? (firstMessage.value?.payload?.status ?? 500) : 500,
+      headers: {
+        "Content-Type": "application/json",
+      },
+    });
+  }
+
+  const seeStream = consumerStream.pipeThrough(
+    new TransformStream({
+      transform(chunk, controller) {
+        const sseString = `event: ${chunk.type}\ndata: ${JSON.stringify(
+          chunk
+        )}\n\n`;
+        controller.enqueue(sseString);
+      },
+    })
+  );
+
+  return new Response(seeStream, {
+    status: 200,
+    headers: {
+      "Content-Type": "text/event-stream; charset=utf-8",
+      "Connection": "keep-alive",
+      "Cache-Control": "no-cache",
+    },
+  });
+};

package/src/errors.ts

@@ -0,0 +1,21 @@
+// TODO: `CodegenErrorReason` should be imported from `anima-public-api`
+export type CodegenErrorReason =
+  | "The selected node is not a frame"
+  | "There is no node with the given id"
+  | "Invalid Figma token"
+  | "Figma token expired"
+  | "No files found"
+  | "Connection closed before the 'done' message"
+  | "Unknown"
+  | "Response body is null";
+
+export class CodegenError extends Error {
+  status?: number;
+
+  constructor({ name, reason, status }: { name: string; reason: CodegenErrorReason; status?: number }) {
+    super();
+    this.name = `[Codegen Error] ${name}`;
+    this.message = reason;
+    this.status = status;
+  }
+}

package/src/figma/figmaError.ts

@@ -0,0 +1,115 @@
+import type { CodegenErrorReason } from "../errors";
+
+const figmaTokenIssueErrorMessage = "Figma Token Issue";
+export class FigmaTokenIssue extends Error {
+  fileKey: string;
+  reason: string;
+
+  constructor({ fileKey, reason }: { fileKey: string; reason: string }) {
+    super(figmaTokenIssueErrorMessage);
+
+    this.fileKey = fileKey;
+    this.reason = reason;
+  }
+}
+
+const rateLimitExceededErrorMessage = "Rate Limit Exceeded";
+export class RateLimitExceeded extends Error {
+  fileKey: string;
+
+  constructor({ fileKey }: { fileKey: string }) {
+    super(rateLimitExceededErrorMessage);
+
+    this.fileKey = fileKey;
+  }
+}
+
+// Not Found
+const notFoundErrorMessage = "Not Found";
+export class NotFound extends Error {
+  fileKey: string;
+
+  constructor({ fileKey }: { fileKey: string }) {
+    super(notFoundErrorMessage);
+
+    this.fileKey = fileKey;
+  }
+}
+export const isNotFound = (error: Error) => {
+  return error.message === notFoundErrorMessage;
+};
+
+// Unknown Exception
+const unknownFigmaApiExceptionMessage = "Unknown Figma API Exception";
+export class UnknownFigmaApiException extends Error {
+  fileKey: string;
+
+  constructor({ fileKey, cause }: { fileKey: string; cause: unknown }) {
+    super(unknownFigmaApiExceptionMessage);
+
+    this.name = "UnknownFigmaApiException";
+    this.fileKey = fileKey;
+    this.cause = cause;
+  }
+}
+export const isUnknownFigmaApiException = (error: Error) => {
+  return error.message === unknownFigmaApiExceptionMessage;
+};
+
+export const isRateLimitExceeded = (error: Error) => {
+  return error.message === rateLimitExceededErrorMessage;
+};
+
+export const isFigmaTokenIssue = (error: Error) => {
+  const figmaTokenCodegenErrors: CodegenErrorReason[] = [
+    "Invalid Figma token",
+    "Figma token expired",
+  ];
+
+  return [figmaTokenIssueErrorMessage, ...figmaTokenCodegenErrors].includes(
+    error.message
+  );
+};
+
+export const handleFigmaApiError = (error: any, fileKey: string) => {
+  const err = error?.cause?.body || error.body;
+
+  if (err?.status === 403) {
+    throw new FigmaTokenIssue({
+      fileKey,
+      reason: error?.cause?.body || error.body,
+    });
+  }
+
+  if (err?.status === 429) {
+    throw new RateLimitExceeded({ fileKey });
+  }
+
+  if (err?.status === 404) {
+    throw new NotFound({ fileKey });
+  }
+
+  throw new UnknownFigmaApiException({ fileKey, cause: error });
+};
+
+export type FigmaApiErrorType =
+  | "FigmaTokenIssue"
+  | "RateLimitExceeded"
+  | "NotFound"
+  | "UnknownFigmaApiException";
+
+export const getFigmaApiErrorType = (error: Error): FigmaApiErrorType => {
+  if (isNotFound(error)) {
+    return "NotFound";
+  }
+
+  if (isRateLimitExceeded(error)) {
+    return "RateLimitExceeded";
+  }
+
+  if (isFigmaTokenIssue(error)) {
+    return "FigmaTokenIssue";
+  }
+
+  return "UnknownFigmaApiException";
+};

package/src/figma/index.ts

@@ -0,0 +1,2 @@
+export * from "./figmaError";
+export * from "./utils";

package/src/figma/utils.ts

@@ -0,0 +1,73 @@
+import type { GetFileResponse, Node } from '@figma/rest-api-spec';
+import { FigmaRestApi } from '@animaapp/http-client-figma';
+import { handleFigmaApiError } from './figmaError';
+
+export type FigmaNode = Node;
+export type GetFileParams = { fileKey: string; authToken?: string; figmaRestApi?: FigmaRestApi };
+
+export type FigmaPage = { id: string; name: string };
+export type GetFilePagesParams = {
+  fileKey: string;
+  authToken?: string;
+  figmaRestApi?: FigmaRestApi;
+  params?: Record<string, any>;
+};
+export type GetFilePagesResult = FigmaPage[] | undefined;
+export type GetFileNodesParams = {
+  fileKey: string;
+  authToken?: string;
+  nodeIds: string[];
+  figmaRestApi?: FigmaRestApi;
+  params?: Record<string, any>;
+};
+
+export type GetFigmaFileResult = GetFileResponse | undefined;
+
+export const getFigmaFile = async ({
+  fileKey,
+  authToken,
+  figmaRestApi = new FigmaRestApi(),
+  params = {},
+}: GetFilePagesParams): Promise<GetFigmaFileResult> => {
+  if (authToken) {
+    figmaRestApi.token = authToken;
+  }
+
+  try {
+    const rootFile = await figmaRestApi.files.get({
+      fileKey,
+      params,
+    });
+
+    return rootFile;
+  } catch (error) {
+    console.error(error);
+    throw error;
+  }
+};
+
+export const getFileNodes = async ({
+  fileKey,
+  authToken,
+  nodeIds,
+  figmaRestApi = new FigmaRestApi(),
+  params = {},
+}: GetFileNodesParams) => {
+  if (authToken) {
+    figmaRestApi.token = authToken;
+  }
+
+  try {
+    const data = await figmaRestApi.nodes.get({
+      fileKey,
+      nodeIds,
+      params: {
+        ...params,
+      },
+    });
+
+    return data.nodes;
+  } catch (error) {
+    return handleFigmaApiError(error, fileKey);
+  }
+};

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./anima";
+export * from "./types";
+export * from "./errors";
+export * from "./utils";
+export * from "./figma";
+export * from "./settings";
+export * from "./dataStream";
+export * from "./codegenToAnimaFiles";

package/src/settings.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+
+const CodegenSettingsSchema = z
+  .object({
+    language: z.enum(["typescript", "javascript"]).optional(),
+  })
+  .and(
+    z.union([
+      z.object({
+        framework: z.literal("react"),
+        styling: z.enum([
+          "plain_css",
+          "css_modules",
+          "styled_components",
+          "tailwind",
+          "sass",
+          "scss",
+          "inline_styles",
+        ]),
+        uiLibrary: z.enum(["mui", "antd", "radix", "shadcn"]).optional(),
+      }),
+      z.object({
+        framework: z.literal("html"),
+        styling: z.enum(["plain_css", "inline_styles"]),
+        enableTranslation: z.boolean().optional(),
+      }),
+    ])
+  );
+
+// We don't use the z.infer method here because the types returned by zod aren't ergonic
+export type CodegenSettings = {
+  language?: "typescript" | "javascript";
+  framework: "react" | "html";
+  styling:
+    | "plain_css"
+    | "css_modules"
+    | "styled_components"
+    | "tailwind"
+    | "sass"
+    | "scss"
+    | "inline_styles"
+  uiLibrary?: "mui" | "antd" | "radix" | "shadcn";
+  enableTranslation?: boolean;
+};
+
+export const validateSettings = (obj: unknown): CodegenSettings => {
+  const parsedObj = CodegenSettingsSchema.safeParse(obj);
+
+  if (parsedObj.success === false) {
+    const error = new Error("Invalid codegen settings");
+    error.cause = parsedObj.error;
+    throw error;
+  }
+
+  return parsedObj.data;
+};