@tinybirdco/sdk 0.0.1

package/src/client/types.ts

@@ -0,0 +1,165 @@
+/**
+ * Client types for Tinybird API interactions
+ */
+
+/**
+ * Configuration for the Tinybird client
+ */
+export interface ClientConfig {
+  /** Tinybird API base URL (e.g., 'https://api.tinybird.co' or 'https://api.us-east.tinybird.co') */
+  baseUrl: string;
+  /** API token for authentication */
+  token: string;
+  /** Custom fetch implementation (optional, defaults to global fetch) */
+  fetch?: typeof fetch;
+  /** Default timeout in milliseconds (optional) */
+  timeout?: number;
+  /**
+   * Enable dev mode to automatically use branch tokens when on a feature branch.
+   * When enabled, the client will detect the git branch and use the corresponding
+   * Tinybird branch token instead of the workspace token.
+   */
+  devMode?: boolean;
+}
+
+/**
+ * Column metadata from query response
+ */
+export interface ColumnMeta {
+  /** Column name */
+  name: string;
+  /** Column type (Tinybird/ClickHouse type) */
+  type: string;
+}
+
+/**
+ * Query statistics from response
+ */
+export interface QueryStatistics {
+  /** Time elapsed in seconds */
+  elapsed: number;
+  /** Number of rows read */
+  rows_read: number;
+  /** Number of bytes read */
+  bytes_read: number;
+}
+
+/**
+ * Result of a query operation
+ */
+export interface QueryResult<T> {
+  /** Query result data */
+  data: T[];
+  /** Column metadata */
+  meta: ColumnMeta[];
+  /** Number of rows returned */
+  rows: number;
+  /** Query statistics */
+  statistics: QueryStatistics;
+}
+
+/**
+ * Result of an ingest operation
+ */
+export interface IngestResult {
+  /** Number of rows successfully ingested */
+  successful_rows: number;
+  /** Number of rows that failed to ingest */
+  quarantined_rows: number;
+}
+
+/**
+ * Error response from Tinybird API
+ */
+export interface TinybirdErrorResponse {
+  /** Error message */
+  error: string;
+  /** HTTP status code */
+  status?: number;
+  /** Additional error details */
+  documentation?: string;
+}
+
+/**
+ * Custom error class for Tinybird API errors
+ */
+export class TinybirdError extends Error {
+  /** HTTP status code */
+  readonly statusCode: number;
+  /** Raw error response */
+  readonly response?: TinybirdErrorResponse;
+
+  constructor(message: string, statusCode: number, response?: TinybirdErrorResponse) {
+    super(message);
+    this.name = "TinybirdError";
+    this.statusCode = statusCode;
+    this.response = response;
+  }
+
+  /**
+   * Check if this is a rate limit error
+   */
+  isRateLimitError(): boolean {
+    return this.statusCode === 429;
+  }
+
+  /**
+   * Check if this is an authentication error
+   */
+  isAuthError(): boolean {
+    return this.statusCode === 401 || this.statusCode === 403;
+  }
+
+  /**
+   * Check if this is a not found error
+   */
+  isNotFoundError(): boolean {
+    return this.statusCode === 404;
+  }
+
+  /**
+   * Check if this is a server error
+   */
+  isServerError(): boolean {
+    return this.statusCode >= 500;
+  }
+}
+
+/**
+ * Options for query requests
+ */
+export interface QueryOptions {
+  /** Request timeout in milliseconds */
+  timeout?: number;
+  /** AbortController signal for cancellation */
+  signal?: AbortSignal;
+}
+
+/**
+ * Options for ingest requests
+ */
+export interface IngestOptions {
+  /** Request timeout in milliseconds */
+  timeout?: number;
+  /** AbortController signal for cancellation */
+  signal?: AbortSignal;
+  /** Wait for the ingestion to complete before returning */
+  wait?: boolean;
+}
+
+/**
+ * Base interface for typed pipe endpoints
+ */
+export interface TypedPipeEndpoint<TParams, TOutput> {
+  (params: TParams, options?: QueryOptions): Promise<QueryResult<TOutput>>;
+}
+
+/**
+ * Base interface for typed datasource ingestion
+ */
+export interface TypedDatasourceIngest<TRow> {
+  /** Send a single event */
+  send(event: TRow, options?: IngestOptions): Promise<IngestResult>;
+  /** Send multiple events in a batch */
+  sendBatch(events: TRow[], options?: IngestOptions): Promise<IngestResult>;
+}

package/src/generator/client.ts

@@ -0,0 +1,194 @@
+/**
+ * Client file generator
+ * Generates a typed tinybird.ts client file from discovered entities
+ */
+
+import * as path from "path";
+import type { LoadedEntities } from "./loader.js";
+
+/**
+ * Options for generating the client file
+ */
+export interface GenerateClientOptions {
+  /** Loaded entities from source files */
+  entities: LoadedEntities;
+  /** Output file path (relative to cwd) */
+  outputPath: string;
+  /** Working directory */
+  cwd: string;
+}
+
+/**
+ * Result of generating the client file
+ */
+export interface GeneratedClient {
+  /** The generated file content */
+  content: string;
+  /** Absolute path to output file */
+  absolutePath: string;
+}
+
+/**
+ * Convert a file path to a relative import path
+ * e.g., "src/datasources.ts" -> "./datasources" when output is "src/tinybird.ts"
+ */
+function toRelativeImport(fromPath: string, toPath: string): string {
+  // Get directory of the from file
+  const fromDir = path.dirname(fromPath);
+
+  // Get relative path from output dir to source file
+  let relativePath = path.relative(fromDir, toPath);
+
+  // Normalize Windows separators to forward slashes for TS imports
+  relativePath = relativePath.replace(/\\/g, "/");
+
+  // Remove .ts extension
+  relativePath = relativePath.replace(/\.tsx?$/, "");
+
+  // Ensure it starts with ./ or ../
+  if (!relativePath.startsWith(".") && !relativePath.startsWith("/")) {
+    relativePath = "./" + relativePath;
+  }
+
+  return relativePath;
+}
+
+/**
+ * Convert camelCase to PascalCase
+ */
+function toPascalCase(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * Generate the client file content
+ *
+ * @param options - Generation options
+ * @returns Generated client file info
+ *
+ * @example
+ * ```ts
+ * const result = generateClientFile({
+ *   entities: loadedEntities,
+ *   outputPath: 'src/tinybird.ts',
+ *   cwd: '/path/to/project',
+ * });
+ *
+ * fs.writeFileSync(result.absolutePath, result.content);
+ * ```
+ */
+export function generateClientFile(options: GenerateClientOptions): GeneratedClient {
+  const { entities, outputPath, cwd } = options;
+  const absolutePath = path.isAbsolute(outputPath) ? outputPath : path.join(cwd, outputPath);
+
+  // Group entities by source file for imports
+  const importsByFile = new Map<string, { datasources: string[]; pipes: string[] }>();
+
+  for (const [name, { info }] of Object.entries(entities.datasources)) {
+    if (!importsByFile.has(info.sourceFile)) {
+      importsByFile.set(info.sourceFile, { datasources: [], pipes: [] });
+    }
+    importsByFile.get(info.sourceFile)!.datasources.push(name);
+  }
+
+  for (const [name, { info }] of Object.entries(entities.pipes)) {
+    if (!importsByFile.has(info.sourceFile)) {
+      importsByFile.set(info.sourceFile, { datasources: [], pipes: [] });
+    }
+    importsByFile.get(info.sourceFile)!.pipes.push(name);
+  }
+
+  // Build import statements
+  const importLines: string[] = [];
+  const reexportLines: string[] = [];
+
+  // SDK imports
+  const sdkTypes = ["InferRow"];
+  if (Object.keys(entities.pipes).length > 0) {
+    sdkTypes.push("InferParams", "InferOutputRow");
+  }
+  importLines.push(
+    `import { createTinybirdClient, type ${sdkTypes.join(", type ")} } from "@tinybirdco/sdk";`
+  );
+  importLines.push("");
+
+  // Entity imports and re-exports
+  for (const [sourceFile, { datasources, pipes }] of importsByFile) {
+    const allExports = [...datasources, ...pipes];
+    if (allExports.length === 0) continue;
+
+    // Resolve to absolute paths for correct relative path calculation
+    const sourceAbsolute = path.isAbsolute(sourceFile) ? sourceFile : path.join(cwd, sourceFile);
+    const relativePath = toRelativeImport(absolutePath, sourceAbsolute);
+    importLines.push(`import { ${allExports.join(", ")} } from "${relativePath}";`);
+    reexportLines.push(`export { ${allExports.join(", ")} } from "${relativePath}";`);
+  }
+
+  // Build createTinybirdClient call
+  const datasourceNames = Object.keys(entities.datasources);
+  const pipeNames = Object.keys(entities.pipes);
+
+  const clientLines: string[] = [];
+  clientLines.push("export const tinybird = createTinybirdClient({");
+
+  if (datasourceNames.length > 0) {
+    clientLines.push(`  datasources: { ${datasourceNames.join(", ")} },`);
+  } else {
+    clientLines.push("  datasources: {},");
+  }
+
+  if (pipeNames.length > 0) {
+    clientLines.push(`  pipes: { ${pipeNames.join(", ")} },`);
+  } else {
+    clientLines.push("  pipes: {},");
+  }
+
+  clientLines.push("});");
+
+  // Build type exports
+  const typeLines: string[] = [];
+
+  for (const name of datasourceNames) {
+    const pascalName = toPascalCase(name);
+    typeLines.push(`export type ${pascalName}Row = InferRow<typeof ${name}>;`);
+  }
+
+  for (const name of pipeNames) {
+    const { definition } = entities.pipes[name];
+    const pascalName = toPascalCase(name);
+    typeLines.push(`export type ${pascalName}Params = InferParams<typeof ${name}>;`);
+    // Only generate Output type for pipes with output schema
+    if (definition._output) {
+      typeLines.push(`export type ${pascalName}Output = InferOutputRow<typeof ${name}>;`);
+    }
+  }
+
+  // Combine all sections
+  const sections: string[] = [
+    "// Auto-generated by @tinybirdco/sdk - DO NOT EDIT",
+    "// This file is regenerated on every build. Manual changes will be overwritten.",
+    "",
+    importLines.join("\n"),
+    "",
+    "// Typed Tinybird client",
+    clientLines.join("\n"),
+    "",
+    "// Re-export entities for convenience",
+    reexportLines.join("\n"),
+  ];
+
+  if (typeLines.length > 0) {
+    sections.push("");
+    sections.push("// Inferred types from entity definitions");
+    sections.push(typeLines.join("\n"));
+  }
+
+  sections.push(""); // Trailing newline
+
+  const content = sections.join("\n");
+
+  return {
+    content,
+    absolutePath,
+  };
+}

package/src/generator/datasource.test.ts

@@ -0,0 +1,297 @@
+import { describe, it, expect } from 'vitest';
+import { generateDatasource, generateAllDatasources } from './datasource.js';
+import { defineDatasource } from '../schema/datasource.js';
+import { t } from '../schema/types.js';
+import { engine } from '../schema/engines.js';
+
+describe('Datasource Generator', () => {
+  describe('generateDatasource', () => {
+    it('generates basic datasource with schema', () => {
+      const ds = defineDatasource('test_ds', {
+        schema: {
+          id: t.string(),
+          count: t.int32(),
+        },
+      });
+
+      const result = generateDatasource(ds);
+      expect(result.name).toBe('test_ds');
+      expect(result.content).toContain('SCHEMA >');
+      expect(result.content).toContain('id String');
+      expect(result.content).toContain('count Int32');
+    });
+
+    it('includes description when provided', () => {
+      const ds = defineDatasource('test_ds', {
+        description: 'Test datasource description',
+        schema: {
+          id: t.string(),
+        },
+      });
+
+      const result = generateDatasource(ds);
+      expect(result.content).toContain('DESCRIPTION >');
+      expect(result.content).toContain('Test datasource description');
+    });
+
+    it('includes engine configuration', () => {
+      const ds = defineDatasource('test_ds', {
+        schema: {
+          id: t.string(),
+        },
+        engine: engine.mergeTree({
+          sortingKey: ['id'],
+        }),
+      });
+
+      const result = generateDatasource(ds);
+      expect(result.content).toContain('ENGINE "MergeTree"');
+      expect(result.content).toContain('ENGINE_SORTING_KEY "id"');
+    });
+
+    it('includes partition key in engine config', () => {
+      const ds = defineDatasource('test_ds', {
+        schema: {
+          id: t.string(),
+          timestamp: t.dateTime(),
+        },
+        engine: engine.mergeTree({
+          sortingKey: ['id'],
+          partitionKey: 'toYYYYMM(timestamp)',
+        }),
+      });
+
+      const result = generateDatasource(ds);
+      expect(result.content).toContain('ENGINE_PARTITION_KEY "toYYYYMM(timestamp)"');
+    });
+
+    it('includes TTL in engine config', () => {
+      const ds = defineDatasource('test_ds', {
+        schema: {
+          id: t.string(),
+          timestamp: t.dateTime(),
+        },
+        engine: engine.mergeTree({
+          sortingKey: ['id'],
+          ttl: 'timestamp + INTERVAL 90 DAY',
+        }),
+      });
+
+      const result = generateDatasource(ds);
+      expect(result.content).toContain('ENGINE_TTL "timestamp + INTERVAL 90 DAY"');
+    });
+  });
+
+  describe('Column formatting', () => {
+    it('formats Nullable columns correctly', () => {
+      const ds = defineDatasource('test_ds', {
+        schema: {
+          name: t.string().nullable(),
+        },
+      });
+
+      const result = generateDatasource(ds);
+      expect(result.content).toContain('name Nullable(String)');
+    });
+
+    it('formats LowCardinality columns correctly', () => {
+      const ds = defineDatasource('test_ds', {
+        schema: {
+          country: t.string().lowCardinality(),
+        },
+      });
+
+      const result = generateDatasource(ds);
+      expect(result.content).toContain('country LowCardinality(String)');
+    });
+
+    it('formats LowCardinality(Nullable) correctly', () => {
+      const ds = defineDatasource('test_ds', {
+        schema: {
+          country: t.string().lowCardinality().nullable(),
+        },
+      });
+
+      const result = generateDatasource(ds);
+      expect(result.content).toContain('country LowCardinality(Nullable(String))');
+    });
+
+    it('includes default values', () => {
+      const ds = defineDatasource('test_ds', {
+        schema: {
+          status: t.string().default('pending'),
+        },
+      });
+
+      const result = generateDatasource(ds);
+      expect(result.content).toContain("status String `json:$.status` DEFAULT 'pending'");
+    });
+
+    it('formats null default values', () => {
+      const ds = defineDatasource('test_ds', {
+        schema: {
+          // Using nullable with explicit null default
+          status: t.string().nullable().default(null),
+        },
+      });
+
+      const result = generateDatasource(ds);
+      expect(result.content).toContain('DEFAULT NULL');
+    });
+
+    it('formats number default values', () => {
+      const ds = defineDatasource('test_ds', {
+        schema: {
+          count: t.int32().default(42),
+          score: t.float64().default(3.14),
+        },
+      });
+
+      const result = generateDatasource(ds);
+      expect(result.content).toContain('count Int32 `json:$.count` DEFAULT 42');
+      expect(result.content).toContain('score Float64 `json:$.score` DEFAULT 3.14');
+    });
+
+    it('formats boolean default values', () => {
+      const ds = defineDatasource('test_ds', {
+        schema: {
+          is_active: t.bool().default(true),
+          is_deleted: t.bool().default(false),
+        },
+      });
+
+      const result = generateDatasource(ds);
+      expect(result.content).toContain('is_active Bool `json:$.is_active` DEFAULT 1');
+      expect(result.content).toContain('is_deleted Bool `json:$.is_deleted` DEFAULT 0');
+    });
+
+    it('formats Date default values for DateTime type', () => {
+      const ds = defineDatasource('test_ds', {
+        schema: {
+          created_at: t.dateTime().default(new Date('2024-01-15T10:30:00Z')),
+        },
+      });
+
+      const result = generateDatasource(ds);
+      expect(result.content).toContain("created_at DateTime `json:$.created_at` DEFAULT '2024-01-15 10:30:00'");
+    });
+
+    it('formats Date default values for Date type', () => {
+      const ds = defineDatasource('test_ds', {
+        schema: {
+          birth_date: t.date().default(new Date('2024-01-15T10:30:00Z')),
+        },
+      });
+
+      const result = generateDatasource(ds);
+      expect(result.content).toContain("birth_date Date `json:$.birth_date` DEFAULT '2024-01-15'");
+    });
+
+    it('formats array default values', () => {
+      const ds = defineDatasource('test_ds', {
+        schema: {
+          tags: t.array(t.string()).default(['a', 'b']),
+        },
+      });
+
+      const result = generateDatasource(ds);
+      expect(result.content).toContain('tags Array(String) `json:$.tags` DEFAULT ["a","b"]');
+    });
+
+    it('formats object default values for JSON type', () => {
+      const ds = defineDatasource('test_ds', {
+        schema: {
+          metadata: t.json<{ key: string }>().default({ key: 'value' }),
+        },
+      });
+
+      const result = generateDatasource(ds);
+      expect(result.content).toContain('metadata JSON `json:$.metadata` DEFAULT {"key":"value"}');
+    });
+
+    it('escapes single quotes in string default values', () => {
+      const ds = defineDatasource('test_ds', {
+        schema: {
+          message: t.string().default("it's working"),
+        },
+      });
+
+      const result = generateDatasource(ds);
+      expect(result.content).toContain("message String `json:$.message` DEFAULT 'it\\'s working'");
+    });
+
+    it('includes codec', () => {
+      const ds = defineDatasource('test_ds', {
+        schema: {
+          data: t.string().codec('LZ4'),
+        },
+      });
+
+      const result = generateDatasource(ds);
+      expect(result.content).toContain('data String `json:$.data` CODEC(LZ4)');
+    });
+
+    it('adds commas between columns except last', () => {
+      const ds = defineDatasource('test_ds', {
+        schema: {
+          id: t.string(),
+          name: t.string(),
+          count: t.int32(),
+        },
+      });
+
+      const result = generateDatasource(ds);
+      const lines = result.content.split('\n');
+      const schemaLines = lines.filter(l => l.trim().startsWith('id') || l.trim().startsWith('name') || l.trim().startsWith('count'));
+
+      expect(schemaLines[0]).toContain(',');
+      expect(schemaLines[1]).toContain(',');
+      expect(schemaLines[2]).not.toContain(',');
+    });
+  });
+
+  describe('generateAllDatasources', () => {
+    it('generates all datasources', () => {
+      const ds1 = defineDatasource('ds1', { schema: { id: t.string() } });
+      const ds2 = defineDatasource('ds2', { schema: { id: t.int32() } });
+
+      const results = generateAllDatasources({ ds1, ds2 });
+      expect(results).toHaveLength(2);
+      expect(results.map(r => r.name).sort()).toEqual(['ds1', 'ds2']);
+    });
+  });
+
+  describe('Full integration', () => {
+    it('generates complete datasource file', () => {
+      const ds = defineDatasource('page_views', {
+        description: 'Page view tracking data',
+        schema: {
+          timestamp: t.dateTime(),
+          pathname: t.string(),
+          session_id: t.string(),
+          country: t.string().lowCardinality().nullable(),
+        },
+        engine: engine.mergeTree({
+          sortingKey: ['pathname', 'timestamp'],
+          partitionKey: 'toYYYYMM(timestamp)',
+          ttl: 'timestamp + INTERVAL 90 DAY',
+        }),
+      });
+
+      const result = generateDatasource(ds);
+
+      expect(result.name).toBe('page_views');
+      expect(result.content).toContain('DESCRIPTION >');
+      expect(result.content).toContain('Page view tracking data');
+      expect(result.content).toContain('SCHEMA >');
+      expect(result.content).toContain('timestamp DateTime');
+      expect(result.content).toContain('pathname String');
+      expect(result.content).toContain('session_id String');
+      expect(result.content).toContain('country LowCardinality(Nullable(String))');
+      expect(result.content).toContain('ENGINE "MergeTree"');
+      expect(result.content).toContain('ENGINE_PARTITION_KEY "toYYYYMM(timestamp)"');
+      expect(result.content).toContain('ENGINE_SORTING_KEY "pathname, timestamp"');
+      expect(result.content).toContain('ENGINE_TTL "timestamp + INTERVAL 90 DAY"');
+    });
+  });
+});