@tinybirdco/sdk 0.0.20 → 0.0.21

package/src/api/dashboard.ts

@@ -0,0 +1,121 @@
+/**
+ * Tinybird Dashboard URL utilities
+ *
+ * Generates dashboard links for workspaces and branches
+ */
+
+/**
+ * Region information extracted from API URL
+ */
+export interface RegionInfo {
+  /** Cloud provider: "gcp" or "aws" */
+  provider: string;
+  /** Region identifier (e.g., "europe-west3", "us-east4", "us-west-2") */
+  region: string;
+}
+
+/**
+ * Mapping of API hostnames to region information
+ *
+ * Based on https://www.tinybird.co/docs/api-reference#current-tinybird-regions
+ */
+const API_REGION_MAP: Record<string, RegionInfo> = {
+  // GCP Regions
+  "api.tinybird.co": { provider: "gcp", region: "europe-west3" },
+  "api.us-east.tinybird.co": { provider: "gcp", region: "us-east4" },
+  // AWS Regions
+  "api.eu-central-1.aws.tinybird.co": { provider: "aws", region: "eu-central-1" },
+  "api.us-east-1.aws.tinybird.co": { provider: "aws", region: "us-east-1" },
+  "api.us-west-2.aws.tinybird.co": { provider: "aws", region: "us-west-2" },
+};
+
+/**
+ * Parse an API URL to extract region information
+ *
+ * @param apiUrl - The Tinybird API base URL (e.g., "https://api.tinybird.co")
+ * @returns Region info or null if the URL doesn't match a known region
+ *
+ * @example
+ * ```ts
+ * parseApiUrl("https://api.tinybird.co")
+ * // => { provider: "gcp", region: "europe-west3" }
+ *
+ * parseApiUrl("https://api.us-west-2.aws.tinybird.co")
+ * // => { provider: "aws", region: "us-west-2" }
+ * ```
+ */
+export function parseApiUrl(apiUrl: string): RegionInfo | null {
+  try {
+    const url = new URL(apiUrl);
+    const hostname = url.hostname;
+    return API_REGION_MAP[hostname] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Generate a Tinybird dashboard URL for a workspace
+ *
+ * @param apiUrl - The Tinybird API base URL
+ * @param workspaceName - The workspace name
+ * @returns Dashboard URL or null if the API URL is not recognized
+ *
+ * @example
+ * ```ts
+ * getDashboardUrl("https://api.tinybird.co", "my_workspace")
+ * // => "https://cloud.tinybird.co/gcp/europe-west3/my_workspace"
+ * ```
+ */
+export function getDashboardUrl(apiUrl: string, workspaceName: string): string | null {
+  const regionInfo = parseApiUrl(apiUrl);
+  if (!regionInfo) {
+    return null;
+  }
+
+  return `https://cloud.tinybird.co/${regionInfo.provider}/${regionInfo.region}/${workspaceName}`;
+}
+
+/**
+ * Generate a Tinybird dashboard URL for a branch
+ *
+ * @param apiUrl - The Tinybird API base URL
+ * @param workspaceName - The workspace name
+ * @param branchName - The branch name
+ * @returns Dashboard URL or null if the API URL is not recognized
+ *
+ * @example
+ * ```ts
+ * getBranchDashboardUrl("https://api.tinybird.co", "my_workspace", "feature_branch")
+ * // => "https://cloud.tinybird.co/gcp/europe-west3/my_workspace~feature_branch"
+ * ```
+ */
+export function getBranchDashboardUrl(
+  apiUrl: string,
+  workspaceName: string,
+  branchName: string
+): string | null {
+  const regionInfo = parseApiUrl(apiUrl);
+  if (!regionInfo) {
+    return null;
+  }
+
+  return `https://cloud.tinybird.co/${regionInfo.provider}/${regionInfo.region}/${workspaceName}~${branchName}`;
+}
+
+/**
+ * Generate a local Tinybird dashboard URL
+ *
+ * @param workspaceName - The local workspace name
+ * @param port - The local Tinybird port (default: 7181)
+ * @returns Local dashboard URL
+ *
+ * @example
+ * ```ts
+ * getLocalDashboardUrl("my_local_workspace")
+ * // => "https://cloud.tinybird.co/local/7181/my_local_workspace"
+ * ```
+ */
+export function getLocalDashboardUrl(workspaceName: string, port = 7181): string {
+  return `https://cloud.tinybird.co/local/${port}/${workspaceName}`;
+}

package/src/cli/commands/branch.ts

@@ -16,6 +16,7 @@ import {
   removeBranch as removeCachedBranch,
   listCachedBranches,
 } from "../branch-store.js";
+import { getBranchDashboardUrl } from "../../api/dashboard.js";
 
 /**
  * Branch command options
@@ -53,6 +54,8 @@ export interface BranchStatusResult {
   tinybirdBranch?: TinybirdBranch;
   /** Whether a cached token exists */
   hasCachedToken: boolean;
+  /** Dashboard URL for the branch */
+  dashboardUrl?: string;
   /** Error message if failed */
   error?: string;
 }
@@ -135,14 +138,16 @@ export async function runBranchStatus(
   const tinybirdBranchName = config.tinybirdBranch; // Sanitized name
   const isMainBranch = config.isMainBranch;
 
-  // Fetch the workspace ID from the API
+  // Fetch the workspace from the API
   let workspaceId: string;
+  let workspaceName: string;
   try {
     const workspace = await getWorkspace({
       baseUrl: config.baseUrl,
       token: config.token,
     });
     workspaceId = workspace.id;
+    workspaceName = workspace.name;
   } catch (error) {
     return {
       success: false,
@@ -154,6 +159,11 @@ export async function runBranchStatus(
     };
   }
 
+  // Generate dashboard URL for the branch
+  const dashboardUrl = tinybirdBranchName
+    ? getBranchDashboardUrl(config.baseUrl, workspaceName, tinybirdBranchName) ?? undefined
+    : undefined;
+
   // Check for cached token (use sanitized name)
   const cachedBranch = tinybirdBranchName ? getBranchToken(workspaceId, tinybirdBranchName) : null;
   const hasCachedToken = cachedBranch !== null;
@@ -166,6 +176,7 @@ export async function runBranchStatus(
       tinybirdBranchName,
       isMainBranch,
       hasCachedToken,
+      dashboardUrl,
     };
   }
 
@@ -186,6 +197,7 @@ export async function runBranchStatus(
       isMainBranch,
       tinybirdBranch,
       hasCachedToken,
+      dashboardUrl,
     };
   } catch (error) {
     // If 404, branch doesn't exist yet
@@ -196,6 +208,7 @@ export async function runBranchStatus(
         tinybirdBranchName,
         isMainBranch,
         hasCachedToken,
+        dashboardUrl,
       };
     }
 
@@ -205,6 +218,7 @@ export async function runBranchStatus(
       tinybirdBranchName,
       isMainBranch,
       hasCachedToken,
+      dashboardUrl,
       error: (error as Error).message,
     };
   }

package/src/cli/commands/build.ts

@@ -12,6 +12,8 @@ import {
   getLocalWorkspaceName,
   LocalNotRunningError,
 } from "../../api/local.js";
+import { getWorkspace } from "../../api/workspaces.js";
+import { getBranchDashboardUrl, getLocalDashboardUrl } from "../../api/dashboard.js";
 
 /**
  * Build command options
@@ -27,6 +29,22 @@ export interface BuildCommandOptions {
   devModeOverride?: DevMode;
 }
 
+/**
+ * Branch info included in build result
+ */
+export interface BuildBranchInfo {
+  /** Git branch name */
+  gitBranch: string | null;
+  /** Tinybird branch name */
+  tinybirdBranch: string | null;
+  /** Whether the branch was newly created */
+  wasCreated: boolean;
+  /** Dashboard URL for the branch */
+  dashboardUrl?: string;
+  /** Whether using local mode */
+  isLocal: boolean;
+}
+
 /**
  * Build command result
  */
@@ -37,6 +55,8 @@ export interface BuildCommandResult {
   build?: BuildFromIncludeResult;
   /** Build API result (if not dry run) */
   deploy?: BuildApiResult;
+  /** Branch info (when building to a branch) */
+  branchInfo?: BuildBranchInfo;
   /** Error message if failed */
   error?: string;
   /** Duration in milliseconds */
@@ -101,6 +121,7 @@ export async function runBuild(options: BuildCommandOptions = {}): Promise<Build
   }
 
   let deployResult: BuildApiResult;
+  let branchInfo: BuildBranchInfo | undefined;
 
   // Handle local mode
   if (devMode === "local") {
@@ -123,6 +144,14 @@ export async function runBuild(options: BuildCommandOptions = {}): Promise<Build
         console.log(`[debug] Workspace ${wasCreated ? "created" : "found"}: ${workspace.name}`);
       }
 
+      branchInfo = {
+        gitBranch: config.gitBranch,
+        tinybirdBranch: workspaceName,
+        wasCreated,
+        dashboardUrl: getLocalDashboardUrl(workspaceName),
+        isLocal: true,
+      };
+
       // Always use /v1/build for local (no deploy endpoint)
       deployResult = await buildToTinybird(
         {
@@ -197,6 +226,21 @@ export async function runBuild(options: BuildCommandOptions = {}): Promise<Build
         if (debug) {
           console.log(`[debug] Using branch token for branch: ${config.tinybirdBranch}`);
         }
+
+        // Get workspace name for dashboard URL
+        const workspace = await getWorkspace({
+          baseUrl: config.baseUrl,
+          token: config.token,
+        });
+        const dashboardUrl = getBranchDashboardUrl(config.baseUrl, workspace.name, config.tinybirdBranch!) ?? undefined;
+
+        branchInfo = {
+          gitBranch: config.gitBranch,
+          tinybirdBranch: config.tinybirdBranch,
+          wasCreated: tinybirdBranch.wasCreated ?? false,
+          dashboardUrl,
+          isLocal: false,
+        };
       } catch (error) {
         return {
           success: false,
@@ -231,6 +275,7 @@ export async function runBuild(options: BuildCommandOptions = {}): Promise<Build
       success: false,
       build: buildResult,
       deploy: deployResult,
+      branchInfo,
       error: deployResult.error,
       durationMs: Date.now() - startTime,
     };
@@ -240,6 +285,7 @@ export async function runBuild(options: BuildCommandOptions = {}): Promise<Build
     success: true,
     build: buildResult,
     deploy: deployResult,
+    branchInfo,
     durationMs: Date.now() - startTime,
   };
 }

package/src/cli/commands/dev.ts

@@ -4,7 +4,16 @@
 
 import * as path from "path";
 import { watch } from "chokidar";
-import { loadConfig, configExists, findConfigFile, hasValidToken, updateConfig, LOCAL_BASE_URL, type ResolvedConfig, type DevMode } from "../config.js";
+import {
+  loadConfig,
+  configExists,
+  findConfigFile,
+  hasValidToken,
+  updateConfig,
+  LOCAL_BASE_URL,
+  type ResolvedConfig,
+  type DevMode,
+} from "../config.js";
 import { runBuild, type BuildCommandResult } from "./build.js";
 import { getOrCreateBranch, type TinybirdBranch } from "../../api/branches.js";
 import { browserLogin } from "../auth.js";
@@ -19,6 +28,8 @@ import {
   getLocalWorkspaceName,
   type LocalWorkspace,
 } from "../../api/local.js";
+import { getWorkspace } from "../../api/workspaces.js";
+import { getBranchDashboardUrl, getLocalDashboardUrl } from "../../api/dashboard.js";
 
 /**
  * Login result info
@@ -70,6 +81,8 @@ export interface BranchReadyInfo {
   isLocal?: boolean;
   /** Local workspace info (only in local mode) */
   localWorkspace?: LocalWorkspace;
+  /** Dashboard URL for the branch (only in branch mode) */
+  dashboardUrl?: string;
 }
 
 /**
@@ -99,7 +112,9 @@ export interface DevController {
  * @param options - Dev options
  * @returns Dev controller
  */
-export async function runDev(options: DevCommandOptions = {}): Promise<DevController> {
+export async function runDev(
+  options: DevCommandOptions = {}
+): Promise<DevController> {
   const cwd = options.cwd ?? process.cwd();
   const debounceMs = options.debounce ?? 100;
 
@@ -129,7 +144,8 @@ export async function runDev(options: DevCommandOptions = {}): Promise<DevContro
 
     if (!authResult.success || !authResult.token) {
       throw new Error(
-        authResult.error ?? "Login failed. Run 'npx tinybird login' to authenticate."
+        authResult.error ??
+          "Login failed. Run 'npx tinybird login' to authenticate."
       );
     }
 
@@ -173,8 +189,14 @@ export async function runDev(options: DevCommandOptions = {}): Promise<DevContro
   if (devMode === "local") {
     // Local mode: get tokens from local container and set up workspace
     const localTokens = await getLocalTokens();
-    const workspaceName = getLocalWorkspaceName(config.tinybirdBranch, config.cwd);
-    const { workspace, wasCreated } = await getOrCreateLocalWorkspace(localTokens, workspaceName);
+    const workspaceName = getLocalWorkspaceName(
+      config.tinybirdBranch,
+      config.cwd
+    );
+    const { workspace, wasCreated } = await getOrCreateLocalWorkspace(
+      localTokens,
+      workspaceName
+    );
 
     effectiveToken = workspace.token;
     effectiveBaseUrl = LOCAL_BASE_URL;
@@ -184,6 +206,7 @@ export async function runDev(options: DevCommandOptions = {}): Promise<DevContro
       isLocal: true,
       localWorkspace: workspace,
       wasCreated,
+      dashboardUrl: getLocalDashboardUrl(workspace.name),
     };
   } else {
     // Branch mode: use Tinybird cloud with branches
@@ -216,11 +239,22 @@ export async function runDev(options: DevCommandOptions = {}): Promise<DevContro
       }
 
       effectiveToken = tinybirdBranch.token;
+
+      // Get workspace name for dashboard URL
+      const workspace = await getWorkspace({
+        baseUrl: config.baseUrl,
+        token: config.token,
+      });
+      const dashboardUrl =
+        getBranchDashboardUrl(config.baseUrl, workspace.name, branchName) ??
+        undefined;
+
       branchInfo = {
         gitBranch: config.gitBranch, // Original git branch name for display
         isMainBranch: false,
         tinybirdBranch,
         wasCreated: tinybirdBranch.wasCreated ?? false,
+        dashboardUrl,
       };
     }
   }
@@ -246,7 +280,11 @@ export async function runDev(options: DevCommandOptions = {}): Promise<DevContro
   async function doBuild(): Promise<BuildCommandResult> {
     if (isBuilding) {
       pendingBuild = true;
-      return { success: false, error: "Build already in progress", durationMs: 0 };
+      return {
+        success: false,
+        error: "Build already in progress",
+        durationMs: 0,
+      };
     }
 
     isBuilding = true;
@@ -357,7 +395,9 @@ export async function runDev(options: DevCommandOptions = {}): Promise<DevContro
   });
 
   watcher.on("error", (error: unknown) => {
-    options.onError?.(error instanceof Error ? error : new Error(String(error)));
+    options.onError?.(
+      error instanceof Error ? error : new Error(String(error))
+    );
   });
 
   // Do initial build

package/src/cli/index.ts

@@ -188,15 +188,19 @@ function createCli(): Command {
         devModeOverride = "local";
       }
 
-      const modeLabel = devModeOverride === "local" ? " (local)" : "";
-      output.highlight(`Building${modeLabel}...`);
-
       const result = await runBuild({
         dryRun: options.dryRun,
         devModeOverride,
       });
 
-      const { build, deploy } = result;
+      const { build, deploy, branchInfo } = result;
+
+      // Show branch info
+      if (branchInfo) {
+        output.showBranchInfo(branchInfo);
+      }
+
+      output.highlight("Building...");
 
       if (!result.success) {
         // Show detailed errors if available
@@ -486,32 +490,23 @@ function createCli(): Command {
           },
           onBranchReady: (info) => {
             if (info.isLocal) {
-              // Local mode
-              const workspaceName = info.localWorkspace?.name ?? "unknown";
-              if (info.wasCreated) {
-                console.log(`Using local Tinybird container`);
-                console.log(`Creating local workspace '${workspaceName}'...`);
-                console.log("Workspace created.\n");
-              } else {
-                console.log(`Using local Tinybird container`);
-                console.log(
-                  `Using existing local workspace '${workspaceName}'\n`
-                );
-              }
+              output.showBranchInfo({
+                gitBranch: info.gitBranch,
+                tinybirdBranch: info.localWorkspace?.name ?? null,
+                wasCreated: info.wasCreated ?? false,
+                dashboardUrl: info.dashboardUrl,
+                isLocal: true,
+              });
             } else if (info.isMainBranch) {
               console.log("On main branch - deploying to workspace\n");
             } else if (info.gitBranch) {
-              const tinybirdName = info.tinybirdBranch?.name ?? info.gitBranch;
-              if (info.wasCreated) {
-                console.log(`Detected git branch: ${info.gitBranch}`);
-                console.log(`Creating Tinybird branch '${tinybirdName}'...`);
-                console.log("Branch created and token cached.\n");
-              } else {
-                console.log(`Detected git branch: ${info.gitBranch}`);
-                console.log(
-                  `Using existing Tinybird branch '${tinybirdName}'\n`
-                );
-              }
+              output.showBranchInfo({
+                gitBranch: info.gitBranch,
+                tinybirdBranch: info.tinybirdBranch?.name ?? null,
+                wasCreated: info.wasCreated ?? false,
+                dashboardUrl: info.dashboardUrl,
+                isLocal: false,
+              });
             } else {
               console.log("Not in a git repository - deploying to workspace\n");
             }
@@ -659,6 +654,9 @@ function createCli(): Command {
         console.log(`  Tinybird branch: ${result.tinybirdBranch.name}`);
         console.log(`  Branch ID: ${result.tinybirdBranch.id}`);
         console.log(`  Created: ${result.tinybirdBranch.created_at}`);
+        if (result.dashboardUrl) {
+          console.log(`  Dashboard: ${result.dashboardUrl}`);
+        }
       } else if (!result.isMainBranch && result.tinybirdBranchName) {
         console.log("  Tinybird branch: not created yet");
         console.log("  (Run 'npx tinybird dev' to create it)");

package/src/cli/output.ts

@@ -239,6 +239,59 @@ export function showDeployFailure(): void {
   error(`\n✗ Deploy failed`);
 }
 
+/**
+ * Branch info for display
+ */
+export interface BranchDisplayInfo {
+  /** Git branch name */
+  gitBranch: string | null;
+  /** Tinybird branch name */
+  tinybirdBranch: string | null;
+  /** Whether the branch was newly created */
+  wasCreated: boolean;
+  /** Dashboard URL for the branch */
+  dashboardUrl?: string;
+  /** Whether using local mode */
+  isLocal?: boolean;
+}
+
+/**
+ * Show branch information in a compact, styled format
+ */
+export function showBranchInfo(info: BranchDisplayInfo): void {
+  const status = info.wasCreated
+    ? colorize("✓ created", "green")
+    : colorize("existing", "gray");
+
+  if (info.isLocal) {
+    // Show git branch
+    if (info.gitBranch) {
+      console.log(`» Git branch:      ${info.gitBranch}`);
+    }
+    // Show local workspace
+    const name = info.tinybirdBranch ?? "unknown";
+    console.log(`» Local workspace: ${name} ${status}`);
+    // Show dashboard URL
+    if (info.dashboardUrl) {
+      console.log(colorize(`  ↳ ${info.dashboardUrl}`, "gray"));
+    }
+  } else {
+    // Show git branch
+    if (info.gitBranch) {
+      console.log(`» Git branch:      ${info.gitBranch}`);
+    }
+    // Show Tinybird branch
+    if (info.tinybirdBranch) {
+      console.log(`» Tinybird branch: ${info.tinybirdBranch} ${status}`);
+    }
+    // Show dashboard URL
+    if (info.dashboardUrl) {
+      console.log(colorize(`  ↳ ${info.dashboardUrl}`, "gray"));
+    }
+  }
+  console.log("");
+}
+
 /**
  * Output object containing all output functions
  */
@@ -265,4 +318,5 @@ export const output = {
   showValidatingDeployment,
   showDeploySuccess,
   showDeployFailure,
+  showBranchInfo,
 };

package/src/index.ts

@@ -235,3 +235,12 @@ export {
   resolveToken,
   clearTokenCache,
 } from "./client/preview.js";
+
+// ============ Dashboard URL Utilities ============
+export {
+  parseApiUrl,
+  getDashboardUrl,
+  getBranchDashboardUrl,
+  getLocalDashboardUrl,
+} from "./api/dashboard.js";
+export type { RegionInfo } from "./api/dashboard.js";