@builder.io/ai-utils 0.1.1 → 0.1.3

package/src/events.d.ts

@@ -0,0 +1,354 @@
+import type { BuilderContent, BuilderElement } from "@builder.io/sdk";
+import type { AssistantMessage } from "./messages.js";
+import type { AssistantSettings } from "./settings.js";
+export type BuilderAssistantEventHandler = (ev: BuilderAssistantEvent) => void;
+export type BuilderAssistantEvent = AssistantCompletionResultEvent | AssistantErrorEvent | AssistantStreamErrorEvent | AppCloseEvent | AppMessagesClickEvent | AppMessagesGenerationEvent | AppMessageEditCustomInstructionsEvent | AppPromptAbortEvent | AppPromptFocusEvent | AppPromptSubmitEvent | AppReadyEvent | AppSettingsSetEvent | AppThreadNewEvent | AssistantStatsEvent | AssistantThemeEvent | BuilderEditorAuthEvent | BuilderEditorStateEvent | ContentUpdateEvent | ContentApplySnapshotEvent | ModelUndoEvent | ModelRedoEvent | ResultEvent | ThreadCreatedEvent | ThreadMessageCompletedEvent | ThreadMessageCreatedEvent | ThreadMessageDeltaEvent | ThreadMessageFeedbackEvent | ThreadRunStepCreatedEvent | ThreadRunStepDeltaEvent | AppAcceptChangeEvent | AppAcceptRejectEvent | AssistantTrackEvent | AssistantEditorAuthMessage | AppAttachmentTemplateEvent | ThreadMessageRetryEvent | AppFigmaImportEvent | AppWebImportEvent | AppAiTemplatesEvent | AssistantContentInitialEvent;
+export interface AssistantCompletionResultEvent {
+    type: "assistant.result";
+    data: {
+        content?: BuilderContent;
+        stats?: AssistantStats;
+    };
+    resolveId?: string;
+}
+export interface AssistantError {
+    message: string;
+    status?: number;
+}
+export interface AssistantErrorEvent {
+    type: "assistant.error";
+    data: AssistantError;
+}
+export interface AssistantStreamErrorEvent {
+    type: "assistant.stream.error";
+    data: AssistantError;
+}
+export interface AppFigmaImportEvent {
+    type: "assistant.app.figmaImport";
+}
+export interface AppWebImportEvent {
+    type: "assistant.app.webImport";
+}
+export interface AppAiTemplatesEvent {
+    type: "assistant.app.aiTemplates";
+}
+export interface AssistantTrackEvent {
+    type: "assistant.track";
+    data: {
+        name: string;
+        properties: Record<string, any>;
+    };
+}
+export interface AssistantThemeEvent {
+    type: "assistant.app.theme.update";
+    data: {
+        theme: string;
+    };
+}
+export interface AppCloseEvent {
+    type: "assistant.app.close";
+}
+export interface AppMessagesClickEvent {
+    type: "assistant.app.messages.click";
+}
+export interface AppAcceptChangeEvent {
+    type: "assistant.app.change.accept";
+}
+export interface AppAcceptRejectEvent {
+    type: "assistant.app.change.reject";
+}
+export interface AppMessageEditCustomInstructionsEvent {
+    type: "assistant.app.messages.editCustomInstructions";
+}
+export interface AppAttachmentTemplateEvent {
+    type: "assistant.app.attachment.template";
+    data: {
+        id: number;
+        name: string;
+    };
+}
+export interface AppMessagesGenerationEvent {
+    type: "assistant.app.messages.generation";
+    data: {
+        state: GenerationState;
+    };
+}
+/**
+ * idle: no messages are being generated or queued to be generated
+ *
+ * queued: messages have been sent to the LLM, but no response has been received yet
+ *
+ * generating: messages are actively being generated and streaming back to the UI
+ */
+export type GenerationState = "idle" | "queued" | "generating";
+export interface AppPromptAbortEvent {
+    type: "assistant.app.prompt.abort";
+}
+export interface AppPromptFocusEvent {
+    type: "assistant.app.prompt.focus";
+}
+export interface AppPromptSubmitEvent {
+    type: "assistant.app.prompt.submit";
+    data: {
+        prompt: string;
+        attachments: any[];
+    };
+}
+export interface AppReadyEvent {
+    type: "assistant.app.ready";
+}
+export interface AppSettingsSetEvent {
+    type: "assistant.app.settings.set";
+    data: Partial<AssistantSettings>;
+}
+export interface AppThreadNewEvent {
+    type: "assistant.app.thread.new";
+}
+export interface AssistantEditorAuthMessage {
+    type: "assistant.editor.auth.update";
+}
+export interface BuilderEditorAuthEvent extends AwaitResultEvent {
+    type: "assistant.editor.auth";
+}
+export interface BuilderEditorStateEvent extends AwaitResultEvent {
+    type: "assistant.editor.state";
+}
+export interface AwaitResultEvent {
+    resolveId?: string;
+}
+export interface ResultEvent {
+    type: "assistant.result";
+    resolveId: string;
+    data: any;
+}
+export interface ContentCreatePatch {
+    parentId: string;
+    insertBeforeId: string;
+    element: BuilderElement;
+}
+export interface ContentApplySnapshot {
+    /**
+     * The id of the BuilderContent to apply the snapshot to
+     */
+    id: string;
+    /**
+     * Each snapshot can be either a full BuilderContent or individual BuilderElements.
+     * Order matters, as the snapshots will be applied in the order they are listed.
+     * The builder app will handle the logic of applying the snapshots in the correct order
+     * and to the right content/elements.
+     */
+    snapshots: (BuilderElement | BuilderContent)[];
+}
+export interface ContentApplySnapshotEvent {
+    type: "assistant.content.applysnapshot";
+    data: ContentApplySnapshot;
+}
+export interface ContentUpdateEvent {
+    type: "assistant.content.update";
+    data: ContentUpdatePatch[];
+}
+export type ContentUpdatePatch = ContentTsUpdateComponentPatch;
+interface ContentPatchBase {
+    id: string;
+    nodeId?: string;
+    builderId?: string;
+    description?: string;
+    value: string;
+    displayValue?: string;
+    ts: number;
+    /**
+     * A change value is considered incomplete until we also parsed it's closing xml tag.
+     */
+    incomplete?: boolean;
+    /**
+     * If there was an error applying the patch, this will contain the error message.
+     */
+    error?: string;
+}
+export interface ContentTsUpdateComponentPatch extends ContentPatchBase {
+    type: "update_component";
+}
+export interface AssistantStatsEvent {
+    type: "assistant.stats";
+    data: AssistantStats;
+}
+export interface AssistantStats {
+    /**
+     * The unique id of the thread (not the openai threadId)
+     */
+    threadId: string;
+    /**
+     * The unique id of the completion, which is a combination of the user's prompt and assistant's response.
+     */
+    completionId: string;
+    /**
+     * The model id used to generate this completion.
+     */
+    modelId: string;
+    /**
+     * The assistant's response message.
+     */
+    assistantMessage: string;
+    /**
+     * The user's prompt message.
+     */
+    userMessage: string;
+    /**
+     * The index within the thread the assistant message is.
+     * For a first assistant message, the index will be 1 (the user message is index 0).
+     * For a second assistant message, the index will be 3 (the user message is index 2), and so on.
+     */
+    assistantMessageIndex: number;
+    /**
+     * The timestamp (Date.now()) of when the user first submitted their prompt.
+     */
+    userPromptMs: number;
+    /**
+     * The timestamp of the first assistant chunk in the response.
+     */
+    firstChunkMs: number;
+    /**
+     * The timestamp of the last assistant chunk in the response.
+     */
+    lastChunkMs: number;
+    /**
+     * The total number of chunks in the assistant's streamed response.
+     */
+    chunkCount: number;
+    /**
+     * The total number of characters in the generated prompt sent to the LLM.
+     */
+    promptLength: number;
+    /**
+     * The total number of characters in the assistant's response.
+     */
+    completionLength: number;
+    /**
+     * If the user provided custom instructions for the prompt.
+     */
+    hasCustomInstructions: boolean;
+    /**
+     * The deployed version.
+     */
+    version: string;
+    /**
+     * Error message if there was one.
+     */
+    errorMessage?: string;
+    /**
+     * Input tokens
+     */
+    inputTokens?: number;
+    /**
+     * Output tokens
+     */
+    outputTokens?: number;
+    /**
+     * Output tokens
+     */
+    completionCost?: number;
+    /**
+     * Number of streamed snapshots
+     */
+    streamedSnapshots?: number;
+    /**
+     * Number of cached input tokens
+     */
+    cacheInputTokens?: number;
+    /**
+     * Number of cached created tokens
+     */
+    cacheCreatedTokens?: number;
+}
+export interface ModelUndoEvent {
+    type: "assistant.model.undo";
+}
+export interface ModelRedoEvent {
+    type: "assistant.model.redo";
+}
+export interface BuilderModel {
+    name?: string;
+    friendlyName?: string;
+    description?: string;
+    type?: string;
+    fields?: BuilderModelField[];
+}
+export interface BuilderModelField {
+    name?: string;
+    type?: string;
+    description?: string;
+}
+export interface ThreadMessageFeedbackEvent {
+    type: "assistant.thread.message.feedback";
+    data: CompletionResponseFeedback;
+}
+export interface CompletionResponseFeedback {
+    userId: string;
+    builderUserId?: string;
+    builderEmail?: string;
+    responseId?: string;
+    frontendUrl: string | undefined;
+    frontendCommitId: string | undefined;
+    backendDomain?: string;
+    backendCommitId: string | undefined;
+    feedbackText: string;
+    sentiment?: "positive" | "negative";
+}
+export interface ThreadCreatedEvent {
+    type: "assistant.thread.created";
+    data: ThreadCreated;
+}
+export interface ThreadCreated {
+    platformId: string;
+    threadId: string;
+    vectorStoreId: string;
+}
+export interface ThreadMessageCreatedEvent {
+    type: "assistant.thread.message.created";
+    data: ThreadMessageCreated;
+}
+export interface ThreadMessageCreated {
+    id: string;
+    responseId: string;
+    threadId: string;
+}
+export interface ThreadMessageDeltaEvent {
+    type: "assistant.thread.message.delta";
+    data: ThreadMessageDelta;
+}
+export interface ThreadMessageDelta {
+    id: string;
+    text: string;
+}
+export interface ThreadMessageCompletedEvent {
+    type: "assistant.thread.message.completed";
+    data: ThreadMessageCompleted;
+}
+export interface ThreadMessageRetryEvent {
+    type: "assistant.thread.message.retry";
+}
+export interface ThreadMessageCompleted extends AssistantMessage {
+    platformId: string;
+    threadId: string;
+    commitId?: string;
+}
+export interface ThreadRunStepDeltaEvent {
+    type: "assistant.thread.run.step.delta";
+    data: ThreadMessageStepDelta;
+}
+export interface ThreadMessageStepDelta {
+    delta: any;
+}
+export interface ThreadRunStepCreatedEvent {
+    type: "assistant.thread.run.step.created";
+}
+export type DeepPartial<T> = T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
+export interface AssistantContentInitialEvent {
+    type: "assistant.content.initial";
+    data: {
+        code: string;
+    };
+}
+export {};

package/src/events.js

@@ -0,0 +1 @@
+export {};

package/src/fetch.d.ts

@@ -0,0 +1 @@
+export declare function fetchJsonl<T>(input: string | URL, init: RequestInit, onData: (ev: T) => void): Promise<Response>;

package/src/fetch.js

@@ -0,0 +1,83 @@
+export async function fetchJsonl(input, init, onData) {
+    return new Promise(async (resolve, reject) => {
+        try {
+            init = {
+                ...init,
+                headers: {
+                    accept: "application/jsonl",
+                    "content-type": "application/json",
+                    ...init.headers,
+                },
+            };
+            const rsp = await (async () => {
+                try {
+                    return await fetch(input, init);
+                }
+                catch (err) {
+                    reject(new NetworkError(`${input}, status: network failure`));
+                }
+            })();
+            if (!rsp) {
+                return;
+            }
+            if (!rsp.ok) {
+                reject(new APIError(`${input}, status: ${rsp.status}`));
+                return;
+            }
+            if (!rsp.body) {
+                reject(new APIError(`${input}, missing body`));
+                return;
+            }
+            const reader = rsp.body.getReader();
+            const decoder = new TextDecoder();
+            let data = "";
+            const processStream = async () => {
+                const { done, value } = await reader.read();
+                data += decoder.decode(value, { stream: !done });
+                if (!done) {
+                    let lines = data.split("\n");
+                    if (!done) {
+                        data = lines.pop() || "";
+                    }
+                    for (let line of lines) {
+                        if (line) {
+                            try {
+                                line = line.trim();
+                                if (line.startsWith("{") && line.endsWith("}")) {
+                                    onData(JSON.parse(line));
+                                }
+                                else {
+                                    reject(`Invalid JSONL line: ${line}`);
+                                    return;
+                                }
+                            }
+                            catch (e) {
+                                console.error(`Failed to parse JSONL: ${line}`);
+                                reject(e);
+                                return;
+                            }
+                        }
+                    }
+                    await processStream();
+                }
+            };
+            await processStream();
+            resolve(rsp);
+        }
+        catch (e) {
+            reject(e);
+        }
+    });
+}
+class NetworkError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NetworkError";
+    }
+}
+class APIError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "APIError";
+    }
+}

package/src/index.js

@@ -0,0 +1,6 @@
+export * from "./completion.js";
+export * from "./events.js";
+export * from "./messages.js";
+export * from "./settings.js";
+export * from "./mapping.js";
+export * from "./codegen.js";

package/src/mapping.d.ts

@@ -0,0 +1,86 @@
+import type { ESMImport } from "./codegen";
+export interface RawFigmaJson {
+    documents: any[];
+    document?: any;
+    components?: Record<string, any>;
+    styles?: Record<string, any>;
+    componentSets?: Record<string, any>;
+    schemaVersion?: number;
+}
+export interface UserContext {
+    client: string;
+    clientVersion: string;
+    nodeVersion: string;
+    systemPlatform: string;
+    frameworks: string[];
+    systemEOL: string;
+    systemArch: string;
+    systemShell?: string;
+    inGitRepo?: boolean;
+    [key: string]: string | string[] | boolean | undefined;
+}
+export type ExportType = "default" | "named";
+/**
+ * Gets the latest component mappings for a space
+ */
+export interface FigmaMappingsData {
+    id: string;
+    figmaBuilderLinks: FigmaBuilderLink[];
+    framework: string;
+    version?: number;
+    createdDate?: string;
+    local: boolean;
+    userEmail?: string;
+    remoteUrl?: string;
+}
+export interface FigmaBuilderLink {
+    builderName: string;
+    figmaName: string;
+    figmaKey: string;
+    figmaUrl?: string;
+    inputMapper?: string;
+    originalInputMapper?: string;
+    exportType?: ExportType;
+    importName?: string;
+    importPath?: string;
+    source: string;
+    loc?: string;
+    imports?: ESMImport[];
+}
+export interface FigmaMapperFile {
+    filePath: string;
+    content: string;
+}
+export interface PublishedMapping {
+    figmaBuilderLinks: FigmaBuilderLink[];
+    mapperFiles: FigmaMapperFile[];
+    remoteUrl?: string;
+    defaultBranch?: string;
+    currentBranch?: string;
+    commit?: string;
+    spaceKind?: string;
+    userContext?: UserContext;
+}
+export interface FigmaComponentInfo {
+    documentName: string;
+    key: string;
+    tree?: string;
+    jsx?: string;
+    type: string;
+    name: string;
+    exportJson?: any;
+    inputs: FigmaComponentInput[];
+    description: string;
+    documentationLinks: string[];
+    instanceId: string;
+}
+export interface FigmaComponentInput {
+    id: string;
+    name: string;
+    value?: any;
+    type: string;
+    baseType: "text" | "variant" | "boolean" | "slot";
+    variantOptions?: string[];
+    isDefault: boolean;
+    ref?: string;
+}

package/src/mapping.js

@@ -0,0 +1 @@
+export {};

package/src/messages.d.ts

@@ -0,0 +1,165 @@
+import type { ContentUpdatePatch } from "./events.js";
+/**
+ * Message param does not know the id of the message.
+ * This is an input message.
+ */
+export type MessageParam = SystemMessageParam | UserMessageParam | AssistantMessageParam;
+export interface ContentMessageItemText {
+    type: "text";
+    text: string;
+    cache?: boolean;
+}
+export interface ContentMessageItemImage {
+    type: "image";
+    source: ImageBase64Source | ImageUrlSource;
+    cache?: boolean;
+}
+export interface ContentMessageItemDocument {
+    type: "document";
+    source: DocumentBase64Source | DocumentUrlSource;
+    cache?: boolean;
+}
+export interface DocumentBase64Source {
+    type: "base64";
+    media_type: "application/pdf";
+    data: string;
+}
+export interface DocumentUrlSource {
+    type: "url";
+    url: string;
+}
+export interface ContentMessageItemToolResult {
+    type: "tool_result";
+    tool_use_id: string;
+    tool_name?: string;
+    tool_input?: string;
+    title?: string;
+    content: string;
+    is_error: boolean;
+    cache?: boolean;
+}
+export interface ImageBase64Source {
+    type: "base64";
+    media_type: "image/webp" | "image/png" | "image/jpeg";
+    data: string;
+}
+export interface ImageUrlSource {
+    type: "url";
+    url: string;
+}
+export interface ContentMessageItemThinking {
+    type: "thinking";
+    thinking: string;
+    signature: string;
+}
+export interface ContentMessageItemRedactedThinking {
+    type: "redacted_thinking";
+    data: string;
+}
+export interface ContentMessageItemToolUse {
+    type: "tool_use";
+    id: string;
+    input: unknown;
+    completion?: string;
+    name: string;
+}
+export type ContentMessageItem = ContentMessageItemText | ContentMessageItemImage | ContentMessageItemDocument | ContentMessageItemThinking | ContentMessageItemRedactedThinking | ContentMessageItemToolUse | ContentMessageItemToolResult;
+export type ContentMessage = ContentMessageItem[];
+export interface SystemMessageParam {
+    /**
+     * The contents of the system message.
+     */
+    content: string | ContentMessageItemText[];
+    responseId?: string;
+    /**
+     * The role of the messages author, in this case `system`.
+     */
+    role: "system";
+    id?: string;
+}
+export interface UserMessageParam {
+    /**
+     * The contents of the user message.
+     */
+    content: string | (ContentMessageItemText | ContentMessageItemImage | ContentMessageItemDocument | ContentMessageItemToolResult)[];
+    responseId?: string;
+    /**
+     * The role of the messages author, in this case `user`.
+     */
+    role: "user";
+    id?: string;
+}
+export interface AssistantMessageParam {
+    /**
+     * The contents of the assistant message.
+     */
+    content: string | ContentMessageItem[];
+    /**
+     * The role of the messages author, in this case `assistant`.
+     */
+    role: "assistant";
+    responseId?: string;
+    /**
+     * The function call name and arguments
+     */
+    action?: {
+        /**
+         * The specific function name
+         */
+        name: string;
+        /** This is arbitrary JSON */
+        arguments: any;
+    };
+    id?: string;
+    skipDelta?: boolean;
+    /**
+     * A summary of the patches which the assistant has made.
+     * Useful for genai.
+     */
+    patches?: ContentUpdatePatch[];
+    state?: "error";
+}
+export interface SystemMessage extends SystemMessageParam {
+    id: string;
+}
+export interface UserMessage extends UserMessageParam {
+    id: string;
+}
+export interface AssistantMessage extends AssistantMessageParam {
+    id: string;
+    status?: "accepted" | "rejected" | "aborted";
+}
+export interface AssistantActionMessage {
+    /**
+     * The role of the messages author, in this case `assistant`.
+     */
+    role: "assistant";
+    id: string;
+}
+/**
+ * Message DOES know the id of the message.
+ * This message is after an id has been assigned
+ * and is the output message.
+ */
+export type Message = SystemMessage | UserMessage | AssistantMessage;
+export type GeneratingMessage = null | Partial<AssistantActionMessage | AssistantMessage>;
+export declare function getContentText(message: string | ContentMessage): string;
+export declare function getContentAttachments(message: string | ContentMessage): (ImageBase64Source | ImageUrlSource)[];
+export type Attachment = FileUpload | Template | URL;
+export interface URL {
+    type: "url";
+    value: string;
+}
+export interface FileUpload {
+    type: "upload";
+    contentType: string;
+    name: string;
+    dataUrl: string;
+    size: number;
+    id: string;
+}
+export interface Template {
+    type: "template";
+    name: string;
+    id: number;
+}