@builder.io/ai-utils 0.0.72 → 0.0.74

package/src/events.ts

@@ -0,0 +1,539 @@
+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
+  | AppPromptTextEvent
+  | AppReadyEvent
+  | AppSettingsResetEvent
+  | AppSettingsSetEvent
+  | AppThreadNewEvent
+  | AssistantStatsEvent
+  | AssistantThemeEvent
+  | BuilderEditorAuthEvent
+  | BuilderEditorStateEvent
+  | ContentUpdateEvent
+  | ContentApplySnapshotEvent
+  | ModelCreateEvent
+  | ModelUpdateEvent
+  | ModelUndoEvent
+  | ModelRedoEvent
+  | ResultEvent
+  | ThreadCreatedEvent
+  | ThreadMessageCompletedEvent
+  | ThreadMessageCreatedEvent
+  | ThreadMessageDeltaEvent
+  | ThreadMessageFeedbackEvent
+  | ThreadRunRequiresActionEvent
+  | ThreadRunStepCreatedEvent
+  | ThreadRunStepDeltaEvent
+  | AppAcceptChangeEvent
+  | AppAcceptRejectEvent
+  | AssistantTrackEvent
+  | AssistantEditorAuthMessage
+  | AppAttachmentTemplateEvent
+  | ThreadMessageRetryEvent;
+
+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 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 AppPromptTextEvent {
+  type: "assistant.app.prompt.text";
+  data: {
+    text: string;
+  };
+}
+
+export interface AppReadyEvent {
+  type: "assistant.app.ready";
+}
+
+export interface AppSettingsResetEvent {
+  type: "assistant.app.settings.reset";
+}
+
+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 =
+  | ContentTsCodePatch
+  | ContentInsertBeforePatch
+  | ContentInsertAfterPatch
+  | ContentPropsUpdatePatch
+  | ContentSetChildrenPatch
+  | ContentStyleUpdatePatch
+  | ContentDeletePatch
+  | ContentSetStorePatch
+  | ContentSetMountPatch
+  | ContentMovePatch
+  | ContentMoveAfterPatch
+  | ContentMoveBeforePatch
+  | ContentSetTagNamePatch
+  | 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 ContentTsCodePatch extends ContentPatchBase {
+  type: "ts_code";
+}
+
+export interface ContentSetTagNamePatch extends ContentPatchBase {
+  type: "set_tag_name";
+}
+
+export interface ContentInsertBeforePatch extends ContentPatchBase {
+  type: "insert_before";
+  snapshotBuilderId?: string;
+}
+
+export interface ContentInsertAfterPatch extends ContentPatchBase {
+  type: "insert_after";
+  snapshotBuilderId?: string;
+}
+
+export interface ContentPropsUpdatePatch extends ContentPatchBase {
+  type: "props";
+}
+
+export interface ContentStyleUpdatePatch extends ContentPatchBase {
+  type: "style";
+}
+
+export interface ContentSetChildrenPatch extends ContentPatchBase {
+  type: "children";
+  snapshotBuilderId?: string;
+}
+
+export interface ContentDeletePatch extends ContentPatchBase {
+  type: "delete";
+}
+
+export interface ContentSetStorePatch extends ContentPatchBase {
+  type: "store";
+}
+
+export interface ContentSetMountPatch extends ContentPatchBase {
+  type: "mount";
+}
+
+export interface ContentMovePatch extends ContentPatchBase {
+  type: "move";
+}
+
+export interface ContentMoveAfterPatch extends ContentPatchBase {
+  type: "move_after";
+}
+
+export interface ContentMoveBeforePatch extends ContentPatchBase {
+  type: "move_before";
+}
+
+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 ModelCreateEvent {
+  type: "assistant.model.create";
+  data: BuilderModel;
+}
+
+export interface ModelUpdateEvent {
+  type: "assistant.model.update";
+  data: ModelUpdate;
+}
+
+export interface ModelUndoEvent {
+  type: "assistant.model.undo";
+}
+
+export interface ModelRedoEvent {
+  type: "assistant.model.redo";
+}
+
+export interface ModelUpdate {
+  patches: ModelPatch[];
+}
+
+export interface BuilderModel {
+  name?: string;
+  friendlyName?: string;
+  description?: string;
+  type?: string;
+  fields?: BuilderModelField[];
+}
+
+export interface BuilderModelField {
+  name?: string;
+  type?: string;
+  description?: string;
+}
+
+export type ModelPatch = {
+  op: "add" | "remove" | "replace";
+  path: string;
+  value?: any;
+};
+
+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 ThreadRunRequiresActionEvent {
+  type: "assistant.thread.run.requires_action";
+  data: ThreadRunRequiredAction;
+}
+
+export interface ThreadRunRequiredAction {
+  platformId: string;
+  threadId: string;
+  action: {
+    name: string;
+    arguments: 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;

package/src/fetch.ts

@@ -0,0 +1,95 @@
+export async function fetchJsonl<T>(
+  input: string | URL,
+  init: RequestInit,
+  onData: (ev: T) => void,
+) {
+  return new Promise<Response>(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: string) {
+    super(message);
+    this.name = "NetworkError";
+  }
+}
+
+class APIError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "APIError";
+  }
+}

package/src/{index.d.ts → index.ts}

@@ -5,3 +5,6 @@ export * from "./fetch.js";
 export * from "./messages.js";
 export * from "./settings.js";
 export * from "./thread.js";
+export * from "./mapping.js";
+export * from "./codegen.js";
+export * from "./vcp.js";

package/src/mapping.ts

@@ -0,0 +1,88 @@
+import type { ESMImport } from "./codegen";
+
+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[];
+  version?: number;
+  createdDate?: string; // ISO string timestamp or unix timestamp
+  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[];
+
+  // Meta data
+  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;
+}