@tinybirdco/sdk 0.0.18 → 0.0.20

package/src/api/api.test.ts

@@ -0,0 +1,295 @@
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { setupServer } from "msw/node";
+import { http, HttpResponse } from "msw";
+import { createTinybirdApi } from "./api.js";
+import { TINYBIRD_FROM_PARAM } from "./fetcher.js";
+import { BASE_URL } from "../test/handlers.js";
+
+const server = setupServer();
+
+beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+
+describe("TinybirdApi", () => {
+  it("sends authorization header and from=ts-sdk param", async () => {
+    let authorizationHeader: string | null = null;
+    let fromParam: string | null = null;
+
+    server.use(
+      http.get(`${BASE_URL}/v1/workspace`, ({ request }) => {
+        authorizationHeader = request.headers.get("Authorization");
+        const url = new URL(request.url);
+        fromParam = url.searchParams.get("from");
+        return HttpResponse.json({ ok: true });
+      })
+    );
+
+    const api = createTinybirdApi({
+      baseUrl: BASE_URL,
+      token: "p.default-token",
+    });
+
+    await api.request("/v1/workspace");
+
+    expect(authorizationHeader).toBe("Bearer p.default-token");
+    expect(fromParam).toBe(TINYBIRD_FROM_PARAM);
+  });
+
+  it("resolves relative paths and preserves query params", async () => {
+    let fooParam: string | null = null;
+    let fromParam: string | null = null;
+
+    server.use(
+      http.get(`${BASE_URL}/v1/build`, ({ request }) => {
+        const url = new URL(request.url);
+        fooParam = url.searchParams.get("foo");
+        fromParam = url.searchParams.get("from");
+        return HttpResponse.json({ ok: true });
+      })
+    );
+
+    const api = createTinybirdApi({
+      baseUrl: `${BASE_URL}/`,
+      token: "p.default-token",
+    });
+
+    await api.request("v1/build?foo=bar");
+
+    expect(fooParam).toBe("bar");
+    expect(fromParam).toBe(TINYBIRD_FROM_PARAM);
+  });
+
+  it("allows per-request token override", async () => {
+    let authorizationHeader: string | null = null;
+
+    server.use(
+      http.get(`${BASE_URL}/v1/workspace`, ({ request }) => {
+        authorizationHeader = request.headers.get("Authorization");
+        return HttpResponse.json({ ok: true });
+      })
+    );
+
+    const api = createTinybirdApi({
+      baseUrl: BASE_URL,
+      token: "p.default-token",
+    });
+
+    await api.request("/v1/workspace", { token: "p.override-token" });
+
+    expect(authorizationHeader).toBe("Bearer p.override-token");
+  });
+
+  it("queries endpoint params via tinybirdApi.query", async () => {
+    let fromParam: string | null = null;
+    let startDateParam: string | null = null;
+    let limitParam: string | null = null;
+    let tagsParams: string[] = [];
+
+    server.use(
+      http.get(`${BASE_URL}/v0/pipes/top_pages.json`, ({ request }) => {
+        const url = new URL(request.url);
+        fromParam = url.searchParams.get("from");
+        startDateParam = url.searchParams.get("start_date");
+        limitParam = url.searchParams.get("limit");
+        tagsParams = url.searchParams.getAll("tags");
+
+        return HttpResponse.json({
+          data: [{ pathname: "/", views: 1 }],
+          meta: [
+            { name: "pathname", type: "String" },
+            { name: "views", type: "UInt64" },
+          ],
+          rows: 1,
+          statistics: {
+            elapsed: 0.001,
+            rows_read: 1,
+            bytes_read: 10,
+          },
+        });
+      })
+    );
+
+    const api = createTinybirdApi({
+      baseUrl: BASE_URL,
+      token: "p.default-token",
+    });
+
+    const result = await api.query<{ pathname: string; views: number }>("top_pages", {
+      start_date: new Date("2024-01-01T00:00:00.000Z"),
+      limit: 5,
+      tags: ["a", "b"],
+    });
+
+    expect(result.rows).toBe(1);
+    expect(result.data[0]).toEqual({ pathname: "/", views: 1 });
+    expect(fromParam).toBe(TINYBIRD_FROM_PARAM);
+    expect(startDateParam).toBe("2024-01-01T00:00:00.000Z");
+    expect(limitParam).toBe("5");
+    expect(tagsParams).toEqual(["a", "b"]);
+  });
+
+  it("ingests rows via tinybirdApi.ingest", async () => {
+    let datasourceName: string | null = null;
+    let waitParam: string | null = null;
+    let fromParam: string | null = null;
+    let contentType: string | null = null;
+    let parsedBody: Record<string, unknown> | null = null;
+
+    server.use(
+      http.post(`${BASE_URL}/v0/events`, async ({ request }) => {
+        const url = new URL(request.url);
+        datasourceName = url.searchParams.get("name");
+        waitParam = url.searchParams.get("wait");
+        fromParam = url.searchParams.get("from");
+        contentType = request.headers.get("content-type");
+
+        const rawBody = await request.text();
+        parsedBody = JSON.parse(rawBody);
+
+        return HttpResponse.json({
+          successful_rows: 1,
+          quarantined_rows: 0,
+        });
+      })
+    );
+
+    const api = createTinybirdApi({
+      baseUrl: BASE_URL,
+      token: "p.default-token",
+    });
+
+    const result = await api.ingest("events", {
+      timestamp: new Date("2024-01-01T00:00:00.000Z"),
+      count: 10n,
+      payload: new Map([["k", "v"]]),
+      nested: {
+        when: new Date("2024-01-02T00:00:00.000Z"),
+      },
+    });
+
+    expect(result).toEqual({ successful_rows: 1, quarantined_rows: 0 });
+    expect(datasourceName).toBe("events");
+    expect(waitParam).toBe("true");
+    expect(fromParam).toBe(TINYBIRD_FROM_PARAM);
+    expect(contentType).toBe("application/x-ndjson");
+    expect(parsedBody).toEqual({
+      timestamp: "2024-01-01T00:00:00.000Z",
+      count: "10",
+      payload: { k: "v" },
+      nested: { when: "2024-01-02T00:00:00.000Z" },
+    });
+  });
+
+  it("executes raw SQL via tinybirdApi.sql", async () => {
+    let rawSql: string | null = null;
+    let contentType: string | null = null;
+
+    server.use(
+      http.post(`${BASE_URL}/v0/sql`, async ({ request }) => {
+        contentType = request.headers.get("content-type");
+        rawSql = await request.text();
+
+        return HttpResponse.json({
+          data: [{ value: 1 }],
+          meta: [{ name: "value", type: "UInt8" }],
+          rows: 1,
+          statistics: {
+            elapsed: 0.001,
+            rows_read: 1,
+            bytes_read: 1,
+          },
+        });
+      })
+    );
+
+    const api = createTinybirdApi({
+      baseUrl: BASE_URL,
+      token: "p.default-token",
+    });
+
+    const result = await api.sql<{ value: number }>("SELECT 1 AS value");
+
+    expect(result.data[0]?.value).toBe(1);
+    expect(contentType).toBe("text/plain");
+    expect(rawSql).toBe("SELECT 1 AS value");
+  });
+
+  it("returns zero counts for empty ingest batches", async () => {
+    const api = createTinybirdApi({
+      baseUrl: BASE_URL,
+      token: "p.default-token",
+    });
+
+    const result = await api.ingestBatch("events", []);
+
+    expect(result).toEqual({ successful_rows: 0, quarantined_rows: 0 });
+  });
+
+  it("parses JSON responses", async () => {
+    server.use(
+      http.get(`${BASE_URL}/v1/workspace`, () => {
+        return HttpResponse.json({ id: "ws_123", name: "main" });
+      })
+    );
+
+    const api = createTinybirdApi({
+      baseUrl: BASE_URL,
+      token: "p.default-token",
+    });
+
+    const result = await api.requestJson<{ id: string; name: string }>("/v1/workspace");
+
+    expect(result.id).toBe("ws_123");
+    expect(result.name).toBe("main");
+  });
+
+  it("throws TinybirdApiError for non-OK responses", async () => {
+    server.use(
+      http.get(`${BASE_URL}/v1/workspace`, () => {
+        return new HttpResponse("Unauthorized", { status: 401 });
+      })
+    );
+
+    const api = createTinybirdApi({
+      baseUrl: BASE_URL,
+      token: "p.default-token",
+    });
+
+    await expect(api.requestJson("/v1/workspace")).rejects.toMatchObject({
+      name: "TinybirdApiError",
+      statusCode: 401,
+      responseBody: "Unauthorized",
+    });
+  });
+
+  it("throws TinybirdApiError with parsed API details", async () => {
+    server.use(
+      http.get(`${BASE_URL}/v0/pipes/broken.json`, () => {
+        return HttpResponse.json(
+          {
+            error: "Invalid query",
+            status: 400,
+            documentation: "https://www.tinybird.co/docs",
+          },
+          { status: 400 }
+        );
+      })
+    );
+
+    const api = createTinybirdApi({
+      baseUrl: BASE_URL,
+      token: "p.default-token",
+    });
+
+    await expect(api.query("broken")).rejects.toMatchObject({
+      name: "TinybirdApiError",
+      statusCode: 400,
+      message: "Invalid query",
+      response: {
+        error: "Invalid query",
+        status: 400,
+      },
+    });
+  });
+});

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/cli/index.ts

@@ -231,34 +231,32 @@ function createCli(): Command {
         if (deploy.result === "no_changes") {
           output.showNoChanges();
         } else {
-          // Collect all changes for table display
-          const changes: ResourceChange[] = [];
-
+          // Show datasource changes
           if (deploy.datasources) {
             for (const name of deploy.datasources.created) {
-              changes.push({ status: "new", name, type: "datasource" });
+              output.showResourceChange(`${name}.datasource`, "created");
             }
             for (const name of deploy.datasources.changed) {
-              changes.push({ status: "modified", name, type: "datasource" });
+              output.showResourceChange(`${name}.datasource`, "changed");
             }
             for (const name of deploy.datasources.deleted) {
-              changes.push({ status: "deleted", name, type: "datasource" });
+              output.showResourceChange(`${name}.datasource`, "deleted");
             }
           }
 
+          // Show pipe changes
           if (deploy.pipes) {
             for (const name of deploy.pipes.created) {
-              changes.push({ status: "new", name, type: "pipe" });
+              output.showResourceChange(`${name}.pipe`, "created");
             }
             for (const name of deploy.pipes.changed) {
-              changes.push({ status: "modified", name, type: "pipe" });
+              output.showResourceChange(`${name}.pipe`, "changed");
             }
             for (const name of deploy.pipes.deleted) {
-              changes.push({ status: "deleted", name, type: "pipe" });
+              output.showResourceChange(`${name}.pipe`, "deleted");
             }
           }
 
-          output.showChangesTable(changes);
           output.showBuildSuccess(result.durationMs);
         }
       }