@tinybirdco/sdk 0.0.1

package/src/schema/project.test.ts

@@ -0,0 +1,236 @@
+import { describe, it, expect } from "vitest";
+import {
+  defineProject,
+  isProjectDefinition,
+  getDatasourceNames,
+  getPipeNames,
+  getDatasource,
+  getPipe,
+} from "./project.js";
+import { defineDatasource } from "./datasource.js";
+import { definePipe, node } from "./pipe.js";
+import { t } from "./types.js";
+
+describe("Project Schema", () => {
+  describe("defineProject", () => {
+    it("creates a project with empty config", () => {
+      const project = defineProject({});
+
+      expect(project._type).toBe("project");
+      expect(project.datasources).toEqual({});
+      expect(project.pipes).toEqual({});
+    });
+
+    it("creates a project with datasources", () => {
+      const events = defineDatasource("events", {
+        schema: { id: t.string(), timestamp: t.dateTime() },
+      });
+
+      const project = defineProject({
+        datasources: { events },
+      });
+
+      expect(project.datasources.events).toBe(events);
+      expect(project.pipes).toEqual({});
+    });
+
+    it("creates a project with pipes", () => {
+      const topEvents = definePipe("top_events", {
+        nodes: [node({ name: "endpoint", sql: "SELECT 1" })],
+        output: { count: t.int64() },
+        endpoint: true,
+      });
+
+      const project = defineProject({
+        pipes: { topEvents },
+      });
+
+      expect(project.pipes.topEvents).toBe(topEvents);
+      expect(project.datasources).toEqual({});
+    });
+
+    it("creates a project with both datasources and pipes", () => {
+      const events = defineDatasource("events", {
+        schema: { id: t.string() },
+      });
+
+      const topEvents = definePipe("top_events", {
+        nodes: [node({ name: "endpoint", sql: "SELECT 1" })],
+        output: { count: t.int64() },
+        endpoint: true,
+      });
+
+      const project = defineProject({
+        datasources: { events },
+        pipes: { topEvents },
+      });
+
+      expect(project.datasources.events).toBe(events);
+      expect(project.pipes.topEvents).toBe(topEvents);
+    });
+
+    it("creates tinybird client with query and ingest methods", () => {
+      const events = defineDatasource("events", {
+        schema: { id: t.string() },
+      });
+
+      const topEvents = definePipe("top_events", {
+        nodes: [node({ name: "endpoint", sql: "SELECT 1" })],
+        output: { count: t.int64() },
+        endpoint: true,
+      });
+
+      const project = defineProject({
+        datasources: { events },
+        pipes: { topEvents },
+      });
+
+      expect(project.tinybird.query).toBeDefined();
+      expect(project.tinybird.ingest).toBeDefined();
+      expect(typeof project.tinybird.query.topEvents).toBe("function");
+      expect(typeof project.tinybird.ingest.events).toBe("function");
+      expect(typeof project.tinybird.ingest.eventsBatch).toBe("function");
+    });
+
+    it("throws error when accessing client before initialization", () => {
+      const project = defineProject({});
+
+      expect(() => project.tinybird.client).toThrow(
+        "Client not initialized"
+      );
+    });
+
+    it("creates stub for non-endpoint pipes that throws clear error", async () => {
+      const internalPipe = definePipe("internal_pipe", {
+        nodes: [node({ name: "endpoint", sql: "SELECT 1" })],
+        output: { count: t.int64() },
+        endpoint: false,
+      });
+
+      const project = defineProject({
+        pipes: { internalPipe },
+      });
+
+      // Cast to any since the type system expects params but stub throws regardless
+      const queryFn = project.tinybird.query.internalPipe as () => Promise<unknown>;
+      await expect(queryFn()).rejects.toThrow(
+        'Pipe "internalPipe" is not exposed as an endpoint'
+      );
+    });
+  });
+
+  describe("isProjectDefinition", () => {
+    it("returns true for valid project", () => {
+      const project = defineProject({});
+
+      expect(isProjectDefinition(project)).toBe(true);
+    });
+
+    it("returns false for non-project objects", () => {
+      expect(isProjectDefinition({})).toBe(false);
+      expect(isProjectDefinition(null)).toBe(false);
+      expect(isProjectDefinition(undefined)).toBe(false);
+      expect(isProjectDefinition("string")).toBe(false);
+      expect(isProjectDefinition(123)).toBe(false);
+      expect(isProjectDefinition({ _type: "project" })).toBe(false);
+    });
+  });
+
+  describe("getDatasourceNames", () => {
+    it("returns all datasource names", () => {
+      const events = defineDatasource("events", {
+        schema: { id: t.string() },
+      });
+      const users = defineDatasource("users", {
+        schema: { id: t.string() },
+      });
+
+      const project = defineProject({
+        datasources: { events, users },
+      });
+
+      const names = getDatasourceNames(project);
+
+      expect(names).toHaveLength(2);
+      expect(names).toContain("events");
+      expect(names).toContain("users");
+    });
+
+    it("returns empty array for project with no datasources", () => {
+      const project = defineProject({});
+
+      const names = getDatasourceNames(project);
+
+      expect(names).toHaveLength(0);
+    });
+  });
+
+  describe("getPipeNames", () => {
+    it("returns all pipe names", () => {
+      const topEvents = definePipe("top_events", {
+        nodes: [node({ name: "endpoint", sql: "SELECT 1" })],
+        output: { count: t.int64() },
+        endpoint: true,
+      });
+      const userActivity = definePipe("user_activity", {
+        nodes: [node({ name: "endpoint", sql: "SELECT 2" })],
+        output: { count: t.int64() },
+        endpoint: true,
+      });
+
+      const project = defineProject({
+        pipes: { topEvents, userActivity },
+      });
+
+      const names = getPipeNames(project);
+
+      expect(names).toHaveLength(2);
+      expect(names).toContain("topEvents");
+      expect(names).toContain("userActivity");
+    });
+
+    it("returns empty array for project with no pipes", () => {
+      const project = defineProject({});
+
+      const names = getPipeNames(project);
+
+      expect(names).toHaveLength(0);
+    });
+  });
+
+  describe("getDatasource", () => {
+    it("returns datasource by name", () => {
+      const events = defineDatasource("events", {
+        schema: { id: t.string() },
+      });
+
+      const project = defineProject({
+        datasources: { events },
+      });
+
+      const retrieved = getDatasource(project, "events");
+
+      expect(retrieved).toBe(events);
+      expect(retrieved._name).toBe("events");
+    });
+  });
+
+  describe("getPipe", () => {
+    it("returns pipe by name", () => {
+      const topEvents = definePipe("top_events", {
+        nodes: [node({ name: "endpoint", sql: "SELECT 1" })],
+        output: { count: t.int64() },
+        endpoint: true,
+      });
+
+      const project = defineProject({
+        pipes: { topEvents },
+      });
+
+      const retrieved = getPipe(project, "topEvents");
+
+      expect(retrieved).toBe(topEvents);
+      expect(retrieved._name).toBe("top_events");
+    });
+  });
+});

package/src/schema/project.ts

@@ -0,0 +1,394 @@
+/**
+ * Project definition for Tinybird
+ * Aggregates all datasources and pipes into a single schema
+ */
+
+import type { DatasourceDefinition, SchemaDefinition } from "./datasource.js";
+import type { PipeDefinition, ParamsDefinition, OutputDefinition } from "./pipe.js";
+import { getEndpointConfig } from "./pipe.js";
+import type { TinybirdClient } from "../client/base.js";
+import type { QueryResult } from "../client/types.js";
+import type { InferRow, InferParams, InferOutputRow } from "../infer/index.js";
+
+// Symbol for brand typing
+const PROJECT_BRAND = Symbol("tinybird.project");
+
+/**
+ * Collection of datasource definitions
+ */
+export type DatasourcesDefinition = Record<string, DatasourceDefinition<SchemaDefinition>>;
+
+/**
+ * Collection of pipe definitions
+ */
+export type PipesDefinition = Record<string, PipeDefinition<ParamsDefinition, OutputDefinition>>;
+
+/**
+ * Type for a single query method
+ */
+type QueryMethod<T extends PipeDefinition<ParamsDefinition, OutputDefinition>> =
+  T extends PipeDefinition<infer P, OutputDefinition>
+    ? keyof P extends never
+      ? () => Promise<QueryResult<InferOutputRow<T>>>
+      : (params: InferParams<T>) => Promise<QueryResult<InferOutputRow<T>>>
+    : never;
+
+/**
+ * Type for query methods object
+ * Note: At runtime, only pipes with endpoint: true are included
+ */
+type QueryMethods<T extends PipesDefinition> = {
+  [K in keyof T]: QueryMethod<T[K]>;
+};
+
+/**
+ * Type for a single ingest method
+ */
+type IngestMethod<T extends DatasourceDefinition<SchemaDefinition>> = (
+  event: InferRow<T>
+) => Promise<void>;
+
+/**
+ * Type for a batch ingest method
+ */
+type IngestBatchMethod<T extends DatasourceDefinition<SchemaDefinition>> = (
+  events: InferRow<T>[]
+) => Promise<void>;
+
+/**
+ * Type for ingest methods object
+ */
+type IngestMethods<T extends DatasourcesDefinition> = {
+  [K in keyof T]: IngestMethod<T[K]>;
+} & {
+  [K in keyof T as `${K & string}Batch`]: IngestBatchMethod<T[K]>;
+};
+
+/**
+ * Typed client interface for a project
+ */
+export interface ProjectClient<
+  TDatasources extends DatasourcesDefinition,
+  TPipes extends PipesDefinition
+> {
+  /** Query endpoint pipes */
+  query: QueryMethods<TPipes>;
+  /** Ingest events to datasources */
+  ingest: IngestMethods<TDatasources>;
+  /** Raw client for advanced usage */
+  readonly client: TinybirdClient;
+}
+
+/**
+ * Configuration for createTinybirdClient
+ */
+export interface TinybirdClientConfig<
+  TDatasources extends DatasourcesDefinition = DatasourcesDefinition,
+  TPipes extends PipesDefinition = PipesDefinition
+> {
+  /** All datasources */
+  datasources: TDatasources;
+  /** All pipes */
+  pipes: TPipes;
+  /** Tinybird API base URL (defaults to TINYBIRD_URL env var or https://api.tinybird.co) */
+  baseUrl?: string;
+  /** Tinybird API token (defaults to TINYBIRD_TOKEN env var) */
+  token?: string;
+}
+
+/**
+ * Project configuration
+ */
+export interface ProjectConfig<
+  TDatasources extends DatasourcesDefinition = DatasourcesDefinition,
+  TPipes extends PipesDefinition = PipesDefinition
+> {
+  /** All datasources in this project */
+  datasources?: TDatasources;
+  /** All pipes in this project */
+  pipes?: TPipes;
+}
+
+/**
+ * A project definition with full type information
+ */
+export interface ProjectDefinition<
+  TDatasources extends DatasourcesDefinition = DatasourcesDefinition,
+  TPipes extends PipesDefinition = PipesDefinition
+> {
+  readonly [PROJECT_BRAND]: true;
+  /** Type marker for inference */
+  readonly _type: "project";
+  /** All datasources */
+  readonly datasources: TDatasources;
+  /** All pipes */
+  readonly pipes: TPipes;
+  /** Typed Tinybird client */
+  readonly tinybird: ProjectClient<TDatasources, TPipes>;
+}
+
+/**
+ * Define a Tinybird project
+ *
+ * This aggregates all datasources and pipes into a single schema definition
+ * that can be used for code generation and type inference.
+ *
+ * @param config - Project configuration with datasources and pipes
+ * @returns A project definition
+ *
+ * @example
+ * ```ts
+ * // tinybird/schema.ts
+ * import { defineProject } from '@tinybirdco/sdk';
+ * import { events, users } from './datasources';
+ * import { topEvents, userActivity } from './pipes';
+ *
+ * export default defineProject({
+ *   datasources: {
+ *     events,
+ *     users,
+ *   },
+ *   pipes: {
+ *     topEvents,
+ *     userActivity,
+ *   },
+ * });
+ * ```
+ */
+export function defineProject<
+  TDatasources extends DatasourcesDefinition,
+  TPipes extends PipesDefinition
+>(
+  config: ProjectConfig<TDatasources, TPipes>
+): ProjectDefinition<TDatasources, TPipes> {
+  const datasources = (config.datasources ?? {}) as TDatasources;
+  const pipes = (config.pipes ?? {}) as TPipes;
+
+  // Use the shared client builder
+  const tinybird = buildProjectClient(datasources, pipes);
+
+  return {
+    [PROJECT_BRAND]: true,
+    _type: "project",
+    datasources,
+    pipes,
+    tinybird,
+  };
+}
+
+/**
+ * Check if a value is a project definition
+ */
+export function isProjectDefinition(value: unknown): value is ProjectDefinition {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    PROJECT_BRAND in value &&
+    (value as Record<symbol, unknown>)[PROJECT_BRAND] === true
+  );
+}
+
+/**
+ * Build a typed Tinybird client from datasources and pipes
+ *
+ * This is an internal helper that builds query/ingest methods.
+ */
+function buildProjectClient<
+  TDatasources extends DatasourcesDefinition,
+  TPipes extends PipesDefinition
+>(
+  datasources: TDatasources,
+  pipes: TPipes,
+  options?: { baseUrl?: string; token?: string }
+): ProjectClient<TDatasources, TPipes> {
+  // Lazy client initialization
+  let _client: TinybirdClient | null = null;
+
+  const getClient = async (): Promise<TinybirdClient> => {
+    if (!_client) {
+      // Dynamic import to avoid circular dependencies
+      const { createClient } = await import("../client/base.js");
+      _client = createClient({
+        baseUrl: options?.baseUrl ?? process.env.TINYBIRD_URL ?? "https://api.tinybird.co",
+        token: options?.token ?? process.env.TINYBIRD_TOKEN!,
+        devMode: process.env.NODE_ENV === "development",
+      });
+    }
+    return _client;
+  };
+
+  // Build query methods for pipes
+  const queryMethods: Record<string, (params?: unknown) => Promise<unknown>> = {};
+  for (const [name, pipe] of Object.entries(pipes)) {
+    const endpointConfig = getEndpointConfig(pipe);
+
+    if (!endpointConfig) {
+      // Non-endpoint pipes get a stub that throws a clear error
+      queryMethods[name] = async () => {
+        throw new Error(
+          `Pipe "${name}" is not exposed as an endpoint. ` +
+            `Set "endpoint: true" in the pipe definition to enable querying.`
+        );
+      };
+      continue;
+    }
+
+    // Use the Tinybird pipe name (snake_case)
+    const tinybirdName = pipe._name;
+    queryMethods[name] = async (params?: unknown) => {
+      const client = await getClient();
+      return client.query(tinybirdName, (params ?? {}) as Record<string, unknown>);
+    };
+  }
+
+  // Build ingest methods for datasources
+  const ingestMethods: Record<string, (data: unknown) => Promise<void>> = {};
+  for (const [name, datasource] of Object.entries(datasources)) {
+    // Use the Tinybird datasource name (snake_case)
+    const tinybirdName = datasource._name;
+
+    // Single event ingest
+    ingestMethods[name] = async (event: unknown) => {
+      const client = await getClient();
+      await client.ingest(tinybirdName, event as Record<string, unknown>);
+    };
+
+    // Batch ingest
+    ingestMethods[`${name}Batch`] = async (events: unknown) => {
+      const client = await getClient();
+      await client.ingestBatch(tinybirdName, events as Record<string, unknown>[]);
+    };
+  }
+
+  // Create the typed client object
+  return {
+    query: queryMethods,
+    ingest: ingestMethods,
+    get client(): TinybirdClient {
+      // Synchronous client access - will throw if not initialized
+      if (!_client) {
+        throw new Error(
+          "Client not initialized. Call a query or ingest method first, or access client asynchronously."
+        );
+      }
+      return _client;
+    },
+  } as ProjectClient<TDatasources, TPipes>;
+}
+
+/**
+ * Create a typed Tinybird client
+ *
+ * Creates a client with typed query and ingest methods based on the provided
+ * datasources and pipes. This is the recommended way to create a Tinybird client
+ * when using the SDK's auto-generated client file.
+ *
+ * @param config - Client configuration with datasources and pipes
+ * @returns A typed client with query and ingest methods
+ *
+ * @example
+ * ```ts
+ * import { createTinybirdClient } from '@tinybirdco/sdk';
+ * import { pageViews, events } from './datasources';
+ * import { topPages } from './pipes';
+ *
+ * export const tinybird = createTinybirdClient({
+ *   datasources: { pageViews, events },
+ *   pipes: { topPages },
+ * });
+ *
+ * // Query a pipe (fully typed)
+ * const result = await tinybird.query.topPages({
+ *   start_date: new Date('2024-01-01'),
+ *   end_date: new Date('2024-01-31'),
+ * });
+ *
+ * // Ingest an event (fully typed)
+ * await tinybird.ingest.pageViews({
+ *   timestamp: new Date(),
+ *   pathname: '/home',
+ *   session_id: 'abc123',
+ * });
+ * ```
+ */
+export function createTinybirdClient<
+  TDatasources extends DatasourcesDefinition,
+  TPipes extends PipesDefinition
+>(
+  config: TinybirdClientConfig<TDatasources, TPipes>
+): ProjectClient<TDatasources, TPipes> {
+  return buildProjectClient(
+    config.datasources,
+    config.pipes,
+    { baseUrl: config.baseUrl, token: config.token }
+  );
+}
+
+/**
+ * Get all datasource names from a project
+ */
+export function getDatasourceNames<T extends ProjectDefinition>(
+  project: T
+): (keyof T["datasources"])[] {
+  return Object.keys(project.datasources) as (keyof T["datasources"])[];
+}
+
+/**
+ * Get all pipe names from a project
+ */
+export function getPipeNames<T extends ProjectDefinition>(project: T): (keyof T["pipes"])[] {
+  return Object.keys(project.pipes) as (keyof T["pipes"])[];
+}
+
+/**
+ * Get a datasource by name from a project
+ */
+export function getDatasource<
+  TDatasources extends DatasourcesDefinition,
+  TPipes extends PipesDefinition,
+  K extends keyof TDatasources
+>(project: ProjectDefinition<TDatasources, TPipes>, name: K): TDatasources[K] {
+  return project.datasources[name];
+}
+
+/**
+ * Get a pipe by name from a project
+ */
+export function getPipe<
+  TDatasources extends DatasourcesDefinition,
+  TPipes extends PipesDefinition,
+  K extends keyof TPipes
+>(project: ProjectDefinition<TDatasources, TPipes>, name: K): TPipes[K] {
+  return project.pipes[name];
+}
+
+/**
+ * Helper type to extract datasources from a project
+ */
+export type ExtractDatasources<T> = T extends ProjectDefinition<infer D, PipesDefinition>
+  ? D
+  : never;
+
+/**
+ * Helper type to extract pipes from a project
+ */
+export type ExtractPipes<T> = T extends ProjectDefinition<DatasourcesDefinition, infer P>
+  ? P
+  : never;
+
+/**
+ * Data model type derived from a project
+ * Useful for generating typed clients
+ */
+export type DataModel<T extends ProjectDefinition> = {
+  datasources: {
+    [K in keyof T["datasources"]]: T["datasources"][K] extends DatasourceDefinition<infer S>
+      ? S
+      : never;
+  };
+  pipes: {
+    [K in keyof T["pipes"]]: T["pipes"][K] extends PipeDefinition<infer P, infer O>
+      ? { params: P; output: O }
+      : never;
+  };
+};