@tinybirdco/sdk 0.0.42 → 0.0.44

package/src/codegen/index.test.ts

@@ -304,7 +304,7 @@ describe("generateClientFile", () => {
 
     const file = generateClientFile(datasources, pipes);
 
-    expect(file).toContain('import { createTinybirdClient } from "@tinybirdco/sdk"');
+    expect(file).toContain('import { Tinybird } from "@tinybirdco/sdk"');
     expect(file).toContain('import { events, type EventsRow } from "./datasources.js"');
     expect(file).toContain('import { topEvents, type TopEventsParams, type TopEventsOutput } from "./pipes.js"');
     expect(file).toContain("datasources: { events }");
@@ -321,7 +321,7 @@ describe("generateClientFile", () => {
     expect(file).toContain('import { dirname } from "path"');
     // Should derive __configDir from import.meta.url
     expect(file).toContain("const __configDir = dirname(fileURLToPath(import.meta.url))");
-    // Should pass configDir to createTinybirdClient
+    // Should pass configDir to Tinybird constructor
     expect(file).toContain("configDir: __configDir");
   });
 
@@ -386,6 +386,6 @@ describe("generateAllFiles", () => {
     expect(result.pipeCount).toBe(1);
     expect(result.datasourcesContent).toContain("defineDatasource");
     expect(result.pipesContent).toContain("defineEndpoint");
-    expect(result.clientContent).toContain("createTinybirdClient");
+    expect(result.clientContent).toContain("new Tinybird");
   });
 });

package/src/codegen/index.ts

@@ -267,7 +267,7 @@ export function generateClientFile(
     " * Generated from existing workspace resources.",
     " */",
     "",
-    'import { createTinybirdClient } from "@tinybirdco/sdk";',
+    'import { Tinybird } from "@tinybirdco/sdk";',
     // Node imports for deriving configDir from import.meta.url (monorepo support)
     'import { fileURLToPath } from "url";',
     'import { dirname } from "path";',
@@ -313,7 +313,7 @@ export function generateClientFile(
   lines.push("const __configDir = dirname(fileURLToPath(import.meta.url));");
   lines.push("");
   lines.push("// Create the typed Tinybird client");
-  lines.push("export const tinybird = createTinybirdClient({");
+  lines.push("export const tinybird = new Tinybird({");
 
   if (datasources.length > 0) {
     const dsNames = datasources.map((ds) => toCamelCase(ds.name)).join(", ");
@@ -417,7 +417,7 @@ export function generateCombinedFile(
   ];
 
   // Build imports
-  const sdkImports: string[] = ["createTinybirdClient", "t"];
+  const sdkImports: string[] = ["Tinybird", "t"];
 
   if (datasources.length > 0) {
     sdkImports.push("defineDatasource", "engine", "type InferRow");
@@ -505,7 +505,7 @@ export function generateCombinedFile(
   lines.push("// This ensures tinybird.json is found regardless of where the app runs from");
   lines.push("const __configDir = dirname(fileURLToPath(import.meta.url));");
   lines.push("");
-  lines.push("export const tinybird = createTinybirdClient({");
+  lines.push("export const tinybird = new Tinybird({");
   lines.push(`  datasources: { ${dsNames} },`);
   lines.push(`  pipes: { ${pipeNames} },`);
   lines.push("  configDir: __configDir,");

package/src/generator/client.ts

@@ -108,7 +108,7 @@ export function generateClientFile(options: GenerateClientOptions): GeneratedCli
     sdkTypes.push("InferParams", "InferOutputRow");
   }
   importLines.push(
-    `import { createTinybirdClient, type ${sdkTypes.join(", type ")} } from "@tinybirdco/sdk";`
+    `import { Tinybird, type ${sdkTypes.join(", type ")} } from "@tinybirdco/sdk";`
   );
   // Node imports for deriving configDir from import.meta.url (monorepo support)
   importLines.push(`import { fileURLToPath } from "url";`);
@@ -127,7 +127,7 @@ export function generateClientFile(options: GenerateClientOptions): GeneratedCli
     reexportLines.push(`export { ${allExports.join(", ")} } from "${relativePath}";`);
   }
 
-  // Build createTinybirdClient call
+  // Build Tinybird constructor call
   const datasourceNames = Object.keys(entities.datasources);
   const pipeNames = Object.keys(entities.pipes);
 
@@ -136,7 +136,7 @@ export function generateClientFile(options: GenerateClientOptions): GeneratedCli
   // This ensures tinybird.json is found regardless of where the app runs from
   clientLines.push("const __configDir = dirname(fileURLToPath(import.meta.url));");
   clientLines.push("");
-  clientLines.push("export const tinybird = createTinybirdClient({");
+  clientLines.push("export const tinybird = new Tinybird({");
 
   if (datasourceNames.length > 0) {
     clientLines.push(`  datasources: { ${datasourceNames.join(", ")} },`);

package/src/index.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from "vitest";
+import * as sdk from "./index.js";
+
+describe("root public exports", () => {
+  it("does not expose legacy project-client aliases", () => {
+    expect("createTinybirdClient" in sdk).toBe(false);
+  });
+
+  it("keeps documented project constructors", () => {
+    expect(typeof sdk.defineProject).toBe("function");
+    expect(typeof sdk.Tinybird).toBe("function");
+  });
+});

package/src/index.ts

@@ -168,12 +168,18 @@ export type {
 } from "./schema/pipe.js";
 
 // ============ Project ============
-export { defineProject, isProjectDefinition, getDatasourceNames, getPipeNames, getDatasource, getPipe, createTinybirdClient } from "./schema/project.js";
+export {
+  defineProject,
+  isProjectDefinition,
+  getDatasourceNames,
+  getPipeNames,
+  getDatasource,
+  getPipe,
+  Tinybird,
+} from "./schema/project.js";
 export type {
   ProjectDefinition,
   ProjectConfig,
-  ProjectClient,
-  TinybirdClientConfig,
   DatasourcesDefinition,
   PipesDefinition,
   ConnectionsDefinition,

package/src/schema/project.test.ts

@@ -410,5 +410,33 @@ describe("Project Schema", () => {
 
       expect(() => client.client).toThrow("Client not initialized");
     });
+
+    it("does not allow datasource names to overwrite internal client state", () => {
+      const events = defineDatasource("events", {
+        schema: { id: t.string() },
+      });
+
+      const client = createTinybirdClient({
+        datasources: { _client: events },
+        pipes: {},
+      });
+
+      expect(client._client).toBeDefined();
+      expect(() => client.client).toThrow("Client not initialized");
+    });
+
+    it("does not allow datasource names to overwrite internal options state", () => {
+      const events = defineDatasource("events", {
+        schema: { id: t.string() },
+      });
+
+      const client = createTinybirdClient({
+        datasources: { _options: events },
+        pipes: {},
+      });
+
+      expect(client._options).toBeDefined();
+      expect(() => client.client).toThrow("Client not initialized");
+    });
   });
 });

package/src/schema/project.ts

@@ -216,8 +216,8 @@ export function defineProject<
   const pipes = (config.pipes ?? {}) as TPipes;
   const connections = (config.connections ?? {}) as TConnections;
 
-  // Use the shared client builder
-  const tinybird = buildProjectClient(datasources, pipes);
+  // Create the typed Tinybird client
+  const tinybird = new Tinybird({ datasources, pipes });
 
   return {
     [PROJECT_BRAND]: true,
@@ -241,220 +241,212 @@ export function isProjectDefinition(value: unknown): value is ProjectDefinition
   );
 }
 
+const RESERVED_CLIENT_NAMES = new Set(["tokens", "datasources", "sql", "client"]);
+
+/**
+ * Constructor interface for Tinybird class
+ * This allows TypeScript to infer the correct return type with typed accessors
+ */
+interface TinybirdConstructor {
+  new <TDatasources extends DatasourcesDefinition, TPipes extends PipesDefinition>(
+    config: TinybirdClientConfig<TDatasources, TPipes>
+  ): ProjectClient<TDatasources, TPipes>;
+}
+
 /**
- * Build a typed Tinybird client from datasources and pipes
+ * Typed Tinybird client
+ *
+ * Creates a client with typed pipe query and datasource methods based on
+ * the provided datasources and pipes.
+ *
+ * @example
+ * ```ts
+ * import { Tinybird } from '@tinybirdco/sdk';
+ * import { pageViews, events } from './datasources';
+ * import { topPages } from './pipes';
+ *
+ * export const tinybird = new Tinybird({
+ *   datasources: { pageViews, events },
+ *   pipes: { topPages },
+ * });
  *
- * This is an internal helper that builds pipe query and datasource methods.
+ * // Query a pipe (fully typed)
+ * const result = await tinybird.topPages.query({
+ *   start_date: new Date('2024-01-01'),
+ *   end_date: new Date('2024-01-31'),
+ * });
+ *
+ * // Ingest an event (fully typed)
+ * await tinybird.pageViews.ingest({
+ *   timestamp: new Date(),
+ *   pathname: '/home',
+ *   session_id: 'abc123',
+ * });
+ * ```
  */
-function buildProjectClient<
-  TDatasources extends DatasourcesDefinition,
-  TPipes extends PipesDefinition
->(
-  datasources: TDatasources,
-  pipes: TPipes,
-  options?: { baseUrl?: string; token?: string; configDir?: string; devMode?: boolean }
-): ProjectClient<TDatasources, TPipes> {
-  const RESERVED_CLIENT_NAMES = new Set([
-    "tokens",
-    "datasources",
-    "sql",
-    "client",
-  ]);
-
-  // Lazy client initialization
-  let _client: TinybirdClient | null = null;
-
-  const getClient = async (): Promise<TinybirdClient> => {
-    if (!_client) {
-      // Dynamic imports to avoid circular dependencies
+export const Tinybird: TinybirdConstructor = class Tinybird<
+  TDatasources extends DatasourcesDefinition = DatasourcesDefinition,
+  TPipes extends PipesDefinition = PipesDefinition
+> {
+  #client: TinybirdClient | null = null;
+  readonly #options: {
+    baseUrl?: string;
+    token?: string;
+    configDir?: string;
+    devMode?: boolean;
+  };
+
+  constructor(config: TinybirdClientConfig<TDatasources, TPipes>) {
+    this.#options = {
+      baseUrl: config.baseUrl,
+      token: config.token,
+      configDir: config.configDir,
+      devMode: config.devMode,
+    };
+
+    // Build pipe accessors with query methods
+    for (const [name, pipe] of Object.entries(config.pipes)) {
+      if (name in config.datasources) {
+        throw new Error(
+          `Name conflict: "${name}" is defined as both datasource and pipe. ` +
+            `Rename one of them to expose both as top-level client properties.`
+        );
+      }
+      if (RESERVED_CLIENT_NAMES.has(name)) {
+        throw new Error(
+          `Name conflict: "${name}" is reserved by the client API. ` +
+            `Rename this pipe to expose it as a top-level client property.`
+        );
+      }
+
+      const endpointConfig = getEndpointConfig(pipe);
+
+      if (!endpointConfig) {
+        (this as Record<string, unknown>)[name] = {
+          query: async () => {
+            throw new Error(
+              `Pipe "${name}" is not exposed as an endpoint. ` +
+                `Set "endpoint: true" in the pipe definition to enable querying.`
+            );
+          },
+        };
+        continue;
+      }
+
+      const tinybirdName = pipe._name;
+      (this as Record<string, unknown>)[name] = {
+        query: async (params?: unknown) => {
+          const client = await this.#getClient();
+          return client.query(tinybirdName, (params ?? {}) as Record<string, unknown>);
+        },
+      };
+    }
+
+    // Build datasource accessors for top-level access
+    for (const [name, datasource] of Object.entries(config.datasources)) {
+      if (RESERVED_CLIENT_NAMES.has(name)) {
+        throw new Error(
+          `Name conflict: "${name}" is reserved by the client API. ` +
+            `Rename this datasource to expose it as a top-level client property.`
+        );
+      }
+
+      const tinybirdName = datasource._name;
+
+      (this as Record<string, unknown>)[name] = {
+        ingest: async (event: unknown) => {
+          const client = await this.#getClient();
+          return client.datasources.ingest(tinybirdName, event as Record<string, unknown>);
+        },
+        append: async (options: AppendOptions) => {
+          const client = await this.#getClient();
+          return client.datasources.append(tinybirdName, options);
+        },
+        replace: async (options: AppendOptions) => {
+          const client = await this.#getClient();
+          return client.datasources.replace(tinybirdName, options);
+        },
+        delete: async (options: DeleteOptions) => {
+          const client = await this.#getClient();
+          return client.datasources.delete(tinybirdName, options);
+        },
+        truncate: async (options: TruncateOptions = {}) => {
+          const client = await this.#getClient();
+          return client.datasources.truncate(tinybirdName, options);
+        },
+      };
+    }
+  }
+
+  async #getClient(): Promise<TinybirdClient> {
+    if (!this.#client) {
       const { createClient } = await import("../client/base.js");
       const { resolveToken } = await import("../client/preview.js");
 
-      // Resolve the token (handles preview environment detection)
-      const baseUrl = options?.baseUrl ?? process.env.TINYBIRD_URL ?? "https://api.tinybird.co";
-      const token = await resolveToken({ baseUrl, token: options?.token });
+      const baseUrl =
+        this.#options.baseUrl ?? process.env.TINYBIRD_URL ?? "https://api.tinybird.co";
+      const token = await resolveToken({ baseUrl, token: this.#options.token });
 
-      _client = createClient({
+      this.#client = createClient({
         baseUrl,
         token,
-        devMode: options?.devMode ?? process.env.NODE_ENV === "development",
-        configDir: options?.configDir,
+        devMode: this.#options.devMode ?? process.env.NODE_ENV === "development",
+        configDir: this.#options.configDir,
       });
     }
-    return _client;
-  };
+    return this.#client;
+  }
+
+  /** Execute raw SQL queries */
+  async sql<T = unknown>(sqlQuery: string, options: QueryOptions = {}): Promise<QueryResult<T>> {
+    const client = await this.#getClient();
+    return client.sql<T>(sqlQuery, options);
+  }
 
-  // Build pipe accessors with query methods
-  const pipeAccessors: Record<string, { query: (params?: unknown) => Promise<unknown> }> = {};
-  for (const [name, pipe] of Object.entries(pipes)) {
-    if (name in datasources) {
+  /** Token operations (JWT creation, etc.) */
+  get tokens(): TokensNamespace {
+    if (!this.#client) {
       throw new Error(
-        `Name conflict in createTinybirdClient(): "${name}" is defined as both datasource and pipe. ` +
-          `Rename one of them to expose both as top-level client properties.`
+        "Client not initialized. Call a query or ingest method first, or access client asynchronously."
       );
     }
-    if (RESERVED_CLIENT_NAMES.has(name)) {
+    return this.#client.tokens;
+  }
+
+  /** Datasource operations (ingest/append/replace/delete/truncate) */
+  get datasources(): DatasourcesNamespace {
+    if (!this.#client) {
       throw new Error(
-        `Name conflict in createTinybirdClient(): "${name}" is reserved by the client API. ` +
-          `Rename this pipe to expose it as a top-level client property.`
+        "Client not initialized. Call a query or ingest method first, or access client asynchronously."
       );
     }
-
-    const endpointConfig = getEndpointConfig(pipe);
-
-    if (!endpointConfig) {
-      // Non-endpoint pipes get a stub that throws a clear error
-      pipeAccessors[name] = {
-        query: 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;
-    pipeAccessors[name] = {
-      query: async (params?: unknown) => {
-        const client = await getClient();
-        return client.query(tinybirdName, (params ?? {}) as Record<string, unknown>);
-      },
-    };
+    return this.#client.datasources;
   }
 
-  // Build datasource accessors for top-level access
-  const datasourceAccessors: Record<
-    string,
-    {
-      ingest: (event: unknown) => Promise<IngestResult>;
-      append: (options: AppendOptions) => Promise<AppendResult>;
-      replace: (options: AppendOptions) => Promise<AppendResult>;
-      delete: (options: DeleteOptions) => Promise<DeleteResult>;
-      truncate: (options?: TruncateOptions) => Promise<TruncateResult>;
-    }
-  > = {};
-  for (const [name, datasource] of Object.entries(datasources)) {
-    if (RESERVED_CLIENT_NAMES.has(name)) {
+  /** Raw client for advanced usage */
+  get client(): TinybirdClient {
+    if (!this.#client) {
       throw new Error(
-        `Name conflict in createTinybirdClient(): "${name}" is reserved by the client API. ` +
-          `Rename this datasource to expose it as a top-level client property.`
+        "Client not initialized. Call a query or ingest method first, or access client asynchronously."
       );
     }
-
-    const tinybirdName = datasource._name;
-
-    datasourceAccessors[name] = {
-      ingest: async (event: unknown) => {
-        const client = await getClient();
-        return client.datasources.ingest(tinybirdName, event as Record<string, unknown>);
-      },
-      append: async (options: AppendOptions) => {
-        const client = await getClient();
-        return client.datasources.append(tinybirdName, options);
-      },
-      replace: async (options: AppendOptions) => {
-        const client = await getClient();
-        return client.datasources.replace(tinybirdName, options);
-      },
-      delete: async (options: DeleteOptions) => {
-        const client = await getClient();
-        return client.datasources.delete(tinybirdName, options);
-      },
-      truncate: async (options: TruncateOptions = {}) => {
-        const client = await getClient();
-        return client.datasources.truncate(tinybirdName, options);
-      },
-    };
+    return this.#client;
   }
-
-  // Create the typed client object
-  return {
-    ...datasourceAccessors,
-    ...pipeAccessors,
-    sql: async <T = unknown>(sql: string, options: QueryOptions = {}) => {
-      const client = await getClient();
-      return client.sql<T>(sql, options);
-    },
-    get tokens(): TokensNamespace {
-      // Synchronous 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.tokens;
-    },
-    get datasources(): DatasourcesNamespace {
-      // Synchronous 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.datasources;
-    },
-    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>;
-}
+} as unknown as TinybirdConstructor;
 
 /**
  * Create a typed Tinybird client
  *
- * Creates a client with typed pipe query and datasource 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.
+ * @deprecated Use `new Tinybird(...)` instead. This function is kept for backward compatibility.
  *
  * @param config - Client configuration with datasources and pipes
  * @returns A typed client with pipe query and datasource 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.topPages.query({
- *   start_date: new Date('2024-01-01'),
- *   end_date: new Date('2024-01-31'),
- * });
- *
- * // Ingest an event (fully typed)
- * await tinybird.pageViews.ingest({
- *   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, configDir: config.configDir, devMode: config.devMode }
-  );
+>(config: TinybirdClientConfig<TDatasources, TPipes>): ProjectClient<TDatasources, TPipes> {
+  return new Tinybird(config);
 }
 
 /**