@lovable.dev/sdk 0.1.3 → 0.1.5

package/dist/index.js

@@ -1,3 +1,16 @@
+// src/types.ts
+var ApiError = class extends Error {
+  status;
+  type;
+  detail;
+  constructor(status, message, type, detail) {
+    super(message);
+    this.status = status;
+    this.type = type;
+    this.detail = detail;
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.lovable.dev";
 function normalizeBaseUrl(url) {
@@ -9,25 +22,36 @@ function normalizeBaseUrl(url) {
   return normalized;
 }
 var LovableClient = class {
-  apiKey;
+  authHeaders;
   baseUrl;
+  extraHeaders;
   constructor(options) {
-    if (!options.apiKey) {
-      throw new Error("API key is required");
+    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.apiKey = options.apiKey;
+    this.authHeaders = hasApiKey ? { "Lovable-API-Key": options.apiKey } : { Authorization: `Bearer ${options.bearerToken}` };
     this.baseUrl = normalizeBaseUrl(options.baseUrl);
+    this.extraHeaders = options.headers ?? {};
   }
-  async request(method, path, body) {
+  async rawRequest(method, path, body) {
     const url = `${this.baseUrl}${path}`;
     const headers = {
-      "Lovable-API-Key": this.apiKey,
-      "Content-Type": "application/json"
+      ...this.authHeaders,
+      ...this.extraHeaders,
+      Accept: "application/json"
     };
+    if (body !== void 0) {
+      headers["Content-Type"] = "application/json";
+    }
     const response = await fetch(url, {
       method,
       headers,
-      body: body ? JSON.stringify(body) : void 0
+      body: body !== void 0 ? JSON.stringify(body) : void 0
     });
     if (!response.ok) {
       let errorBody;
@@ -35,17 +59,22 @@ var LovableClient = class {
         errorBody = await response.json();
       } catch {
       }
-      const error = new Error(errorBody?.title ?? `HTTP ${response.status}: ${response.statusText}`);
-      error.status = response.status;
-      error.type = errorBody?.title;
-      error.detail = errorBody?.detail;
-      throw error;
+      const message = errorBody?.message ?? errorBody?.title ?? `HTTP ${response.status}: ${response.statusText}`;
+      throw new ApiError(response.status, message, errorBody?.title, errorBody?.detail);
     }
+    return response;
+  }
+  async request(method, path, body) {
+    const response = await this.rawRequest(method, path, body);
     if (response.status === 204) {
       return void 0;
     }
     return response.json();
   }
+  async requestText(method, path) {
+    const response = await this.rawRequest(method, path);
+    return response.text();
+  }
   /**
    * Get the current authenticated user and their workspaces.
    * Useful for validating an API key and discovering workspace IDs.
@@ -68,25 +97,36 @@ var LovableClient = class {
     return response.workspace;
   }
   /**
-   * List projects in a workspace
+   * List projects in a workspace.
+   * Supports full-text search, filtering by visibility/publish status/folder/creator,
+   * and pagination via offset or cursor.
    */
   async listProjects(workspaceId, options) {
     const params = new URLSearchParams();
-    if (options?.limit) params.set("limit", options.limit.toString());
-    if (options?.cursor) params.set("cursor", options.cursor);
+    if (options?.query) params.set("q", options.query);
     if (options?.visibility) params.set("visibility", options.visibility);
+    if (options?.publish_status) params.set("publish_status", options.publish_status);
+    if (options?.folder_id) params.set("folder_id", options.folder_id);
+    if (options?.user_id) params.set("user_id", options.user_id);
+    if (options?.sort_by) params.set("sort_by", options.sort_by);
+    if (options?.sort_order) params.set("sort_order", options.sort_order);
+    if (options?.viewed_by_me) params.set("viewed_by_me", "true");
+    if (options?.limit !== void 0) params.set("limit", String(options.limit));
+    if (options?.offset !== void 0) params.set("offset", String(options.offset));
+    if (options?.cursor) params.set("cursor", options.cursor);
     const query = params.toString();
     const path = `/v1/workspaces/${workspaceId}/projects${query ? `?${query}` : ""}`;
-    const response = await this.request("GET", path);
-    return response.projects ?? [];
+    return this.request("GET", path);
   }
   /**
    * Create a new project in a workspace
    */
   async createProject(workspaceId, options) {
-    let uploadedFiles;
-    if (options.files?.length) {
-      uploadedFiles = await this.uploadFiles(options.files);
+    let fileRefs;
+    if (options.uploadedFiles?.length) {
+      fileRefs = options.uploadedFiles;
+    } else if (options.files?.length) {
+      fileRefs = await this.uploadFiles(options.files);
     }
     const body = {
       description: options.description,
@@ -96,49 +136,53 @@ var LovableClient = class {
     if (options.techStack) {
       body.tech_stack = options.techStack;
     }
-    const hasFiles = uploadedFiles && uploadedFiles.length > 0;
-    if (options.initialMessage && !hasFiles) {
+    if (options.selectedLibraries?.length) {
+      body.selected_libraries = options.selectedLibraries;
+    }
+    if (options.initialMessage) {
       body.initial_message = options.initialMessage;
     }
-    const project = await this.request("POST", `/v1/workspaces/${workspaceId}/projects`, body);
-    if (hasFiles && options.initialMessage) {
-      const chatBody = {
-        message: options.initialMessage,
-        files: uploadedFiles
-      };
-      await this.request("POST", `/v1/projects/${project.id}/messages`, chatBody);
+    if (fileRefs?.length) {
+      body.files = fileRefs;
     }
+    const project = await this.request("POST", `/v1/workspaces/${workspaceId}/projects`, body);
     return project;
   }
   /**
-   * Send a chat message to a project
+   * Send a chat message to a project.
    *
-   * Note: This sends a message to the project's AI agent. The response is
-   * asynchronous - the API accepts the message and processes it in the background.
+   * 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, or `waitForResponse()` for SSE streaming.
    */
   async chat(projectId, options) {
-    let uploadedFiles;
-    if (options.files?.length) {
-      uploadedFiles = await this.uploadFiles(options.files);
+    let fileRefs;
+    if (options.uploadedFiles?.length) {
+      fileRefs = options.uploadedFiles;
+    } else if (options.files?.length) {
+      fileRefs = await this.uploadFiles(options.files);
     }
     const body = {
       message: options.message
     };
-    if (uploadedFiles) {
-      body.files = uploadedFiles;
+    if (fileRefs) {
+      body.files = fileRefs;
     }
-    if (options.chatOnly) {
-      body.chat_only = true;
+    if (options.planMode) {
+      body.plan_mode = true;
     }
     if (options.customModel) {
       body.custom_model_endpoint = options.customModel.endpoint;
       body.custom_model_api_key = options.customModel.apiKey;
       body.custom_model_name = options.customModel.modelName;
     }
+    if (options.customModelDisableRace) {
+      body.custom_model_disable_race = true;
+    }
     if (options.continuation) {
       body.continuation = options.continuation;
     }
-    await this.request("POST", `/v1/projects/${projectId}/messages`, body);
+    return this.request("POST", `/v1/projects/${projectId}/messages`, body);
   }
   /**
    * Invite a user to a workspace as a collaborator
@@ -240,6 +284,257 @@ var LovableClient = class {
   async getDatabaseConnectionInfo(projectId) {
     return this.request("GET", `/v1/projects/${projectId}/database/connection-info`);
   }
+  // ---------------------------------------------------------------------------
+  // Messages
+  // ---------------------------------------------------------------------------
+  /**
+   * Get a message by ID. Returns the message content, status, and (for user messages)
+   * the AI response if available. Use to poll for completion after `chat()`.
+   */
+  async getMessage(projectId, messageId) {
+    return this.request("GET", `/v1/projects/${projectId}/messages/${messageId}`);
+  }
+  /**
+   * Poll for message completion. Waits until the AI response reaches a terminal
+   * status (completed, stopped) or the timeout expires.
+   *
+   * Handles edge cases: 404 grace period for race conditions between queue
+   * dequeue and event creation, and queue pause detection.
+   */
+  async waitForMessageCompletion(projectId, messageId, options) {
+    const pollInterval = options?.pollInterval ?? 3e3;
+    const timeout = options?.timeout ?? 6e5;
+    const deadline = Date.now() + timeout;
+    let notFoundSince = null;
+    const notFoundGraceMs = 15e3;
+    while (Date.now() < deadline) {
+      try {
+        const msg = await this.getMessage(projectId, messageId);
+        notFoundSince = null;
+        if (msg.status === "queued") {
+          if (msg.queue_paused && msg.queue_pause_reason !== "hitl_tool") {
+            return {
+              status: "error",
+              message_id: messageId,
+              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.`
+            };
+          }
+          await sleep(pollInterval);
+          continue;
+        }
+        const ai = msg.response;
+        if (ai) {
+          if (ai.status === "completed" || ai.status === "stopped") {
+            return {
+              status: ai.status === "completed" ? "completed" : "error",
+              message_id: ai.message_id,
+              content: ai.content,
+              edit_id: ai.edit_id,
+              commit_sha: ai.commit_sha,
+              summary: ai.summary,
+              cost_credits: ai.cost_credits
+            };
+          }
+        }
+        if (msg.role === "assistant") {
+          if (msg.status === "completed" || msg.status === "stopped") {
+            return {
+              status: msg.status === "completed" ? "completed" : "error",
+              message_id: msg.message_id,
+              content: msg.content,
+              edit_id: msg.edit_id,
+              commit_sha: msg.commit_sha,
+              summary: msg.summary,
+              cost_credits: msg.cost_credits
+            };
+          }
+        }
+        await sleep(pollInterval);
+      } catch (err) {
+        if (err instanceof ApiError && err.status === 404) {
+          if (notFoundSince === null) {
+            notFoundSince = Date.now();
+          }
+          if (Date.now() - notFoundSince < notFoundGraceMs) {
+            await sleep(pollInterval);
+            continue;
+          }
+          return {
+            status: "error",
+            message_id: messageId,
+            content: "",
+            error: "Message not found. It may have been deleted from the queue."
+          };
+        }
+        await sleep(pollInterval);
+      }
+    }
+    return {
+      status: "timeout",
+      message_id: messageId,
+      content: "",
+      error: `Agent did not finish within ${timeout / 1e3}s`
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Knowledge
+  // ---------------------------------------------------------------------------
+  /** Get workspace knowledge (custom instructions for the AI agent). */
+  async getWorkspaceKnowledge(workspaceId) {
+    return this.request("GET", `/v1/workspaces/${workspaceId}/knowledge`);
+  }
+  /** Set workspace knowledge. Max 10,000 characters. */
+  async setWorkspaceKnowledge(workspaceId, content) {
+    return this.request("PUT", `/v1/workspaces/${workspaceId}/knowledge`, { content });
+  }
+  /** Get project knowledge (custom instructions for the AI agent). */
+  async getProjectKnowledge(projectId) {
+    return this.request("GET", `/v1/projects/${projectId}/knowledge`);
+  }
+  /** Set project knowledge. Max 10,000 characters. */
+  async setProjectKnowledge(projectId, content) {
+    return this.request("PUT", `/v1/projects/${projectId}/knowledge`, { content });
+  }
+  // ---------------------------------------------------------------------------
+  // 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, params) {
+    const qs = new URLSearchParams();
+    if (params.messageId) qs.set("message_id", params.messageId);
+    if (params.sha) qs.set("sha", params.sha);
+    if (params.baseSha) qs.set("base_sha", params.baseSha);
+    return this.request("GET", `/v1/projects/${projectId}/git/diff?${qs.toString()}`);
+  }
+  /** List all files in a project at a specific git ref. */
+  async listFiles(projectId, ref) {
+    const qs = new URLSearchParams({ ref });
+    return this.request("GET", `/v1/projects/${projectId}/git/files?${qs.toString()}`);
+  }
+  /** Read the raw content of a single file at a specific git ref. Returns text. */
+  async readFile(projectId, path, ref) {
+    const qs = new URLSearchParams({ path, ref });
+    return this.requestText("GET", `/v1/projects/${projectId}/git/file?${qs.toString()}`);
+  }
+  // ---------------------------------------------------------------------------
+  // Edits
+  // ---------------------------------------------------------------------------
+  /** List the edit history of a project. */
+  async listEdits(projectId, params) {
+    const qs = new URLSearchParams();
+    if (params?.limit !== void 0) qs.set("limit", String(params.limit));
+    if (params?.before) qs.set("before", params.before);
+    const suffix = qs.toString() ? `?${qs.toString()}` : "";
+    return this.request("GET", `/v1/projects/${projectId}/edits${suffix}`);
+  }
+  // ---------------------------------------------------------------------------
+  // File upload
+  // ---------------------------------------------------------------------------
+  /** Get a presigned URL for uploading a file. Returns the upload URL and file ID. */
+  async getFileUploadUrl(params) {
+    return this.request("POST", "/v1/files/upload-url", params);
+  }
+  // ---------------------------------------------------------------------------
+  // Visibility
+  // ---------------------------------------------------------------------------
+  /** Set a project's visibility (draft, private, or public). */
+  async setProjectVisibility(projectId, visibility) {
+    return this.request("PUT", `/v1/projects/${projectId}/visibility`, { visibility });
+  }
+  /** Set a folder's visibility (personal or workspace). */
+  async setFolderVisibility(workspaceId, folderId, visibility) {
+    return this.request("PUT", `/v1/workspaces/${workspaceId}/folders/${folderId}/visibility`, {
+      visibility
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Library & template projects
+  // ---------------------------------------------------------------------------
+  /** List available design system library projects in a workspace. */
+  async listLibraryProjects(workspaceId) {
+    return this.request(
+      "GET",
+      `/v1/workspaces/${workspaceId}/available-library-projects`
+    );
+  }
+  /** List available template projects in a workspace. */
+  async listTemplateProjects(workspaceId) {
+    return this.request(
+      "GET",
+      `/v1/workspaces/${workspaceId}/available-template-projects`
+    );
+  }
+  // ---------------------------------------------------------------------------
+  // MCP servers
+  // ---------------------------------------------------------------------------
+  /** List all MCP servers connected to a workspace. */
+  async listMCPServers(workspaceId) {
+    return this.request("GET", `/v1/workspaces/${workspaceId}/mcp-servers`);
+  }
+  /** Add an MCP server to a workspace. The server URL is tested before saving. */
+  async addMCPServer(workspaceId, body) {
+    return this.request("POST", `/v1/workspaces/${workspaceId}/mcp-servers`, body);
+  }
+  /** Remove an MCP server from a workspace. */
+  async removeMCPServer(workspaceId, serverId) {
+    return this.request("DELETE", `/v1/workspaces/${workspaceId}/mcp-servers/${serverId}`);
+  }
+  /** Browse available MCP server templates (catalog). */
+  async listMCPCatalog(workspaceId) {
+    return this.request("GET", `/v1/workspaces/${workspaceId}/mcp-catalog`);
+  }
+  // ---------------------------------------------------------------------------
+  // Connectors
+  // ---------------------------------------------------------------------------
+  /** List standard (OAuth-based) connectors in a workspace. */
+  async listStandardConnectors(workspaceId) {
+    return this.request(
+      "GET",
+      `/v1/workspaces/${workspaceId}/connectors/standard`
+    );
+  }
+  /** List seamless (zero-config) connectors in a workspace. */
+  async listSeamlessConnectors(workspaceId) {
+    return this.request(
+      "GET",
+      `/v1/workspaces/${workspaceId}/connectors/seamless`
+    );
+  }
+  /** List MCP connectors in a workspace. */
+  async listMCPConnectors(workspaceId) {
+    return this.request(
+      "GET",
+      `/v1/workspaces/${workspaceId}/connectors/mcp`
+    );
+  }
+  /** List authenticated connections (accounts) in a workspace. */
+  async listConnections(workspaceId, params) {
+    const qs = new URLSearchParams();
+    if (params?.connector_id) qs.set("connector_id", params.connector_id);
+    const suffix = qs.toString() ? `?${qs.toString()}` : "";
+    return this.request("GET", `/v1/workspaces/${workspaceId}/connections${suffix}`);
+  }
+  // ---------------------------------------------------------------------------
+  // Analytics
+  // ---------------------------------------------------------------------------
+  /** Get historical analytics for a published project. */
+  async getProjectAnalytics(projectId, params) {
+    const qs = new URLSearchParams({
+      startDate: params.startDate,
+      endDate: params.endDate
+    });
+    if (params.granularity) qs.set("granularity", params.granularity);
+    return this.request("GET", `/v1/projects/${projectId}/analytics?${qs.toString()}`);
+  }
+  /** Get real-time visitor trend for a published project. */
+  async getProjectAnalyticsTrend(projectId) {
+    return this.request("GET", `/v1/projects/${projectId}/analytics/trend`);
+  }
   /**
    * Publish a project.
    *
@@ -277,6 +572,7 @@ var LovableClient = class {
       workspace_id: options.workspaceId,
       include_history: options.includeHistory,
       include_custom_knowledge: options.includeCustomKnowledge,
+      project_name: options.projectName,
       skip_initial_remix_message: options.skipInitialRemixMessage,
       skip_integrations: options.skipIntegrations,
       include_agent_state: options.includeAgentState
@@ -386,14 +682,13 @@ var LovableClient = class {
     try {
       const response = await fetch(url, {
         headers: {
-          "Lovable-API-Key": this.apiKey
+          ...this.authHeaders,
+          ...this.extraHeaders
         },
         signal: controller.signal
       });
       if (!response.ok) {
-        const error = new Error(`Failed to connect to message stream: HTTP ${response.status}`);
-        error.status = response.status;
-        throw error;
+        throw new ApiError(response.status, `Failed to connect to message stream: HTTP ${response.status}`);
       }
       if (!response.body) {
         throw new Error("Response body is not readable");
@@ -606,6 +901,7 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 export {
+  ApiError,
   LovableClient
 };
 //# sourceMappingURL=index.js.map