@lovable.dev/sdk 0.1.3 → 0.1.5

package/README.md

@@ -113,7 +113,7 @@ The `continuation` option on `chat()` overrides prompt cache reuse behavior. API
 
 ### Using a custom model
 
-You can route the main agent to a custom OpenAI-compatible endpoint for eval and RL workflows:
+You can route the main agent to a custom OpenAI-compatible endpoint (for example your own inference base URL):
 
 ```typescript
 await client.chat(project.id, {
@@ -121,11 +121,13 @@ await client.chat(project.id, {
   customModel: {
     endpoint: "https://my-vllm.example.com/v1",
     apiKey: "sk-...",
-    modelName: "meta-llama/Llama-3.3-70B-Instruct",
+    modelName: "my-org/my-model-id",
   },
 });
 ```
 
+Optional `customModelDisableRace` on `chat()` (JSON field `custom_model_disable_race`) skips staggered inference racing when the server supports it for your endpoint. Requires API-key authentication, same as other custom-model fields.
+
 ### Fetching message traces (`_dev`)
 
 Trace APIs are available under the `_dev` namespace. These are not part of the stable v1 surface and may change without notice.
@@ -224,6 +226,7 @@ Options:
 - `files` (optional): Array of files to attach (browser `File` objects or `FileInput` objects)
 - `chatOnly` (optional): If true, only chat without making code changes
 - `customModel` (optional): Route the main agent to a custom OpenAI-compatible endpoint (see `CustomModelConfig`)
+- `customModelDisableRace` (optional): Skip staggered inference racing for allowlisted custom model hosts (JSON `custom_model_disable_race`). API-key auth only; see [Using a custom model](#using-a-custom-model)
 - `continuation` (optional): Override prompt cache continuation behavior (`"force"` | `"fresh_build"` | `"allow_expired_cache"`). API-key auth only. See [Controlling prompt cache continuation](#controlling-prompt-cache-continuation)
 
 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.
@@ -432,7 +435,7 @@ Configuration for routing the main agent to a custom OpenAI-compatible endpoint:
 interface CustomModelConfig {
   endpoint: string;   // Base URL (e.g., "https://my-vllm.example.com/v1")
   apiKey: string;     // API key for the endpoint
-  modelName: string;  // Model identifier (e.g., "meta-llama/Llama-3.3-70B-Instruct")
+  modelName: string;  // Model identifier (e.g., "my-org/my-model-id")
 }
 ```
 

package/dist/index.d.ts

@@ -93,6 +93,8 @@ interface ProjectResponse {
     visibility?: ProjectVisibility;
     publish_visibility?: "private" | "public";
     is_published?: boolean;
+    /** Present in create project response when initial_message was provided */
+    message_id?: string;
     is_starred?: boolean;
     is_template?: boolean;
     is_github?: boolean;
@@ -147,15 +149,13 @@ interface FileInput {
 }
 /**
  * Configuration to use a custom OpenAI-compatible model as the main agent.
- * Enables eval and RL workflows where candidate models are benchmarked
- * against the full Lovable agent pipeline.
  */
 interface CustomModelConfig {
     /** Base URL of the OpenAI-compatible API (e.g. "https://my-vllm.example.com/v1") */
     endpoint: string;
     /** API key for the custom endpoint */
     apiKey: string;
-    /** Model identifier sent in the request (e.g. "meta-llama/Llama-3.3-70B-Instruct") */
+    /** Model identifier sent in the request (e.g. "my-org/my-model-id") */
     modelName: string;
 }
 interface ChatRequest {
@@ -176,6 +176,7 @@ interface ChatRequest {
     custom_model_endpoint?: string;
     custom_model_api_key?: string;
     custom_model_name?: string;
+    custom_model_disable_race?: boolean;
 }
 interface CreateProjectBody {
     description: string;
@@ -183,6 +184,10 @@ interface CreateProjectBody {
     visibility?: ProjectVisibility;
     template_project_id?: string;
     initial_message?: string;
+    files?: UnscopedFile[];
+    selected_libraries?: {
+        project_id: string;
+    }[];
     category?: string;
     project_type?: string;
     prompt_name?: string;
@@ -200,7 +205,14 @@ interface CreateProjectOptions {
     visibility?: ProjectVisibility;
     templateProjectId?: string;
     initialMessage?: string;
+    /** Files to upload and attach to the initial message. The SDK handles uploading. */
     files?: (File | FileInput)[];
+    /** Pre-uploaded file references to attach to the initial message. Skips upload. */
+    uploadedFiles?: UnscopedFile[];
+    /** Design system library projects to connect to the new project. */
+    selectedLibraries?: {
+        project_id: string;
+    }[];
 }
 interface InviteCollaboratorOptions {
     email: string;
@@ -218,9 +230,19 @@ interface InviteCollaboratorOptions {
 type ContinuationOverride = "force" | "fresh_build" | "allow_expired_cache";
 interface ChatMessageOptions {
     message: string;
+    /** Files to upload and attach. The SDK handles uploading them first. */
     files?: (File | FileInput)[];
-    chatOnly?: boolean;
+    /** Pre-uploaded file references (already uploaded via getFileUploadUrl). Skips upload. */
+    uploadedFiles?: UnscopedFile[];
+    /** Enable plan mode: the agent discusses and plans without editing code. */
+    planMode?: boolean;
     customModel?: CustomModelConfig;
+    /**
+     * When true, the server may skip staggered inference racing for that request if your
+     * custom model endpoint supports it; otherwise the request fails with a validation error.
+     * API key authentication only. Sent as `custom_model_disable_race` in the JSON body.
+     */
+    customModelDisableRace?: boolean;
     /**
      * Override continuation behavior for this message.
      * Controls whether the agent reuses the prompt cache or rebuilds from scratch.
@@ -228,8 +250,13 @@ interface ChatMessageOptions {
     continuation?: ContinuationOverride;
 }
 interface LovableClientOptions {
-    apiKey: string;
+    /** API key for authentication (mutually exclusive with bearerToken) */
+    apiKey?: string;
+    /** Bearer token for OAuth authentication (mutually exclusive with apiKey) */
+    bearerToken?: string;
     baseUrl?: string;
+    /** Additional headers to include on every request */
+    headers?: Record<string, string>;
 }
 interface LovableError extends Error {
     status: number;
@@ -343,6 +370,7 @@ interface RemixProjectOptions {
     includeHistory?: boolean;
     includeCustomKnowledge?: boolean;
     initialMessage?: string;
+    projectName?: string;
     skipInitialRemixMessage?: boolean;
     skipIntegrations?: boolean;
     /** Copy agent continuation state so prompt cache can be reused after remix. Requires includeHistory. API-key auth only. */
@@ -376,12 +404,259 @@ interface DatabaseConnectionInfo {
     connection_string: string;
     api_url: string;
 }
+declare class ApiError extends Error {
+    readonly status: number;
+    readonly type?: string;
+    readonly detail?: string;
+    constructor(status: number, message: string, type?: string, detail?: string);
+}
+interface SendMessageResponse {
+    message_id: string;
+    status: string;
+}
+interface GetMessageResponse {
+    message_id: string;
+    role: string;
+    content: string;
+    status: string;
+    created_at: string;
+    edit_id?: string;
+    commit_sha?: string;
+    summary?: string;
+    cost_credits?: number;
+    response?: {
+        message_id: string;
+        status: string;
+        content: string;
+        edit_id?: string;
+        commit_sha?: string;
+        summary?: string;
+        cost_credits?: number;
+    };
+    queue_position?: number;
+    queue_paused?: boolean;
+    queue_pause_reason?: string;
+}
+interface MessageCompletionResult {
+    status: "completed" | "timeout" | "error";
+    message_id: string;
+    content: string;
+    edit_id?: string;
+    commit_sha?: string;
+    summary?: string;
+    cost_credits?: number;
+    error?: string;
+}
+interface MessageCompletionOptions {
+    /** Time between polls in ms (default: 3000) */
+    pollInterval?: number;
+    /** Maximum time to wait in ms (default: 600000 = 10 minutes) */
+    timeout?: number;
+}
+interface KnowledgeResponse {
+    content: string;
+}
+interface FileUploadUrlResponse {
+    url: string;
+    file_id: string;
+}
+interface DiffLine {
+    type: string;
+    content: string;
+}
+interface DiffHunk {
+    oldStart: number;
+    oldCount: number;
+    newStart: number;
+    newCount: number;
+    lines: DiffLine[];
+}
+interface DiffEntry {
+    action: string;
+    file_path: string;
+    original_file_path?: string;
+    file_type?: string;
+    is_image: boolean;
+    is_incomplete?: boolean;
+    hunks?: DiffHunk[];
+}
+interface GitDiffResponse {
+    diffs: DiffEntry[];
+    error?: string;
+}
+interface GitFileEntry {
+    path: string;
+    size: number;
+    binary: boolean;
+}
+interface GitFilesResponse {
+    files: GitFileEntry[];
+    ref: string;
+}
+interface EditSummary {
+    id: string;
+    type: string;
+    commit_sha?: string;
+    commit_message?: string;
+    status: string;
+    created_at: string;
+}
+interface EditsResponse {
+    edits: EditSummary[];
+    has_more: boolean;
+}
+interface ListProjectItem extends ProjectResponse {
+    user_id?: string;
+    is_template?: boolean;
+    is_starred?: boolean;
+    created_at?: string;
+    updated_at?: string;
+    last_edited_at?: string;
+    last_viewed_at?: string;
+    edit_count?: number;
+    remix_count?: number;
+}
+interface ListProjectsResponse {
+    projects: ListProjectItem[];
+    total: number;
+    has_more: boolean;
+}
+interface ListProjectsOptions {
+    query?: string;
+    visibility?: string;
+    publish_status?: string;
+    folder_id?: string;
+    user_id?: string;
+    sort_by?: string;
+    sort_order?: string;
+    viewed_by_me?: boolean;
+    limit?: number;
+    offset?: number;
+    cursor?: string;
+}
+interface LibraryProjectResponse {
+    id: string;
+    name: string | null;
+    description: string;
+    updated_at: string;
+}
+interface TemplateProjectResponse {
+    id: string;
+    name: string | null;
+    description: string;
+    updated_at: string;
+}
+interface MCPServerResponse {
+    id: string;
+    name: string;
+    url?: string;
+    auth_type: string;
+    connector_id?: string;
+    is_connected: boolean;
+}
+interface MCPCatalogEntry {
+    id: string;
+    display_name: string;
+    summary: string;
+    category: string;
+    requires_custom_url?: boolean;
+    documentation_url?: string;
+}
+interface AddMCPServerBody {
+    name: string;
+    url: string;
+    auth_type: "none" | "bearer_token";
+    connector_id?: string;
+    token?: string;
+}
+interface StandardConnectorItem {
+    id: string;
+    display_name: string;
+    short_description: string;
+    categories: string[];
+    is_enabled_for_workspace: boolean;
+    auth_type: string;
+    logo_id?: string;
+    documentation_url?: string;
+    connection_scope?: string;
+}
+interface SeamlessConnectorItem {
+    id: string;
+    display_name: string;
+    short_description: string;
+    categories: string[];
+    is_enabled_for_workspace: boolean;
+    logo_id?: string;
+    documentation_url?: string;
+}
+interface MCPConnectorItem {
+    id: string;
+    display_name: string;
+    summary: string;
+    status: string;
+    is_enabled_for_workspace: boolean;
+    is_connected: boolean;
+    connector_id?: string;
+    documentation_url?: string;
+}
+interface ConnectionItem {
+    id: string;
+    connector_id: string;
+    display_name: string;
+    is_managed: boolean;
+    status: string;
+    created_at: string;
+    updated_at: string;
+}
+interface TimeSeriesDataPoint {
+    date: string;
+    value: number;
+}
+interface TimeSeriesData {
+    total: number;
+    label: string;
+    data: TimeSeriesDataPoint[];
+}
+interface ListDataPoint {
+    label: string;
+    value: number;
+}
+interface ListData {
+    label: string;
+    data: ListDataPoint[];
+}
+interface ProjectAnalyticsResponse {
+    timeSeries: {
+        visitors: TimeSeriesData;
+        pageviews: TimeSeriesData;
+        pageviewsPerVisit: TimeSeriesData;
+        sessionDuration: TimeSeriesData;
+        bounceRate: TimeSeriesData;
+    };
+    lists: {
+        page: ListData;
+        source: ListData;
+        device: ListData;
+        country: ListData;
+    };
+}
+interface TrendDataPoint {
+    time: string;
+    visits: number;
+}
+interface ProjectAnalyticsTrendResponse {
+    data: TrendDataPoint[];
+    currentVisitors: number;
+}
 
 declare class LovableClient {
-    private readonly apiKey;
+    private readonly authHeaders;
     private readonly baseUrl;
+    private readonly extraHeaders;
     constructor(options: LovableClientOptions);
+    private rawRequest;
     private request;
+    private requestText;
     /**
      * Get the current authenticated user and their workspaces.
      * Useful for validating an API key and discovering workspace IDs.
@@ -396,24 +671,23 @@ declare class LovableClient {
      */
     getWorkspace(workspaceId: string): Promise<WorkspaceWithMembership>;
     /**
-     * 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.
      */
-    listProjects(workspaceId: string, options?: {
-        limit?: number;
-        cursor?: string;
-        visibility?: "all" | "draft" | "personal" | "private" | "public" | "workspace";
-    }): Promise<ProjectResponse[]>;
+    listProjects(workspaceId: string, options?: ListProjectsOptions): Promise<ListProjectsResponse>;
     /**
      * Create a new project in a workspace
      */
     createProject(workspaceId: string, options: CreateProjectOptions): Promise<ProjectResponse>;
     /**
-     * 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.
      */
-    chat(projectId: string, options: ChatMessageOptions): Promise<void>;
+    chat(projectId: string, options: ChatMessageOptions): Promise<SendMessageResponse>;
     /**
      * Invite a user to a workspace as a collaborator
      */
@@ -488,6 +762,108 @@ declare class LovableClient {
      * @returns Database connection details
      */
     getDatabaseConnectionInfo(projectId: string): Promise<DatabaseConnectionInfo>;
+    /**
+     * 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()`.
+     */
+    getMessage(projectId: string, messageId: string): Promise<GetMessageResponse>;
+    /**
+     * 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.
+     */
+    waitForMessageCompletion(projectId: string, messageId: string, options?: MessageCompletionOptions): Promise<MessageCompletionResult>;
+    /** Get workspace knowledge (custom instructions for the AI agent). */
+    getWorkspaceKnowledge(workspaceId: string): Promise<KnowledgeResponse>;
+    /** Set workspace knowledge. Max 10,000 characters. */
+    setWorkspaceKnowledge(workspaceId: string, content: string): Promise<KnowledgeResponse>;
+    /** Get project knowledge (custom instructions for the AI agent). */
+    getProjectKnowledge(projectId: string): Promise<KnowledgeResponse>;
+    /** Set project knowledge. Max 10,000 characters. */
+    setProjectKnowledge(projectId: string, content: string): Promise<KnowledgeResponse>;
+    /**
+     * 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.
+     */
+    getDiff(projectId: string, params: {
+        messageId?: string;
+        sha?: string;
+        baseSha?: string;
+    }): Promise<GitDiffResponse>;
+    /** List all files in a project at a specific git ref. */
+    listFiles(projectId: string, ref: string): Promise<GitFilesResponse>;
+    /** Read the raw content of a single file at a specific git ref. Returns text. */
+    readFile(projectId: string, path: string, ref: string): Promise<string>;
+    /** List the edit history of a project. */
+    listEdits(projectId: string, params?: {
+        limit?: number;
+        before?: string;
+    }): Promise<EditsResponse>;
+    /** Get a presigned URL for uploading a file. Returns the upload URL and file ID. */
+    getFileUploadUrl(params: {
+        file_name: string;
+        content_type?: string;
+    }): Promise<FileUploadUrlResponse>;
+    /** Set a project's visibility (draft, private, or public). */
+    setProjectVisibility(projectId: string, visibility: string): Promise<{
+        visibility: string;
+    }>;
+    /** Set a folder's visibility (personal or workspace). */
+    setFolderVisibility(workspaceId: string, folderId: string, visibility: string): Promise<{
+        visibility: string;
+    }>;
+    /** List available design system library projects in a workspace. */
+    listLibraryProjects(workspaceId: string): Promise<{
+        libraries: LibraryProjectResponse[];
+    }>;
+    /** List available template projects in a workspace. */
+    listTemplateProjects(workspaceId: string): Promise<{
+        templates: TemplateProjectResponse[];
+    }>;
+    /** List all MCP servers connected to a workspace. */
+    listMCPServers(workspaceId: string): Promise<{
+        servers: MCPServerResponse[];
+    }>;
+    /** Add an MCP server to a workspace. The server URL is tested before saving. */
+    addMCPServer(workspaceId: string, body: AddMCPServerBody): Promise<MCPServerResponse>;
+    /** Remove an MCP server from a workspace. */
+    removeMCPServer(workspaceId: string, serverId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Browse available MCP server templates (catalog). */
+    listMCPCatalog(workspaceId: string): Promise<{
+        catalog: MCPCatalogEntry[];
+    }>;
+    /** List standard (OAuth-based) connectors in a workspace. */
+    listStandardConnectors(workspaceId: string): Promise<{
+        connectors: StandardConnectorItem[];
+    }>;
+    /** List seamless (zero-config) connectors in a workspace. */
+    listSeamlessConnectors(workspaceId: string): Promise<{
+        connectors: SeamlessConnectorItem[];
+    }>;
+    /** List MCP connectors in a workspace. */
+    listMCPConnectors(workspaceId: string): Promise<{
+        connectors: MCPConnectorItem[];
+        custom_enabled: boolean;
+    }>;
+    /** List authenticated connections (accounts) in a workspace. */
+    listConnections(workspaceId: string, params?: {
+        connector_id?: string;
+    }): Promise<{
+        connections: ConnectionItem[];
+    }>;
+    /** Get historical analytics for a published project. */
+    getProjectAnalytics(projectId: string, params: {
+        startDate: string;
+        endDate: string;
+        granularity?: string;
+    }): Promise<ProjectAnalyticsResponse>;
+    /** Get real-time visitor trend for a published project. */
+    getProjectAnalyticsTrend(projectId: string): Promise<ProjectAnalyticsTrendResponse>;
     /**
      * Publish a project.
      *
@@ -623,4 +999,4 @@ declare class LovableClient {
     waitForProjectPublished(projectId: string, options?: WaitOptions): Promise<ProjectResponse>;
 }
 
-export { type AddUserToWorkspaceInputBody, type BatchItemOutcome, type BatchReplayReviewsOutcome, type BatchTracesResult, type ChatMessageOptions, type ChatRequest, type ChatResponse, type ChatResponseOptions, type ContinuationOverride, type CreateProjectBody, type CreateProjectOptions, type CustomModelConfig, type DatabaseConnectionInfo, type DatabaseQueryResult, type DatabaseStatus, type DeploymentResponse, type EnableDatabaseResult, type FileInput, type GetMessageTracesOptions, type InviteCollaboratorOptions, LovableClient, type LovableClientOptions, type LovableError, type MeResponse, type MeWorkspace, type MemberRole, type MessageTracesResponse, type ProjectResponse, type ProjectStatus, type ProjectVisibility, type RemixJobStatus, type RemixJobStep, type RemixJobStepInfo, type RemixMode, type RemixProjectOptions, type RemixResult, type RemixWaitOptions, type ReplayOutcome, type ReplayReviewsItemInput, type ReplayReviewsRequestBody, type ReplayReviewsResponse, type ReviewerRunResult, type TracePurpose, type TraceQuery, type TraceSpan, type UnscopedFile, type WaitOptions, type WorkspaceMembership, type WorkspaceMembershipResponse, type WorkspaceWithMembership };
+export { type AddMCPServerBody, type AddUserToWorkspaceInputBody, ApiError, type BatchItemOutcome, type BatchReplayReviewsOutcome, type BatchTracesResult, type ChatMessageOptions, type ChatRequest, type ChatResponse, type ChatResponseOptions, type ConnectionItem, type ContinuationOverride, type CreateProjectBody, type CreateProjectOptions, type CustomModelConfig, type DatabaseConnectionInfo, type DatabaseQueryResult, type DatabaseStatus, type DeploymentResponse, type DiffEntry, type DiffHunk, type DiffLine, type EditSummary, type EditsResponse, type EnableDatabaseResult, type FileInput, type FileUploadUrlResponse, type GetMessageResponse, type GetMessageTracesOptions, type GitDiffResponse, type GitFileEntry, type GitFilesResponse, type InviteCollaboratorOptions, type KnowledgeResponse, type LibraryProjectResponse, type ListData, type ListDataPoint, type ListProjectItem, type ListProjectsOptions, type ListProjectsResponse, LovableClient, type LovableClientOptions, type LovableError, type MCPCatalogEntry, type MCPConnectorItem, type MCPServerResponse, type MeResponse, type MeWorkspace, type MemberRole, type MessageCompletionOptions, type MessageCompletionResult, type MessageTracesResponse, type ProjectAnalyticsResponse, type ProjectAnalyticsTrendResponse, type ProjectResponse, type ProjectStatus, type ProjectVisibility, type RemixJobStatus, type RemixJobStep, type RemixJobStepInfo, type RemixMode, type RemixProjectOptions, type RemixResult, type RemixWaitOptions, type ReplayOutcome, type ReplayReviewsItemInput, type ReplayReviewsRequestBody, type ReplayReviewsResponse, type ReviewerRunResult, type SeamlessConnectorItem, type SendMessageResponse, type StandardConnectorItem, type TemplateProjectResponse, type TimeSeriesData, type TimeSeriesDataPoint, type TracePurpose, type TraceQuery, type TraceSpan, type TrendDataPoint, type UnscopedFile, type WaitOptions, type WorkspaceMembership, type WorkspaceMembershipResponse, type WorkspaceWithMembership };