@animaapp/anima-sdk 0.3.0 → 0.3.4

package/example.env

@@ -0,0 +1,2 @@
+# `FIGMA_AUTH_TOKEN` is used only for updating the design snapshot used by the tests
+FIGMA_AUTH_TOKEN=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animaapp/anima-sdk",
-  "version": "0.3.0",
+  "version": "0.3.4",
   "type": "module",
   "description": "Anima's JavaScript utilities library",
   "author": "Anima App, Inc.",
@@ -22,7 +22,8 @@
     "build": "vite build",
     "dev": "vite build --watch",
     "test": "vitest --watch=false",
-    "prepack": "yarn build"
+    "prepack": "yarn build",
+    "update-design-test-snapshot": "tsx tests/design/update.ts"
   },
   "dependencies": {
     "@animaapp/http-client-figma": "^1.0.2",
@@ -30,9 +31,11 @@
     "zod": "^3.24.1"
   },
   "devDependencies": {
+    "dotenv": "^16.4.7",
+    "tsx": "^4.19.3",
     "vite": "^6.0.11",
     "vite-plugin-dts": "^4.5.0",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^3.0.5"
   }
-}
+}

package/tsconfig.json

@@ -1,5 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/tsconfig",
   "extends": "../tsconfig.json",
+  "include": ["./src/**/*", "./tests/**/*"],
   "exclude": ["../sdk-react"]
 }

package/.turbo/turbo-build.log

@@ -1,12 +0,0 @@
-
-vite v6.0.11 building for production...
-transforming (1) src/index.ts✓ 14 modules transformed.
-rendering chunks (1)...
-[vite:dts] Start generate declaration files...
-computing gzip size (0)...computing gzip size (1)...dist/index.cjs  88.33 kB │ gzip: 23.70 kB │ map: 326.42 kB
-[vite:dts] Start rollup declaration files...
-Analysis will use the bundled TypeScript version 5.7.2
-[vite:dts] Declaration files built in 2117ms.
-
-rendering chunks (1)...computing gzip size (1)...dist/index.js  125.80 kB │ gzip: 28.43 kB │ map: 340.53 kB
-✓ built in 2.40s

package/.turbo/turbo-test.log

@@ -1,21 +0,0 @@
-
-[?25l
- RUN  v3.0.5 /Users/macabeus/ApenasMeu/anima/anima-sdk/sdk
-
-[?2026h
- ❯ src/utils/figma.spec.ts [queued]
-
- Test Files 0 passed (1)
-      Tests 0 passed (0)
-   Start at 21:43:55
-   Duration 102ms
-[?2026l ✓ src/utils/figma.spec.ts (2 tests) 2ms
-   ✓ # figma > .formatToFigmaLink > generates a link with file key and node id
-   ✓ # figma > .formatToFigmaLink > when the "duplicate" flag is enabled > generates a link including the '/duplicated' path
-
- Test Files  1 passed (1)
-      Tests  2 passed (2)
-   Start at  21:43:55
-   Duration  234ms (transform 24ms, setup 0ms, collect 20ms, tests 2ms, environment 0ms, prepare 44ms)
-
-[?25h

package/src/anima.ts

@@ -1,281 +0,0 @@
-import { CodegenError } from "./errors";
-import { validateSettings } from "./settings";
-import {
-  AnimaSDKResult,
-  GetCodeHandler,
-  GetCodeParams,
-  SSECodgenMessage,
-} from "./types";
-
-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 integrations, 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;
-      }
-    }
-
-    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);
-
-    let tracking = params.tracking;
-    if (this.#auth && "userId" in this.#auth && this.#auth.userId) {
-      if (!tracking?.externalId) {
-        tracking = { externalId: this.#auth.userId };
-      }
-    }
-
-    const response = await fetch(`${this.#apiBaseAddress}/v1/codegen`, {
-      method: "POST",
-      headers: {
-        ...this.headers,
-        Accept: "text/event-stream",
-      },
-      body: JSON.stringify({
-        tracking,
-        fileKey: params.fileKey,
-        figmaToken: params.figmaToken,
-        nodesId: params.nodesId,
-        assetsStorage: params.assetsStorage,
-        language: settings.language,
-        model: settings.model,
-        framework: settings.framework,
-        styling: settings.styling,
-        uiLibrary: settings.uiLibrary,
-        enableTranslation: settings.enableTranslation,
-        enableUILibraryTheming: settings.enableUILibraryTheming,
-        enableCompactStructure: settings.enableCompactStructure,
-        enableAutoSplit: settings.enableAutoSplit,
-        autoSplitThreshold: settings.autoSplitThreshold,
-        disableMarkedForExport: settings.disableMarkedForExport,
-      }),
-    });
-
-    if (!response.ok) {
-      const errorData = await response
-        .json()
-        .catch(() => "HTTP error from Anima API");
-
-      if (typeof errorData === "string") {
-        throw new CodegenError({
-          name: errorData,
-          reason: "Unknown",
-          detail: { status: response.status },
-          status: response.status,
-        });
-      }
-
-      if (typeof errorData !== "object") {
-        throw new CodegenError({
-          name: `Error "${errorData}"`,
-          reason: "Unknown",
-          detail: { status: response.status },
-          status: response.status,
-        });
-      }
-
-      if (errorData.error?.name === "ZodError") {
-        throw new CodegenError({
-          name: "HTTP error from Anima API",
-          reason: "Invalid body payload",
-          detail: errorData.error.issues,
-          status: response.status,
-        });
-      }
-
-      throw new CodegenError({
-        name: errorData.error?.name || "HTTP error from Anima API",
-        reason: "Unknown",
-        detail: { status: response.status },
-        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 "queueing": {
-                typeof handler === "function"
-                  ? handler(data)
-                  : handler.onQueueing?.();
-                break;
-              }
-              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 "assets_list": {
-                result.assets = data.payload.assets;
-
-                typeof handler === "function"
-                  ? handler(data)
-                  : handler.onAssetsList?.(data.payload);
-                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": {
-                if (data.payload.status === "success") {
-                  result.files = data.payload.files;
-                }
-
-                typeof handler === "function"
-                  ? handler(data)
-                  : handler.onGeneratingCode?.({
-                      status: data.payload.status,
-                      progress: data.payload.progress,
-                      files: data.payload.files,
-                    });
-                break;
-              }
-
-              case "codegen_completed": {
-                typeof handler === "function"
-                  ? handler(data)
-                  : handler.onCodegenCompleted?.();
-                break;
-              }
-
-              case "error": {
-                throw new CodegenError({
-                  name: data.payload.errorName,
-                  reason: data.payload.reason,
-                });
-              }
-
-              case "done": {
-                if (!result.files) {
-                  throw new CodegenError({
-                    name: "Invalid response",
-                    reason: "No code generated",
-                  });
-                }
-
-                result.tokenUsage = data.payload.tokenUsage;
-                return result as AnimaSDKResult;
-              }
-            }
-          }
-        }
-      }
-    } finally {
-      reader.cancel();
-    }
-
-    throw new CodegenError({
-      name: "Connection",
-      reason: "Connection closed before the 'done' message",
-      status: 500,
-    });
-  }
-}

package/src/dataStream.ts

@@ -1,129 +0,0 @@
-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: {
-        name: string;
-        message: CodegenErrorReason;
-        status?: number;
-        detail?: unknown;
-      };
-    };
-
-/**
- * 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") {
-            // TODO: It's a dead code. It's never reached, since all errors are thrown.
-            // 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",
-            payload: {
-              tokenUsage: _result.tokenUsage,
-              sessionId: _result.sessionId,
-            },
-          });
-          controller.close();
-        })
-        .catch((error) => {
-          controller.enqueue({
-            type: "error",
-            payload: {
-              name: "name" in error ? error.name : "Unknown error",
-              message: "message" in error ? error.message : "Unknown",
-              status: "status" in error ? error.status : undefined,
-              detail: "detail" in error ? error.detail : 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 encoder = new TextEncoder();
-  const seeStream = consumerStream.pipeThrough(
-    new TransformStream({
-      transform(chunk, controller) {
-        const sseString = `event: ${chunk.type}\ndata: ${JSON.stringify(
-          chunk
-        )}\n\n`;
-        controller.enqueue(encoder.encode(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

@@ -1,47 +0,0 @@
-// TODO: `CodegenErrorReason` should be imported from `anima-public-api`
-/**
- * Errors from Public API
- */
-export type CodegenErrorReason =
-  | "Selected node type is not supported"
-  | "Selected node is a page with multiple children"
-  | "There is no node with the given id"
-  | "Invalid Figma token"
-  | "Anima API connection error"
-  | "Figma token expired"
-  | "Invalid user token"
-  | "Figma file not found"
-  | "Figma rate limit exceeded"
-  | "Unknown";
-
-/**
- * Errors from the SDK
- */
-export type SDKErrorReason =
-  | "Invalid body payload"
-  | "No code generated"
-  | "Connection closed before the 'done' message"
-  | "Response body is null";
-
-export class CodegenError extends Error {
-  status?: number;
-  detail?: unknown;
-
-  constructor({
-    name,
-    reason,
-    status,
-    detail,
-  }: {
-    name: string;
-    reason: CodegenErrorReason | SDKErrorReason;
-    status?: number;
-    detail?: unknown;
-  }) {
-    super();
-    this.name = name;
-    this.message = reason;
-    this.detail = detail;
-    this.status = status;
-  }
-}

package/src/figma/figmaError.ts

@@ -1,120 +0,0 @@
-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 type FigmaApiError = {
-  cause?: { body?: { status?: number; reason?: string } };
-  body?: { status?: number; reason?: string };
-};
-
-export const handleFigmaApiError = (error: FigmaApiError, fileKey: string) => {
-  const err = error?.cause?.body || error.body;
-
-  if (err?.status === 403) {
-    throw new FigmaTokenIssue({
-      fileKey,
-      reason: (error?.cause?.body?.reason || error.body?.reason || "Access denied").toString(),
-    });
-  }
-
-  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

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