@tinybirdco/sdk 0.0.37 → 0.0.39

package/src/client/types.ts

@@ -236,10 +236,64 @@ export interface AppendResult {
   import_id?: string;
 }
 
+/**
+ * Options for deleting rows from a datasource
+ */
+export interface DeleteOptions {
+  /** SQL WHERE clause condition used to select rows to delete */
+  deleteCondition: string;
+  /** Validate and return matched rows without executing deletion */
+  dryRun?: boolean;
+  /** Request timeout in milliseconds */
+  timeout?: number;
+  /** AbortController signal for cancellation */
+  signal?: AbortSignal;
+}
+
+/**
+ * Result of deleting rows from a datasource
+ */
+export interface DeleteResult {
+  /** Delete job ID */
+  id?: string;
+  /** Same value as id */
+  job_id?: string;
+  /** Job status URL */
+  job_url?: string;
+  /** Job status */
+  status?: string;
+  /** Same value as id */
+  delete_id?: string;
+  /** Number of rows matched in dry run mode */
+  rows_to_be_deleted?: number;
+}
+
+/**
+ * Options for truncating a datasource
+ */
+export interface TruncateOptions {
+  /** Request timeout in milliseconds */
+  timeout?: number;
+  /** AbortController signal for cancellation */
+  signal?: AbortSignal;
+}
+
+/**
+ * Result of truncating a datasource
+ */
+export interface TruncateResult {
+  /** Optional status returned by the API */
+  status?: string;
+}
+
 /**
  * Datasources namespace interface for raw client
  */
 export interface DatasourcesNamespace {
   /** Append data to a datasource from a URL or file */
   append(datasourceName: string, options: AppendOptions): Promise<AppendResult>;
+  /** Delete rows from a datasource using a SQL condition */
+  delete(datasourceName: string, options: DeleteOptions): Promise<DeleteResult>;
+  /** Truncate all rows from a datasource */
+  truncate(datasourceName: string, options?: TruncateOptions): Promise<TruncateResult>;
 }

package/src/index.ts

@@ -208,10 +208,14 @@ export type {
   ClientContext,
   CsvDialectOptions,
   DatasourcesNamespace,
+  DeleteOptions,
+  DeleteResult,
   QueryResult,
   IngestResult,
   QueryOptions,
   IngestOptions,
+  TruncateOptions,
+  TruncateResult,
   ColumnMeta,
   QueryStatistics,
   TinybirdErrorResponse,
@@ -231,7 +235,13 @@ export type {
   TinybirdApiQueryOptions,
   TinybirdApiIngestOptions,
   TinybirdApiAppendOptions,
+  TinybirdApiDeleteOptions,
+  TinybirdApiTruncateOptions,
   TinybirdApiRequestInit,
+  TinybirdApiTokenScope,
+  TinybirdApiCreateTokenRequest,
+  TinybirdApiCreateTokenOptions,
+  TinybirdApiCreateTokenResult,
 } from "./api/api.js";
 
 // ============ Preview Environment ============
@@ -251,6 +261,17 @@ export {
 } from "./api/dashboard.js";
 export type { RegionInfo } from "./api/dashboard.js";
 
+// ============ Token API ============
+export { createJWT, TokenApiError } from "./api/tokens.js";
+export type {
+  TokenApiConfig,
+  JWTScope,
+  JWTScopeType,
+  JWTLimits,
+  CreateJWTOptions,
+  CreateJWTResult,
+} from "./api/tokens.js";
+
 // ============ Config Types ============
 // Import from config-types.ts to avoid bundling esbuild in client code
 export type { TinybirdConfig, DevMode } from "./cli/config-types.js";

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,14 +86,15 @@ 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", () => {
+    it("creates datasource accessors with append/delete/truncate methods", () => {
       const events = defineDatasource("events", {
         schema: { timestamp: t.dateTime() },
       });
@@ -104,6 +105,8 @@ describe("Project Schema", () => {
 
       expect(project.tinybird.events).toBeDefined();
       expect(typeof project.tinybird.events.append).toBe("function");
+      expect(typeof project.tinybird.events.delete).toBe("function");
+      expect(typeof project.tinybird.events.truncate).toBe("function");
     });
 
     it("creates multiple datasource accessors", () => {
@@ -122,6 +125,10 @@ describe("Project Schema", () => {
       expect(project.tinybird.pageViews).toBeDefined();
       expect(typeof project.tinybird.events.append).toBe("function");
       expect(typeof project.tinybird.pageViews.append).toBe("function");
+      expect(typeof project.tinybird.events.delete).toBe("function");
+      expect(typeof project.tinybird.pageViews.delete).toBe("function");
+      expect(typeof project.tinybird.events.truncate).toBe("function");
+      expect(typeof project.tinybird.pageViews.truncate).toBe("function");
     });
 
     it("throws error when accessing client before initialization", () => {
@@ -144,7 +151,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 +284,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,14 +300,17 @@ 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", () => {
+    it("creates datasource accessors with append/delete/truncate methods", () => {
       const events = defineDatasource("events", {
         schema: { id: t.string() },
       });
@@ -312,6 +322,8 @@ describe("Project Schema", () => {
 
       expect(client.events).toBeDefined();
       expect(typeof client.events.append).toBe("function");
+      expect(typeof client.events.delete).toBe("function");
+      expect(typeof client.events.truncate).toBe("function");
     });
 
     it("creates multiple datasource accessors", () => {
@@ -331,6 +343,10 @@ describe("Project Schema", () => {
       expect(client.pageViews).toBeDefined();
       expect(typeof client.events.append).toBe("function");
       expect(typeof client.pageViews.append).toBe("function");
+      expect(typeof client.events.delete).toBe("function");
+      expect(typeof client.pageViews.delete).toBe("function");
+      expect(typeof client.events.truncate).toBe("function");
+      expect(typeof client.pageViews.truncate).toBe("function");
     });
 
     it("accepts devMode option", () => {
@@ -345,7 +361,6 @@ describe("Project Schema", () => {
         devMode: true,
       });
 
-      expect(clientWithDevMode.query).toBeDefined();
       expect(clientWithDevMode.ingest).toBeDefined();
 
       const clientWithoutDevMode = createTinybirdClient({
@@ -354,7 +369,6 @@ describe("Project Schema", () => {
         devMode: false,
       });
 
-      expect(clientWithoutDevMode.query).toBeDefined();
       expect(clientWithoutDevMode.ingest).toBeDefined();
     });
 
@@ -373,7 +387,6 @@ describe("Project Schema", () => {
         devMode: true,
       });
 
-      expect(client.query).toBeDefined();
       expect(client.ingest).toBeDefined();
     });
 

package/src/schema/project.ts

@@ -8,8 +8,19 @@ 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,
+  DeleteOptions,
+  DeleteResult,
+  QueryOptions,
+  QueryResult,
+  TruncateOptions,
+  TruncateResult,
+} 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 +52,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,16 +86,20 @@ type IngestMethods<T extends DatasourcesDefinition> = {
 };
 
 /**
- * Type for a datasource accessor with append method
+ * Type for a datasource accessor with import/mutation methods
  */
 type DatasourceAccessor = {
   /** Append data from a URL or file */
   append(options: AppendOptions): Promise<AppendResult>;
+  /** Delete rows using a SQL condition */
+  delete(options: DeleteOptions): Promise<DeleteResult>;
+  /** Truncate all rows */
+  truncate(options?: TruncateOptions): Promise<TruncateResult>;
 };
 
 /**
  * Type for datasource accessors object
- * Maps each datasource to an accessor with append method
+ * Maps each datasource to an accessor with import/mutation methods
  */
 type DatasourceAccessors<T extends DatasourcesDefinition> = {
   [K in keyof T]: DatasourceAccessor;
@@ -90,14 +108,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/delete/truncate) */
+  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 +128,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 +264,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 +274,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 +305,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;
 
@@ -329,14 +382,44 @@ function buildProjectClient<
         const client = await getClient();
         return client.datasources.append(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);
+      },
     };
   }
 
   // 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 +435,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 +455,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'),
  * });