@lovable.dev/sdk 0.1.9 → 1.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 TypeScript SDK for the Lovable API.
 
-Currently in preview.
+Stable for the public API v1 surface and versioned with semver.
 
 ## Installation
 
@@ -28,11 +28,11 @@ const project = await client.createProject(workspaces[0].id, {
   initialMessage: "Create a todo app with authentication"
 });
 
-// 2. Wait for the AI response and get the preview URL
-const response = await client.waitForResponse(project.id);
-console.log(response.content);    // AI's response text
-console.log(response.messageId);  // AI message ID (for traces)
-console.log(response.previewUrl); // Preview URL for the project
+// 2. Wait for the AI response, then get the preview URL
+const response = await client.waitForMessageCompletion(project.id, project.message_id);
+console.log(response.content);                  // AI's response text
+console.log(response.message_id);               // AI message ID
+console.log(client.getPreviewUrl(project.id));  // Preview URL for the project
 
 // 3. Send a follow-up chat message
 await client.chat(project.id, {
@@ -75,8 +75,10 @@ const { projectId } = await client.waitForRemix("source-project-id", jobId, {
 console.log(`Remixed project: ${projectId}`);
 
 // Send a follow-up message to the remixed project
-await client.chat(projectId, { message: "Add dark mode" });
-const response = await client.waitForResponse(projectId);
+const followUp = await client.chat(projectId, { message: "Add dark mode" });
+const response = await client.waitForMessageCompletion(projectId, followUp.message_id, {
+  threadId: followUp.thread_id,
+});
 ```
 
 ### Continuation override
@@ -91,6 +93,8 @@ The `continuation` option on `chat()` overrides prompt cache reuse behavior. API
 
 ## API Reference
 
+HTTPie examples live in [examples/httpie.md](examples/httpie.md).
+
 ### `LovableClient`
 
 #### Constructor
@@ -134,36 +138,84 @@ Options:
 - `initialMessage` (optional): Initial chat message to send to the AI agent
 - `files` (optional): Array of files to attach (browser `File` objects or `FileInput` objects)
 
-##### `chat(projectId: string, options): Promise<void>`
+##### `getProject(projectId: string): Promise<ProjectResponse>`
+
+Get a project by ID.
+
+##### `updateProject(projectId: string, options): Promise<ProjectResponse>`
+
+Update supported project fields through `PATCH /v1/projects/{project_id}`.
+
+Options:
+
+- `display_name` (optional): Project display name
+- `visibility` (optional): Project visibility (`"draft"` | `"private"` | `"public"` | `"workspace_view"`)
+
+##### `deleteProject(projectId: string): Promise<void>`
+
+Soft-delete a project through `DELETE /v1/projects/{project_id}`.
+
+##### `chat(projectId: string, options): Promise<SendMessageResponse>`
 
 Send a chat message to a project's AI agent.
 
 Options:
 
 - `message` (required): The message to send
+- `variantId` (optional): Variant ID from `createVariant()`. Omit to send the message to the project's main agent
 - `files` (optional): Array of files to attach (browser `File` objects or `FileInput` objects)
-- `chatOnly` (optional): If true, only chat without making code changes
 - `continuation` (optional): Override prompt cache continuation behavior (`"force"` | `"fresh_build"` | `"allow_expired_cache"`). API-key auth only. See [Continuation override](#continuation-override)
 
-Note: This is an asynchronous operation. The API accepts the message and processes it in the background. Use `waitForResponse()` to wait for the AI's reply.
+The response includes the created `message_id` and its trajectory `thread_id`. Pass both to `waitForMessageCompletion()` to wait for the matching AI reply.
 
-##### `waitForResponse(projectId: string, options?): Promise<ChatResponse>`
+##### `listMessages(projectId: string, options?): Promise<ListMessagesResponse>`
+
+List recent project messages through `GET /v1/messages`.
+
+##### `getMessage(projectId: string, messageId: string, options?): Promise<GetMessageResponse>`
+
+Get a message through `GET /v1/messages/{message_id}`. Pass `waitSeconds` for server-side long polling.
 
-Wait for the AI's response to a chat message. Connects to the project's message stream (SSE) and returns the full response once complete.
+##### `createVariant(projectId: string, options?): Promise<CreateVariantResponse>`
 
-Use this after `chat()` or after `createProject()` with `initialMessage`.
+Create an independent variant from the project's current main branch, or from a specific full 40-character commit SHA.
+
+Options:
+
+- `label` (optional): Display name. Defaults to the next Draft number
+- `baseSha` (optional): Full 40-character commit SHA to base the variant branch on
 
 Returns:
 
+- `variant_id` (string): The variant ID to pass to `chat()`
+- `label` (string): The variant's display name
+- `branch` (string): The git branch attached to the variant
+- `thread_id` (string): The trajectory thread driving the variant
+
+The API returns `403 variants_not_enabled` when variants are unavailable for the authenticated user and project workspace.
+
+##### `waitForMessageCompletion(projectId: string, messageId: string, options?): Promise<MessageCompletionResult>`
+
+Wait for a specific message's AI response to finish. Pass the `message_id` from `chat()` or from `createProject()` with `initialMessage` (and the `thread_id` via `options.threadId` for non-main threads).
+
+Use `getPreviewUrl(projectId)` to construct the preview URL.
+
+Returns:
+
+- `status` (`"completed" | "awaiting_input" | "stopped" | "timeout" | "error"`): Terminal state
 - `content` (string): The AI's full response text
-- `messageId` (string): The AI message ID
-- `previewUrl` (string): The project's preview URL
+- `message_id` (string): The AI message ID
+- `awaiting_input` (optional): Present when `status` is `"awaiting_input"` — a non-headless turn paused by a human-in-the-loop tool. Carries the resumable `event_id`, `prev_session_id`, and optional `input_schema`
+- `edit_id` / `commit_sha` / `summary` / `cost_credits` (optional): Result metadata
 
 Options:
 
-- `timeout` (optional): Maximum time to wait in ms (default: 300000 = 5 minutes)
+- `threadId` (optional): Trajectory thread returned by `chat()`
+- `timeout` (optional): Maximum total time to wait in ms (default: 600000 = 10 minutes)
+
+##### `waitForResponse(projectId: string, options?): Promise<ChatResponse>`
 
-Throws an error if the stream fails or timeout is reached.
+Deprecated compatibility helper. Prefer `waitForMessageCompletion(projectId, messageId)`.
 
 ##### `getPreviewUrl(projectId: string): string`
 
@@ -246,27 +298,6 @@ Options:
 
 Throws an error if the remix fails or timeout is reached.
 
-##### `inviteCollaborator(workspaceId: string, options): Promise<WorkspaceMembershipResponse>`
-
-Invite a user to a workspace.
-
-Options:
-
-- `email` (required): Email address of the user to invite
-- `role` (optional): Role to assign (`"admin"` | `"collaborator"` | `"member"` | `"viewer"`)
-
-##### `listWorkspaceMembers(workspaceId: string): Promise<WorkspaceMembershipResponse[]>`
-
-List all members of a workspace.
-
-##### `removeWorkspaceMember(workspaceId: string, userId: string): Promise<void>`
-
-Remove a member from a workspace.
-
-##### `getProject(projectId: string): Promise<ProjectResponse>`
-
-Get project details by ID.
-
 ## Types
 
 The SDK exports TypeScript types for all API responses. See `src/types.ts` for the full list.
@@ -276,7 +307,7 @@ import type {
   WorkspaceWithMembership,
   ProjectResponse,
   CreateProjectOptions,
-  ChatResponse,
+  MessageCompletionResult,
   ContinuationOverride,
   FileInput,
   RemixProjectOptions,