@tinybirdco/sdk 0.0.13 → 0.0.14

package/src/cli/output.test.ts

@@ -6,10 +6,17 @@ import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import {
   formatDuration,
   showResourceChange,
+  showChangesTable,
   showBuildErrors,
   showBuildSuccess,
   showBuildFailure,
   showNoChanges,
+  showWaitingForDeployment,
+  showDeploymentReady,
+  showDeploymentLive,
+  showValidatingDeployment,
+  showDeploySuccess,
+  showDeployFailure,
 } from "./output.js";
 
 describe("output utilities", () => {
@@ -58,6 +65,50 @@ describe("output utilities", () => {
     });
   });
 
+  describe("showChangesTable", () => {
+    it("shows no changes message when empty", () => {
+      showChangesTable([]);
+      expect(consoleLogSpy).toHaveBeenCalled();
+      const call = consoleLogSpy.mock.calls[0][0];
+      expect(call).toContain("No changes to be deployed");
+    });
+
+    it("shows table with changes", () => {
+      showChangesTable([
+        { status: "new", name: "events", type: "datasource" },
+        { status: "modified", name: "top_pages", type: "pipe" },
+        { status: "deleted", name: "old_data", type: "datasource" },
+      ]);
+
+      // Check that table header and data were logged
+      const allCalls = consoleLogSpy.mock.calls.map((c: unknown[]) => c[0]).join("\n");
+      expect(allCalls).toContain("Changes to be deployed");
+      expect(allCalls).toContain("status");
+      expect(allCalls).toContain("name");
+      expect(allCalls).toContain("type");
+      expect(allCalls).toContain("new");
+      expect(allCalls).toContain("events");
+      expect(allCalls).toContain("datasource");
+      expect(allCalls).toContain("modified");
+      expect(allCalls).toContain("top_pages");
+      expect(allCalls).toContain("pipe");
+      expect(allCalls).toContain("deleted");
+      expect(allCalls).toContain("old_data");
+    });
+
+    it("shows table borders", () => {
+      showChangesTable([{ status: "new", name: "test", type: "pipe" }]);
+
+      const allCalls = consoleLogSpy.mock.calls.map((c: unknown[]) => c[0]).join("\n");
+      expect(allCalls).toContain("┌");
+      expect(allCalls).toContain("┐");
+      expect(allCalls).toContain("├");
+      expect(allCalls).toContain("┤");
+      expect(allCalls).toContain("└");
+      expect(allCalls).toContain("┘");
+    });
+  });
+
   describe("showBuildErrors", () => {
     it("shows errors with filename", () => {
       showBuildErrors([
@@ -138,7 +189,71 @@ describe("output utilities", () => {
   describe("showNoChanges", () => {
     it("shows no changes message", () => {
       showNoChanges();
-      expect(consoleLogSpy).toHaveBeenCalledWith("No changes. Build skipped.");
+      expect(consoleLogSpy).toHaveBeenCalled();
+      const call = consoleLogSpy.mock.calls[0][0];
+      expect(call).toContain("△");
+      expect(call).toContain("Not deploying. No changes.");
+    });
+  });
+
+  describe("showWaitingForDeployment", () => {
+    it("shows waiting for deployment message", () => {
+      showWaitingForDeployment();
+      expect(consoleLogSpy).toHaveBeenCalledWith("» Waiting for deployment to be ready...");
+    });
+  });
+
+  describe("showDeploymentReady", () => {
+    it("shows deployment ready message", () => {
+      showDeploymentReady();
+      expect(consoleLogSpy).toHaveBeenCalled();
+      const call = consoleLogSpy.mock.calls[0][0];
+      expect(call).toContain("✓");
+      expect(call).toContain("Deployment is ready");
+    });
+  });
+
+  describe("showDeploymentLive", () => {
+    it("shows deployment live message with ID", () => {
+      showDeploymentLive("abc123");
+      expect(consoleLogSpy).toHaveBeenCalled();
+      const call = consoleLogSpy.mock.calls[0][0];
+      expect(call).toContain("✓");
+      expect(call).toContain("Deployment #abc123 is live!");
+    });
+  });
+
+  describe("showValidatingDeployment", () => {
+    it("shows validating deployment message", () => {
+      showValidatingDeployment();
+      expect(consoleLogSpy).toHaveBeenCalledWith("» Validating deployment...");
+    });
+  });
+
+  describe("showDeploySuccess", () => {
+    it("shows deploy success with duration in ms", () => {
+      showDeploySuccess(500);
+      expect(consoleLogSpy).toHaveBeenCalled();
+      const call = consoleLogSpy.mock.calls[0][0];
+      expect(call).toContain("✓");
+      expect(call).toContain("Deploy completed in 500ms");
+    });
+
+    it("shows deploy success with duration in seconds", () => {
+      showDeploySuccess(2500);
+      expect(consoleLogSpy).toHaveBeenCalled();
+      const call = consoleLogSpy.mock.calls[0][0];
+      expect(call).toContain("Deploy completed in 2.5s");
+    });
+  });
+
+  describe("showDeployFailure", () => {
+    it("shows deploy failure", () => {
+      showDeployFailure();
+      expect(consoleErrorSpy).toHaveBeenCalled();
+      const call = consoleErrorSpy.mock.calls[0][0];
+      expect(call).toContain("✗");
+      expect(call).toContain("Deploy failed");
     });
   });
 });

package/src/cli/output.ts

@@ -90,6 +90,7 @@ export function formatDuration(ms: number): string {
 
 /**
  * Show a resource change (checkmark + path + status)
+ * @deprecated Use showChangesTable instead for table format
  */
 export function showResourceChange(
   path: string,
@@ -98,6 +99,51 @@ export function showResourceChange(
   console.log(`✓ ${path} ${status}`);
 }
 
+/**
+ * Resource change entry for table display
+ */
+export interface ResourceChange {
+  status: "new" | "modified" | "deleted";
+  name: string;
+  type: "datasource" | "pipe" | "connection";
+}
+
+/**
+ * Show changes table similar to Python CLI
+ * Displays a formatted table of resource changes
+ */
+export function showChangesTable(changes: ResourceChange[]): void {
+  if (changes.length === 0) {
+    gray("* No changes to be deployed");
+    return;
+  }
+
+  info("\n* Changes to be deployed:");
+
+  // Calculate column widths
+  const statusWidth = Math.max(6, ...changes.map((c) => c.status.length));
+  const nameWidth = Math.max(4, ...changes.map((c) => c.name.length));
+  const typeWidth = Math.max(4, ...changes.map((c) => c.type.length));
+
+  // Build table
+  const separator = `├${"─".repeat(statusWidth + 2)}┼${"─".repeat(nameWidth + 2)}┼${"─".repeat(typeWidth + 2)}┤`;
+  const topBorder = `┌${"─".repeat(statusWidth + 2)}┬${"─".repeat(nameWidth + 2)}┬${"─".repeat(typeWidth + 2)}┐`;
+  const bottomBorder = `└${"─".repeat(statusWidth + 2)}┴${"─".repeat(nameWidth + 2)}┴${"─".repeat(typeWidth + 2)}┘`;
+
+  const padRight = (str: string, width: number) => str + " ".repeat(width - str.length);
+
+  // Print table
+  console.log(topBorder);
+  console.log(`│ ${padRight("status", statusWidth)} │ ${padRight("name", nameWidth)} │ ${padRight("type", typeWidth)} │`);
+  console.log(separator);
+
+  for (const change of changes) {
+    console.log(`│ ${padRight(change.status, statusWidth)} │ ${padRight(change.name, nameWidth)} │ ${padRight(change.type, typeWidth)} │`);
+  }
+
+  console.log(bottomBorder);
+}
+
 /**
  * Show a warning for a resource
  */
@@ -148,7 +194,49 @@ export function showBuildFailure(isRebuild = false): void {
  * Show no changes message
  */
 export function showNoChanges(): void {
-  info("No changes. Build skipped.");
+  warning("△ Not deploying. No changes.");
+}
+
+/**
+ * Show waiting for deployment message
+ */
+export function showWaitingForDeployment(): void {
+  info("» Waiting for deployment to be ready...");
+}
+
+/**
+ * Show deployment ready message
+ */
+export function showDeploymentReady(): void {
+  success("✓ Deployment is ready");
+}
+
+/**
+ * Show deployment live message
+ */
+export function showDeploymentLive(deploymentId: string): void {
+  success(`✓ Deployment #${deploymentId} is live!`);
+}
+
+/**
+ * Show validating deployment message
+ */
+export function showValidatingDeployment(): void {
+  info("» Validating deployment...");
+}
+
+/**
+ * Show final deploy success message
+ */
+export function showDeploySuccess(durationMs: number): void {
+  success(`\n✓ Deploy completed in ${formatDuration(durationMs)}`);
+}
+
+/**
+ * Show final deploy failure message
+ */
+export function showDeployFailure(): void {
+  error(`\n✗ Deploy failed`);
 }
 
 /**
@@ -165,9 +253,16 @@ export const output = {
   formatTime,
   formatDuration,
   showResourceChange,
+  showChangesTable,
   showResourceWarning,
   showBuildErrors,
   showBuildSuccess,
   showBuildFailure,
   showNoChanges,
+  showWaitingForDeployment,
+  showDeploymentReady,
+  showDeploymentLive,
+  showValidatingDeployment,
+  showDeploySuccess,
+  showDeployFailure,
 };

package/src/client/preview.test.ts

@@ -0,0 +1,168 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  isPreviewEnvironment,
+  getPreviewBranchName,
+  resolveToken,
+  clearTokenCache,
+} from "./preview.js";
+
+describe("Preview environment detection", () => {
+  const originalEnv = { ...process.env };
+
+  beforeEach(() => {
+    // Clear all relevant env vars before each test
+    delete process.env.VERCEL_ENV;
+    delete process.env.GITHUB_HEAD_REF;
+    delete process.env.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME;
+    delete process.env.CI;
+    delete process.env.TINYBIRD_PREVIEW_MODE;
+    delete process.env.VERCEL_GIT_COMMIT_REF;
+    delete process.env.GITHUB_REF_NAME;
+    delete process.env.CI_COMMIT_BRANCH;
+    delete process.env.CIRCLE_BRANCH;
+    delete process.env.BUILD_SOURCEBRANCHNAME;
+    delete process.env.BITBUCKET_BRANCH;
+    delete process.env.TINYBIRD_BRANCH_NAME;
+    delete process.env.TINYBIRD_BRANCH_TOKEN;
+    delete process.env.TINYBIRD_TOKEN;
+    delete process.env.TINYBIRD_URL;
+    clearTokenCache();
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+    clearTokenCache();
+    vi.restoreAllMocks();
+  });
+
+  describe("isPreviewEnvironment", () => {
+    it("returns false in non-preview environment", () => {
+      expect(isPreviewEnvironment()).toBe(false);
+    });
+
+    it("returns true for Vercel preview deployments", () => {
+      process.env.VERCEL_ENV = "preview";
+      expect(isPreviewEnvironment()).toBe(true);
+    });
+
+    it("returns false for Vercel production deployments", () => {
+      process.env.VERCEL_ENV = "production";
+      expect(isPreviewEnvironment()).toBe(false);
+    });
+
+    it("returns true for GitHub Actions PRs", () => {
+      process.env.GITHUB_HEAD_REF = "feature-branch";
+      expect(isPreviewEnvironment()).toBe(true);
+    });
+
+    it("returns true for GitLab merge requests", () => {
+      process.env.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME = "feature-branch";
+      expect(isPreviewEnvironment()).toBe(true);
+    });
+
+    it("returns true for generic CI with preview mode", () => {
+      process.env.CI = "true";
+      process.env.TINYBIRD_PREVIEW_MODE = "true";
+      expect(isPreviewEnvironment()).toBe(true);
+    });
+
+    it("returns false for generic CI without preview mode", () => {
+      process.env.CI = "true";
+      expect(isPreviewEnvironment()).toBe(false);
+    });
+  });
+
+  describe("getPreviewBranchName", () => {
+    it("returns null when no env vars are set", () => {
+      expect(getPreviewBranchName()).toBeNull();
+    });
+
+    it("prefers explicit TINYBIRD_BRANCH_NAME override", () => {
+      process.env.TINYBIRD_BRANCH_NAME = "override-branch";
+      process.env.VERCEL_GIT_COMMIT_REF = "vercel-branch";
+      expect(getPreviewBranchName()).toBe("override-branch");
+    });
+
+    it("uses VERCEL_GIT_COMMIT_REF for Vercel", () => {
+      process.env.VERCEL_GIT_COMMIT_REF = "vercel-branch";
+      expect(getPreviewBranchName()).toBe("vercel-branch");
+    });
+
+    it("uses GITHUB_HEAD_REF for GitHub Actions PRs", () => {
+      process.env.GITHUB_HEAD_REF = "pr-branch";
+      expect(getPreviewBranchName()).toBe("pr-branch");
+    });
+
+    it("uses GITHUB_REF_NAME for GitHub Actions pushes", () => {
+      process.env.GITHUB_REF_NAME = "main";
+      expect(getPreviewBranchName()).toBe("main");
+    });
+
+    it("prefers GITHUB_HEAD_REF over GITHUB_REF_NAME", () => {
+      process.env.GITHUB_HEAD_REF = "pr-branch";
+      process.env.GITHUB_REF_NAME = "main";
+      expect(getPreviewBranchName()).toBe("pr-branch");
+    });
+
+    it("uses CI_MERGE_REQUEST_SOURCE_BRANCH_NAME for GitLab MRs", () => {
+      process.env.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME = "mr-branch";
+      expect(getPreviewBranchName()).toBe("mr-branch");
+    });
+
+    it("uses CI_COMMIT_BRANCH for GitLab CI branches", () => {
+      process.env.CI_COMMIT_BRANCH = "gitlab-branch";
+      expect(getPreviewBranchName()).toBe("gitlab-branch");
+    });
+
+    it("uses CIRCLE_BRANCH for CircleCI", () => {
+      process.env.CIRCLE_BRANCH = "circle-branch";
+      expect(getPreviewBranchName()).toBe("circle-branch");
+    });
+
+    it("uses BUILD_SOURCEBRANCHNAME for Azure Pipelines", () => {
+      process.env.BUILD_SOURCEBRANCHNAME = "azure-branch";
+      expect(getPreviewBranchName()).toBe("azure-branch");
+    });
+
+    it("uses BITBUCKET_BRANCH for Bitbucket Pipelines", () => {
+      process.env.BITBUCKET_BRANCH = "bitbucket-branch";
+      expect(getPreviewBranchName()).toBe("bitbucket-branch");
+    });
+  });
+
+  describe("resolveToken", () => {
+    it("returns TINYBIRD_BRANCH_TOKEN if set", async () => {
+      process.env.TINYBIRD_BRANCH_TOKEN = "branch-token";
+      process.env.TINYBIRD_TOKEN = "workspace-token";
+      const token = await resolveToken();
+      expect(token).toBe("branch-token");
+    });
+
+    it("throws if no token is configured", async () => {
+      await expect(resolveToken()).rejects.toThrow("TINYBIRD_TOKEN is not configured");
+    });
+
+    it("returns configured token from options", async () => {
+      const token = await resolveToken({ token: "option-token" });
+      expect(token).toBe("option-token");
+    });
+
+    it("returns TINYBIRD_TOKEN when not in preview environment", async () => {
+      process.env.TINYBIRD_TOKEN = "workspace-token";
+      const token = await resolveToken();
+      expect(token).toBe("workspace-token");
+    });
+
+    it("passes token from options", async () => {
+      const token = await resolveToken({ token: "my-token" });
+      expect(token).toBe("my-token");
+    });
+  });
+
+  describe("clearTokenCache", () => {
+    it("clears the cached token", async () => {
+      // Just verify it doesn't throw
+      expect(() => clearTokenCache()).not.toThrow();
+    });
+  });
+});

package/src/client/preview.ts

@@ -0,0 +1,210 @@
+/**
+ * Preview environment detection and branch token resolution
+ *
+ * Automatically detects preview/CI environments and resolves the appropriate
+ * Tinybird branch token for the current git branch.
+ */
+
+import { tinybirdFetch } from "../api/fetcher.js";
+
+/**
+ * Branch information with token
+ */
+interface BranchWithToken {
+  id: string;
+  name: string;
+  token: string;
+  created_at: string;
+}
+
+/**
+ * Cached branch token to avoid repeated API calls
+ */
+let cachedBranchToken: string | null = null;
+let cachedBranchName: string | null = null;
+
+/**
+ * Detect if we're running in a preview/CI environment
+ */
+export function isPreviewEnvironment(): boolean {
+  return !!(
+    // Vercel preview deployments
+    process.env.VERCEL_ENV === "preview" ||
+    // GitHub Actions (PRs)
+    process.env.GITHUB_HEAD_REF ||
+    // GitLab CI (merge requests)
+    process.env.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME ||
+    // Generic CI with preview indicator
+    (process.env.CI && process.env.TINYBIRD_PREVIEW_MODE === "true")
+  );
+}
+
+/**
+ * Get the current git branch name from environment variables
+ * Supports various CI platforms
+ */
+export function getPreviewBranchName(): string | null {
+  // Explicit override
+  if (process.env.TINYBIRD_BRANCH_NAME) {
+    return process.env.TINYBIRD_BRANCH_NAME;
+  }
+
+  // Vercel
+  if (process.env.VERCEL_GIT_COMMIT_REF) {
+    return process.env.VERCEL_GIT_COMMIT_REF;
+  }
+
+  // GitHub Actions (PR)
+  if (process.env.GITHUB_HEAD_REF) {
+    return process.env.GITHUB_HEAD_REF;
+  }
+
+  // GitHub Actions (push)
+  if (process.env.GITHUB_REF_NAME) {
+    return process.env.GITHUB_REF_NAME;
+  }
+
+  // GitLab CI (merge request)
+  if (process.env.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME) {
+    return process.env.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME;
+  }
+
+  // GitLab CI (branch)
+  if (process.env.CI_COMMIT_BRANCH) {
+    return process.env.CI_COMMIT_BRANCH;
+  }
+
+  // CircleCI
+  if (process.env.CIRCLE_BRANCH) {
+    return process.env.CIRCLE_BRANCH;
+  }
+
+  // Azure Pipelines
+  if (process.env.BUILD_SOURCEBRANCHNAME) {
+    return process.env.BUILD_SOURCEBRANCHNAME;
+  }
+
+  // Bitbucket Pipelines
+  if (process.env.BITBUCKET_BRANCH) {
+    return process.env.BITBUCKET_BRANCH;
+  }
+
+  return null;
+}
+
+/**
+ * Sanitize a git branch name for use as a Tinybird branch name
+ * Tinybird only accepts alphanumeric characters and underscores
+ */
+function sanitizeBranchName(branchName: string): string {
+  return branchName
+    .replace(/[^a-zA-Z0-9_]/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^_|_$/g, "");
+}
+
+/**
+ * Fetch branch token from Tinybird API
+ */
+async function fetchBranchToken(
+  baseUrl: string,
+  workspaceToken: string,
+  branchName: string
+): Promise<string | null> {
+  const sanitizedName = sanitizeBranchName(branchName);
+  const url = new URL(`/v0/environments/${encodeURIComponent(sanitizedName)}`, baseUrl);
+  url.searchParams.set("with_token", "true");
+
+  try {
+    const response = await tinybirdFetch(url.toString(), {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${workspaceToken}`,
+      },
+    });
+
+    if (!response.ok) {
+      // Branch doesn't exist or access denied
+      return null;
+    }
+
+    const branch = (await response.json()) as BranchWithToken;
+    return branch.token ?? null;
+  } catch {
+    // Network error or other issue
+    return null;
+  }
+}
+
+/**
+ * Resolve the token to use for API calls
+ *
+ * Priority:
+ * 1. Explicit TINYBIRD_BRANCH_TOKEN env var
+ * 2. In preview environment: fetch branch token using workspace token
+ * 3. Fall back to TINYBIRD_TOKEN
+ *
+ * @param options - Optional configuration overrides
+ * @returns The resolved token to use
+ */
+export async function resolveToken(options?: {
+  baseUrl?: string;
+  token?: string;
+}): Promise<string> {
+  // 1. Check for explicit branch token override
+  if (process.env.TINYBIRD_BRANCH_TOKEN) {
+    return process.env.TINYBIRD_BRANCH_TOKEN;
+  }
+
+  // Get the configured token (workspace token)
+  const configuredToken = options?.token ?? process.env.TINYBIRD_TOKEN;
+
+  if (!configuredToken) {
+    throw new Error(
+      "TINYBIRD_TOKEN is not configured. Set it in your environment or pass it to createTinybirdClient()."
+    );
+  }
+
+  // 2. Check if we're in a preview environment
+  if (isPreviewEnvironment()) {
+    const branchName = getPreviewBranchName();
+
+    if (branchName) {
+      // Check cache first
+      if (cachedBranchToken && cachedBranchName === branchName) {
+        return cachedBranchToken;
+      }
+
+      const baseUrl = options?.baseUrl ?? process.env.TINYBIRD_URL ?? "https://api.tinybird.co";
+
+      // Fetch branch token
+      const branchToken = await fetchBranchToken(baseUrl, configuredToken, branchName);
+
+      if (branchToken) {
+        // Cache for subsequent calls
+        cachedBranchToken = branchToken;
+        cachedBranchName = branchName;
+        return branchToken;
+      }
+
+      // Branch doesn't exist - fall back to workspace token
+      // This allows the app to still work, just using main workspace
+      console.warn(
+        `[tinybird] Preview branch "${branchName}" not found. ` +
+          `Run "tinybird preview" to create it. Falling back to workspace token.`
+      );
+    }
+  }
+
+  // 3. Fall back to configured token
+  return configuredToken;
+}
+
+/**
+ * Clear the cached branch token
+ * Useful for testing or when switching branches
+ */
+export function clearTokenCache(): void {
+  cachedBranchToken = null;
+  cachedBranchName = null;
+}

package/src/index.ts

@@ -213,3 +213,11 @@ export type {
   TypedPipeEndpoint,
   TypedDatasourceIngest,
 } from "./client/types.js";
+
+// ============ Preview Environment ============
+export {
+  isPreviewEnvironment,
+  getPreviewBranchName,
+  resolveToken,
+  clearTokenCache,
+} from "./client/preview.js";

package/src/schema/project.ts

@@ -222,11 +222,17 @@ function buildProjectClient<
 
   const getClient = async (): Promise<TinybirdClient> => {
     if (!_client) {
-      // Dynamic import to avoid circular dependencies
+      // Dynamic imports to avoid circular dependencies
       const { createClient } = await import("../client/base.js");
+      const { resolveToken } = await import("../client/preview.js");
+
+      // Resolve the token (handles preview environment detection)
+      const baseUrl = options?.baseUrl ?? process.env.TINYBIRD_URL ?? "https://api.tinybird.co";
+      const token = await resolveToken({ baseUrl, token: options?.token });
+
       _client = createClient({
-        baseUrl: options?.baseUrl ?? process.env.TINYBIRD_URL ?? "https://api.tinybird.co",
-        token: options?.token ?? process.env.TINYBIRD_TOKEN!,
+        baseUrl,
+        token,
         devMode: process.env.NODE_ENV === "development",
       });
     }