@animaapp/anima-sdk 0.6.18 → 0.6.21

package/dist/index.d.ts

@@ -17,6 +17,39 @@ export declare class Anima {
     protected get headers(): Record<string, string>;
     generateCode(params: GetCodeParams, handler?: GetCodeHandler, signal?: AbortSignal): Promise<AnimaSDKResult>;
     generateCodeFromWebsite(params: GetCodeFromWebsiteParams, handler?: GetCodeFromWebsiteHandler, signal?: AbortSignal): Promise<AnimaSDKResult>;
+    /**
+     * Generates code from a text prompt using AI.
+     *
+     * This method sends a prompt to the Anima API and generates code based on the description provided.
+     * It supports real-time streaming of the generation process through Server-Sent Events (SSE).
+     *
+     * @param params - The parameters for code generation
+     * @param params.prompt - The text prompt describing what code to generate
+     * @param params.settings - Code generation settings (framework, language, styling, etc.)
+     * @param params.assetsStorage - Optional asset storage configuration
+     * @param params.tracking - Optional tracking information
+     * @param params.webhookUrl - Optional webhook URL for completion notification
+     * @param handler - Event handler for processing SSE messages during generation
+     * @param signal - Optional AbortSignal to cancel the request
+     * @returns Promise resolving to AnimaSDKResult with generated files and metadata
+     *
+     * @example
+     * ```typescript
+     * const result = await anima.generateCodeFromPrompt({
+     *   prompt: "Create a login form with email and password fields",
+     *   settings: {
+     *     framework: "react",
+     *     language: "typescript",
+     *     styling: "tailwind"
+     *   }
+     * }, {
+     *   onStart: ({ sessionId }) => console.log("Started:", sessionId),
+     *   onGeneratingCode: ({ progress }) => console.log("Progress:", progress),
+     *   onCodegenCompleted: () => console.log("Generation completed!")
+     * });
+     * ```
+     */
+    generateCodeFromPrompt(params: GetCodeFromPromptParams, handler?: GetCodeFromPromptHandler, signal?: AbortSignal): Promise<AnimaSDKResult>;
     /**
      * @deprecated This method will be removed soon, please use `generateCodeFromWebsite` instead.
      */
@@ -53,26 +86,30 @@ export declare type Auth = {
 
 export declare type BaseResult = {
     sessionId: string;
-    figmaFileName: string;
-    figmaSelectedFrameName: string;
+    figmaFileName?: string;
+    figmaSelectedFrameName?: string;
     tokenUsage: number;
 };
 
+export declare type BaseSettings = {
+    codegenSettings?: Record<string, unknown>;
+};
+
 export declare class CodegenError extends Error {
     status?: number;
     detail?: unknown;
     constructor({ name, reason, status, detail, }: {
         name: string;
-        reason: CommonApiError | CodegenErrorReason | CodegenRouteErrorReason | SDKErrorReason | GetCodeFromWebsiteErrorReason;
+        reason: CommonApiError | GetCodeFromFigmaErrorReason | CodegenRouteErrorReason | SDKErrorReason | GetCodeFromWebsiteErrorReason | GetCodeFromPromptErrorReason;
         status?: number;
         detail?: unknown;
     });
 }
 
 /**
- * Codegen errors from the worker
+ * @deprecated This type is deprecated and will be removed soon.
  */
-export declare type CodegenErrorReason = "Selected node type is not supported" | "Invisible group nodes are unsupported" | "Selected node is a page with multiple children" | "Selected node is a page with no valid 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 CodegenErrorReason = GetCodeFromFigmaErrorReason;
 
 export declare type CodegenResult = BaseResult & {
     files: Record<string, {
@@ -86,7 +123,7 @@ export declare type CodegenResult = BaseResult & {
  */
 export declare type CodegenRouteErrorReason = "Not all frames id from responsive pages are mentioned on the nodes id list" | "Too many screens to import";
 
-export declare type CodegenSettings = {
+export declare type CodegenSettings = BaseSettings & {
     language?: "typescript" | "javascript";
     model?: string;
     framework: "react" | "html";
@@ -109,7 +146,6 @@ export declare type CodegenSettings = {
     enableDisplayDataId?: boolean;
     enableDisplayDataName?: boolean;
     url?: string;
-    codegenSettings?: Record<string, unknown>;
 };
 
 /**
@@ -117,6 +153,30 @@ export declare type CodegenSettings = {
  */
 export declare type CommonApiError = "Missing Authorization header" | "Invalid Authorization header" | "Missing teamId" | "Internal server error" | "Forbidden, no team access" | "Requested Usage Exceeds Limit" | "Too many concurrent jobs" | "Invalid Anima token";
 
+/**
+ * Creates a Server-Sent Events (SSE) `Response` that forwards all messages from the code generation from prompt 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 {GetCodeFromPromptParams} params - The parameters for the code generation request.
+ * @returns {Promise<Response>} - A promise that resolves to an HTTP response.
+ */
+export declare const createCodeFromPromptResponseEventStream: (anima: Anima, params: GetCodeFromPromptParams) => Promise<Response>;
+
+/**
+ * Prompt to Code (p2c) stream flow.
+ *
+ * Start the prompt to code generation and creates a ReadableStream to output its result.
+ *
+ * The stream is closed when the code generation ends.
+ *
+ * @param {Anima} anima - An Anima service instance to generate the code from.
+ * @param {GetCodeFromPromptParams} params - Parameters required for the code generation process.
+ * @returns {ReadableStream<StreamCodeFromPromptMessage>} - A ReadableStream that emits messages related to the code generation process.
+ */
+export declare const createCodeFromPromptStream: (anima: Anima, params: GetCodeFromPromptParams) => ReadableStream<StreamCodeFromPromptMessage>;
+
 /**
  * Creates a Server-Sent Events (SSE) `Response` that forwards all messages from the code generation from website stream.
  *
@@ -232,6 +292,51 @@ export declare type GeneratingCodePayload = {
     files: AnimaFiles;
 };
 
+/**
+ * Codegen errors from the worker
+ */
+export declare type GetCodeFromFigmaErrorReason = "Selected node type is not supported" | "Invisible group nodes are unsupported" | "Selected node is a page with multiple children" | "Selected node is a page with no valid 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";
+
+/**
+ * Errors from the Prompt To Code Flow
+ */
+export declare type GetCodeFromPromptErrorReason = "Invalid prompt" | "Generation failed" | "Unknown";
+
+export declare type GetCodeFromPromptHandler = ((message: SSEGetCodeFromPromptMessage) => 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 GetCodeFromPromptParams = {
+    prompt: string;
+    assetsStorage?: AssetsStorage;
+    settings: GetCodeFromPromptSettings;
+    tracking?: TrackingInfos;
+    webhookUrl?: string;
+};
+
+export declare type GetCodeFromPromptSettings = BaseSettings & {
+    language?: "typescript";
+    framework: "react" | "html";
+    styling: "tailwind" | "inline_styles";
+    uiLibrary?: "shadcn";
+};
+
 /**
  * Errors from the Website To Code Flow
  */
@@ -266,14 +371,14 @@ export declare type GetCodeFromWebsiteParams = {
     webhookUrl?: string;
 };
 
-export declare type GetCodeFromWebsiteSettings = {
+export declare type GetCodeFromWebsiteSettings = BaseSettings & {
     language?: "typescript";
     framework: "react" | "html";
     styling: "tailwind" | "inline_styles";
     uiLibrary?: "shadcn";
 };
 
-export declare type GetCodeHandler = ((message: SSECodgenMessage) => void) | {
+export declare type GetCodeHandler = ((message: SSEGetCodeFromFigmaMessage) => void) | {
     onQueueing?: () => void;
     onStart?: ({ sessionId }: {
         sessionId: string;
@@ -467,7 +572,7 @@ export declare type L2CParamsStyling = 'tailwind' | 'inline-styles';
  * @deprecated This type is deprecated and will be removed soon.
  */
 export declare type L2CParamsUrlInput = {
-    type: 'url';
+    type: "url";
     url: string;
 };
 
@@ -479,6 +584,14 @@ export declare class NotFound extends Error {
     });
 }
 
+export declare type ProgressMessage = {
+    id: string;
+    text: string;
+    attachments?: {
+        images?: string[];
+    };
+};
+
 export declare class RateLimitExceeded extends Error {
     fileKey: string;
     constructor({ fileKey, cause }: {
@@ -503,32 +616,49 @@ export declare class ResponseError extends Error {
 /**
  * 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 SDKErrorReason = "Invalid body payload" | "Connection closed before the 'done' message" | "Response body is null";
+
+/**
+ * @deprecated This type is deprecated and will be removed soon.
+ */
+export declare type SSECodegenMessage = SSEGetCodeFromFigmaMessage;
+
+export declare type SSECommonMessage = {
+    type: "queueing";
+} | {
+    type: "progress_messages_updated";
+    payload: {
+        progressMessages: ProgressMessage[];
+    };
+} | {
+    type: "aborted";
+};
 
-export declare type SSECodegenMessageErrorPayload = {
+export declare type SSEErrorPayload<Reason> = {
     errorName: string;
     task?: string;
-    reason: CodegenErrorReason;
+    reason: Reason;
     sentryTraceId?: string;
 };
 
-export declare type SSECodgenMessage = {
-    type: "queueing";
-} | {
+export declare type SSEGetCodeFromFigmaMessage = SSECommonMessage | {
     type: "start";
     sessionId: string;
-} | {
-    type: "pre_codegen";
-    message: string;
 } | {
     type: "figma_metadata";
     figmaFileName: string;
     figmaSelectedFrameName: string;
+} | {
+    type: "pre_codegen";
+    message: string;
 } | {
     type: "generating_code";
     payload: GeneratingCodePayload;
 } | {
     type: "codegen_completed";
+} | {
+    type: "post_codegen";
+    message: string;
 } | {
     type: "assets_uploaded";
 } | {
@@ -539,11 +669,9 @@ export declare type SSECodgenMessage = {
             url: string;
         }>;
     };
-} | {
-    type: "aborted";
 } | {
     type: "error";
-    payload: SSECodgenMessageErrorPayload;
+    payload: SSEGetCodeFromFigmaMessageErrorPayload;
 } | {
     type: "done";
     payload: {
@@ -552,26 +680,41 @@ export declare type SSECodgenMessage = {
     };
 };
 
-export declare type SSECodgenMessageErrorPayload = {
-    errorName: string;
-    task?: string;
-    reason: CodegenErrorReason;
-};
+export declare type SSEGetCodeFromFigmaMessageErrorPayload = SSEErrorPayload<GetCodeFromFigmaErrorReason>;
 
-export declare type SSEGetCodeFromWebsiteMessage = {
-    type: 'queueing';
+export declare type SSEGetCodeFromPromptMessage = SSECommonMessage | {
+    type: "start";
+    sessionId: string;
+} | {
+    type: "generation_completed";
+} | {
+    type: "error";
+    payload: SSEGetCodeFromPromptMessageErrorPayload;
 } | {
-    type: 'start';
+    type: "done";
+    payload: {
+        sessionId: string;
+        tokenUsage: number;
+    };
+};
+
+export declare type SSEGetCodeFromPromptMessageErrorPayload = SSEErrorPayload<GetCodeFromPromptErrorReason>;
+
+export declare type SSEGetCodeFromWebsiteMessage = SSECommonMessage | {
+    type: "start";
     sessionId: string;
 } | {
-    type: 'generating_code';
+    type: "generating_code";
     payload: GeneratingCodePayload;
 } | {
-    type: 'generation_completed';
+    type: "generation_completed";
+} | {
+    type: "post_codegen";
+    message: string;
 } | {
-    type: 'assets_uploaded';
+    type: "assets_uploaded";
 } | {
-    type: 'assets_list';
+    type: "assets_list";
     payload: {
         assets: Array<{
             name: string;
@@ -579,43 +722,38 @@ export declare type SSEGetCodeFromWebsiteMessage = {
         }>;
     };
 } | {
-    type: 'aborted';
-} | {
-    type: 'error';
+    type: "error";
     payload: SSEGetCodeFromWebsiteMessageErrorPayload;
 } | {
-    type: 'done';
+    type: "done";
     payload: {
         sessionId: string;
         tokenUsage: number;
     };
 };
 
-export declare type SSEGetCodeFromWebsiteMessageErrorPayload = {
-    errorName: string;
-    task?: string;
-    reason: GetCodeFromWebsiteErrorReason;
-    sentryTraceId?: string;
-};
+export declare type SSEGetCodeFromWebsiteMessageErrorPayload = SSEErrorPayload<GetCodeFromWebsiteErrorReason>;
 
 /**
  * @deprecated This type is deprecated and will be removed soon.
  */
 export declare type SSEL2CMessage = SSEGetCodeFromWebsiteMessage;
 
+export declare type StreamCodeFromPromptMessage = StreamMessage<SSEGetCodeFromPromptMessage>;
+
 export declare type StreamCodeFromWebsiteMessage = StreamMessage<SSEGetCodeFromWebsiteMessage>;
 
-export declare type StreamCodgenMessage = StreamMessage<SSECodgenMessage>;
+export declare type StreamCodgenMessage = StreamMessage<SSEGetCodeFromFigmaMessage>;
 
 declare type StreamErrorPayload = {
     name: string;
-    message: CodegenErrorReason;
+    message: GetCodeFromFigmaErrorReason;
     status?: number;
     detail?: unknown;
-    errorPayload?: SSECodegenMessageErrorPayload;
+    errorPayload?: SSEGetCodeFromFigmaMessageErrorPayload;
 };
 
-export declare type StreamL2CMessage = StreamMessage<SSEL2CMessage>;
+export declare type StreamL2CMessage = StreamMessage<SSEGetCodeFromWebsiteMessage>;
 
 export declare type StreamMessage<T> = Exclude<T, {
     type: "error";