@tinybirdco/sdk 0.0.19 → 0.0.20

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/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,