@lovable.dev/sdk 0.1.9 → 1.1.0

package/src/client.ts

@@ -0,0 +1,1597 @@
+import type { Client, Middleware } from "openapi-fetch";
+
+import createClient from "openapi-fetch";
+
+import type { components, paths } from "./generated/paths.js";
+
+type Schemas = components["schemas"];
+type CreateProjectPostBody = paths["/v1/projects"]["post"]["requestBody"]["content"]["application/json"];
+
+// POST /v1/database/query is served but sits outside the public OpenAPI
+// boundary, so the generated paths omit it; this mirrors the openapi-typescript
+// operation shape for queryDatabase.
+type DatabaseQueryCompatPaths = {
+  "/v1/database/query": {
+    parameters: { query?: never; header?: never; path?: never; cookie?: never };
+    get?: never;
+    put?: never;
+    post: {
+      parameters: { query?: never; header?: never; path?: never; cookie?: never };
+      requestBody: {
+        content: { "application/json": { project_id: string; sql: string } };
+      };
+      responses: {
+        200: {
+          headers: { [name: string]: unknown };
+          content: { "application/json": DatabaseQueryResult };
+        };
+        default: {
+          headers: { [name: string]: unknown };
+          content: { "application/problem+json": Record<string, unknown> };
+        };
+      };
+    };
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
+};
+import type {
+  LovableClientOptions,
+  CreateProjectOptions,
+  ChatMessageOptions,
+  CreateVariantOptions,
+  WaitOptions,
+  ProjectResponse,
+  CreateProjectResponse,
+  CreateProjectBody,
+  UpdateProjectOptions,
+  EmbedURLResponse,
+  ProjectPatchVisibility,
+  DeploymentResponse,
+  UnscopedFile,
+  FileInput,
+  RemixProjectOptions,
+  RemixCreateProjectBody,
+  RemixJobStatus,
+  RemixResult,
+  RemixWaitOptions,
+  MeResponse,
+  MeWorkspace,
+  GetWorkspacesResponse,
+  WorkspaceWithMembership,
+  DatabaseStatus,
+  EnableDatabaseResult,
+  DatabaseQueryResult,
+  SendMessageResponse,
+  GetMessageResponse,
+  ListMessagesResponse,
+  ListMessagesOptions,
+  ChatResponse,
+  ChatResponseOptions,
+  CreateVariantResponse,
+  MessageCompletionResult,
+  MessageCompletionOptions,
+  GetMessageOptions,
+  KnowledgeResponse,
+  FileUploadUrlResponse,
+  GitDiffResponse,
+  GitFilesResponse,
+  EditsResponse,
+  ListProjectsResponse,
+  ListProjectsOptions,
+  ListConnectorsOptions,
+  ListCursorPaginationOptions,
+  ListHybridPaginationOptions,
+  ListOffsetPaginationOptions,
+  CursorPaginationOptions,
+  MoveProjectsToFolderResponse,
+  ConnectorResponse,
+  AddConnectorBody,
+  ListConnectorsResponse,
+  ListAvailableConnectorsResponse,
+  ListStandardConnectorsResponse,
+  ListSeamlessConnectorsResponse,
+  ListMCPConnectorsResponse,
+  ListConnectionsResponse,
+  ProjectAnalyticsResponse,
+  ProjectAnalyticsTrendResponse,
+  ListLibraryProjectsResponse,
+  ListTemplateProjectsResponse,
+  ListWorkspaceSkillsResponse,
+  WorkspaceSkillResponse,
+  WorkspaceSkillWriteResponse,
+  WorkspaceSkillDeleteResponse,
+  ListProjectSkillsResponse,
+  ProjectSkillResponse,
+  RateLimitInfo,
+} from "./types.js";
+
+import { makeRetryFetch } from "./retryFetch.js";
+import { ApiError } from "./types.js";
+
+const DEFAULT_BASE_URL = "https://api.lovable.dev";
+const PUBLIC_API_CURSOR_VERSION = 1;
+
+function normalizeBaseUrl(url: string | undefined): string {
+  if (!url) return DEFAULT_BASE_URL;
+
+  const normalized = url.replace(/\/$/, "");
+
+  if (!normalized.startsWith("http://") && !normalized.startsWith("https://")) {
+    throw new Error(`baseUrl must include a protocol (http:// or https://). Got: "${url}"`);
+  }
+
+  return normalized;
+}
+
+function encodePublicCursor(id: string): string {
+  const raw = JSON.stringify({ v: PUBLIC_API_CURSOR_VERSION, id });
+  const bytes = new TextEncoder().encode(raw);
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function normalizeWorkspaceList<T>(body: { data?: T[] | null; workspaces?: T[] | null }): T[] {
+  return body.data ?? body.workspaces ?? [];
+}
+
+function cursorHasMore(body: { pagination?: { has_more?: boolean } | null; has_more?: boolean }): boolean {
+  return body.pagination?.has_more ?? body.has_more ?? false;
+}
+
+function requireCreateProjectId<T extends { id?: string }>(project: T): T & { id: string } {
+  if (!project.id) throw new Error("Create project response missing project ID");
+  return project as T & { id: string };
+}
+
+/**
+ * openapi-fetch middleware that converts non-2xx Response objects into the
+ * SDK's ApiError, preserving the existing error contract (status/type/detail/
+ * props) used by every other method in this client.
+ */
+const errorMiddleware: Middleware = {
+  async onResponse({ response }) {
+    if (response.ok) return;
+    let errorBody:
+      | {
+          type?: string;
+          title?: string;
+          message?: string;
+          detail?: string;
+          details?: string;
+          props?: Record<string, unknown>;
+        }
+      | undefined;
+    try {
+      errorBody = (await response.clone().json()) as typeof errorBody;
+    } catch {
+      // Ignore JSON parse errors
+    }
+    const message = buildErrorMessage(errorBody, response.status, response.statusText);
+    const type = errorBody?.type ?? errorBody?.title;
+    const detail = errorBody?.detail ?? errorBody?.details;
+    throw new ApiError(response.status, message, type, detail, errorBody?.props, parseRateLimitInfo(response.headers));
+  },
+};
+
+function parseRateLimitInfo(headers: Headers): RateLimitInfo | undefined {
+  const limit = parsePositiveInt(headers.get("x-ratelimit-limit"));
+  const remaining = parsePositiveInt(headers.get("x-ratelimit-remaining"));
+  const retryAfterMs = parseRetryAfterMs(headers.get("retry-after"));
+  if (limit == null && remaining == null && retryAfterMs == null) return undefined;
+  return { limit, remaining, retryAfterMs };
+}
+
+function parsePositiveInt(raw: string | null): number | undefined {
+  if (raw == null) return undefined;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+
+function parseRetryAfterMs(raw: string | null): number | undefined {
+  if (!raw) return undefined;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
+  const dateMs = Date.parse(raw);
+  if (!Number.isNaN(dateMs)) {
+    const delta = dateMs - Date.now();
+    return delta > 0 ? delta : 0;
+  }
+  return undefined;
+}
+
+// HTTP/2 leaves response.statusText empty, and some Go API endpoints return
+// `{message: ""}` / `{title: ""}` bodies on errors. `??` would preserve the
+// empty string and produce an ApiError with no usable message; consumers
+// downstream (MCP, logs, UI) then render an unlabeled failure.
+function buildErrorMessage(
+  body: { message?: string; title?: string } | undefined,
+  status: number,
+  statusText: string,
+): string {
+  return body?.message || body?.title || (statusText ? `HTTP ${status}: ${statusText}` : `HTTP ${status}`);
+}
+
+export class LovableClient {
+  private readonly authHeaders: Record<string, string>;
+  private readonly baseUrl: string;
+  private readonly extraHeaders: Record<string, string>;
+  private readonly clientSource: string;
+  private readonly typedClient: Client<paths>;
+
+  constructor(options: LovableClientOptions) {
+    const hasApiKey = !!options.apiKey;
+    const hasBearerToken = !!options.bearerToken;
+
+    if (!hasApiKey && !hasBearerToken) {
+      throw new Error("Either apiKey or bearerToken is required");
+    }
+    if (hasApiKey && hasBearerToken) {
+      throw new Error("Provide either apiKey or bearerToken, not both");
+    }
+
+    this.authHeaders = hasApiKey
+      ? { "Lovable-API-Key": options.apiKey! }
+      : { Authorization: `Bearer ${options.bearerToken}` };
+
+    this.baseUrl = normalizeBaseUrl(options.baseUrl);
+    this.extraHeaders = options.headers ?? {};
+    this.clientSource = options.clientSource ?? "sdk";
+
+    this.typedClient = createClient<paths>({
+      baseUrl: this.baseUrl,
+      headers: {
+        "X-Client-Source": this.clientSource,
+        ...this.authHeaders,
+        ...this.extraHeaders,
+        Accept: "application/json",
+      },
+      fetch: makeRetryFetch(),
+    });
+    this.typedClient.use(errorMiddleware);
+  }
+
+  /**
+   * Type-safe access to any documented API route, driven by the auto-generated
+   * OpenAPI schema. Path / query params and request bodies are checked at compile
+   * time; calling an unknown path is a type error.
+   *
+   * Non-2xx responses throw `ApiError`; on success, `data` is set on the result.
+   */
+  get typed(): Client<paths> {
+    return this.typedClient;
+  }
+
+  /**
+   * Get the current authenticated user and their workspaces.
+   * Useful for validating an API key and discovering workspace IDs.
+   */
+  async me(): Promise<MeResponse> {
+    const { data } = await this.typed.GET("/v1/me");
+    return {
+      ...data!,
+      workspaces: normalizeWorkspaceList<MeWorkspace>(
+        data! as { data?: MeWorkspace[] | null; workspaces?: MeWorkspace[] | null },
+      ),
+    };
+  }
+
+  /**
+   * List workspaces the authenticated user has access to.
+   */
+  async listWorkspaces(options: ListHybridPaginationOptions = {}): Promise<GetWorkspacesResponse> {
+    const { data } = await this.typed.GET("/v1/workspaces", {
+      params: { query: options },
+    });
+    return { ...data!, workspaces: normalizeWorkspaceList<WorkspaceWithMembership>(data!) };
+  }
+
+  /**
+   * Get a specific workspace by ID
+   */
+  async getWorkspace(workspaceId: string) {
+    const { data } = await this.typed.GET("/v1/workspaces/{workspace_id}", {
+      params: { path: { workspace_id: workspaceId } },
+    });
+    return data!.workspace;
+  }
+
+  /**
+   * List projects in a workspace.
+   * Supports full-text search, filtering by visibility/publish status/folder/creator,
+   * and cursor pagination.
+   */
+  async listProjects(workspaceId: string, options?: ListProjectsOptions): Promise<ListProjectsResponse> {
+    const { data } = await this.typed.GET("/v1/projects", {
+      params: {
+        query: {
+          workspace_id: workspaceId,
+          q: options?.query,
+          visibility: options?.visibility,
+          publish_status: options?.publish_status,
+          folder_id: options?.folder_id,
+          folder_ids: options?.folder_ids,
+          user_id: options?.user_id,
+          type: options?.type,
+          include_risk: options?.include_risk,
+          search_fields: options?.search_fields,
+          viewed_by_me: options?.viewed_by_me,
+          cursor: options?.cursor,
+          limit: options?.limit,
+        },
+      },
+    });
+    const projects =
+      (data as unknown as { projects?: ListProjectsResponse["projects"] }).projects ?? data!.data ?? null;
+    const total = (data as unknown as { total?: number }).total;
+    return {
+      ...data!,
+      projects,
+      ...(total === undefined ? {} : { total }),
+      has_more: data!.pagination?.has_more ?? (data as unknown as { has_more?: boolean }).has_more,
+    };
+  }
+
+  /**
+   * Create a new project in a workspace
+   */
+  async createProject(workspaceId: string, options: CreateProjectOptions): Promise<CreateProjectResponse> {
+    let fileRefs: UnscopedFile[] | undefined;
+    let ephemeralFileRefs: UnscopedFile[] | undefined;
+    if (options.uploadedFiles?.length) {
+      ({ fileRefs, ephemeralFileRefs } = this.partitionUploadedFiles(options.uploadedFiles));
+    } else if (options.files?.length) {
+      ephemeralFileRefs = await this.uploadEphemeralFiles(options.files);
+    }
+
+    const body: CreateProjectBody = {
+      description: options.description,
+      template_project_id: options.templateProjectId,
+    };
+    if (options.projectName) {
+      body.display_name = options.projectName;
+    }
+    if (options.visibility) {
+      body.visibility = options.visibility;
+    }
+    if (options.techStack) {
+      body.tech_stack = options.techStack;
+    }
+    if (options.sandboxTemplate) {
+      body.sandbox_template = options.sandboxTemplate;
+    }
+    if (options.selectedLibraries?.length) {
+      body.selected_libraries = options.selectedLibraries;
+    }
+    if (options.initialMessage) {
+      body.initial_message = options.initialMessage;
+    }
+    if (fileRefs?.length) {
+      body.files = fileRefs;
+    }
+    if (options.fileUrls?.length) {
+      body.file_urls = options.fileUrls;
+    }
+    if (ephemeralFileRefs?.length) {
+      body.ephemeral_files = ephemeralFileRefs;
+    }
+
+    const { data } = await this.typed.POST("/v1/projects", {
+      body: { ...body, workspace_id: workspaceId },
+    });
+    return requireCreateProjectId(data!);
+  }
+
+  /**
+   * Send a chat message to a project.
+   *
+   * The API accepts the message and processes it in the background.
+   * Returns the message ID and status. Use `waitForMessageCompletion()`
+   * to poll for the AI response.
+   */
+  async chat(projectId: string, options: ChatMessageOptions): Promise<SendMessageResponse> {
+    let fileRefs: UnscopedFile[] | undefined;
+    let ephemeralFileRefs: UnscopedFile[] | undefined;
+    if (options.uploadedFiles?.length) {
+      ({ fileRefs, ephemeralFileRefs } = this.partitionUploadedFiles(options.uploadedFiles));
+    } else if (options.files?.length) {
+      fileRefs = await this.uploadProjectFiles(projectId, options.files);
+    }
+
+    const body: Omit<Schemas["PublicV1SendMessageInputBody"], "project_id"> = {
+      message: options.message,
+    };
+    if (options.variantId) {
+      body.variant_id = options.variantId;
+    }
+    if (fileRefs) {
+      body.files = fileRefs;
+    }
+    if (ephemeralFileRefs) {
+      body.ephemeral_files = ephemeralFileRefs;
+    }
+    if (options.planMode) {
+      body.plan_mode = true;
+    }
+    if (options.continuation) {
+      body.continuation = options.continuation;
+    }
+
+    const { data } = await this.typed.POST("/v1/messages", {
+      body: { ...body, project_id: projectId },
+    });
+    return data!;
+  }
+
+  /**
+   * Create an independent variant from the project's current main branch, or from a full baseSha when provided.
+   */
+  async createVariant(projectId: string, options: CreateVariantOptions = {}): Promise<CreateVariantResponse> {
+    const { data } = await this.typed.POST("/v1/projects/{project_id}/variants", {
+      params: { path: { project_id: projectId } },
+      body: { label: options.label, base_sha: options.baseSha },
+    });
+    return data!;
+  }
+
+  /**
+   * Get project details by ID
+   */
+  async getProject(projectId: string): Promise<ProjectResponse> {
+    const { data } = await this.typed.GET("/v1/projects/{project_id}", {
+      params: { path: { project_id: projectId } },
+    });
+    return data!;
+  }
+
+  /**
+   * Create an anonymous, one-hour static preview URL for one exact HTTPS parent origin.
+   */
+  async createEmbedUrl(projectId: string, parentOrigin: string): Promise<EmbedURLResponse> {
+    const { data } = await this.typed.POST("/v1/projects/{project_id}/embed-url", {
+      params: { path: { project_id: projectId } },
+      body: { parent_origin: parentOrigin },
+    });
+    return data!;
+  }
+
+  /**
+   * Update supported project fields.
+   */
+  async updateProject(projectId: string, options: UpdateProjectOptions): Promise<ProjectResponse> {
+    const { data } = await this.typed.PATCH("/v1/projects/{project_id}", {
+      params: { path: { project_id: projectId } },
+      body: options,
+    });
+    return data!;
+  }
+
+  /**
+   * Soft-delete a project. Repeated deletes are treated as successful.
+   */
+  async deleteProject(projectId: string): Promise<void> {
+    await this.typed.DELETE("/v1/projects/{project_id}", {
+      params: { path: { project_id: projectId } },
+    });
+  }
+
+  /**
+   * Get the preview URL for a project.
+   *
+   * The preview URL is available once the project reaches "completed" status.
+   * This URL allows viewing the project in development mode.
+   *
+   * @param projectId - The project ID
+   * @returns The preview URL
+   */
+  getPreviewUrl(projectId: string): string {
+    return `https://id-preview--${projectId}.lovable.app`;
+  }
+
+  /**
+   * Get the published URL for a project (if published).
+   *
+   * Returns the public URL if the project has been published, or null if not.
+   *
+   * @param projectId - The project ID
+   * @returns The published URL or null if not published
+   */
+  async getPublishedUrl(projectId: string): Promise<string | null> {
+    const project = await this.getProject(projectId);
+    return project.is_published && project.url ? project.url : null;
+  }
+
+  /**
+   * Get the cloud database status for a project.
+   *
+   * @param projectId - The project ID
+   * @returns Whether the database is enabled and which stack is used
+   */
+  async getDatabaseStatus(projectId: string): Promise<DatabaseStatus> {
+    const { data } = await this.typed.GET("/v1/database", {
+      params: { query: { project_id: projectId } },
+    });
+    return data!;
+  }
+
+  /**
+   * Enable (provision) a cloud database for a project.
+   *
+   * This triggers database provisioning which takes 30-60 seconds.
+   * The call blocks until provisioning completes.
+   *
+   * @param projectId - The project ID
+   * @returns The database status after enablement
+   */
+  async enableDatabase(projectId: string): Promise<EnableDatabaseResult> {
+    const { data } = await this.typed.POST("/v1/database/enable", {
+      body: { project_id: projectId },
+    });
+    return data!;
+  }
+
+  /**
+   * Execute a SQL query against the project's cloud database.
+   *
+   * Supports SELECT, INSERT, UPDATE, DELETE, and DDL statements.
+   * The database must be enabled first (see enableDatabase).
+   *
+   * @param projectId - The project ID
+   * @param sql - SQL query to execute
+   * @returns Query result rows as JSON objects
+   */
+  async queryDatabase(projectId: string, sql: string): Promise<DatabaseQueryResult> {
+    // The route sits outside the public OpenAPI boundary, so the generated
+    // paths lack it; DatabaseQueryCompatPaths stands in for the generated shape.
+    const compat = this.typedClient as unknown as Client<DatabaseQueryCompatPaths>;
+    const { data } = await compat.POST("/v1/database/query", {
+      body: { project_id: projectId, sql },
+    });
+    return data!;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Messages
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Get a message by ID. Returns the message content, status, and (for user messages)
+   * the AI response if available.
+   *
+   * Pass `waitSeconds` to long-poll: the server holds the request until the
+   * message reaches a terminal state (completed / stopped / error / awaiting_input) or the
+   * duration elapses. This replaces client-side polling for `waitForMessageCompletion`.
+   */
+  async getMessage(projectId: string, messageId: string, options?: GetMessageOptions): Promise<GetMessageResponse> {
+    const waitSeconds = options?.waitSeconds;
+    const query = {
+      wait: waitSeconds && waitSeconds > 0 ? `${Math.floor(waitSeconds)}s` : undefined,
+      thread_id: options?.threadId,
+    };
+    const { data } = await this.typed.GET("/v1/messages/{message_id}", {
+      params: { path: { message_id: messageId }, query: { ...query, project_id: projectId } },
+    });
+    return data!;
+  }
+
+  /**
+   * List recent messages in a project, newest first. Use `cursor` from the
+   * previous page's `pagination.next_cursor` to paginate through history.
+   */
+  async listMessages(projectId: string, params?: ListMessagesOptions): Promise<ListMessagesResponse> {
+    const cursor = params?.cursor ?? (params?.before ? encodePublicCursor(params.before) : undefined);
+    const { data } = await this.typed.GET("/v1/messages", {
+      params: {
+        query: { project_id: projectId, limit: params?.limit, cursor },
+      },
+    });
+    return {
+      ...data!,
+      messages: data!.data,
+      has_more: cursorHasMore(data!),
+    };
+  }
+
+  /**
+   * Wait for the AI response to reach a terminal status (completed, stopped, error, awaiting_input)
+   * or for `timeout` to elapse.
+   *
+   * Primary path is SSE against `/v1/messages/{message_id}/stream`: one
+   * held connection that pushes a snapshot on every relevant change and closes
+   * on terminal. If SSE isn't reachable (proxy strips text/event-stream, server
+   * returns 404 / 415 / 501) we fall back to the long-poll JSON endpoint on the
+   * same URL. Both paths share the same `MessageCompletionResult` shape.
+   */
+  async waitForMessageCompletion(
+    projectId: string,
+    messageId: string,
+    options?: MessageCompletionOptions,
+  ): Promise<MessageCompletionResult> {
+    const timeout = options?.timeout ?? 600_000;
+    const deadline = Date.now() + timeout;
+
+    const sse = await this.waitForMessageCompletionViaSSE(projectId, messageId, deadline, options?.threadId);
+    if (sse.kind === "result") {
+      return sse.result;
+    }
+    if (Date.now() >= deadline) {
+      return timeoutResult(messageId, timeout);
+    }
+    return this.waitForMessageCompletionViaLongPoll(projectId, messageId, deadline, timeout, options);
+  }
+
+  /**
+   * @deprecated Use `chat()` or `createProject()`'s returned `message_id`,
+   * then call `waitForMessageCompletion(projectId, messageId)`.
+   *
+   * Throws when the turn pauses for human input (`awaiting_input`) — the
+   * legacy `ChatResponse` shape cannot carry resume metadata. HITL-capable
+   * flows need `waitForMessageCompletion` plus `respondToTool`.
+   */
+  async waitForResponse(projectId: string, options?: ChatResponseOptions): Promise<ChatResponse> {
+    const messages = await this.listMessages(projectId, { limit: 10 });
+    const latest = messages.messages?.find((message) => message.role === "user");
+
+    if (!latest?.message_id) {
+      throw new Error(`No messages found for project ${projectId}`);
+    }
+
+    const completionOptions = options?.timeout === undefined ? undefined : { timeout: options.timeout };
+    const result = await this.waitForMessageCompletion(projectId, latest.message_id, completionOptions);
+    // Preserve the pre-deprecation contract: throw on failure. waitForMessageCompletion
+    // returns (never throws) on timeout/error, so without this a timed-out or errored run
+    // looks like a successful empty response to try/catch callers.
+    if (result.status !== "completed" && result.status !== "stopped") {
+      throw new Error(result.error ?? `Message ${latest.message_id} did not complete (status: ${result.status})`);
+    }
+    return {
+      content: result.content,
+      messageId: result.message_id,
+      previewUrl: this.getPreviewUrl(projectId),
+    };
+  }
+
+  private async waitForMessageCompletionViaSSE(
+    projectId: string,
+    messageId: string,
+    deadline: number,
+    threadId?: string,
+  ): Promise<{ kind: "result"; result: MessageCompletionResult } | { kind: "fallback" } | { kind: "timeout" }> {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return { kind: "timeout" };
+
+    const url = new URL(`${this.baseUrl}/v1/messages/${encodeURIComponent(messageId)}/stream`);
+    url.searchParams.set("project_id", projectId);
+    if (threadId) {
+      url.searchParams.set("thread_id", threadId);
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), remaining);
+
+    let response: Response;
+    try {
+      response = await fetch(url, {
+        headers: {
+          ...this.authHeaders,
+          ...this.extraHeaders,
+          "X-Client-Source": this.clientSource,
+          Accept: "text/event-stream",
+        },
+        signal: controller.signal,
+      });
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (isAbortError(err)) return { kind: "timeout" };
+      return { kind: "fallback" };
+    }
+
+    if (!response.ok) {
+      clearTimeout(timeoutId);
+      if (response.status === 404 || response.status === 415 || response.status === 501) {
+        await cancelResponseBody(response);
+        return { kind: "fallback" };
+      }
+      if (response.status >= 500) {
+        await cancelResponseBody(response);
+        return { kind: "fallback" };
+      }
+      const detail = await safeReadText(response);
+      throw new ApiError(response.status, detail || `HTTP ${response.status}`);
+    }
+
+    if (!response.body) {
+      clearTimeout(timeoutId);
+      return { kind: "fallback" };
+    }
+
+    try {
+      for await (const frame of parseSSEFrames(response.body)) {
+        if (!frame.data) continue;
+        let snapshot: GetMessageResponse;
+        try {
+          snapshot = JSON.parse(frame.data) as GetMessageResponse;
+        } catch {
+          continue;
+        }
+
+        const queuedResult = queuedExitResult(snapshot, messageId);
+        if (queuedResult) return { kind: "result", result: queuedResult };
+
+        const terminal = terminalResultFromMessage(snapshot, messageId);
+        if (terminal) {
+          return { kind: "result", result: terminal };
+        }
+      }
+      return { kind: "fallback" };
+    } catch (err) {
+      if (isAbortError(err)) return { kind: "timeout" };
+      return { kind: "fallback" };
+    } finally {
+      clearTimeout(timeoutId);
+      controller.abort();
+    }
+  }
+
+  private async waitForMessageCompletionViaLongPoll(
+    projectId: string,
+    messageId: string,
+    deadline: number,
+    totalTimeoutMs: number,
+    options?: MessageCompletionOptions,
+  ): Promise<MessageCompletionResult> {
+    const waitSeconds = Math.max(1, Math.min(55, options?.waitSeconds ?? 30));
+    const transientBackoffMs = 1000;
+    let notFoundSince: number | null = null;
+    const notFoundGraceMs = 15_000;
+
+    while (Date.now() < deadline) {
+      const remainingMs = deadline - Date.now();
+      const perCallSeconds = Math.min(waitSeconds, Math.floor(remainingMs / 1000));
+      const waitOptions = perCallSeconds > 0 ? { waitSeconds: perCallSeconds } : undefined;
+
+      const callStartedAt = Date.now();
+      try {
+        const msg = await this.getMessage(projectId, messageId, { ...waitOptions, threadId: options?.threadId });
+        notFoundSince = null;
+
+        const queuedResult = queuedExitResult(msg, messageId);
+        if (queuedResult) return queuedResult;
+
+        const terminal = terminalResultFromMessage(msg, messageId);
+        if (terminal) return terminal;
+
+        // Server returned a non-terminal snapshot far faster than the wait
+        // window it was given. That happens when the streamer is nil or its
+        // subscription fails server-side, or for queued messages that have no
+        // stream events yet. Backoff so we don't tight-loop until the deadline.
+        if (Date.now() - callStartedAt < transientBackoffMs) {
+          await sleep(Math.min(transientBackoffMs, Math.max(0, deadline - Date.now())));
+        }
+      } catch (err) {
+        if (err instanceof ApiError) {
+          if (err.status === 404) {
+            if (notFoundSince === null) {
+              notFoundSince = Date.now();
+            }
+            if (Date.now() - notFoundSince < notFoundGraceMs) {
+              await sleep(Math.min(transientBackoffMs, Math.max(0, deadline - Date.now())));
+              continue;
+            }
+            return {
+              status: "error",
+              message_id: messageId,
+              content: "",
+              error: "Message not found. It may have been deleted from the queue.",
+            };
+          }
+          if (err.status < 500) {
+            throw err;
+          }
+        }
+        await sleep(Math.min(transientBackoffMs, Math.max(0, deadline - Date.now())));
+      }
+    }
+
+    return timeoutResult(messageId, totalTimeoutMs);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Knowledge
+  // ---------------------------------------------------------------------------
+
+  /** Get workspace knowledge (custom instructions for the AI agent). */
+  async getWorkspaceKnowledge(workspaceId: string): Promise<KnowledgeResponse> {
+    const { data } = await this.typed.GET("/v1/workspaces/{workspace_id}/knowledge", {
+      params: { path: { workspace_id: workspaceId } },
+    });
+    return data!;
+  }
+
+  /** Set workspace knowledge. Max 10,000 characters. */
+  async setWorkspaceKnowledge(workspaceId: string, content: string): Promise<KnowledgeResponse> {
+    const { data } = await this.typed.PUT("/v1/workspaces/{workspace_id}/knowledge", {
+      params: { path: { workspace_id: workspaceId } },
+      body: { content },
+    });
+    return data!;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Workspace skills
+  // ---------------------------------------------------------------------------
+
+  /** List workspace skills. */
+  async listWorkspaceSkills(
+    workspaceId: string,
+    options: { includeMarkdown?: boolean } & ListOffsetPaginationOptions = {},
+  ): Promise<ListWorkspaceSkillsResponse> {
+    const { data } = await this.typed.GET("/v1/workspaces/{workspace_id}/skills", {
+      params: {
+        path: { workspace_id: workspaceId },
+        query: { include_markdown: options.includeMarkdown, limit: options.limit, offset: options.offset },
+      },
+    });
+    return { ...data!, skills: data!.skills ?? [] };
+  }
+
+  /** Get a single workspace skill, including SKILL.md contents. */
+  async getWorkspaceSkill(workspaceId: string, skillName: string): Promise<WorkspaceSkillResponse> {
+    const { data } = await this.typed.GET("/v1/workspaces/{workspace_id}/skills/{skill_name}", {
+      params: { path: { workspace_id: workspaceId, skill_name: skillName } },
+    });
+    return data!;
+  }
+
+  /** Create a workspace skill from full SKILL.md markdown. */
+  async createWorkspaceSkill(
+    workspaceId: string,
+    skillName: string,
+    markdown: string,
+  ): Promise<WorkspaceSkillWriteResponse> {
+    const { data } = await this.typed.POST("/v1/workspaces/{workspace_id}/skills/{skill_name}", {
+      params: { path: { workspace_id: workspaceId, skill_name: skillName } },
+      body: { markdown },
+    });
+    return data!;
+  }
+
+  /** Update a workspace skill by replacing its SKILL.md markdown. */
+  async updateWorkspaceSkill(
+    workspaceId: string,
+    skillName: string,
+    markdown: string,
+  ): Promise<WorkspaceSkillWriteResponse> {
+    const { data } = await this.typed.PUT("/v1/workspaces/{workspace_id}/skills/{skill_name}", {
+      params: { path: { workspace_id: workspaceId, skill_name: skillName } },
+      body: { markdown },
+    });
+    return data!;
+  }
+
+  /** Delete a workspace skill. */
+  async deleteWorkspaceSkill(workspaceId: string, skillName: string): Promise<WorkspaceSkillDeleteResponse> {
+    const { data } = await this.typed.DELETE("/v1/workspaces/{workspace_id}/skills/{skill_name}", {
+      params: { path: { workspace_id: workspaceId, skill_name: skillName } },
+    });
+    return data!;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Project skills
+  // ---------------------------------------------------------------------------
+
+  /** List project skills, including whether each skill is enabled. */
+  async listProjectSkills(
+    projectId: string,
+    options: ListCursorPaginationOptions = {},
+  ): Promise<ListProjectSkillsResponse> {
+    const { data } = await this.typed.GET("/v1/skills", {
+      params: { query: { project_id: projectId, limit: options.limit, cursor: options.cursor } },
+    });
+    const skills = (data as unknown as { skills?: ListProjectSkillsResponse["skills"] }).skills ?? data!.data ?? [];
+    return { ...data!, skills };
+  }
+
+  /** Enable or disable a project skill without removing it from the project repo. */
+  async setProjectSkillEnabled(projectId: string, skillName: string, enabled: boolean): Promise<ProjectSkillResponse> {
+    const { data } = await this.typed.PATCH("/v1/skills/{skill_name}", {
+      params: { path: { skill_name: skillName } },
+      body: { project_id: projectId, enabled },
+    });
+    return data!;
+  }
+
+  /** Get project knowledge (custom instructions for the AI agent). */
+  async getProjectKnowledge(projectId: string): Promise<KnowledgeResponse> {
+    const { data } = await this.typed.GET("/v1/knowledge", {
+      params: { query: { project_id: projectId } },
+    });
+    return data!;
+  }
+
+  /** Set project knowledge. Max 10,000 characters. */
+  async setProjectKnowledge(projectId: string, content: string): Promise<KnowledgeResponse> {
+    const { data } = await this.typed.PUT("/v1/knowledge", {
+      body: { project_id: projectId, content },
+    });
+    return data!;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Git operations
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Get the structured diff for a message or commit.
+   * Pass `messageId` to get the diff for a specific AI message,
+   * or `sha` for a specific commit.
+   */
+  async getDiff(
+    projectId: string,
+    params: { messageId?: string; sha?: string; baseSha?: string },
+  ): Promise<GitDiffResponse> {
+    const { data } = await this.typed.GET("/v1/git/diff", {
+      params: {
+        query: { project_id: projectId, message_id: params.messageId, sha: params.sha, base_sha: params.baseSha },
+      },
+    });
+    return data!;
+  }
+
+  /** List files in a project. Omitting ref uses the API default. */
+  async listFiles(projectId: string, ref?: string, options?: CursorPaginationOptions): Promise<GitFilesResponse>;
+  async listFiles(projectId: string, options?: CursorPaginationOptions): Promise<GitFilesResponse>;
+  async listFiles(
+    projectId: string,
+    refOrOptions?: string | CursorPaginationOptions,
+    options: CursorPaginationOptions = {},
+  ): Promise<GitFilesResponse> {
+    const ref = typeof refOrOptions === "string" ? refOrOptions : undefined;
+    const pagination = typeof refOrOptions === "string" ? options : (refOrOptions ?? options);
+    const { data } = await this.typed.GET("/v1/git/files", {
+      params: { query: { project_id: projectId, ref, limit: pagination.limit, cursor: pagination.cursor } },
+    });
+    const files = data!.data ?? [];
+    return { ...data!, data: files, files };
+  }
+
+  /** Read the raw content of a single file. Omitting ref uses the API default. */
+  async readFile(projectId: string, path: string, ref?: string): Promise<string> {
+    // The Go OpenAPI annotation for this route declares 200 as `content?: never`
+    // even though the handler returns the raw file text. `parseAs: "text"` makes
+    // openapi-fetch read the body as text at runtime; the cast covers the spec
+    // gap. Drop the cast once the Go annotation declares text/plain content.
+    const { data } = await this.typed.GET("/v1/git/files/{path}", {
+      params: { path: { path }, query: { project_id: projectId, ref } },
+      parseAs: "text",
+    });
+    return data as unknown as string;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Edits
+  // ---------------------------------------------------------------------------
+
+  /** List the edit history of a project. */
+  async listEdits(projectId: string, params?: { limit?: number; before?: string }): Promise<EditsResponse> {
+    const { data } = await this.typed.GET("/v1/edits", {
+      params: {
+        query: { project_id: projectId, limit: params?.limit, before: params?.before },
+      },
+    });
+    return data!;
+  }
+
+  // ---------------------------------------------------------------------------
+  // File upload
+  // ---------------------------------------------------------------------------
+
+  /** Get an ephemeral presigned URL for uploading a file before a project exists. */
+  async getFileUploadUrl(params: { file_name: string; content_type?: string }): Promise<FileUploadUrlResponse> {
+    return this.getEphemeralFileUploadUrl({ content_type: params.content_type });
+  }
+
+  /** Get a project-scoped presigned URL for uploading a file. Returns the upload URL, file ID, and required PUT headers. */
+  async getProjectFileUploadUrl(projectId: string, params: { content_type?: string }): Promise<FileUploadUrlResponse> {
+    const { data } = await this.typed.POST("/v1/project-files/upload-url", {
+      body: { project_id: projectId, ...params },
+    });
+    return data!;
+  }
+
+  /** Get an ephemeral presigned URL for uploading a file before a project exists. */
+  async getEphemeralFileUploadUrl(params: { content_type?: string }): Promise<FileUploadUrlResponse> {
+    const { data } = await this.typed.POST("/v1/files/ephemeral-upload-url", { body: params });
+    return data!;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Visibility
+  // ---------------------------------------------------------------------------
+
+  /** Set a project's visibility (draft, private, workspace_view, or public). */
+  async setProjectVisibility(projectId: string, visibility: ProjectPatchVisibility): Promise<ProjectResponse> {
+    return this.updateProject(projectId, { visibility });
+  }
+
+  /** Set a folder's visibility (personal or workspace). */
+  async setFolderVisibility(workspaceId: string, folderId: string, visibility: "personal" | "workspace") {
+    const { data } = await this.typed.PUT("/v1/workspaces/{workspace_id}/folders/{folder_id}/visibility", {
+      params: { path: { workspace_id: workspaceId, folder_id: folderId } },
+      body: { visibility },
+    });
+    return data!;
+  }
+
+  /** Move projects into a folder, removing existing folder memberships first. */
+  async moveProjectsToFolder(
+    workspaceId: string,
+    folderId: string,
+    projectIds: string[],
+  ): Promise<MoveProjectsToFolderResponse> {
+    const { data } = await this.typed.POST("/v1/workspaces/{workspace_id}/folders/{folder_id}/projects/move", {
+      params: { path: { workspace_id: workspaceId, folder_id: folderId } },
+      body: { project_ids: projectIds },
+    });
+    return data!;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Library & template projects
+  // ---------------------------------------------------------------------------
+
+  /** List available design system library projects in a workspace. */
+  async listLibraryProjects(
+    workspaceId: string,
+    options: ListOffsetPaginationOptions = {},
+  ): Promise<ListLibraryProjectsResponse> {
+    const { data } = await this.typed.GET("/v1/workspaces/{workspace_id}/available-library-projects", {
+      params: { path: { workspace_id: workspaceId }, query: options },
+    });
+    return { ...data!, libraries: data!.libraries ?? [] };
+  }
+
+  /** List available template projects in a workspace. */
+  async listTemplateProjects(
+    workspaceId: string,
+    options: ListOffsetPaginationOptions = {},
+  ): Promise<ListTemplateProjectsResponse> {
+    const { data } = await this.typed.GET("/v1/workspaces/{workspace_id}/available-template-projects", {
+      params: { path: { workspace_id: workspaceId }, query: options },
+    });
+    return { ...data!, templates: data!.templates ?? [] };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Connectors (MCP servers)
+  // ---------------------------------------------------------------------------
+
+  /** List all connectors in a workspace. */
+  async listConnectors(workspaceId: string, options: ListConnectorsOptions = {}): Promise<ListConnectorsResponse> {
+    const { data } = await this.typed.GET("/v1/connectors", {
+      params: {
+        query: {
+          workspace_id: workspaceId,
+          type: options.type,
+          status: options.status,
+          limit: options.limit,
+          cursor: options.cursor,
+        },
+      },
+    });
+    const connectors =
+      (data as unknown as { connectors?: ListConnectorsResponse["connectors"] }).connectors ?? data!.data ?? [];
+    return { ...data!, data: connectors, connectors, has_more: cursorHasMore(data!) };
+  }
+
+  /** Add a connector to a workspace. The server URL is tested before saving. */
+  async addConnector(workspaceId: string, body: AddConnectorBody): Promise<ConnectorResponse> {
+    const { data } = await this.typed.POST("/v1/connectors", {
+      body: { ...body, workspace_id: workspaceId },
+    });
+    return data!;
+  }
+
+  /** Remove a connector from a workspace. */
+  async removeConnector(workspaceId: string, connectorId: string) {
+    const { data } = await this.typed.DELETE("/v1/connectors/{connector_id}", {
+      params: { path: { connector_id: connectorId }, query: { workspace_id: workspaceId } },
+    });
+    return data!;
+  }
+
+  /** Browse available connector templates. */
+  async listAvailableConnectors(
+    workspaceId: string,
+    options: ListCursorPaginationOptions = {},
+  ): Promise<ListAvailableConnectorsResponse> {
+    const { data } = await this.typed.GET("/v1/available-connectors", {
+      params: { query: { workspace_id: workspaceId, limit: options.limit, cursor: options.cursor } },
+    });
+    const catalog =
+      (data as unknown as { catalog?: ListAvailableConnectorsResponse["catalog"] }).catalog ?? data!.data ?? [];
+    return { ...data!, data: catalog, catalog, has_more: cursorHasMore(data!) };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Connectors
+  // ---------------------------------------------------------------------------
+
+  /** List standard (OAuth-based) connectors in a workspace. */
+  async listStandardConnectors(
+    workspaceId: string,
+    options: ListCursorPaginationOptions = {},
+  ): Promise<ListStandardConnectorsResponse> {
+    const { data } = await this.typed.GET("/v1/connectors", {
+      params: { query: { workspace_id: workspaceId, type: "standard", limit: options.limit, cursor: options.cursor } },
+    });
+    const connectors =
+      (data as unknown as { connectors?: ListStandardConnectorsResponse["connectors"] }).connectors ?? data!.data ?? [];
+    return { ...data!, data: connectors, connectors, has_more: cursorHasMore(data!) };
+  }
+
+  /** List seamless (zero-config) connectors in a workspace. */
+  async listSeamlessConnectors(
+    workspaceId: string,
+    options: ListCursorPaginationOptions = {},
+  ): Promise<ListSeamlessConnectorsResponse> {
+    const { data } = await this.typed.GET("/v1/connectors", {
+      params: { query: { workspace_id: workspaceId, type: "seamless", limit: options.limit, cursor: options.cursor } },
+    });
+    const connectors =
+      (data as unknown as { connectors?: ListSeamlessConnectorsResponse["connectors"] }).connectors ?? data!.data ?? [];
+    return { ...data!, data: connectors, connectors, has_more: cursorHasMore(data!) };
+  }
+
+  /** List MCP connectors in a workspace. */
+  async listMCPConnectors(
+    workspaceId: string,
+    options: ListCursorPaginationOptions = {},
+  ): Promise<ListMCPConnectorsResponse> {
+    const { data } = await this.typed.GET("/v1/connectors", {
+      params: { query: { workspace_id: workspaceId, type: "mcp", limit: options.limit, cursor: options.cursor } },
+    });
+    const connectors =
+      (data as unknown as { connectors?: ListMCPConnectorsResponse["connectors"] }).connectors ?? data!.data ?? [];
+    return { ...data!, data: connectors, connectors, has_more: cursorHasMore(data!) };
+  }
+
+  /** List authenticated connections (accounts) in a workspace. */
+  async listConnections(
+    workspaceId: string,
+    params: { connector_id?: string; limit?: number; cursor?: string } = {},
+  ): Promise<ListConnectionsResponse> {
+    const { data } = await this.typed.GET("/v1/connections", {
+      params: {
+        query: {
+          workspace_id: workspaceId,
+          connector_id: params.connector_id,
+          limit: params.limit,
+          cursor: params.cursor,
+        },
+      },
+    });
+    const connections = data!.data ?? [];
+    return { ...data!, data: connections, connections, has_more: cursorHasMore(data!) };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Analytics
+  // ---------------------------------------------------------------------------
+
+  /** Get historical analytics for a published project. */
+  async getProjectAnalytics(
+    projectId: string,
+    params: { startDate: string; endDate: string; granularity?: string },
+  ): Promise<ProjectAnalyticsResponse> {
+    const { data } = await this.typed.GET("/v1/analytics", {
+      params: {
+        query: {
+          project_id: projectId,
+          startDate: params.startDate,
+          endDate: params.endDate,
+          granularity: params.granularity,
+        },
+      },
+    });
+    return data!;
+  }
+
+  /** Get real-time visitor trend for a published project. */
+  async getProjectAnalyticsTrend(projectId: string): Promise<ProjectAnalyticsTrendResponse> {
+    const { data } = await this.typed.GET("/v1/analytics/trend", {
+      params: { query: { project_id: projectId } },
+    });
+    return data!;
+  }
+
+  /**
+   * Publish a project.
+   *
+   * This triggers a deployment which makes the project publicly accessible.
+   * The deployment runs asynchronously - use waitForProjectPublished() to wait for completion.
+   *
+   * @param projectId - The project ID to publish
+   * @param options.name - Optional custom slug for the published URL
+   * @returns Deployment info including deployment ID
+   */
+  async publish(projectId: string, options?: { name?: string }): Promise<DeploymentResponse> {
+    const { data } = await this.typed.POST("/v1/deployments", {
+      body: { project_id: projectId, name: options?.name },
+    });
+    return data!;
+  }
+
+  /**
+   * Remix (fork) an existing project, optionally at a specific message point in time.
+   *
+   * When `messageId` is provided, the remix captures the project state after
+   * that message and its AI response by default. Set `remixMode: "before"` to
+   * start before the message was processed.
+   * Without `messageId`, the full current state is remixed.
+   *
+   * @param sourceProjectId - The project to remix from
+   * @param options.workspaceId - Target workspace for the new project
+   * @param options.messageId - Optional message ID to snapshot at
+   * @param options.remixMode - "including" (server default): state after the message and its AI response; "before": state before the message
+   * @param options.includeHistory - Whether to preserve chat history (default: false)
+   * @param options.includeCustomKnowledge - Whether to copy custom instructions (default: false)
+   * @param options.initialMessage - Optional initial message to send after remix
+   * @param options.description - Optional custom description for the new project
+   * @returns The remix job ID for polling progress
+   */
+  async remixProject(sourceProjectId: string, options: RemixProjectOptions): Promise<string> {
+    const body: RemixCreateProjectBody = {
+      workspace_id: options.workspaceId,
+      source_project_id: sourceProjectId,
+      include_history: options.includeHistory,
+      include_custom_knowledge: options.includeCustomKnowledge,
+      description: options.description,
+      display_name: options.projectName,
+      skip_initial_remix_message: options.skipInitialRemixMessage,
+      skip_integrations: options.skipIntegrations,
+    };
+
+    if (options.messageId) {
+      body.message_id = options.messageId;
+      if (options.remixMode) {
+        body.remix_mode = options.remixMode;
+      }
+    }
+
+    if (options.initialMessage) {
+      body.initial_message = options.initialMessage;
+    }
+
+    const { data } = await this.typed.POST("/v1/projects", {
+      body: body as CreateProjectPostBody,
+    });
+    const remix = data;
+    if (!remix?.job_id) {
+      throw new Error("Failed to get job ID from remix create");
+    }
+    return remix.job_id;
+  }
+
+  /**
+   * Wait for a remix operation to complete.
+   *
+   * Polls the remix progress endpoint until the job reaches "completed" or "error" status.
+   *
+   * @param sourceProjectId - The source project ID (used for the progress endpoint)
+   * @param jobId - The job ID returned by `remixProject()`
+   * @param options.pollInterval - Time between polls in ms (default: 2000)
+   * @param options.timeout - Maximum time to wait in ms (default: 300000 = 5 minutes)
+   * @param options.onProgress - Optional callback for status/step updates
+   * @returns The new project ID
+   * @throws Error if the remix fails or timeout is reached
+   */
+  async waitForRemix(sourceProjectId: string, jobId: string, options?: RemixWaitOptions): Promise<RemixResult> {
+    const pollInterval = options?.pollInterval ?? 2000;
+    const timeout = options?.timeout ?? 300000;
+    const startTime = Date.now();
+
+    while (true) {
+      const { data } = await this.typed.GET("/v1/projects/{project_id}/remix/progress", {
+        params: {
+          path: { project_id: sourceProjectId },
+          query: { job_id: jobId },
+        },
+      });
+      const progress = data!;
+      const status = progress.status as RemixJobStatus;
+      options?.onProgress?.(status, progress.step);
+
+      if (status === "completed" && progress.result) {
+        return { projectId: progress.result.project_id };
+      }
+
+      if (status === "error") {
+        throw new Error(progress.error_message ?? "Remix failed");
+      }
+
+      if (Date.now() - startTime > timeout) {
+        throw new Error(`Timeout waiting for remix of project ${sourceProjectId}`);
+      }
+
+      await sleep(pollInterval);
+    }
+  }
+
+  /**
+   * Wait for a project to reach "completed" status.
+   *
+   * Projects start in "in_progress" status while being created/built.
+   * This method polls until the status becomes "completed" or "failed".
+   * A successful completion means the project's preview is ready to view.
+   *
+   * @param projectId - The project ID to wait for
+   * @param options.pollInterval - Time between polls in ms (default: 2000)
+   * @param options.timeout - Maximum time to wait in ms (default: 300000 = 5 minutes)
+   * @param options.onProgress - Optional callback for status updates
+   * @returns The completed project
+   * @throws Error if project fails or timeout is reached
+   */
+  async waitForProjectReady(projectId: string, options?: WaitOptions): Promise<ProjectResponse> {
+    const pollInterval = options?.pollInterval ?? 2000;
+    const timeout = options?.timeout ?? 300000;
+    const startTime = Date.now();
+
+    while (true) {
+      const project = await this.getProject(projectId);
+      options?.onProgress?.(project);
+
+      if (project.status === "completed") {
+        return project;
+      }
+
+      if (project.status === "failed") {
+        throw new Error(`Project ${projectId} failed to build`);
+      }
+
+      if (Date.now() - startTime > timeout) {
+        throw new Error(`Timeout waiting for project ${projectId} to be ready`);
+      }
+
+      await sleep(pollInterval);
+    }
+  }
+
+  private isFileInput(file: File | FileInput): file is FileInput {
+    return "data" in file;
+  }
+
+  private async uploadFile(
+    file: File | FileInput,
+    getUploadUrl: (fileName: string, mimeType: string) => Promise<FileUploadUrlResponse>,
+  ): Promise<UnscopedFile> {
+    const fileName = this.isFileInput(file) ? file.name : file.name;
+    const mimeType = this.isFileInput(file) ? file.type : file.type;
+    const body = this.isFileInput(file) ? file.data : file;
+
+    const uploadUrl = await getUploadUrl(fileName, mimeType);
+    const { url, file_id: objectPath, headers } = uploadUrl;
+
+    const uploadResponse = await fetch(url, {
+      method: "PUT",
+      body,
+      headers: { "Content-Type": mimeType, ...headers },
+    });
+    if (!uploadResponse.ok) {
+      throw new Error(`File upload failed for "${fileName}": HTTP ${uploadResponse.status}`);
+    }
+
+    return { file_id: objectPath, type: "user_upload", file_name: fileName, mime_type: mimeType };
+  }
+
+  private async uploadProjectFiles(projectId: string, files: (File | FileInput)[]): Promise<UnscopedFile[]> {
+    return Promise.all(
+      files.map((file) =>
+        this.uploadFile(file, (_fileName, mimeType) =>
+          this.getProjectFileUploadUrl(projectId, { content_type: mimeType }),
+        ),
+      ),
+    );
+  }
+
+  private async uploadEphemeralFiles(files: (File | FileInput)[]): Promise<UnscopedFile[]> {
+    return Promise.all(
+      files.map((file) =>
+        this.uploadFile(file, (_fileName, mimeType) => this.getEphemeralFileUploadUrl({ content_type: mimeType })),
+      ),
+    );
+  }
+
+  private partitionUploadedFiles(files: UnscopedFile[]): {
+    fileRefs: UnscopedFile[] | undefined;
+    ephemeralFileRefs: UnscopedFile[] | undefined;
+  } {
+    const fileRefs: UnscopedFile[] = [];
+    const ephemeralFileRefs: UnscopedFile[] = [];
+    for (const file of files) {
+      if (file.file_id.startsWith("ephemeral/")) {
+        ephemeralFileRefs.push(file);
+      } else {
+        fileRefs.push(file);
+      }
+    }
+    return {
+      fileRefs: fileRefs.length > 0 ? fileRefs : undefined,
+      ephemeralFileRefs: ephemeralFileRefs.length > 0 ? ephemeralFileRefs : undefined,
+    };
+  }
+  /**
+   * Wait for a project to be published (deployed).
+   *
+   * This method polls until the project has `is_published: true` and a `url`.
+   *
+   * @param projectId - The project ID to wait for
+   * @param options.pollInterval - Time between polls in ms (default: 3000)
+   * @param options.timeout - Maximum time to wait in ms (default: 600000 = 10 minutes)
+   * @param options.onProgress - Optional callback for status updates
+   * @returns The published project with URL
+   * @throws Error if timeout is reached
+   */
+  async waitForProjectPublished(projectId: string, options?: WaitOptions): Promise<ProjectResponse> {
+    const pollInterval = options?.pollInterval ?? 3000;
+    const timeout = options?.timeout ?? 600000;
+    const startTime = Date.now();
+
+    while (true) {
+      const project = await this.getProject(projectId);
+      options?.onProgress?.(project);
+
+      if (project.is_published && project.url) {
+        return project;
+      }
+
+      if (project.status === "failed") {
+        throw new Error(`Project ${projectId} failed to build`);
+      }
+
+      if (Date.now() - startTime > timeout) {
+        throw new Error(`Timeout waiting for project ${projectId} to be published`);
+      }
+
+      await sleep(pollInterval);
+    }
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isAbortError(err: unknown): boolean {
+  return typeof err === "object" && err !== null && "name" in err && err.name === "AbortError";
+}
+
+async function safeReadText(response: Response): Promise<string> {
+  try {
+    return await response.text();
+  } catch {
+    return "";
+  }
+}
+
+async function cancelResponseBody(response: Response): Promise<void> {
+  try {
+    await response.body?.cancel();
+  } catch {}
+}
+
+async function* parseSSEFrames(
+  body: ReadableStream<Uint8Array>,
+): AsyncGenerator<{ event: string; data: string }, void, void> {
+  const reader = 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 });
+
+      let sep = buffer.indexOf("\n\n");
+      while (sep !== -1) {
+        const raw = buffer.slice(0, sep);
+        buffer = buffer.slice(sep + 2);
+        sep = buffer.indexOf("\n\n");
+
+        let event = "message";
+        const dataLines: string[] = [];
+        for (const line of raw.split("\n")) {
+          if (!line || line.startsWith(":")) continue;
+          if (line.startsWith("event:")) {
+            event = line.slice(6).trimStart();
+          } else if (line.startsWith("data:")) {
+            dataLines.push(line.slice(5).trimStart());
+          }
+        }
+        if (dataLines.length === 0) continue;
+        yield { event, data: dataLines.join("\n") };
+      }
+    }
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+      // ignore
+    }
+    try {
+      await body.cancel();
+    } catch {
+      // ignore
+    }
+  }
+}
+
+function terminalResultFromMessage(msg: GetMessageResponse, fallbackMessageId: string): MessageCompletionResult | null {
+  const ai = msg.response;
+  if (ai && isTerminalAIStatus(ai.status)) {
+    return {
+      status: messageCompletionStatus(ai.status),
+      message_id: ai.message_id || fallbackMessageId,
+      content: ai.content,
+      edit_id: ai.edit_id,
+      commit_sha: ai.commit_sha,
+      summary: ai.summary,
+      cost_credits: ai.cost_credits,
+      awaiting_input: ai.awaiting_input,
+      ...(ai.status === "error" ? { error: "Agent reported an error." } : {}),
+    };
+  }
+  if (msg.role === "assistant" && isTerminalAIStatus(msg.status)) {
+    return {
+      status: messageCompletionStatus(msg.status),
+      message_id: msg.message_id || fallbackMessageId,
+      content: msg.content,
+      edit_id: msg.edit_id,
+      commit_sha: msg.commit_sha,
+      summary: msg.summary,
+      cost_credits: msg.cost_credits,
+      awaiting_input: msg.awaiting_input,
+      ...(msg.status === "error" ? { error: "Agent reported an error." } : {}),
+    };
+  }
+  return null;
+}
+
+function messageCompletionStatus(status: string): MessageCompletionResult["status"] {
+  return status === "completed" || status === "stopped" || status === "awaiting_input" ? status : "error";
+}
+
+function isTerminalAIStatus(status: string | undefined): boolean {
+  return status === "completed" || status === "stopped" || status === "error" || status === "awaiting_input";
+}
+
+function queuedExitResult(msg: GetMessageResponse, fallbackMessageId: string): MessageCompletionResult | null {
+  if (msg.status !== "queued") return null;
+  if (!msg.queue_paused) return null;
+  if (msg.queue_pause_reason === "hitl_tool") return null;
+  return {
+    status: "error",
+    message_id: fallbackMessageId,
+    content: "",
+    error:
+      `Message is queued (position ${msg.queue_position ?? "unknown"}) but the queue is paused` +
+      (msg.queue_pause_reason ? ` (reason: ${msg.queue_pause_reason})` : "") +
+      `. Unpause the queue in the Lovable editor, or use wait=false to return immediately.`,
+  };
+}
+
+function timeoutResult(messageId: string, timeoutMs: number): MessageCompletionResult {
+  return {
+    status: "timeout",
+    message_id: messageId,
+    content: "",
+    error: `Agent did not finish within ${Math.max(0, Math.round(timeoutMs / 1000))}s`,
+  };
+}