@tinybirdco/sdk 0.0.36 → 0.0.38

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 { 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]>;
+  };
 };
 
 /**
@@ -72,20 +82,48 @@ type IngestMethods<T extends DatasourcesDefinition> = {
 };
 
 /**
- * Typed client interface for a project
+ * Type for a datasource accessor with append method
  */
-export interface ProjectClient<
-  TDatasources extends DatasourcesDefinition,
-  TPipes extends PipesDefinition
-> {
-  /** Query endpoint pipes */
-  query: QueryMethods<TPipes>;
+type DatasourceAccessor = {
+  /** Append data from a URL or file */
+  append(options: AppendOptions): Promise<AppendResult>;
+};
+
+/**
+ * Type for datasource accessors object
+ * Maps each datasource to an accessor with append method
+ */
+type DatasourceAccessors<T extends DatasourcesDefinition> = {
+  [K in keyof T]: DatasourceAccessor;
+};
+
+/**
+ * Base project client interface
+ */
+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;
 }
 
+/**
+ * Typed client interface for a project
+ * Includes datasource accessors as top-level properties
+ */
+export type ProjectClient<
+  TDatasources extends DatasourcesDefinition,
+  TPipes extends PipesDefinition
+> = ProjectClientBase<TDatasources> &
+  DatasourceAccessors<TDatasources> &
+  PipeEntityAccessors<TPipes>;
+
 /**
  * Configuration for createTinybirdClient
  */
@@ -218,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,
@@ -228,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;
 
@@ -251,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;
 
@@ -294,10 +364,46 @@ function buildProjectClient<
     };
   }
 
+  // Build datasource accessors for top-level access
+  const datasourceAccessors: Record<string, DatasourceAccessor> = {};
+  for (const [name, datasource] of Object.entries(datasources)) {
+    const tinybirdName = datasource._name;
+
+    datasourceAccessors[name] = {
+      append: async (options: AppendOptions) => {
+        const client = await getClient();
+        return client.datasources.append(tinybirdName, options);
+      },
+    };
+  }
+
   // Create the typed client object
   return {
-    query: queryMethods,
+    ...datasourceAccessors,
+    ...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) {
@@ -313,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
@@ -332,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'),
  * });