@tinybirdco/sdk 0.0.79 → 0.0.81

package/src/api/deploy.ts

@@ -10,6 +10,19 @@ import { tinybirdFetch } from "./fetcher.js";
 const FORWARD_CLASSIC_GUIDANCE =
   "Use the Tinybird Classic CLI (`tb`) from a Tinybird Classic workspace for this operation.";
 
+/**
+ * Poll interval used while waiting for a deployment to reach `data_ready`
+ * (and, when auto-promoting, `live`). Matches the Tinybird CLI (`tb deploy`).
+ */
+const POLL_INTERVAL_MS = 5_000;
+
+/**
+ * How many consecutive `failed` status polls to tolerate before giving up.
+ * With a 5s poll interval this is ~5 minutes, matching the CLI safety valve
+ * for deployments that fail but never auto-delete.
+ */
+export const MAX_CONSECUTIVE_FAILED_POLLS = 60;
+
 /**
  * Feedback item from deployment response
  */
@@ -87,8 +100,10 @@ export interface DeploymentStatusResponse {
  *
  * Uses the /v1/deploy endpoint which accepts all resources in a single
  * multipart form request. After creating the deployment, this function:
- * 1. Polls until the deployment is ready (status === 'data_ready')
- * 2. Sets the deployment as live via /v1/deployments/{id}/set-live
+ * 1. When `auto` is true (default), sends `auto_promote=true` so the
+ *    server promotes the deployment as soon as it's ready.
+ * 2. When `wait` is true (default), polls until the deployment reaches
+ *    `data_ready` (and, if `auto` is also true, until it becomes live).
  *
  * @param config - Build configuration with API URL and token
  * @param resources - Generated resources to deploy
@@ -139,6 +154,8 @@ export interface DeploymentChanges {
 export interface DeployCallbacks {
   /** Called when deployment is created and changes are available */
   onChanges?: (changes: DeploymentChanges) => void;
+  /** Called when deployment was submitted but wait was disabled */
+  onDeploymentSubmitted?: (deploymentId: string) => void;
   /** Called when waiting for deployment to be ready */
   onWaitingForReady?: () => void;
   /** Called when deployment is ready */
@@ -158,18 +175,17 @@ export async function deployToMain(
   resources: GeneratedResources,
   options?: {
     debug?: boolean;
-    pollIntervalMs?: number;
-    maxPollAttempts?: number;
     check?: boolean;
     allowDestructiveOperations?: boolean;
+    wait?: boolean;
+    auto?: boolean;
     callbacks?: DeployCallbacks;
   }
 ): Promise<BuildApiResult> {
   const debug = options?.debug ?? !!process.env.TINYBIRD_DEBUG;
-  const pollIntervalMs = options?.pollIntervalMs ?? 1000;
-  const maxPollAttempts = options?.maxPollAttempts ?? 120; // 2 minutes max
+  const wait = options?.wait ?? true;
+  const auto = options?.auto ?? true;
   const baseUrl = config.baseUrl.replace(/\/$/, "");
-  let previousLiveDeploymentId: string | undefined;
 
   const formData = new FormData();
 
@@ -231,10 +247,6 @@ export async function deployToMain(
 
       if (deploymentsResponse.ok) {
         const deploymentsBody = (await deploymentsResponse.json()) as DeploymentsListResponse;
-        const previousLiveDeployment = deploymentsBody.deployments.find(
-          (d) => d.live || d.status === "live"
-        );
-        previousLiveDeploymentId = previousLiveDeployment?.id;
         const staleDeployments = deploymentsBody.deployments.filter(
           (d) => !d.live && d.status !== "live"
         );
@@ -264,6 +276,9 @@ export async function deployToMain(
   const urlParams = new URLSearchParams();
   if (options?.check) {
     urlParams.set("check", "true");
+  } else if (auto) {
+    // Server will auto-promote the deployment when it's ready
+    urlParams.set("auto_promote", "true");
   }
   if (options?.allowDestructiveOperations) {
     urlParams.set("allow_destructive_operations", "true");
@@ -431,18 +446,67 @@ export async function deployToMain(
     });
   }
 
-  // Step 2: Poll until deployment is ready
+  const deploymentChanges = {
+    pipes: {
+      changed: deploymentDetails.changed_pipe_names ?? [],
+      created: deploymentDetails.new_pipe_names ?? [],
+      deleted: deploymentDetails.deleted_pipe_names ?? [],
+    },
+    datasources: {
+      changed: deploymentDetails.changed_datasource_names ?? [],
+      created: deploymentDetails.new_datasource_names ?? [],
+      deleted: deploymentDetails.deleted_datasource_names ?? [],
+    },
+  };
+
+  // If we're not waiting, return as soon as the server accepted the deployment.
+  if (!wait) {
+    options?.callbacks?.onDeploymentSubmitted?.(deploymentId);
+    return {
+      success: true,
+      result: "success",
+      datasourceCount: resources.datasources.length,
+      pipeCount: resources.pipes.length,
+      connectionCount: resources.connections?.length ?? 0,
+      buildId: deploymentId,
+      ...deploymentChanges,
+    };
+  }
+
+  // Step 2: Poll until the deployment reaches a terminal state.
   let deployment = body.deployment;
-  let attempts = 0;
+  let timesSeenFailed = 0;
+  let notifiedReady = false;
+  let notifiedWaitingForPromote = false;
 
   options?.callbacks?.onWaitingForReady?.();
 
-  while (deployment.status !== "data_ready" && attempts < maxPollAttempts) {
-    await sleep(pollIntervalMs);
-    attempts++;
+  const isDone = (): boolean => {
+    if (deployment.status !== "data_ready") {
+      return false;
+    }
+    if (auto) {
+      // When auto-promoting we must also wait for the server to flip it live.
+      return deployment.live === true;
+    }
+    return true;
+  };
+
+  const buildError = (message: string): BuildApiResult => ({
+    success: false,
+    result: "failed",
+    error: message,
+    datasourceCount: resources.datasources.length,
+    pipeCount: resources.pipes.length,
+    connectionCount: resources.connections?.length ?? 0,
+    buildId: deploymentId,
+  });
+
+  while (!isDone()) {
+    await sleep(POLL_INTERVAL_MS);
 
     if (debug) {
-      console.log(`[debug] Polling deployment status (attempt ${attempts})...`);
+      console.log(`[debug] Polling deployment status...`);
     }
 
     const statusUrl = `${baseUrl}/v1/deployments/${deploymentId}`;
@@ -453,114 +517,72 @@ export async function deployToMain(
     });
 
     if (!statusResponse.ok) {
-      return {
-        success: false,
-        result: "failed",
-        error: `Failed to check deployment status: ${statusResponse.status} ${statusResponse.statusText}`,
-        datasourceCount: resources.datasources.length,
-        pipeCount: resources.pipes.length,
-        connectionCount: resources.connections?.length ?? 0,
-        buildId: deploymentId,
-      };
+      return buildError(
+        `Failed to check deployment status: ${statusResponse.status} ${statusResponse.statusText}`
+      );
     }
 
     const statusBody = (await statusResponse.json()) as DeploymentStatusResponse;
     deployment = statusBody.deployment;
 
     if (debug) {
-      console.log(`[debug] Deployment status: ${deployment.status}`);
+      console.log(
+        `[debug] Deployment status: ${deployment.status} (live=${deployment.live ?? false})`
+      );
     }
 
-    // Check for failed status
-    if (deployment.status === "failed" || deployment.status === "error") {
-      return {
-        success: false,
-        result: "failed",
-        error: `Deployment failed with status: ${deployment.status}`,
-        datasourceCount: resources.datasources.length,
-        pipeCount: resources.pipes.length,
-        connectionCount: resources.connections?.length ?? 0,
-        buildId: deploymentId,
-      };
+    if (deployment.status === "failed") {
+      timesSeenFailed++;
+      if (timesSeenFailed > MAX_CONSECUTIVE_FAILED_POLLS) {
+        return buildError(
+          "Deployment failed to create and didn't start deleting automatically after 5 minutes. " +
+            "You might need to delete it manually in the UI."
+        );
+      }
+      continue;
     }
-  }
-
-  if (deployment.status !== "data_ready") {
-    return {
-      success: false,
-      result: "failed",
-      error: `Deployment timed out after ${maxPollAttempts} attempts. Last status: ${deployment.status}`,
-      datasourceCount: resources.datasources.length,
-      pipeCount: resources.pipes.length,
-      connectionCount: resources.connections?.length ?? 0,
-      buildId: deploymentId,
-    };
-  }
 
-  options?.callbacks?.onDeploymentReady?.();
-
-  // Step 3: Set the deployment as live
-  const setLiveUrl = `${baseUrl}/v1/deployments/${deploymentId}/set-live`;
-
-  if (debug) {
-    console.log(`[debug] POST ${setLiveUrl}`);
-  }
-
-  const setLiveResponse = await tinybirdFetch(setLiveUrl, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${config.token}`,
-    },
-  });
+    if (deployment.status === "deleting" || deployment.status === "deleted") {
+      const errors = deployment.feedback
+        ?.filter((f) => f.level === "ERROR")
+        .map((f) => f.message)
+        .join("\n");
+      const errorSuffix = errors ? `\n${errors}` : "";
+      return buildError(
+        `Deployment failed and ${
+          deployment.status === "deleting" ? "is being" : "was"
+        } deleted automatically.${errorSuffix}`
+      );
+    }
 
-  if (!setLiveResponse.ok) {
-    const setLiveBody = await setLiveResponse.text();
-    return {
-      success: false,
-      result: "failed",
-      error: `Failed to set deployment as live: ${setLiveResponse.status} ${setLiveResponse.statusText}\n${setLiveBody}`,
-      datasourceCount: resources.datasources.length,
-      pipeCount: resources.pipes.length,
-      connectionCount: resources.connections?.length ?? 0,
-      buildId: deploymentId,
-    };
+    if (
+      auto &&
+      deployment.status === "data_ready" &&
+      !deployment.live &&
+      !notifiedWaitingForPromote
+    ) {
+      if (!notifiedReady) {
+        options?.callbacks?.onDeploymentReady?.();
+        notifiedReady = true;
+      }
+      options?.callbacks?.onWaitingForPromote?.();
+      notifiedWaitingForPromote = true;
+    }
   }
 
-  if (debug) {
-    console.log(`[debug] Deployment ${deploymentId} is now live`);
+  if (!notifiedReady) {
+    options?.callbacks?.onDeploymentReady?.();
+    notifiedReady = true;
   }
 
-  if (previousLiveDeploymentId && previousLiveDeploymentId !== deploymentId) {
+  if (auto) {
     if (debug) {
-      console.log(`[debug] Removing previous deployment: ${previousLiveDeploymentId}`);
-    }
-
-    const deletePreviousResponse = await tinybirdFetch(
-      `${baseUrl}/v1/deployments/${previousLiveDeploymentId}`,
-      {
-        method: "DELETE",
-        headers: {
-          Authorization: `Bearer ${config.token}`,
-        },
-      }
-    );
-
-    if (!deletePreviousResponse.ok) {
-      const deletePreviousBody = await deletePreviousResponse.text();
-      return {
-        success: false,
-        result: "failed",
-        error: `Failed to remove previous deployment: ${deletePreviousResponse.status} ${deletePreviousResponse.statusText}\n${deletePreviousBody}`,
-        datasourceCount: resources.datasources.length,
-        pipeCount: resources.pipes.length,
-        connectionCount: resources.connections?.length ?? 0,
-        buildId: deploymentId,
-      };
+      console.log(`[debug] Deployment ${deploymentId} is now live`);
     }
+    options?.callbacks?.onDeploymentPromoted?.();
+    options?.callbacks?.onDeploymentLive?.(deploymentId);
   }
 
-  options?.callbacks?.onDeploymentLive?.(deploymentId);
-
   return {
     success: true,
     result: "success",
@@ -568,16 +590,7 @@ export async function deployToMain(
     pipeCount: resources.pipes.length,
     connectionCount: resources.connections?.length ?? 0,
     buildId: deploymentId,
-    pipes: {
-      changed: deploymentDetails.changed_pipe_names ?? [],
-      created: deploymentDetails.new_pipe_names ?? [],
-      deleted: deploymentDetails.deleted_pipe_names ?? [],
-    },
-    datasources: {
-      changed: deploymentDetails.changed_datasource_names ?? [],
-      created: deploymentDetails.new_datasource_names ?? [],
-      deleted: deploymentDetails.deleted_datasource_names ?? [],
-    },
+    ...deploymentChanges,
   };
 }
 

package/src/cli/commands/deploy.ts

@@ -19,6 +19,14 @@ export interface DeployCommandOptions {
   check?: boolean;
   /** Allow deleting existing resources in main workspace deploys */
   allowDestructiveOperations?: boolean;
+  /**
+   * Wait for the deployment to finish. Defaults to true.
+   */
+  wait?: boolean;
+  /**
+   * Auto-promote the deployment when it's ready. Defaults to true.
+   */
+  auto?: boolean;
   /** Callbacks for deploy progress */
   callbacks?: DeployCallbacks;
 }
@@ -106,6 +114,8 @@ export async function runDeploy(options: DeployCommandOptions = {}): Promise<Dep
       {
         check: options.check,
         allowDestructiveOperations: options.allowDestructiveOperations,
+        wait: options.wait,
+        auto: options.auto,
         callbacks: options.callbacks,
       }
     );

package/src/cli/index.ts

@@ -482,18 +482,33 @@ function createCli(): Command {
       "--allow-destructive-operations",
       "Allow deploys that delete existing datasources, pipes, or connections"
     )
+    .option("--wait", "Wait for the deployment to finish (default)")
+    .option("--no-wait", "Return as soon as the deployment is submitted")
+    .option(
+      "--auto",
+      "Auto-promote the deployment when it's ready (default)"
+    )
+    .option(
+      "--no-auto",
+      "Do not auto-promote the deployment; leave it staged for a manual promote"
+    )
     .option("--debug", "Show debug output including API requests/responses")
     .action(async (options) => {
       if (options.debug) {
         process.env.TINYBIRD_DEBUG = "1";
       }
 
+      const wait = options.wait !== false;
+      const auto = options.auto !== false;
+
       output.highlight("Deploying to main workspace...");
 
       const result = await runDeploy({
         dryRun: options.dryRun,
         check: options.check,
         allowDestructiveOperations: options.allowDestructiveOperations,
+        wait,
+        auto,
         callbacks: {
           onChanges: (deployChanges) => {
             // Show changes table immediately after deployment is created
@@ -531,8 +546,11 @@ function createCli(): Command {
 
             output.showChangesTable(changes);
           },
+          onDeploymentSubmitted: (id) => output.showDeploymentSubmitted(id, auto),
           onWaitingForReady: () => output.showWaitingForDeployment(),
           onDeploymentReady: () => output.showDeploymentReady(),
+          onWaitingForPromote: () => output.showWaitingForPromote(),
+          onDeploymentPromoted: () => output.showDeploymentPromoted(),
           onDeploymentLive: (id) => output.showDeploymentLive(id),
           onValidating: () => output.showValidatingDeployment(),
         },

package/src/cli/output.ts

@@ -218,6 +218,30 @@ export function showDeploymentLive(deploymentId: string): void {
   success(`✓ Deployment #${deploymentId} is live!`);
 }
 
+/**
+ * Show waiting for deployment promotion message
+ */
+export function showWaitingForPromote(): void {
+  info("» Waiting for deployment to be promoted...");
+}
+
+/**
+ * Show deployment submitted message (used when --no-wait is set)
+ */
+export function showDeploymentSubmitted(deploymentId: string, autoPromote: boolean): void {
+  const autoFrag = autoPromote
+    ? " It will be auto-promoted when ready."
+    : " It won't be auto-promoted when ready.";
+  success(`✓ Deployment #${deploymentId} submitted.${autoFrag}`);
+}
+
+/**
+ * Show deployment promoted message
+ */
+export function showDeploymentPromoted(): void {
+  success("✓ Deployment promoted");
+}
+
 /**
  * Show validating deployment message
  */
@@ -424,6 +448,9 @@ export const output = {
   showNoChanges,
   showWaitingForDeployment,
   showDeploymentReady,
+  showWaitingForPromote,
+  showDeploymentPromoted,
+  showDeploymentSubmitted,
   showDeploymentLive,
   showValidatingDeployment,
   showDeploySuccess,

package/src/test/handlers.ts

@@ -86,25 +86,21 @@ export function createDeploySuccessResponse(options?: {
 export function createDeploymentStatusResponse(options?: {
   deploymentId?: string;
   status?: string;
+  live?: boolean;
 }) {
+  const status = options?.status ?? "data_ready";
   return {
     result: "success",
     deployment: {
       id: options?.deploymentId ?? "deploy-123",
-      status: options?.status ?? "data_ready",
+      status,
+      // When the deployment is `data_ready` the default assumes the server
+      // has already auto-promoted it, which is what most tests exercise.
+      live: options?.live ?? status === "data_ready",
     },
   };
 }
 
-/**
- * Create set-live success response (for /v1/deployments/:id/set-live endpoint)
- */
-export function createSetLiveSuccessResponse() {
-  return {
-    result: "success",
-  };
-}
-
 /**
  * Create deployments list response (for /v1/deployments endpoint)
  */