@tinybirdco/sdk 0.0.19 → 0.0.21

package/src/api/api.ts

@@ -0,0 +1,345 @@
+import { createTinybirdFetcher, type TinybirdFetch } from "./fetcher.js";
+import type {
+  IngestOptions,
+  IngestResult,
+  QueryOptions,
+  QueryResult,
+  TinybirdErrorResponse,
+} from "../client/types.js";
+
+const DEFAULT_TIMEOUT = 30000;
+
+/**
+ * Public, decoupled Tinybird API wrapper configuration
+ */
+export interface TinybirdApiConfig {
+  /** Tinybird API base URL (e.g. https://api.tinybird.co) */
+  baseUrl: string;
+  /** Tinybird token used for Authorization bearer header */
+  token: string;
+  /** Custom fetch implementation (optional) */
+  fetch?: typeof fetch;
+  /** Default timeout in milliseconds (optional) */
+  timeout?: number;
+}
+
+/**
+ * Request options for the API layer
+ */
+export interface TinybirdApiRequestInit extends RequestInit {
+  /** Optional token override for a specific request */
+  token?: string;
+}
+
+export interface TinybirdApiQueryOptions extends QueryOptions {
+  /** Optional token override for this request */
+  token?: string;
+}
+
+export interface TinybirdApiIngestOptions extends IngestOptions {
+  /** Optional token override for this request */
+  token?: string;
+}
+
+/**
+ * Error thrown by TinybirdApi when a response is not OK
+ */
+export class TinybirdApiError extends Error {
+  readonly statusCode: number;
+  readonly responseBody?: string;
+  readonly response?: TinybirdErrorResponse;
+
+  constructor(
+    message: string,
+    statusCode: number,
+    responseBody?: string,
+    response?: TinybirdErrorResponse
+  ) {
+    super(message);
+    this.name = "TinybirdApiError";
+    this.statusCode = statusCode;
+    this.responseBody = responseBody;
+    this.response = response;
+  }
+}
+
+/**
+ * Low-level Tinybird API wrapper.
+ *
+ * This layer is intentionally decoupled from the typed TinybirdClient layer
+ * so it can be used standalone with just baseUrl + token.
+ */
+export class TinybirdApi {
+  private readonly config: TinybirdApiConfig;
+  private readonly baseUrl: string;
+  private readonly defaultToken: string;
+  private readonly fetchFn: TinybirdFetch;
+
+  constructor(config: TinybirdApiConfig) {
+    if (!config.baseUrl) {
+      throw new Error("baseUrl is required");
+    }
+
+    if (!config.token) {
+      throw new Error("token is required");
+    }
+
+    this.config = config;
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.defaultToken = config.token;
+    this.fetchFn = createTinybirdFetcher(config.fetch ?? globalThis.fetch);
+  }
+
+  /**
+   * Execute a request against Tinybird API.
+   */
+  request(path: string, init: TinybirdApiRequestInit = {}): Promise<Response> {
+    const { token, headers, ...requestInit } = init;
+    const authToken = token ?? this.defaultToken;
+    const requestHeaders = new Headers(headers);
+
+    if (!requestHeaders.has("Authorization")) {
+      requestHeaders.set("Authorization", `Bearer ${authToken}`);
+    }
+
+    return this.fetchFn(this.resolveUrl(path), {
+      ...requestInit,
+      headers: requestHeaders,
+    });
+  }
+
+  /**
+   * Execute a request and parse JSON response.
+   */
+  async requestJson<T = unknown>(
+    path: string,
+    init: TinybirdApiRequestInit = {}
+  ): Promise<T> {
+    const response = await this.request(path, init);
+
+    if (!response.ok) {
+      await this.handleErrorResponse(response);
+    }
+
+    return (await response.json()) as T;
+  }
+
+  /**
+   * Query a Tinybird endpoint
+   */
+  async query<T = unknown, P extends Record<string, unknown> = Record<string, unknown>>(
+    endpointName: string,
+    params: P = {} as P,
+    options: TinybirdApiQueryOptions = {}
+  ): Promise<QueryResult<T>> {
+    const url = new URL(`/v0/pipes/${endpointName}.json`, `${this.baseUrl}/`);
+
+    for (const [key, value] of Object.entries(params)) {
+      if (value === undefined || value === null) {
+        continue;
+      }
+
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          url.searchParams.append(key, String(item));
+        }
+        continue;
+      }
+
+      if (value instanceof Date) {
+        url.searchParams.set(key, value.toISOString());
+        continue;
+      }
+
+      url.searchParams.set(key, String(value));
+    }
+
+    const response = await this.request(url.toString(), {
+      method: "GET",
+      token: options.token,
+      signal: this.createAbortSignal(options.timeout, options.signal),
+    });
+
+    if (!response.ok) {
+      await this.handleErrorResponse(response);
+    }
+
+    return (await response.json()) as QueryResult<T>;
+  }
+
+  /**
+   * Ingest a single row into a datasource
+   */
+  async ingest<T extends Record<string, unknown>>(
+    datasourceName: string,
+    event: T,
+    options: TinybirdApiIngestOptions = {}
+  ): Promise<IngestResult> {
+    return this.ingestBatch(datasourceName, [event], options);
+  }
+
+  /**
+   * Ingest a batch of rows into a datasource
+   */
+  async ingestBatch<T extends Record<string, unknown>>(
+    datasourceName: string,
+    events: T[],
+    options: TinybirdApiIngestOptions = {}
+  ): Promise<IngestResult> {
+    if (events.length === 0) {
+      return { successful_rows: 0, quarantined_rows: 0 };
+    }
+
+    const url = new URL("/v0/events", `${this.baseUrl}/`);
+    url.searchParams.set("name", datasourceName);
+
+    if (options.wait !== false) {
+      url.searchParams.set("wait", "true");
+    }
+
+    const ndjson = events
+      .map((event) => JSON.stringify(this.serializeEvent(event)))
+      .join("\n");
+
+    const response = await this.request(url.toString(), {
+      method: "POST",
+      token: options.token,
+      headers: {
+        "Content-Type": "application/x-ndjson",
+      },
+      body: ndjson,
+      signal: this.createAbortSignal(options.timeout, options.signal),
+    });
+
+    if (!response.ok) {
+      await this.handleErrorResponse(response);
+    }
+
+    return (await response.json()) as IngestResult;
+  }
+
+  /**
+   * Execute raw SQL against Tinybird
+   */
+  async sql<T = unknown>(
+    sql: string,
+    options: TinybirdApiQueryOptions = {}
+  ): Promise<QueryResult<T>> {
+    const response = await this.request("/v0/sql", {
+      method: "POST",
+      token: options.token,
+      headers: {
+        "Content-Type": "text/plain",
+      },
+      body: sql,
+      signal: this.createAbortSignal(options.timeout, options.signal),
+    });
+
+    if (!response.ok) {
+      await this.handleErrorResponse(response);
+    }
+
+    return (await response.json()) as QueryResult<T>;
+  }
+
+  private createAbortSignal(
+    timeout?: number,
+    existingSignal?: AbortSignal
+  ): AbortSignal | undefined {
+    const timeoutMs = timeout ?? this.config.timeout ?? DEFAULT_TIMEOUT;
+
+    if (!timeoutMs && !existingSignal) {
+      return undefined;
+    }
+
+    if (!timeoutMs && existingSignal) {
+      return existingSignal;
+    }
+
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+
+    if (!existingSignal) {
+      return timeoutSignal;
+    }
+
+    return AbortSignal.any([timeoutSignal, existingSignal]);
+  }
+
+  private serializeEvent(
+    event: Record<string, unknown>
+  ): Record<string, unknown> {
+    const serialized: Record<string, unknown> = {};
+
+    for (const [key, value] of Object.entries(event)) {
+      serialized[key] = this.serializeValue(value);
+    }
+
+    return serialized;
+  }
+
+  private serializeValue(value: unknown): unknown {
+    if (value instanceof Date) {
+      return value.toISOString();
+    }
+
+    if (value instanceof Map) {
+      return Object.fromEntries(value);
+    }
+
+    if (typeof value === "bigint") {
+      return value.toString();
+    }
+
+    if (Array.isArray(value)) {
+      return value.map((item) => this.serializeValue(item));
+    }
+
+    if (typeof value === "object" && value !== null) {
+      return this.serializeEvent(value as Record<string, unknown>);
+    }
+
+    return value;
+  }
+
+  private async handleErrorResponse(response: Response): Promise<never> {
+    const rawBody = await response.text();
+    let errorResponse: TinybirdErrorResponse | undefined;
+
+    try {
+      errorResponse = JSON.parse(rawBody) as TinybirdErrorResponse;
+    } catch {
+      // ignore parse error and keep raw body
+    }
+
+    const message =
+      errorResponse?.error ??
+      (rawBody
+        ? `Request failed with status ${response.status}: ${rawBody}`
+        : `Request failed with status ${response.status}`);
+
+    throw new TinybirdApiError(
+      message,
+      response.status,
+      rawBody || undefined,
+      errorResponse
+    );
+  }
+
+  private resolveUrl(path: string): string {
+    return new URL(path, `${this.baseUrl}/`).toString();
+  }
+}
+
+/**
+ * Create a decoupled Tinybird API wrapper.
+ */
+export function createTinybirdApi(
+  config: TinybirdApiConfig
+): TinybirdApi {
+  return new TinybirdApi(config);
+}
+
+/**
+ * Alias for teams that prefer "wrapper" naming.
+ */
+export const createTinybirdApiWrapper = createTinybirdApi;

package/src/api/dashboard.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect } from "vitest";
+import {
+  parseApiUrl,
+  getDashboardUrl,
+  getBranchDashboardUrl,
+  getLocalDashboardUrl,
+} from "./dashboard.js";
+
+describe("parseApiUrl", () => {
+  it("parses EU GCP region", () => {
+    const result = parseApiUrl("https://api.tinybird.co");
+    expect(result).toEqual({ provider: "gcp", region: "europe-west3" });
+  });
+
+  it("parses US East GCP region", () => {
+    const result = parseApiUrl("https://api.us-east.tinybird.co");
+    expect(result).toEqual({ provider: "gcp", region: "us-east4" });
+  });
+
+  it("parses EU Central AWS region", () => {
+    const result = parseApiUrl("https://api.eu-central-1.aws.tinybird.co");
+    expect(result).toEqual({ provider: "aws", region: "eu-central-1" });
+  });
+
+  it("parses US East AWS region", () => {
+    const result = parseApiUrl("https://api.us-east-1.aws.tinybird.co");
+    expect(result).toEqual({ provider: "aws", region: "us-east-1" });
+  });
+
+  it("parses US West AWS region", () => {
+    const result = parseApiUrl("https://api.us-west-2.aws.tinybird.co");
+    expect(result).toEqual({ provider: "aws", region: "us-west-2" });
+  });
+
+  it("returns null for unknown regions", () => {
+    const result = parseApiUrl("https://api.unknown.tinybird.co");
+    expect(result).toBeNull();
+  });
+
+  it("returns null for invalid URLs", () => {
+    const result = parseApiUrl("not-a-url");
+    expect(result).toBeNull();
+  });
+
+  it("returns null for localhost", () => {
+    const result = parseApiUrl("http://localhost:7181");
+    expect(result).toBeNull();
+  });
+});
+
+describe("getDashboardUrl", () => {
+  it("generates EU GCP workspace URL", () => {
+    const result = getDashboardUrl("https://api.tinybird.co", "my_workspace");
+    expect(result).toBe("https://cloud.tinybird.co/gcp/europe-west3/my_workspace");
+  });
+
+  it("generates US East GCP workspace URL", () => {
+    const result = getDashboardUrl("https://api.us-east.tinybird.co", "my_workspace");
+    expect(result).toBe("https://cloud.tinybird.co/gcp/us-east4/my_workspace");
+  });
+
+  it("generates AWS workspace URL", () => {
+    const result = getDashboardUrl("https://api.us-west-2.aws.tinybird.co", "my_workspace");
+    expect(result).toBe("https://cloud.tinybird.co/aws/us-west-2/my_workspace");
+  });
+
+  it("returns null for unknown regions", () => {
+    const result = getDashboardUrl("https://api.unknown.tinybird.co", "my_workspace");
+    expect(result).toBeNull();
+  });
+});
+
+describe("getBranchDashboardUrl", () => {
+  it("generates EU GCP branch URL", () => {
+    const result = getBranchDashboardUrl("https://api.tinybird.co", "my_workspace", "feature_branch");
+    expect(result).toBe("https://cloud.tinybird.co/gcp/europe-west3/my_workspace~feature_branch");
+  });
+
+  it("generates US East GCP branch URL", () => {
+    const result = getBranchDashboardUrl("https://api.us-east.tinybird.co", "my_workspace", "feature_branch");
+    expect(result).toBe("https://cloud.tinybird.co/gcp/us-east4/my_workspace~feature_branch");
+  });
+
+  it("generates AWS branch URL", () => {
+    const result = getBranchDashboardUrl("https://api.us-west-2.aws.tinybird.co", "my_workspace", "my_feature");
+    expect(result).toBe("https://cloud.tinybird.co/aws/us-west-2/my_workspace~my_feature");
+  });
+
+  it("returns null for unknown regions", () => {
+    const result = getBranchDashboardUrl("https://api.unknown.tinybird.co", "my_workspace", "branch");
+    expect(result).toBeNull();
+  });
+
+  it("handles branch names with underscores", () => {
+    const result = getBranchDashboardUrl("https://api.tinybird.co", "my_workspace", "feature_with_underscores");
+    expect(result).toBe("https://cloud.tinybird.co/gcp/europe-west3/my_workspace~feature_with_underscores");
+  });
+});
+
+describe("getLocalDashboardUrl", () => {
+  it("generates local dashboard URL with default port", () => {
+    const result = getLocalDashboardUrl("my_local_workspace");
+    expect(result).toBe("https://cloud.tinybird.co/local/7181/my_local_workspace");
+  });
+
+  it("generates local dashboard URL with custom port", () => {
+    const result = getLocalDashboardUrl("my_local_workspace", 8080);
+    expect(result).toBe("https://cloud.tinybird.co/local/8080/my_local_workspace");
+  });
+
+  it("handles workspace names with underscores", () => {
+    const result = getLocalDashboardUrl("dublin_feature_branch");
+    expect(result).toBe("https://cloud.tinybird.co/local/7181/dublin_feature_branch");
+  });
+});

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,
     };
   }