@animaapp/anima-sdk 0.3.11 → 0.4.3

package/dist/index.d.ts

@@ -0,0 +1,533 @@
+import { Component } from '@figma/rest-api-spec';
+import { ComponentSet } from '@figma/rest-api-spec';
+import { FigmaRestApi } from '@animaapp/http-client-figma';
+import { GetFileResponse } from '@figma/rest-api-spec';
+import { Node as Node_2 } from '@figma/rest-api-spec';
+import { Style } from '@figma/rest-api-spec';
+
+export declare class Anima {
+    #private;
+    constructor({ auth, apiBaseAddress, }?: {
+        auth?: Auth;
+        apiBaseAddress?: string;
+        path?: string;
+    });
+    protected hasAuth(): boolean;
+    set auth(auth: Auth);
+    protected get headers(): Record<string, string>;
+    generateCode(params: GetCodeParams, handler?: GetCodeHandler): Promise<AnimaSDKResult>;
+    /**
+     * @experimental
+     * This API is experimental and may change or be removed in future releases.
+     * Link2Code (l2c) flow.
+     */
+    generateLink2Code(params: GetLink2CodeParams, handler?: GetLink2CodeHandler): Promise<AnimaSDKResult>;
+}
+
+export declare type AnimaFiles = Record<string, {
+    content: string;
+    isBinary: boolean;
+}>;
+
+export declare type AnimaSDKResult = BaseResult & {
+    files: AnimaFiles;
+    assets?: Array<{
+        name: string;
+        url: string;
+    }>;
+};
+
+export declare type AssetsStorage = {
+    strategy: "host";
+} | {
+    strategy: "external";
+    url: string;
+};
+
+export declare type Auth = {
+    token: string;
+    teamId: string;
+} | {
+    token: string;
+    userId?: string;
+};
+
+export declare type BaseResult = {
+    sessionId: string;
+    figmaFileName: string;
+    figmaSelectedFrameName: string;
+    tokenUsage: number;
+};
+
+export declare class CodegenError extends Error {
+    status?: number;
+    detail?: unknown;
+    constructor({ name, reason, status, detail, }: {
+        name: string;
+        reason: CodegenErrorReason | CodegenRouteErrorReason | SDKErrorReason;
+        status?: number;
+        detail?: unknown;
+    });
+}
+
+/**
+ * Codegen errors from the worker
+ */
+export declare type CodegenErrorReason = "Selected node type is not supported" | "Invisible group nodes are unsupported" | "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" | "Figma selection too large" | "Invalid responsive page node type" | "Unknown";
+
+export declare type CodegenResult = BaseResult & {
+    files: Record<string, {
+        code: string;
+        type: "code";
+    }>;
+};
+
+/**
+ * Codegen errors from the "/codegen" route
+ */
+export declare type CodegenRouteErrorReason = "Missing Authorization header" | "Invalid Authorization header" | "Missing teamId" | "Internal server error" | "Forbidden, no team access" | "Requested Usage Exceeds Limit" | "Not all frames id from responsive pages are mentioned on the nodes id list" | "Too many screens to import" | "Invalid Anima token";
+
+export declare type CodegenSettings = {
+    language?: "typescript" | "javascript";
+    model?: string;
+    framework: "react" | "html";
+    styling: "plain_css" | "css_modules" | "styled_components" | "tailwind" | "sass" | "scss" | "inline_styles";
+    uiLibrary?: "mui" | "antd" | "radix" | "shadcn";
+    responsivePages?: Array<{
+        name: string;
+        framesId: string[];
+    }>;
+    enableTranslation?: boolean;
+    enableUILibraryTheming?: boolean;
+    enableCompactStructure?: boolean;
+    enableAutoSplit?: boolean;
+    autoSplitThreshold?: number;
+    disableMarkedForExport?: boolean;
+    enableDisplayScreenModelId?: boolean;
+    enableGeneratePackageLock?: boolean;
+};
+
+/**
+ * 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 declare const createCodegenResponseEventStream: (anima: Anima, params: GetCodeParams) => Promise<Response>;
+
+/**
+ * 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 declare const createCodegenStream: (anima: Anima, params: GetCodeParams) => ReadableStream<StreamCodgenMessage>;
+
+/**
+ * Creates a Server-Sent Events (SSE) `Response` that forwards all messages from the URL to 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 {GetLink2CodeParams} params - The parameters for the URL to code generation request.
+ * @returns {Promise<Response>} - A promise that resolves to an HTTP response.
+ */
+export declare const createLink2CodeResponseEventStream: (anima: Anima, params: GetLink2CodeParams) => Promise<Response>;
+
+/**
+ * @experimental
+ * This API is experimental and may change or be removed in future releases.
+ * Link2Code (l2c) stream flow.
+ *
+ * Start the URL to code generation and creates a ReadableStream to output its result.
+ *
+ * The stream is closed when the URL to code generation ends.
+ *
+ * @param {Anima} anima - An Anima service instance to generate the code from.
+ * @param {GetLink2CodeParams} params - Parameters required for the URL to code generation process.
+ * @returns {ReadableStream<StreamL2CMessage>} - A ReadableStream that emits messages related to the URL to code generation process.
+ */
+export declare const createLink2CodeStream: (anima: Anima, params: GetLink2CodeParams) => ReadableStream<StreamL2CMessage>;
+
+export declare type FigmaApiError = {
+    cause: {
+        message?: string;
+        body: {
+            err: string;
+            status: number;
+        };
+    };
+};
+
+export declare type FigmaApiErrorType = "FigmaTokenIssue" | "RateLimitExceeded" | "NotFound" | "UnknownFigmaApiException" | "RequestTooLarge";
+
+export declare type FigmaNode = Node_2;
+
+export declare type FigmaPage = {
+    id: string;
+    name: string;
+};
+
+export declare class FigmaTokenIssue extends Error {
+    fileKey: string;
+    reason: string;
+    constructor({ fileKey, reason, cause, }: {
+        fileKey: string;
+        reason: string;
+        cause?: unknown;
+    });
+}
+
+export declare const findChildrenNode: (node: FigmaNode, targetNodeId: string) => FigmaNode | null;
+
+export declare const formatToFigmaLink: ({ fileKey, nodeId, duplicate, }: {
+    fileKey: string;
+    nodeId: string;
+    duplicate?: boolean;
+}) => URL;
+
+export declare type GeneratingCodePayload = {
+    status: "success" | "running" | "failure";
+    progress: number;
+    files: AnimaFiles;
+};
+
+export declare type GetCodeHandler = ((message: SSECodgenMessage) => void) | {
+    onQueueing?: () => void;
+    onStart?: ({ sessionId }: {
+        sessionId: string;
+    }) => void;
+    onPreCodegen?: ({ message }: {
+        message: string;
+    }) => void;
+    onAssetsUploaded?: () => void;
+    onAssetsList?: ({ assets, }: {
+        assets: Array<{
+            name: string;
+            url: string;
+        }>;
+    }) => void;
+    onFigmaMetadata?: ({ figmaFileName, figmaSelectedFrameName, }: {
+        figmaFileName: string;
+        figmaSelectedFrameName: string;
+    }) => void;
+    onGeneratingCode?: ({ status, progress, files, }: {
+        status: "success" | "running" | "failure";
+        progress: number;
+        files: AnimaFiles;
+    }) => void;
+    onCodegenCompleted?: () => void;
+};
+
+export declare type GetCodeParams = {
+    fileKey: string;
+    figmaToken?: string;
+    nodesId: string[];
+    assetsStorage?: AssetsStorage;
+    settings: CodegenSettings;
+    tracking?: TrackingInfos;
+};
+
+export declare const getFigmaApiErrorType: (error: Error) => FigmaApiErrorType;
+
+export declare const getFigmaFile: ({ fileKey, authToken, figmaRestApi, params, }: GetFilePagesParams) => Promise<GetFileResponse>;
+
+export declare const getFileNodes: ({ fileKey, authToken, nodeIds, figmaRestApi, params, }: GetFileNodesParams) => Promise<{
+    [key: string]: {
+        document: Node_2;
+        components: {
+            [key: string]: Component;
+        };
+        componentSets: {
+            [key: string]: ComponentSet;
+        };
+        schemaVersion: number;
+        styles: {
+            [key: string]: Style;
+        };
+    };
+}>;
+
+export declare type GetFileNodesParams = {
+    fileKey: string;
+    authToken?: string;
+    nodeIds: string[];
+    figmaRestApi?: FigmaRestApi;
+    params?: Record<string, string | number>;
+};
+
+export declare type GetFilePagesParams = {
+    fileKey: string;
+    authToken?: string;
+    figmaRestApi?: FigmaRestApi;
+    params?: Record<string, string | number | undefined>;
+};
+
+export declare type GetFilePagesResult = FigmaPage[] | undefined;
+
+export declare type GetFileParams = {
+    fileKey: string;
+    authToken?: string;
+    figmaRestApi?: FigmaRestApi;
+};
+
+export declare type GetLink2CodeHandler = ((message: SSEL2CMessage) => void) | {
+    onQueueing?: () => void;
+    onStart?: ({ sessionId }: {
+        sessionId: string;
+    }) => void;
+    onAssetsUploaded?: () => void;
+    onAssetsList?: ({ assets, }: {
+        assets: Array<{
+            name: string;
+            url: string;
+        }>;
+    }) => void;
+    onGeneratingCode?: ({ status, progress, files, }: {
+        status: "success" | "running" | "failure";
+        progress: number;
+        files: AnimaFiles;
+    }) => void;
+    onCodegenCompleted?: () => void;
+};
+
+export declare type GetLink2CodeParams = {
+    params: L2CParams;
+    assetsStorage?: AssetsStorage;
+    tracking?: TrackingInfos;
+};
+
+export declare const getRelatedScreenFiles: ({ files, screenPath, }: {
+    files: AnimaFiles;
+    screenPath?: string;
+}) => AnimaFiles;
+
+declare type InvalidNodeForCodegenReason = "Selected node is a page with multiple children" | "There is no node with the given id" | "Selected node type is not supported";
+
+export declare const isFigmaTokenIssue: (error: Error) => boolean;
+
+/**
+ * Check if the pair "design" + "node id" are valid for code generation.
+ */
+export declare const isNodeCodegenCompatible: (design: GetFileResponse, nodeId: string) => ValidateNodeForCodegenResult;
+
+export declare const isNotFound: (error: Error) => boolean;
+
+export declare const isRateLimitExceeded: (error: Error) => boolean;
+
+export declare const isRequestTooLarge: (error: Error) => boolean;
+
+export declare const isUnknownFigmaApiException: (error: Error) => boolean;
+
+export declare const isValidFigmaUrl: (figmaLink: string) => [hasCorrectPrefix: boolean, fileKey: string, nodeId: string];
+
+export declare type L2CParams = {
+    input: L2CParamsInput;
+    conventions: L2CParamsConvention;
+    assetsStorage: L2CParamsAssetsStorage;
+};
+
+export declare type L2CParamsAssetsStorage = L2CParamsBundledAssetsStorage;
+
+export declare type L2CParamsBundledAssetsStorage = {
+    type: 'bundled';
+    referencePath?: string;
+};
+
+export declare type L2CParamsConvention = L2CParamsHtmlConvention | L2CParamsReactConvention;
+
+export declare type L2CParamsFramework = 'html' | 'react';
+
+export declare type L2CParamsHtmlConvention = {
+    framework: 'html';
+    styling: L2CParamsStyling;
+};
+
+export declare type L2CParamsInput = L2CParamsUrlInput;
+
+export declare type L2CParamsLanguage = 'typescript';
+
+export declare type L2CParamsReactConvention = {
+    framework: 'react';
+    language: L2CParamsLanguage;
+    styling: L2CParamsStyling;
+};
+
+export declare type L2CParamsStyling = 'tailwind' | 'inline-styles';
+
+export declare type L2CParamsUrlInput = {
+    type: 'url';
+    url: string;
+};
+
+export declare class NotFound extends Error {
+    fileKey: string;
+    constructor({ fileKey, cause }: {
+        fileKey: string;
+        cause?: unknown;
+    });
+}
+
+export declare class RateLimitExceeded extends Error {
+    fileKey: string;
+    constructor({ fileKey, cause }: {
+        fileKey: string;
+        cause?: unknown;
+    });
+}
+
+export declare class RequestTooLarge extends Error {
+    fileKey: string;
+    constructor({ fileKey, cause }: {
+        fileKey: string;
+        cause?: unknown;
+    });
+}
+
+export declare class ResponseError extends Error {
+    response: Response;
+    constructor(message: string, res: Response);
+}
+
+/**
+ * Errors from the SDK
+ */
+export declare type SDKErrorReason = "Invalid body payload" | "No code generated" | "Connection closed before the 'done' message" | "Response body is null";
+
+export declare type SSECodegenMessageErrorPayload = {
+    errorName: string;
+    task?: string;
+    reason: CodegenErrorReason;
+    sentryTraceId?: string;
+};
+
+export declare type SSECodgenMessage = {
+    type: "queueing";
+} | {
+    type: "start";
+    sessionId: string;
+} | {
+    type: "pre_codegen";
+    message: string;
+} | {
+    type: "figma_metadata";
+    figmaFileName: string;
+    figmaSelectedFrameName: string;
+} | {
+    type: "generating_code";
+    payload: GeneratingCodePayload;
+} | {
+    type: "codegen_completed";
+} | {
+    type: "assets_uploaded";
+} | {
+    type: "assets_list";
+    payload: {
+        assets: Array<{
+            name: string;
+            url: string;
+        }>;
+    };
+} | {
+    type: "aborted";
+} | {
+    type: "error";
+    payload: SSECodgenMessageErrorPayload;
+} | {
+    type: "done";
+    payload: {
+        sessionId: string;
+        tokenUsage: number;
+    };
+};
+
+export declare type SSECodgenMessageErrorPayload = {
+    errorName: string;
+    task?: string;
+    reason: CodegenErrorReason;
+};
+
+export declare type SSEL2CMessage = {
+    type: 'queueing';
+} | {
+    type: 'start';
+    sessionId: string;
+} | {
+    type: 'generating_code';
+    payload: GeneratingCodePayload;
+} | {
+    type: 'generation_completed';
+} | {
+    type: 'assets_uploaded';
+} | {
+    type: 'assets_list';
+    payload: {
+        assets: Array<{
+            name: string;
+            url: string;
+        }>;
+    };
+} | {
+    type: 'aborted';
+} | {
+    type: 'error';
+    payload: SSECodegenMessageErrorPayload;
+} | {
+    type: 'done';
+    payload: {
+        sessionId: string;
+        tokenUsage: number;
+    };
+};
+
+export declare type StreamCodgenMessage = StreamMessage<SSECodgenMessage>;
+
+declare type StreamErrorPayload = {
+    name: string;
+    message: CodegenErrorReason;
+    status?: number;
+    detail?: unknown;
+    errorPayload?: SSECodegenMessageErrorPayload;
+};
+
+export declare type StreamL2CMessage = StreamMessage<SSEL2CMessage>;
+
+export declare type StreamMessage<T> = Exclude<T, {
+    type: "error";
+}> | {
+    type: "error";
+    payload: StreamErrorPayload;
+};
+
+export declare type TrackingInfos = {
+    externalId: string;
+};
+
+export declare class UnknownFigmaApiException extends Error {
+    fileKey: string;
+    constructor({ fileKey, cause }: {
+        fileKey: string;
+        cause: unknown;
+    });
+}
+
+declare type ValidateNodeForCodegenResult = {
+    isValid: true;
+    node: FigmaNode;
+    note?: "Selected node is a page with a single valid children - returning it instead";
+} | {
+    isValid: false;
+    reason: InvalidNodeForCodegenReason;
+};
+
+export declare const validateSettings: (obj: unknown) => CodegenSettings;
+
+export declare const wrapFigmaApiError: (error: FigmaApiError, fileKey: string) => Error;
+
+export { }