@tinybirdco/sdk 0.0.37 → 0.0.38

package/src/schema/project.test.ts

@@ -70,7 +70,7 @@ describe("Project Schema", () => {
       expect(project.pipes.topEvents).toBe(topEvents);
     });
 
-    it("creates tinybird client with query and ingest methods", () => {
+    it("creates tinybird client with pipe accessors and ingest methods", () => {
       const events = defineDatasource("events", {
         schema: { id: t.string() },
       });
@@ -86,11 +86,12 @@ describe("Project Schema", () => {
         pipes: { topEvents },
       });
 
-      expect(project.tinybird.query).toBeDefined();
       expect(project.tinybird.ingest).toBeDefined();
-      expect(typeof project.tinybird.query.topEvents).toBe("function");
+      expect(typeof project.tinybird.topEvents.query).toBe("function");
       expect(typeof project.tinybird.ingest.events).toBe("function");
       expect(typeof project.tinybird.ingest.eventsBatch).toBe("function");
+      expect((project.tinybird as unknown as Record<string, unknown>).query).toBeUndefined();
+      expect((project.tinybird as unknown as Record<string, unknown>).pipes).toBeUndefined();
     });
 
     it("creates datasource accessors with append method", () => {
@@ -144,7 +145,7 @@ describe("Project Schema", () => {
       });
 
       // Cast to any since the type system expects params but stub throws regardless
-      const queryFn = project.tinybird.query.internalPipe as () => Promise<unknown>;
+      const queryFn = project.tinybird.internalPipe.query as () => Promise<unknown>;
       await expect(queryFn()).rejects.toThrow(
         'Pipe "internalPipe" is not exposed as an endpoint'
       );
@@ -277,7 +278,7 @@ describe("Project Schema", () => {
       process.env.NODE_ENV = originalNodeEnv;
     });
 
-    it("creates a client with query and ingest methods", () => {
+    it("creates a client with pipe accessors and ingest methods", () => {
       const events = defineDatasource("events", {
         schema: { id: t.string() },
       });
@@ -293,11 +294,14 @@ describe("Project Schema", () => {
         pipes: { topEvents },
       });
 
-      expect(client.query).toBeDefined();
       expect(client.ingest).toBeDefined();
-      expect(typeof client.query.topEvents).toBe("function");
+      expect(client.sql).toBeDefined();
+      expect(typeof client.topEvents.query).toBe("function");
       expect(typeof client.ingest.events).toBe("function");
       expect(typeof client.ingest.eventsBatch).toBe("function");
+      expect(typeof client.sql).toBe("function");
+      expect((client as unknown as Record<string, unknown>).query).toBeUndefined();
+      expect((client as unknown as Record<string, unknown>).pipes).toBeUndefined();
     });
 
     it("creates datasource accessors with append method", () => {
@@ -345,7 +349,6 @@ describe("Project Schema", () => {
         devMode: true,
       });
 
-      expect(clientWithDevMode.query).toBeDefined();
       expect(clientWithDevMode.ingest).toBeDefined();
 
       const clientWithoutDevMode = createTinybirdClient({
@@ -354,7 +357,6 @@ describe("Project Schema", () => {
         devMode: false,
       });
 
-      expect(clientWithoutDevMode.query).toBeDefined();
       expect(clientWithoutDevMode.ingest).toBeDefined();
     });
 
@@ -373,7 +375,6 @@ describe("Project Schema", () => {
         devMode: true,
       });
 
-      expect(client.query).toBeDefined();
       expect(client.ingest).toBeDefined();
     });
 

package/src/schema/project.ts

@@ -8,8 +8,15 @@ import type { PipeDefinition, ParamsDefinition, OutputDefinition } from "./pipe.
 import type { ConnectionDefinition } from "./connection.js";
 import { getEndpointConfig } from "./pipe.js";
 import type { TinybirdClient } from "../client/base.js";
-import type { AppendOptions, AppendResult, QueryResult } from "../client/types.js";
+import type {
+  AppendOptions,
+  AppendResult,
+  DatasourcesNamespace,
+  QueryOptions,
+  QueryResult,
+} from "../client/types.js";
 import type { InferRow, InferParams, InferOutputRow } from "../infer/index.js";
+import type { TokensNamespace } from "../client/tokens.js";
 
 // Symbol for brand typing - use Symbol.for() for global registry
 // This ensures the same symbol is used across module instances
@@ -41,11 +48,14 @@ type QueryMethod<T extends PipeDefinition<ParamsDefinition, OutputDefinition>> =
     : never;
 
 /**
- * Type for query methods object
- * Note: At runtime, only pipes with endpoint: true are included
+ * Type for pipe entity accessors object
+ * Note: At runtime, all declared pipes are included. Non-endpoint pipes throw
+ * when queried with a clear error message.
  */
-type QueryMethods<T extends PipesDefinition> = {
-  [K in keyof T]: QueryMethod<T[K]>;
+type PipeEntityAccessors<T extends PipesDefinition> = {
+  [K in keyof T]: {
+    query: QueryMethod<T[K]>;
+  };
 };
 
 /**
@@ -90,14 +100,15 @@ type DatasourceAccessors<T extends DatasourcesDefinition> = {
 /**
  * Base project client interface
  */
-interface ProjectClientBase<
-  TDatasources extends DatasourcesDefinition,
-  TPipes extends PipesDefinition
-> {
-  /** Query endpoint pipes */
-  query: QueryMethods<TPipes>;
+interface ProjectClientBase<TDatasources extends DatasourcesDefinition> {
   /** Ingest events to datasources */
   ingest: IngestMethods<TDatasources>;
+  /** Token operations (JWT creation, etc.) */
+  readonly tokens: TokensNamespace;
+  /** Datasource operations (append from URL/file) */
+  readonly datasources: DatasourcesNamespace;
+  /** Execute raw SQL queries */
+  sql<T = unknown>(sql: string, options?: QueryOptions): Promise<QueryResult<T>>;
   /** Raw client for advanced usage */
   readonly client: TinybirdClient;
 }
@@ -109,7 +120,9 @@ interface ProjectClientBase<
 export type ProjectClient<
   TDatasources extends DatasourcesDefinition,
   TPipes extends PipesDefinition
-> = ProjectClientBase<TDatasources, TPipes> & DatasourceAccessors<TDatasources>;
+> = ProjectClientBase<TDatasources> &
+  DatasourceAccessors<TDatasources> &
+  PipeEntityAccessors<TPipes>;
 
 /**
  * Configuration for createTinybirdClient
@@ -243,7 +256,7 @@ export function isProjectDefinition(value: unknown): value is ProjectDefinition
 /**
  * Build a typed Tinybird client from datasources and pipes
  *
- * This is an internal helper that builds query/ingest methods.
+ * This is an internal helper that builds pipe query and datasource ingest methods.
  */
 function buildProjectClient<
   TDatasources extends DatasourcesDefinition,
@@ -253,6 +266,14 @@ function buildProjectClient<
   pipes: TPipes,
   options?: { baseUrl?: string; token?: string; configDir?: string; devMode?: boolean }
 ): ProjectClient<TDatasources, TPipes> {
+  const RESERVED_CLIENT_NAMES = new Set([
+    "ingest",
+    "tokens",
+    "datasources",
+    "sql",
+    "client",
+  ]);
+
   // Lazy client initialization
   let _client: TinybirdClient | null = null;
 
@@ -276,33 +297,57 @@ function buildProjectClient<
     return _client;
   };
 
-  // Build query methods for pipes
-  const queryMethods: Record<string, (params?: unknown) => Promise<unknown>> = {};
+  // 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) {
+      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.`
+      );
+    }
+    if (RESERVED_CLIENT_NAMES.has(name)) {
+      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.`
+      );
+    }
+
     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.`
-        );
+      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;
-    queryMethods[name] = async (params?: unknown) => {
-      const client = await getClient();
-      return client.query(tinybirdName, (params ?? {}) as Record<string, unknown>);
+    pipeAccessors[name] = {
+      query: 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)) {
+    if (RESERVED_CLIENT_NAMES.has(name)) {
+      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.`
+      );
+    }
+
     // Use the Tinybird datasource name (snake_case)
     const tinybirdName = datasource._name;
 
@@ -335,8 +380,30 @@ function buildProjectClient<
   // Create the typed client object
   return {
     ...datasourceAccessors,
-    query: queryMethods,
+    ...pipeAccessors,
     ingest: ingestMethods,
+    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) {
@@ -352,12 +419,13 @@ function buildProjectClient<
 /**
  * Create a typed Tinybird client
  *
- * Creates a client with typed query and ingest methods based on the provided
+ * Creates a client with typed pipe query and datasource 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
+ * @returns A typed client with pipe query and datasource ingest methods
  *
  * @example
  * ```ts
@@ -371,7 +439,7 @@ function buildProjectClient<
  * });
  *
  * // Query a pipe (fully typed)
- * const result = await tinybird.query.topPages({
+ * const result = await tinybird.topPages.query({
  *   start_date: new Date('2024-01-01'),
  *   end_date: new Date('2024-01-31'),
  * });