@tinybirdco/sdk 0.0.35 → 0.0.37

package/src/client/types.ts

@@ -189,3 +189,57 @@ export interface TypedDatasourceIngest<TRow> {
   /** Send multiple events in a batch */
   sendBatch(events: TRow[], options?: IngestOptions): Promise<IngestResult>;
 }
+
+/**
+ * Data format for append operations
+ */
+export type AppendFormat = "csv" | "ndjson" | "parquet";
+
+/**
+ * CSV dialect options for customizing CSV parsing
+ */
+export interface CsvDialectOptions {
+  /** Field delimiter character (default: ',') */
+  delimiter?: string;
+  /** New line character(s) (default: '\n') */
+  newLine?: string;
+  /** Escape character for special characters */
+  escapeChar?: string;
+}
+
+/**
+ * Options for append operation
+ * Exactly one of `url` or `file` must be provided
+ */
+export interface AppendOptions {
+  /** Remote URL to import data from */
+  url?: string;
+  /** Local file path to import data from */
+  file?: string;
+  /** CSV dialect options (only applicable for csv format) */
+  csvDialect?: CsvDialectOptions;
+  /** Request timeout in milliseconds */
+  timeout?: number;
+  /** AbortController signal for cancellation */
+  signal?: AbortSignal;
+}
+
+/**
+ * Result of an append operation
+ */
+export interface AppendResult {
+  /** Number of rows successfully appended */
+  successful_rows: number;
+  /** Number of rows that failed to append (quarantined) */
+  quarantined_rows: number;
+  /** Import ID for tracking */
+  import_id?: 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>;
+}

package/src/index.ts

@@ -202,8 +202,12 @@ export type {
 export { TinybirdClient, createClient } from "./client/base.js";
 export { TinybirdError } from "./client/types.js";
 export type {
+  AppendOptions,
+  AppendResult,
   ClientConfig,
   ClientContext,
+  CsvDialectOptions,
+  DatasourcesNamespace,
   QueryResult,
   IngestResult,
   QueryOptions,
@@ -226,6 +230,7 @@ export type {
   TinybirdApiConfig,
   TinybirdApiQueryOptions,
   TinybirdApiIngestOptions,
+  TinybirdApiAppendOptions,
   TinybirdApiRequestInit,
 } from "./api/api.js";
 

package/src/schema/project.test.ts

@@ -93,6 +93,37 @@ describe("Project Schema", () => {
       expect(typeof project.tinybird.ingest.eventsBatch).toBe("function");
     });
 
+    it("creates datasource accessors with append method", () => {
+      const events = defineDatasource("events", {
+        schema: { timestamp: t.dateTime() },
+      });
+
+      const project = defineProject({
+        datasources: { events },
+      });
+
+      expect(project.tinybird.events).toBeDefined();
+      expect(typeof project.tinybird.events.append).toBe("function");
+    });
+
+    it("creates multiple datasource accessors", () => {
+      const events = defineDatasource("events", {
+        schema: { timestamp: t.dateTime() },
+      });
+      const pageViews = defineDatasource("page_views", {
+        schema: { pathname: t.string() },
+      });
+
+      const project = defineProject({
+        datasources: { events, pageViews },
+      });
+
+      expect(project.tinybird.events).toBeDefined();
+      expect(project.tinybird.pageViews).toBeDefined();
+      expect(typeof project.tinybird.events.append).toBe("function");
+      expect(typeof project.tinybird.pageViews.append).toBe("function");
+    });
+
     it("throws error when accessing client before initialization", () => {
       const project = defineProject({});
 
@@ -269,6 +300,39 @@ describe("Project Schema", () => {
       expect(typeof client.ingest.eventsBatch).toBe("function");
     });
 
+    it("creates datasource accessors with append method", () => {
+      const events = defineDatasource("events", {
+        schema: { id: t.string() },
+      });
+
+      const client = createTinybirdClient({
+        datasources: { events },
+        pipes: {},
+      });
+
+      expect(client.events).toBeDefined();
+      expect(typeof client.events.append).toBe("function");
+    });
+
+    it("creates multiple datasource accessors", () => {
+      const events = defineDatasource("events", {
+        schema: { id: t.string() },
+      });
+      const pageViews = defineDatasource("page_views", {
+        schema: { pathname: t.string() },
+      });
+
+      const client = createTinybirdClient({
+        datasources: { events, pageViews },
+        pipes: {},
+      });
+
+      expect(client.events).toBeDefined();
+      expect(client.pageViews).toBeDefined();
+      expect(typeof client.events.append).toBe("function");
+      expect(typeof client.pageViews.append).toBe("function");
+    });
+
     it("accepts devMode option", () => {
       const events = defineDatasource("events", {
         schema: { id: t.string() },

package/src/schema/project.ts

@@ -8,7 +8,7 @@ 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, QueryResult } from "../client/types.js";
 import type { InferRow, InferParams, InferOutputRow } from "../infer/index.js";
 
 // Symbol for brand typing - use Symbol.for() for global registry
@@ -72,9 +72,25 @@ type IngestMethods<T extends DatasourcesDefinition> = {
 };
 
 /**
- * Typed client interface for a project
+ * Type for a datasource accessor with append method
+ */
+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
  */
-export interface ProjectClient<
+type DatasourceAccessors<T extends DatasourcesDefinition> = {
+  [K in keyof T]: DatasourceAccessor;
+};
+
+/**
+ * Base project client interface
+ */
+interface ProjectClientBase<
   TDatasources extends DatasourcesDefinition,
   TPipes extends PipesDefinition
 > {
@@ -86,6 +102,15 @@ export interface ProjectClient<
   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, TPipes> & DatasourceAccessors<TDatasources>;
+
 /**
  * Configuration for createTinybirdClient
  */
@@ -294,8 +319,22 @@ 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 {
+    ...datasourceAccessors,
     query: queryMethods,
     ingest: ingestMethods,
     get client(): TinybirdClient {