@lovable.dev/sdk 1.7.5 → 1.9.1

package/README.md

@@ -2,7 +2,10 @@
 
 TypeScript SDK for the Lovable API.
 
-Stable for the public API v1 surface and versioned with semver.
+> **Warning: experimental software.** This SDK is not covered by the public
+> API v1 stability guarantees. Any release, including minor and patch versions,
+> may change or remove methods, types, and behavior. Pin an exact version. For
+> production integrations, call the public API directly.
 
 ## Installation
 
@@ -10,357 +13,205 @@ Stable for the public API v1 surface and versioned with semver.
 npm install @lovable.dev/sdk
 ```
 
-## Usage
+## Create an API key
 
-```typescript
-import { LovableClient } from "@lovable.dev/sdk";
+Keys are created in the workspace settings at `https://lovable.dev/settings/api-keys`
+(the **Access tokens** tab). You need the admin or owner role in the workspace.
 
-const client = new LovableClient({
-  apiKey: "lov_your-api-key",
-});
+| Setting | Effect |
+| --- | --- |
+| Workspace | A key belongs to one workspace and can only read or change that workspace. Resources in other workspaces return `404`. |
+| Plan | The workspace must be on Business or higher; every public v1 call from a lower plan returns `402 payment_required`. Two operations (project PII labels, Security Center project inventory) require Enterprise. |
+| Access | Pick Read-only or Full access per resource. Projects maps to `projects:read` / `projects:write`, Workspace maps to `workspaces:read` / `workspaces:write`. A write scope includes the matching read scope. |
 
-// List workspaces
-const workspaces = await client.listWorkspaces();
+Every key from this page carries the `public:v1` audience: it reaches the
+advertised public v1 management operations and nothing else. The audience is
+not shown in the settings page.
 
-// 1. Create a project
-const project = await client.createProject(workspaces[0].id, {
-  description: "Best todo app",
-  initialMessage: "Create a todo app with authentication"
-});
+## Quick start
 
-// 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
+```typescript
+import { LovableClient } from "@lovable.dev/sdk";
 
-// 3. Send a follow-up chat message
-await client.chat(project.id, {
-  message: "Add a footer",
-});
+const client = new LovableClient({ apiKey: process.env.LOVABLE_API_KEY! });
 
-// 4. Send a message with file attachments
-import { readFile } from "fs/promises";
-const imageData = await readFile("design.png");
-await client.chat(project.id, {
-  message: "Update the hero section to match this design",
-  files: [{ name: "design.png", data: imageData, type: "image/png" }],
-});
+// GET /v1/me: validates the key. A workspace-scoped key returns one workspace.
+const me = await client.me();
+console.log(me.email, me.workspaces?.[0]?.name);
+
+// GET /v1/workspaces: list envelope (`data`, `pagination`) plus `workspaces`, an alias of `data`.
+const { workspaces } = await client.listWorkspaces();
+const workspaceId = workspaces[0].id;
 
-// 5. Publish the project and get the live URL
-await client.publish(project.id);
-const published = await client.waitForProjectPublished(project.id);
-console.log(published.url); // Live public URL
+// GET /v1/projects?workspace_id=...: same envelope, plus `projects` as an alias of `data`.
+const page = await client.listProjects(workspaceId, { limit: 20 });
+for (const project of page.data ?? []) {
+  console.log(project.id, project.name, project.is_published ? project.url : "(not published)");
+}
 ```
 
-### Code-first workflows
+Every hand-written method returns the response body unchanged, apart from the
+aliases noted above. `client.typed` is an [openapi-fetch](https://openapi-ts.dev/openapi-fetch/)
+client over the generated route types for any advertised operation without a
+hand-written method.
+
+## Pagination
 
-Use the `workflows` subpath to define compute-only durable workflows for the Cloudflare runtime:
+List operations take `limit` (1 to 100, default 50) and `cursor`, and return
+`data` with `pagination.next_cursor` and `pagination.has_more`. Keep the same
+filters across pages.
 
 ```typescript
-import { defineWorkflow, toWorker } from "@lovable.dev/sdk/workflows";
+let cursor: string | undefined;
+do {
+  const page = await client.listProjects(workspaceId, { limit: 100, cursor });
+  for (const project of page.data ?? []) console.log(project.id);
+  cursor = page.pagination.has_more ? (page.pagination.next_cursor ?? undefined) : undefined;
+} while (cursor);
+```
 
-const workflow = defineWorkflow<{ message: string }, { message: string; runId: string }>(
-  "project-showcase",
-  async (ctx) => {
-    const message = await ctx.step.run("normalize", () => ctx.input.message.trim());
-    return { message, runId: await ctx.uuid("run") };
-  },
-);
+## Create an embed URL
 
-export default toWorker(workflow);
-```
+`client.createEmbedUrl(projectId, parentOrigin)` calls
+`POST /v1/projects/{project_id}/embed-url` with scope `projects:write`. It
+requires Business or higher and edit permission on the project. The response
+contains a preview URL valid for one hour and bound to one exact HTTPS parent
+origin. Visitors can view the built preview without a Lovable login.
 
-Bundle the static ESM module and register it through the workflow service. Connector and internal-service access remain disabled until workflow workload identity and platform egress are available.
+## Publish a project and poll the deployment
 
-### Remixing a project at a specific message
+`POST /v1/projects/{project_id}/publish` (scope `projects:write`) returns `202`
+with a `deployment_id`. Poll `GET /v1/projects/{project_id}/publish/{deployment_id}`
+(scope `projects:read`) no more than once every 2 seconds. `completed` and
+`error` are terminal; keep polling on `running` and on `unknown` (a degraded,
+non-terminal state). Give up after a deadline; the example uses 10 minutes.
 
 ```typescript
-const client = new LovableClient({ apiKey: "lov_your-api-key" });
-
-// Remix a project at the state just before a specific message
-const jobId = await client.remixProject("source-project-id", {
-  workspaceId: "target-workspace-id",
-  messageId: "message-id-to-snapshot-at",
-  // remixMode: "including", // use "including" to keep the message and its AI response
-  includeHistory: true,
-  includeCustomKnowledge: true,
+const { data: accepted } = await client.typed.POST("/v1/projects/{project_id}/publish", {
+  params: { path: { project_id: projectId } },
+  body: {}, // optional: { visibility: "workspace" }
 });
+if (!accepted?.deployment_id) throw new Error("publish was not accepted");
+
+const deadline = Date.now() + 10 * 60 * 1000;
+let deployment;
+do {
+  if (Date.now() > deadline) throw new Error(`deployment ${accepted.deployment_id} did not finish in 10 minutes`);
+  await new Promise((resolve) => setTimeout(resolve, 2000));
+  ({ data: deployment } = await client.typed.GET("/v1/projects/{project_id}/publish/{deployment_id}", {
+    params: { path: { project_id: projectId, deployment_id: accepted.deployment_id } },
+  }));
+} while (deployment?.status === "running" || deployment?.status === "unknown");
+
+if (deployment?.status === "completed") console.log(deployment.url);
+else console.error(deployment?.error_code, deployment?.error_message);
+```
 
-// Wait for the remix to complete
-const { projectId } = await client.waitForRemix("source-project-id", jobId, {
-  onProgress: (status, step) => console.log(`Remix: ${status}`, step),
-});
+## Errors
 
-console.log(`Remixed project: ${projectId}`);
+Non-2xx responses throw `ApiError`. The API returns one error envelope on
+every operation:
 
-// Send a follow-up message to the remixed project
-const followUp = await client.chat(projectId, { message: "Add dark mode" });
-const response = await client.waitForMessageCompletion(projectId, followUp.message_id, {
-  threadId: followUp.thread_id,
-});
+```json
+{
+  "type": "invalid_argument",
+  "title": "Invalid argument",
+  "status": 400,
+  "request_id": "4bf92f3577b34da6a3ce929d0e0e4736",
+  "detail": "validation failed",
+  "errors": [{ "location": "query.limit", "message": "expected integer <= 100" }]
+}
 ```
 
-### Continuation override
-
-The `continuation` option on `chat()` overrides prompt cache reuse behavior. API-key auth only.
+`type`, `title`, `status`, and `request_id` are always present. `detail`,
+`errors[]`, and `props` are optional. Branch on `type`; `title` wording can
+change.
 
-| Value | Effect |
+| Envelope field | On `ApiError` |
 | --- | --- |
-| `"force"` | Skip all checks, force cache reuse |
-| `"fresh_build"` | Force full prompt rebuild |
-| `"allow_expired_cache"` | Skip expiry check only |
+| `status` | `status` |
+| `type` | `type` |
+| `title` | `message` |
+| `detail` | `detail` |
+| `props` | `props` |
+| `request_id`, `errors[]` | Not exposed by the SDK. Both are in the response body when you call the API directly. |
 
-## API Reference
-
-HTTPie examples live in [examples/httpie.md](examples/httpie.md).
+```typescript
+import { ApiError } from "@lovable.dev/sdk";
 
-### `LovableClient`
+try {
+  await client.getProject(projectId);
+} catch (err) {
+  if (err instanceof ApiError && err.type === "project_not_found") return null;
+  throw err;
+}
+```
 
-#### Constructor
+Types you will meet first:
+
+| `status` | `type` | Cause |
+| --- | --- | --- |
+| 401 | `unauthorized` | Missing, revoked, or expired key |
+| 402 | `payment_required` | Workspace plan below Business (or Enterprise where required) |
+| 403 | `insufficient_scope` | Key lacks the operation's scope |
+| 403 | `forbidden` | Caller lacks the workspace or project permission |
+| 403 | `audience_forbidden` | A `public:v1` key called a route outside the public v1 contract |
+| 404 | `project_not_found`, `workspace_not_found` | Missing resource, or a resource in another workspace |
+| 406 | `not_acceptable` | `Accept` header excludes `application/json` |
+| 429 | `rate_limited` | Rate limit hit; see below |
+
+## Rate limits
+
+Responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and, when
+known, `X-RateLimit-Reset` (Unix seconds). Limits use a sliding window: per
+API key for key-authenticated requests, per user for session and OAuth
+requests. Publishing is limited separately (10 per minute by default), as are
+deployment status polling (120 per minute), analytics, security-center
+insights, and collaborator reads (300 per minute).
+
+On `429` the client retries the request up to three times, waiting 100 ms,
+300 ms, then 500 ms, or longer when the `Retry-After` header asks for more.
+After the last retry it throws `ApiError` with `status: 429` and
+`rateLimit.retryAfterMs` parsed from `Retry-After`.
 
 ```typescript
-new LovableClient(options: LovableClientOptions)
+if (err instanceof ApiError && err.status === 429) {
+  await new Promise((resolve) => setTimeout(resolve, err.rateLimit?.retryAfterMs ?? 1000));
+}
 ```
 
-- `apiKey` (required): Your Lovable API key
-- `baseUrl` (optional): Override the default API base URL
-
-#### Methods
-
-##### `listWorkspaces(): Promise<WorkspaceWithMembership[]>`
-
-List all workspaces the authenticated user has access to.
-
-##### `getWorkspace(workspaceId: string): Promise<WorkspaceWithMembership>`
-
-Get a specific workspace by ID.
-
-##### `listProjects(workspaceId: string, options?): Promise<ProjectResponse[]>`
-
-List projects in a workspace.
-
-Options:
-
-- `limit` (optional): Maximum number of projects to return
-- `visibility` (optional): Filter by visibility (`"all"` | `"personal"` | `"public"` | `"workspace"`)
-
-##### `createProject(workspaceId: string, options): Promise<ProjectResponse>`
-
-Create a new project in a workspace.
-
-Options:
-
-- `description` (required): Project description
-- `techStack` (optional): Technology stack (e.g., `"react"`)
-- `visibility` (optional): Project visibility (`"draft"` | `"private"` | `"public"`)
-- `templateProjectId` (optional): ID of a template project to clone
-- `initialMessage` (optional): Initial chat message to send to the AI agent
-- `files` (optional): Array of files to attach (browser `File` objects or `FileInput` objects)
-
-##### `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
-- `files` (optional): Array of files to attach (browser `File` objects or `FileInput` objects)
-- `continuation` (optional): Override prompt cache continuation behavior (`"force"` | `"fresh_build"` | `"allow_expired_cache"`). API-key auth only. See [Continuation override](#continuation-override)
-
-The response includes the created `message_id` and its trajectory `thread_id`. Pass both to `waitForMessageCompletion()` to wait for the matching AI reply.
-
-##### `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.
-
-##### `createVariant(projectId: string, options?): Promise<CreateVariantResponse>`
-
-Create an independent variant from the project's current main branch, or from a specific full 40-character commit SHA.
-
-Options:
+## Operations outside the public v1 contract
 
-- `label` (optional): Display name. Defaults to the next Draft number
-- `baseSha` (optional): Full 40-character commit SHA to base the variant branch on
+The client also exposes builder operations: project creation and remix
+(`createProject`, `remixProject`), messages (`chat`, `listMessages`,
+`getMessage`, `waitForMessageCompletion`, `createVariant`), database, git and
+file access, uploads, knowledge, skills, connectors, folders, and
+`publish()` (which calls the deprecated `POST /v1/deployments` alias). These
+routes are not part of the public v1 contract. A key created in the settings
+page receives `403 audience_forbidden` from all of them. They require a key
+without a public audience, they carry no stability guarantee, and they are not
+documented here.
 
-Returns:
+## Workflows subpath
 
-- `variant_id` (string): The variant's identifier
-- `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
-- `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:
-
-- `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>`
-
-Deprecated compatibility helper. Prefer `waitForMessageCompletion(projectId, messageId)`.
-
-##### `getPreviewUrl(projectId: string): string`
-
-Get the preview URL for a project. This is a synchronous method that constructs the URL from the project ID.
-
-##### `publish(projectId: string, options?): Promise<DeploymentResponse>`
-
-Publish (deploy) a project to make it publicly accessible. The deployment runs asynchronously — use `waitForProjectPublished()` to wait for completion.
-
-Options:
-
-- `name` (optional): Custom slug for the published URL
-
-Returns:
-
-- `status` (string): Deployment status
-- `deployment_id` (string): The deployment ID
-- `url` (string): The published URL (may not be available until deployment completes)
-
-##### `getPublishedUrl(projectId: string): Promise<string | null>`
-
-Get the published URL for a project, or `null` if not published. Fetches the latest project details to check publication status.
-
-##### `waitForProjectReady(projectId: string, options?): Promise<ProjectResponse>`
-
-Wait for a project to reach "completed" status. Projects start in "in_progress" status while being created/built.
-
-Options:
-
-- `pollInterval` (optional): Time between polls in ms (default: 2000)
-- `timeout` (optional): Maximum time to wait in ms (default: 300000 = 5 minutes)
-- `onProgress` (optional): Callback for status updates
-
-Throws an error if the project fails or timeout is reached.
-
-##### `waitForProjectPublished(projectId: string, options?): Promise<ProjectResponse>`
-
-Wait for a project to be published (deployed) and have a live URL.
-
-Options:
-
-- `pollInterval` (optional): Time between polls in ms (default: 3000)
-- `timeout` (optional): Maximum time to wait in ms (default: 600000 = 10 minutes)
-- `onProgress` (optional): Callback for status updates
-
-Throws an error if timeout is reached.
-
-##### `remixProject(sourceProjectId: string, options): Promise<string>`
-
-Remix (fork) an existing project, optionally at a specific message point in time.
-
-When `messageId` is provided, the remix captures the project state as it was just before that message was processed (default `remixMode: "before"`). Set `remixMode: "including"` to include the message and its AI response in the remix. Without `messageId`, the full current state is remixed.
-
-Returns the remix job ID for polling with `waitForRemix()`.
-
-Options:
-
-- `workspaceId` (required): Target workspace for the new project
-- `messageId` (optional): Message ID to snapshot at — by default the remix reflects the project state just before this message
-- `remixMode` (optional): `"before"` (default) captures state before the message; `"including"` captures state after the message and its AI response
-- `includeHistory` (optional, default: `false`): Copy chat history. Requires edit access to the original project. View-only access or a public remix link is not enough.
-- `includeFiles` (optional, default: `false`): Copy project Files. Requires edit access to the original project. View-only access or a public remix link is not enough.
-- `includeCustomKnowledge` (optional, default: `false`): Whether to copy custom instructions/knowledge
-- `initialMessage` (optional): Initial chat message to send after remix completes
-- `skipInitialRemixMessage` (optional, default: `false`): When true, suppresses the default "I've successfully remixed this project" message
-- `skipIntegrations` (optional, default: `false`): When true, skips copying integrations to the remixed project
-
-Omitting `includeFiles` or setting it to `false` skips Files for everyone. Set it to `true` to copy Files; without edit access to the original project, the request returns `403 insufficient_permissions`.
-
-Existing callers that relied on automatic Files copying must now send `includeFiles: true`. Chat history stays independent.
-
-This option does not control attachments in copied chat history or app code and assets.
-
-##### `waitForRemix(sourceProjectId: string, jobId: string, options?): Promise<RemixResult>`
-
-Wait for a remix operation to complete. Polls `GET /v1/remix-jobs/{job_id}` until the job finishes. The `sourceProjectId` argument is kept for SDK compatibility.
-
-Returns:
-
-- `projectId` (string): The ID of the newly created project
-
-Options:
-
-- `pollInterval` (optional): Time between polls in ms (default: 2000)
-- `timeout` (optional): Maximum time to wait in ms (default: 300000 = 5 minutes)
-- `onProgress` (optional): Callback with `(status, step?)` for progress updates
-
-Throws an error if the remix fails or timeout is reached.
-
-## Types
-
-The SDK exports TypeScript types for all API responses. See `src/types.ts` for the full list.
+`@lovable.dev/sdk/workflows` defines compute-only durable workflows for the
+Cloudflare runtime; it does not call the Lovable API.
 
 ```typescript
-import type {
-  WorkspaceWithMembership,
-  ProjectResponse,
-  CreateProjectOptions,
-  MessageCompletionResult,
-  ContinuationOverride,
-  FileInput,
-  RemixProjectOptions,
-  // ... etc
-} from "@lovable.dev/sdk";
-```
-
-### `FileInput`
+import { defineWorkflow, toWorker } from "@lovable.dev/sdk/workflows";
 
-For Node.js or non-browser environments, use `FileInput` instead of the browser `File` API:
+const workflow = defineWorkflow<{ message: string }, { message: string }>("normalize", async (ctx) => ({
+  message: await ctx.step.run("normalize", () => ctx.input.message.trim()),
+}));
 
-```typescript
-interface FileInput {
-  name: string;              // Original file name (e.g., "screenshot.png")
-  data: Blob | ArrayBuffer | Uint8Array;  // File contents
-  type: string;              // MIME type (e.g., "image/png")
-}
+export default toWorker(workflow);
 ```
 
-### `ContinuationOverride`
+## Reference
 
-Controls prompt cache continuation behavior for a message:
-
-```typescript
-type ContinuationOverride = "force" | "fresh_build" | "allow_expired_cache";
-```
-
-- `"force"` — skip all continuation checks (force continuation)
-- `"fresh_build"` — force a full prompt rebuild from scratch
-- `"allow_expired_cache"` — skip cache expiry check but respect other continuation checks
+| Document | Content |
+| --- | --- |
+| [API_SPEC.md](API_SPEC.md) | Every advertised public v1 operation with its scope, parameters, and response schema |
+| https://api.lovable.dev/v1/openapi.json | The served OpenAPI document; authoritative when the two disagree |
+| [examples/httpie.md](examples/httpie.md) | The same calls over plain HTTP |
+| [src/types.ts](src/types.ts) | Exported request and response types |