@tinybirdco/sdk 0.0.19 → 0.0.21

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

@@ -8,15 +8,9 @@ import type {
   IngestResult,
   QueryOptions,
   IngestOptions,
-  TinybirdErrorResponse,
 } from "./types.js";
 import { TinybirdError } from "./types.js";
-import { createTinybirdFetcher, type TinybirdFetch } from "../api/fetcher.js";
-
-/**
- * Default timeout for requests (30 seconds)
- */
-const DEFAULT_TIMEOUT = 30000;
+import { TinybirdApi, TinybirdApiError } from "../api/api.js";
 
 /**
  * Resolved token info from dev mode
@@ -57,7 +51,7 @@ interface ResolvedTokenInfo {
  */
 export class TinybirdClient {
   private readonly config: ClientConfig;
-  private readonly fetchFn: TinybirdFetch;
+  private readonly apisByToken = new Map<string, TinybirdApi>();
   private tokenPromise: Promise<ResolvedTokenInfo> | null = null;
   private resolvedToken: string | null = null;
 
@@ -75,8 +69,6 @@ export class TinybirdClient {
       ...config,
       baseUrl: config.baseUrl.replace(/\/$/, ""),
     };
-
-    this.fetchFn = createTinybirdFetcher(config.fetch ?? globalThis.fetch);
   }
 
   /**
@@ -159,39 +151,12 @@ export class TinybirdClient {
     options: QueryOptions = {}
   ): Promise<QueryResult<T>> {
     const token = await this.getToken();
-    const url = new URL(`/v0/pipes/${pipeName}.json`, this.config.baseUrl);
-
-    // Add parameters to query string
-    for (const [key, value] of Object.entries(params)) {
-      if (value !== undefined && value !== null) {
-        if (Array.isArray(value)) {
-          // Handle array parameters
-          for (const item of value) {
-            url.searchParams.append(key, String(item));
-          }
-        } else if (value instanceof Date) {
-          // Handle Date objects
-          url.searchParams.set(key, value.toISOString());
-        } else {
-          url.searchParams.set(key, String(value));
-        }
-      }
-    }
 
-    const response = await this.fetch(url.toString(), {
-      method: "GET",
-      headers: {
-        Authorization: `Bearer ${token}`,
-      },
-      signal: this.createAbortSignal(options.timeout, options.signal),
-    });
-
-    if (!response.ok) {
-      await this.handleErrorResponse(response);
+    try {
+      return await this.getApi(token).query<T>(pipeName, params, options);
+    } catch (error) {
+      this.rethrowApiError(error);
     }
-
-    const result = (await response.json()) as QueryResult<T>;
-    return result;
   }
 
   /**
@@ -223,39 +188,13 @@ export class TinybirdClient {
     events: T[],
     options: IngestOptions = {}
   ): Promise<IngestResult> {
-    if (events.length === 0) {
-      return { successful_rows: 0, quarantined_rows: 0 };
-    }
-
     const token = await this.getToken();
-    const url = new URL("/v0/events", this.config.baseUrl);
-    url.searchParams.set("name", datasourceName);
 
-    if (options.wait !== false) {
-      url.searchParams.set("wait", "true");
-    }
-
-    // Convert events to NDJSON format
-    const ndjson = events
-      .map((event) => JSON.stringify(this.serializeEvent(event)))
-      .join("\n");
-
-    const response = await this.fetch(url.toString(), {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "Content-Type": "application/x-ndjson",
-      },
-      body: ndjson,
-      signal: this.createAbortSignal(options.timeout, options.signal),
-    });
-
-    if (!response.ok) {
-      await this.handleErrorResponse(response);
+    try {
+      return await this.getApi(token).ingestBatch(datasourceName, events, options);
+    } catch (error) {
+      this.rethrowApiError(error);
     }
-
-    const result = (await response.json()) as IngestResult;
-    return result;
   }
 
   /**
@@ -270,127 +209,41 @@ export class TinybirdClient {
     options: QueryOptions = {}
   ): Promise<QueryResult<T>> {
     const token = await this.getToken();
-    const url = new URL("/v0/sql", this.config.baseUrl);
-
-    const response = await this.fetch(url.toString(), {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "Content-Type": "text/plain",
-      },
-      body: sql,
-      signal: this.createAbortSignal(options.timeout, options.signal),
-    });
-
-    if (!response.ok) {
-      await this.handleErrorResponse(response);
-    }
-
-    const result = (await response.json()) as QueryResult<T>;
-    return result;
-  }
 
-  /**
-   * Serialize an event for ingestion, handling Date objects and other special types
-   */
-  private serializeEvent<T extends Record<string, unknown>>(
-    event: T
-  ): Record<string, unknown> {
-    const serialized: Record<string, unknown> = {};
-
-    for (const [key, value] of Object.entries(event)) {
-      if (value instanceof Date) {
-        // Convert Date to ISO string
-        serialized[key] = value.toISOString();
-      } else if (value instanceof Map) {
-        // Convert Map to object
-        serialized[key] = Object.fromEntries(value);
-      } else if (typeof value === "bigint") {
-        // Convert BigInt to string (ClickHouse will parse it)
-        serialized[key] = value.toString();
-      } else if (Array.isArray(value)) {
-        // Recursively serialize array elements
-        serialized[key] = value.map((item) =>
-          typeof item === "object" && item !== null
-            ? this.serializeEvent(item as Record<string, unknown>)
-            : item instanceof Date
-              ? item.toISOString()
-              : item
-        );
-      } else if (typeof value === "object" && value !== null) {
-        // Recursively serialize nested objects
-        serialized[key] = this.serializeEvent(value as Record<string, unknown>);
-      } else {
-        serialized[key] = value;
-      }
+    try {
+      return await this.getApi(token).sql<T>(sql, options);
+    } catch (error) {
+      this.rethrowApiError(error);
     }
-
-    return serialized;
   }
 
-  /**
-   * Create an AbortSignal with timeout
-   */
-  private createAbortSignal(
-    timeout?: number,
-    existingSignal?: AbortSignal
-  ): AbortSignal | undefined {
-    const timeoutMs = timeout ?? this.config.timeout ?? DEFAULT_TIMEOUT;
-
-    // If no timeout and no existing signal, return undefined
-    if (!timeoutMs && !existingSignal) {
-      return undefined;
-    }
-
-    // If only existing signal, return it
-    if (!timeoutMs && existingSignal) {
-      return existingSignal;
+  private getApi(token: string): TinybirdApi {
+    const existing = this.apisByToken.get(token);
+    if (existing) {
+      return existing;
     }
 
-    // Create timeout signal
-    const timeoutSignal = AbortSignal.timeout(timeoutMs);
-
-    // If only timeout, return timeout signal
-    if (!existingSignal) {
-      return timeoutSignal;
-    }
+    const api = new TinybirdApi({
+      baseUrl: this.config.baseUrl,
+      token,
+      fetch: this.config.fetch,
+      timeout: this.config.timeout,
+    });
 
-    // Combine both signals
-    return AbortSignal.any([timeoutSignal, existingSignal]);
+    this.apisByToken.set(token, api);
+    return api;
   }
 
-  /**
-   * Handle error responses from the API
-   */
-  private async handleErrorResponse(response: Response): Promise<never> {
-    let errorResponse: TinybirdErrorResponse | undefined;
-    let rawBody: string | undefined;
-
-    try {
-      rawBody = await response.text();
-      errorResponse = JSON.parse(rawBody) as TinybirdErrorResponse;
-    } catch {
-      // Failed to parse error response - include raw body in message
-      if (rawBody) {
-        throw new TinybirdError(
-          `Request failed with status ${response.status}: ${rawBody}`,
-          response.status,
-          undefined
-        );
-      }
+  private rethrowApiError(error: unknown): never {
+    if (error instanceof TinybirdApiError) {
+      throw new TinybirdError(
+        error.message,
+        error.statusCode,
+        error.response
+      );
     }
 
-    const message =
-      errorResponse?.error ?? `Request failed with status ${response.status}`;
-
-    throw new TinybirdError(message, response.status, errorResponse);
-  }
-
-  /**
-   * Internal fetch wrapper
-   */
-  private fetch(url: string, init?: RequestInit): Promise<Response> {
-    return this.fetchFn(url, init);
+    throw error;
   }
 }
 

package/src/index.ts

@@ -214,6 +214,20 @@ export type {
   TypedDatasourceIngest,
 } from "./client/types.js";
 
+// ============ Public Tinybird API ============
+export {
+  TinybirdApi,
+  TinybirdApiError,
+  createTinybirdApi,
+  createTinybirdApiWrapper,
+} from "./api/api.js";
+export type {
+  TinybirdApiConfig,
+  TinybirdApiQueryOptions,
+  TinybirdApiIngestOptions,
+  TinybirdApiRequestInit,
+} from "./api/api.js";
+
 // ============ Preview Environment ============
 export {
   isPreviewEnvironment,
@@ -221,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";