@tinybirdco/sdk 0.0.38 → 0.0.39

package/src/api/api.ts

@@ -2,10 +2,14 @@ import { createTinybirdFetcher, type TinybirdFetch } from "./fetcher.js";
 import type {
   AppendOptions,
   AppendResult,
+  DeleteOptions,
+  DeleteResult,
   IngestOptions,
   IngestResult,
   QueryOptions,
   QueryResult,
+  TruncateOptions,
+  TruncateResult,
   TinybirdErrorResponse,
 } from "../client/types.js";
 
@@ -48,6 +52,16 @@ export interface TinybirdApiAppendOptions extends Omit<AppendOptions, 'url' | 'f
   token?: string;
 }
 
+export interface TinybirdApiDeleteOptions extends Omit<DeleteOptions, 'deleteCondition'> {
+  /** Optional token override for this request */
+  token?: string;
+}
+
+export interface TinybirdApiTruncateOptions extends TruncateOptions {
+  /** Optional token override for this request */
+  token?: string;
+}
+
 /**
  * Scope definition for token creation APIs
  */
@@ -369,6 +383,82 @@ export class TinybirdApi {
     return (await response.json()) as AppendResult;
   }
 
+  /**
+   * Delete rows from a datasource using a SQL condition
+   */
+  async deleteDatasource(
+    datasourceName: string,
+    options: DeleteOptions,
+    apiOptions: TinybirdApiDeleteOptions = {}
+  ): Promise<DeleteResult> {
+    const deleteCondition = options.deleteCondition?.trim();
+
+    if (!deleteCondition) {
+      throw new Error("'deleteCondition' must be provided in options");
+    }
+
+    const url = new URL(
+      `/v0/datasources/${encodeURIComponent(datasourceName)}/delete`,
+      `${this.baseUrl}/`
+    );
+
+    const requestBody = new URLSearchParams();
+    requestBody.set("delete_condition", deleteCondition);
+
+    const dryRun = options.dryRun ?? apiOptions.dryRun;
+    if (dryRun !== undefined) {
+      requestBody.set("dry_run", String(dryRun));
+    }
+
+    const response = await this.request(url.toString(), {
+      method: "POST",
+      token: apiOptions.token,
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: requestBody.toString(),
+      signal: this.createAbortSignal(
+        options.timeout ?? apiOptions.timeout,
+        options.signal ?? apiOptions.signal
+      ),
+    });
+
+    if (!response.ok) {
+      await this.handleErrorResponse(response);
+    }
+
+    return (await response.json()) as DeleteResult;
+  }
+
+  /**
+   * Truncate all rows from a datasource
+   */
+  async truncateDatasource(
+    datasourceName: string,
+    options: TruncateOptions = {},
+    apiOptions: TinybirdApiTruncateOptions = {}
+  ): Promise<TruncateResult> {
+    const url = new URL(
+      `/v0/datasources/${encodeURIComponent(datasourceName)}/truncate`,
+      `${this.baseUrl}/`
+    );
+
+    const response = await this.request(url.toString(), {
+      method: "POST",
+      token: apiOptions.token,
+      signal: this.createAbortSignal(
+        options.timeout ?? apiOptions.timeout,
+        options.signal ?? apiOptions.signal
+      ),
+    });
+
+    if (!response.ok) {
+      await this.handleErrorResponse(response);
+    }
+
+    return this.parseOptionalJson(response);
+  }
+
   /**
    * Create a token using Tinybird Token API.
    * Supports both static and JWT token payloads.
@@ -438,6 +528,20 @@ export class TinybirdApi {
     return formData;
   }
 
+  private async parseOptionalJson<T extends object>(response: Response): Promise<T> {
+    const rawBody = await response.text();
+
+    if (!rawBody.trim()) {
+      return {} as T;
+    }
+
+    try {
+      return JSON.parse(rawBody) as T;
+    } catch {
+      return {} as T;
+    }
+  }
+
   private createAbortSignal(
     timeout?: number,
     existingSignal?: AbortSignal

package/src/client/base.test.ts

@@ -156,6 +156,8 @@ describe("TinybirdClient", () => {
       });
 
       expect(typeof client.datasources.append).toBe("function");
+      expect(typeof client.datasources.delete).toBe("function");
+      expect(typeof client.datasources.truncate).toBe("function");
     });
 
     it("datasources conforms to DatasourcesNamespace interface", () => {
@@ -167,6 +169,8 @@ describe("TinybirdClient", () => {
       const datasources: DatasourcesNamespace = client.datasources;
       expect(datasources).toBeDefined();
       expect(typeof datasources.append).toBe("function");
+      expect(typeof datasources.delete).toBe("function");
+      expect(typeof datasources.truncate).toBe("function");
     });
   });
 });

package/src/client/base.ts

@@ -8,10 +8,14 @@ import type {
   ClientConfig,
   ClientContext,
   DatasourcesNamespace,
+  DeleteOptions,
+  DeleteResult,
   QueryResult,
   IngestResult,
   QueryOptions,
   IngestOptions,
+  TruncateOptions,
+  TruncateResult,
 } from "./types.js";
 import { TinybirdError } from "./types.js";
 import { TinybirdApi, TinybirdApiError } from "../api/api.js";
@@ -89,6 +93,15 @@ export class TinybirdClient {
       append: (datasourceName: string, options: AppendOptions): Promise<AppendResult> => {
         return this.appendDatasource(datasourceName, options);
       },
+      delete: (datasourceName: string, options: DeleteOptions): Promise<DeleteResult> => {
+        return this.deleteDatasource(datasourceName, options);
+      },
+      truncate: (
+        datasourceName: string,
+        options: TruncateOptions = {}
+      ): Promise<TruncateResult> => {
+        return this.truncateDatasource(datasourceName, options);
+      },
     };
 
     // Initialize tokens namespace
@@ -133,6 +146,46 @@ export class TinybirdClient {
     }
   }
 
+  /**
+   * Delete rows from a datasource using a SQL condition
+   *
+   * @param datasourceName - Name of the datasource
+   * @param options - Delete options including deleteCondition
+   * @returns Delete job result
+   */
+  private async deleteDatasource(
+    datasourceName: string,
+    options: DeleteOptions
+  ): Promise<DeleteResult> {
+    const token = await this.getToken();
+
+    try {
+      return await this.getApi(token).deleteDatasource(datasourceName, options);
+    } catch (error) {
+      this.rethrowApiError(error);
+    }
+  }
+
+  /**
+   * Truncate all rows from a datasource
+   *
+   * @param datasourceName - Name of the datasource
+   * @param options - Truncate options
+   * @returns Truncate result
+   */
+  private async truncateDatasource(
+    datasourceName: string,
+    options: TruncateOptions = {}
+  ): Promise<TruncateResult> {
+    const token = await this.getToken();
+
+    try {
+      return await this.getApi(token).truncateDatasource(datasourceName, options);
+    } catch (error) {
+      this.rethrowApiError(error);
+    }
+  }
+
   /**
    * Get the effective token, resolving branch token in dev mode if needed
    */

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,6 +235,8 @@ export type {
   TinybirdApiQueryOptions,
   TinybirdApiIngestOptions,
   TinybirdApiAppendOptions,
+  TinybirdApiDeleteOptions,
+  TinybirdApiTruncateOptions,
   TinybirdApiRequestInit,
   TinybirdApiTokenScope,
   TinybirdApiCreateTokenRequest,

package/src/schema/project.test.ts

@@ -94,7 +94,7 @@ describe("Project Schema", () => {
       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() },
       });
@@ -105,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", () => {
@@ -123,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", () => {
@@ -304,7 +310,7 @@ describe("Project Schema", () => {
       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() },
       });
@@ -316,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", () => {
@@ -335,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", () => {

package/src/schema/project.ts

@@ -12,8 +12,12 @@ 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";
@@ -82,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;
@@ -105,7 +113,7 @@ interface ProjectClientBase<TDatasources extends DatasourcesDefinition> {
   ingest: IngestMethods<TDatasources>;
   /** Token operations (JWT creation, etc.) */
   readonly tokens: TokensNamespace;
-  /** Datasource operations (append from URL/file) */
+  /** Datasource operations (append/delete/truncate) */
   readonly datasources: DatasourcesNamespace;
   /** Execute raw SQL queries */
   sql<T = unknown>(sql: string, options?: QueryOptions): Promise<QueryResult<T>>;
@@ -374,6 +382,14 @@ 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);
+      },
     };
   }