@lovable.dev/sdk 0.1.4 → 0.1.7

package/README.md

@@ -79,28 +79,6 @@ await client.chat(projectId, { message: "Add dark mode" });
 const response = await client.waitForResponse(projectId);
 ```
 
-### Remixing with agent state
-
-Enable `includeAgentState` to carry over the agent's continuation state to the remixed project, allowing prompt cache reuse on the first follow-up message.
-
-```typescript
-const jobId = await client.remixProject("source-project-id", {
-  workspaceId: "target-workspace-id",
-  messageId: "message-id-to-snapshot-at",
-  includeHistory: true,
-  includeCustomKnowledge: true,
-  includeAgentState: true,
-});
-const { projectId } = await client.waitForRemix("source-project-id", jobId);
-
-await client.chat(projectId, {
-  message: "Add dark mode",
-  continuation: "allow_expired_cache",
-});
-```
-
-Requires `includeHistory`, `includeCustomKnowledge`, and API-key auth.
-
 ### Continuation override
 
 The `continuation` option on `chat()` overrides prompt cache reuse behavior. API-key auth only.
@@ -310,7 +288,6 @@ Options:
 - `remixMode` (optional): `"before"` (default) captures state before the message; `"including"` captures state after the message and its AI response
 - `includeHistory` (optional, default: `false`): Whether to preserve chat history
 - `includeCustomKnowledge` (optional, default: `false`): Whether to copy custom instructions/knowledge
-- `includeAgentState` (optional, default: `false`): Copy agent continuation state so the prompt cache can be reused after remix. Requires `includeHistory: true`, `includeCustomKnowledge: true`, and API-key auth. See [Remixing with agent state](#remixing-with-agent-state-prompt-cache-continuation)
 - `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

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;
@@ -182,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;
@@ -199,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;
@@ -217,8 +230,12 @@ 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
@@ -233,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;
@@ -334,7 +356,7 @@ interface ReplayReviewsResponse {
     results: BatchReplayReviewsOutcome;
 }
 type RemixJobStatus = "unknown" | "preparing" | "running" | "completed" | "error";
-type RemixJobStep = "starting" | "creating_new_project" | "remixing_integration" | "finalizing" | "completed";
+type RemixJobStep = "starting" | "creating_new_project" | "restoring_supabase" | "copying_history" | "preparing_repository" | "remixing_integration" | "pushing_repository" | "finalizing" | "completed";
 interface RemixJobStepInfo {
     step: RemixJobStep;
     integration_name?: string;
@@ -348,10 +370,9 @@ 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. */
-    includeAgentState?: boolean;
 }
 interface RemixResult {
     projectId: string;
@@ -381,12 +402,260 @@ interface DatabaseConnectionInfo {
     connection_string: string;
     api_url: string;
 }
+declare class ApiError extends Error {
+    readonly status: number;
+    readonly type?: string;
+    readonly detail?: string;
+    readonly props?: Record<string, unknown>;
+    constructor(status: number, message: string, type?: string, detail?: string, props?: Record<string, unknown>);
+}
+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 ConnectorResponse {
+    id: string;
+    name: string;
+    url?: string;
+    auth_type: string;
+    connector_id?: string;
+    is_connected: boolean;
+}
+interface AvailableConnectorEntry {
+    id: string;
+    display_name: string;
+    summary: string;
+    category: string;
+    requires_custom_url?: boolean;
+    documentation_url?: string;
+}
+interface AddConnectorBody {
+    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.
@@ -401,24 +670,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
      */
@@ -493,6 +761,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 connectors in a workspace. */
+    listConnectors(workspaceId: string): Promise<{
+        connectors: ConnectorResponse[];
+    }>;
+    /** Add a connector to a workspace. The server URL is tested before saving. */
+    addConnector(workspaceId: string, body: AddConnectorBody): Promise<ConnectorResponse>;
+    /** Remove a connector from a workspace. */
+    removeConnector(workspaceId: string, connectorId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Browse available connector templates. */
+    listAvailableConnectors(workspaceId: string): Promise<{
+        catalog: AvailableConnectorEntry[];
+    }>;
+    /** 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.
      *
@@ -628,4 +998,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 AddConnectorBody, type AddUserToWorkspaceInputBody, ApiError, type AvailableConnectorEntry, type BatchItemOutcome, type BatchReplayReviewsOutcome, type BatchTracesResult, type ChatMessageOptions, type ChatRequest, type ChatResponse, type ChatResponseOptions, type ConnectionItem, type ConnectorResponse, 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 MCPConnectorItem, 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 };