@tinybirdco/sdk 0.0.20 → 0.0.22

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/client/base.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect } from "vitest";
+import { TinybirdClient, createClient } from "./base.js";
+
+describe("TinybirdClient", () => {
+  describe("constructor", () => {
+    it("throws error when baseUrl is missing", () => {
+      expect(() => new TinybirdClient({ baseUrl: "", token: "test-token" })).toThrow(
+        "baseUrl is required"
+      );
+    });
+
+    it("throws error when token is missing", () => {
+      expect(
+        () => new TinybirdClient({ baseUrl: "https://api.tinybird.co", token: "" })
+      ).toThrow("token is required");
+    });
+
+    it("creates client with valid config", () => {
+      const client = new TinybirdClient({
+        baseUrl: "https://api.tinybird.co",
+        token: "test-token",
+      });
+      expect(client).toBeInstanceOf(TinybirdClient);
+    });
+
+    it("normalizes baseUrl by removing trailing slash", async () => {
+      const client = new TinybirdClient({
+        baseUrl: "https://api.tinybird.co/",
+        token: "test-token",
+      });
+      const context = await client.getContext();
+      expect(context.baseUrl).toBe("https://api.tinybird.co");
+    });
+  });
+
+  describe("getContext", () => {
+    it("returns correct context in non-devMode", async () => {
+      const client = new TinybirdClient({
+        baseUrl: "https://api.tinybird.co",
+        token: "test-token",
+      });
+
+      const context = await client.getContext();
+
+      expect(context).toEqual({
+        token: "test-token",
+        baseUrl: "https://api.tinybird.co",
+        devMode: false,
+        isBranchToken: false,
+        branchName: null,
+      });
+    });
+
+    it("returns devMode: false when devMode is not set", async () => {
+      const client = new TinybirdClient({
+        baseUrl: "https://api.tinybird.co",
+        token: "test-token",
+      });
+
+      const context = await client.getContext();
+      expect(context.devMode).toBe(false);
+    });
+
+    it("returns isBranchToken: false when not in devMode", async () => {
+      const client = new TinybirdClient({
+        baseUrl: "https://api.tinybird.co",
+        token: "test-token",
+      });
+
+      const context = await client.getContext();
+      expect(context.isBranchToken).toBe(false);
+    });
+
+    it("returns branchName: null when not in devMode", async () => {
+      const client = new TinybirdClient({
+        baseUrl: "https://api.tinybird.co",
+        token: "test-token",
+      });
+
+      const context = await client.getContext();
+      expect(context.branchName).toBeNull();
+    });
+
+    it("caches the resolved context", async () => {
+      const client = new TinybirdClient({
+        baseUrl: "https://api.tinybird.co",
+        token: "test-token",
+      });
+
+      const context1 = await client.getContext();
+      const context2 = await client.getContext();
+
+      expect(context1).toBe(context2);
+    });
+
+    it("works with different baseUrl regions", async () => {
+      const client = new TinybirdClient({
+        baseUrl: "https://api.us-east.tinybird.co",
+        token: "us-token",
+      });
+
+      const context = await client.getContext();
+      expect(context.baseUrl).toBe("https://api.us-east.tinybird.co");
+      expect(context.token).toBe("us-token");
+    });
+  });
+
+  describe("createClient", () => {
+    it("creates a TinybirdClient instance", () => {
+      const client = createClient({
+        baseUrl: "https://api.tinybird.co",
+        token: "test-token",
+      });
+
+      expect(client).toBeInstanceOf(TinybirdClient);
+    });
+
+    it("passes config to the client correctly", async () => {
+      const client = createClient({
+        baseUrl: "https://api.tinybird.co",
+        token: "my-token",
+      });
+
+      const context = await client.getContext();
+      expect(context.token).toBe("my-token");
+      expect(context.baseUrl).toBe("https://api.tinybird.co");
+    });
+  });
+});

package/src/client/base.ts

@@ -4,6 +4,7 @@
 
 import type {
   ClientConfig,
+  ClientContext,
   QueryResult,
   IngestResult,
   QueryOptions,
@@ -52,8 +53,8 @@ interface ResolvedTokenInfo {
 export class TinybirdClient {
   private readonly config: ClientConfig;
   private readonly apisByToken = new Map<string, TinybirdApi>();
-  private tokenPromise: Promise<ResolvedTokenInfo> | null = null;
-  private resolvedToken: string | null = null;
+  private contextPromise: Promise<ClientContext> | null = null;
+  private resolvedContext: ClientContext | null = null;
 
   constructor(config: ClientConfig) {
     // Validate required config
@@ -75,31 +76,55 @@ export class TinybirdClient {
    * Get the effective token, resolving branch token in dev mode if needed
    */
   private async getToken(): Promise<string> {
+    const context = await this.resolveContext();
+    return context.token;
+  }
+
+  /**
+   * Resolve the client context, including branch token resolution in dev mode
+   * This is the single source of truth for all context data
+   */
+  private async resolveContext(): Promise<ClientContext> {
     // If already resolved, return it
-    if (this.resolvedToken) {
-      return this.resolvedToken;
+    if (this.resolvedContext) {
+      return this.resolvedContext;
     }
 
     // If not in dev mode, use the configured token
     if (!this.config.devMode) {
-      this.resolvedToken = this.config.token;
-      return this.resolvedToken;
+      this.resolvedContext = this.buildContext({
+        token: this.config.token,
+        isBranchToken: false,
+      });
+      return this.resolvedContext;
     }
 
     // In dev mode, lazily resolve the branch token
-    if (!this.tokenPromise) {
-      this.tokenPromise = this.resolveBranchToken();
+    if (!this.contextPromise) {
+      this.contextPromise = this.resolveBranchContext();
     }
 
-    const resolved = await this.tokenPromise;
-    this.resolvedToken = resolved.token;
-    return this.resolvedToken;
+    this.resolvedContext = await this.contextPromise;
+    return this.resolvedContext;
+  }
+
+  /**
+   * Build the client context from resolved token info
+   */
+  private buildContext(tokenInfo: ResolvedTokenInfo): ClientContext {
+    return {
+      token: tokenInfo.token,
+      baseUrl: this.config.baseUrl,
+      devMode: this.config.devMode ?? false,
+      isBranchToken: tokenInfo.isBranchToken,
+      branchName: tokenInfo.branchName ?? null,
+    };
   }
 
   /**
-   * Resolve the branch token in dev mode
+   * Resolve the branch context in dev mode
    */
-  private async resolveBranchToken(): Promise<ResolvedTokenInfo> {
+  private async resolveBranchContext(): Promise<ClientContext> {
     try {
       // Dynamic import to avoid circular dependencies and to keep CLI code
       // out of the client bundle when not using dev mode
@@ -110,7 +135,7 @@ export class TinybirdClient {
 
       // If on main branch, use the workspace token
       if (config.isMainBranch || !config.tinybirdBranch) {
-        return { token: this.config.token, isBranchToken: false };
+        return this.buildContext({ token: this.config.token, isBranchToken: false });
       }
 
       const branchName = config.tinybirdBranch;
@@ -123,17 +148,17 @@ export class TinybirdClient {
 
       if (!branch.token) {
         // Fall back to workspace token if no branch token
-        return { token: this.config.token, isBranchToken: false };
+        return this.buildContext({ token: this.config.token, isBranchToken: false });
       }
 
-      return {
+      return this.buildContext({
         token: branch.token,
         isBranchToken: true,
         branchName,
-      };
+      });
     } catch {
       // If anything fails, fall back to the workspace token
-      return { token: this.config.token, isBranchToken: false };
+      return this.buildContext({ token: this.config.token, isBranchToken: false });
     }
   }
 
@@ -217,6 +242,31 @@ export class TinybirdClient {
     }
   }
 
+  /**
+   * Get the current client context
+   *
+   * Returns information about the resolved configuration including the token being used,
+   * API URL, dev mode status, and branch information.
+   *
+   * @returns Client context with resolved configuration
+   *
+   * @example
+   * ```ts
+   * const client = createClient({
+   *   baseUrl: 'https://api.tinybird.co',
+   *   token: process.env.TINYBIRD_TOKEN,
+   *   devMode: true,
+   * });
+   *
+   * const context = await client.getContext();
+   * console.log(context.branchName); // 'feature_my_branch'
+   * console.log(context.isBranchToken); // true
+   * ```
+   */
+  async getContext(): Promise<ClientContext> {
+    return this.resolveContext();
+  }
+
   private getApi(token: string): TinybirdApi {
     const existing = this.apisByToken.get(token);
     if (existing) {

package/src/client/types.ts

@@ -147,6 +147,23 @@ export interface IngestOptions {
   wait?: boolean;
 }
 
+/**
+ * Client context information
+ * Contains the resolved configuration and state of the client
+ */
+export interface ClientContext {
+  /** The resolved token being used for requests (workspace or branch token) */
+  token: string;
+  /** Tinybird API base URL */
+  baseUrl: string;
+  /** Whether dev mode is enabled */
+  devMode: boolean;
+  /** Whether the resolved token is a branch token (vs workspace token) */
+  isBranchToken: boolean;
+  /** The branch name if using a branch token */
+  branchName: string | null;
+}
+
 /**
  * Base interface for typed pipe endpoints
  */

package/src/index.ts

@@ -203,6 +203,7 @@ export { TinybirdClient, createClient } from "./client/base.js";
 export { TinybirdError } from "./client/types.js";
 export type {
   ClientConfig,
+  ClientContext,
   QueryResult,
   IngestResult,
   QueryOptions,
@@ -235,3 +236,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";