@tinybirdco/sdk 0.0.36 → 0.0.38

package/src/client/base.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from "vitest";
 import { TinybirdClient, createClient } from "./base.js";
+import type { DatasourcesNamespace } from "./types.js";
 
 describe("TinybirdClient", () => {
   describe("constructor", () => {
@@ -137,4 +138,35 @@ describe("TinybirdClient", () => {
       expect(context.baseUrl).toBe("https://api.tinybird.co");
     });
   });
+
+  describe("datasources", () => {
+    it("exposes datasources namespace", () => {
+      const client = createClient({
+        baseUrl: "https://api.tinybird.co",
+        token: "test-token",
+      });
+
+      expect(client.datasources).toBeDefined();
+    });
+
+    it("datasources namespace has append method", () => {
+      const client = createClient({
+        baseUrl: "https://api.tinybird.co",
+        token: "test-token",
+      });
+
+      expect(typeof client.datasources.append).toBe("function");
+    });
+
+    it("datasources conforms to DatasourcesNamespace interface", () => {
+      const client = createClient({
+        baseUrl: "https://api.tinybird.co",
+        token: "test-token",
+      });
+
+      const datasources: DatasourcesNamespace = client.datasources;
+      expect(datasources).toBeDefined();
+      expect(typeof datasources.append).toBe("function");
+    });
+  });
 });

package/src/client/base.ts

@@ -3,8 +3,11 @@
  */
 
 import type {
+  AppendOptions,
+  AppendResult,
   ClientConfig,
   ClientContext,
+  DatasourcesNamespace,
   QueryResult,
   IngestResult,
   QueryOptions,
@@ -12,6 +15,7 @@ import type {
 } from "./types.js";
 import { TinybirdError } from "./types.js";
 import { TinybirdApi, TinybirdApiError } from "../api/api.js";
+import { TokensNamespace } from "./tokens.js";
 
 /**
  * Resolved token info from dev mode
@@ -57,6 +61,14 @@ export class TinybirdClient {
   private contextPromise: Promise<ClientContext> | null = null;
   private resolvedContext: ClientContext | null = null;
 
+  /**
+   * Datasources namespace for import operations
+   */
+  readonly datasources: DatasourcesNamespace;
+
+  /** Token operations (JWT creation, etc.) */
+  public readonly tokens: TokensNamespace;
+
   constructor(config: ClientConfig) {
     // Validate required config
     if (!config.baseUrl) {
@@ -71,6 +83,54 @@ export class TinybirdClient {
       ...config,
       baseUrl: config.baseUrl.replace(/\/$/, ""),
     };
+
+    // Initialize datasources namespace
+    this.datasources = {
+      append: (datasourceName: string, options: AppendOptions): Promise<AppendResult> => {
+        return this.appendDatasource(datasourceName, options);
+      },
+    };
+
+    // Initialize tokens namespace
+    this.tokens = new TokensNamespace(
+      () => this.getToken(),
+      this.config.baseUrl,
+      this.config.fetch,
+      this.config.timeout
+    );
+  }
+
+  /**
+   * Append data to a datasource from a URL or local file
+   *
+   * @param datasourceName - Name of the datasource
+   * @param options - Append options including url or file source
+   * @returns Append result
+   *
+   * @example
+   * ```ts
+   * // Append from URL
+   * await client.datasources.append('events', {
+   *   url: 'https://example.com/data.csv',
+   * });
+   *
+   * // Append from local file
+   * await client.datasources.append('events', {
+   *   file: './data/events.ndjson',
+   * });
+   * ```
+   */
+  private async appendDatasource(
+    datasourceName: string,
+    options: AppendOptions
+  ): Promise<AppendResult> {
+    const token = await this.getToken();
+
+    try {
+      return await this.getApi(token).appendDatasource(datasourceName, options);
+    } catch (error) {
+      this.rethrowApiError(error);
+    }
   }
 
   /**

package/src/client/tokens.test.ts

@@ -0,0 +1,103 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { TinybirdClient } from "./base.js";
+
+const mockFetch = vi.fn();
+global.fetch = mockFetch;
+
+describe("TokensNamespace", () => {
+  beforeEach(() => {
+    mockFetch.mockReset();
+  });
+
+  it("uses client custom fetch for createJWT", async () => {
+    const customFetch = vi.fn().mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ token: "jwt-token" }),
+    });
+
+    const client = new TinybirdClient({
+      baseUrl: "https://api.tinybird.co",
+      token: "p.admin-token",
+      fetch: customFetch as typeof fetch,
+    });
+
+    const result = await client.tokens.createJWT({
+      name: "user_token",
+      expiresAt: 1700000000,
+      scopes: [{ type: "PIPES:READ", resource: "analytics_pipe" }],
+    });
+
+    expect(result).toEqual({ token: "jwt-token" });
+    expect(customFetch).toHaveBeenCalledTimes(1);
+    expect(mockFetch).not.toHaveBeenCalled();
+
+    const [url, init] = customFetch.mock.calls[0] as [string, RequestInit];
+    const parsed = new URL(url);
+    expect(parsed.pathname).toBe("/v0/tokens/");
+    expect(parsed.searchParams.get("expiration_time")).toBe("1700000000");
+    expect(parsed.searchParams.get("from")).toBe("ts-sdk");
+    expect(init.method).toBe("POST");
+    const headers = new Headers(init.headers);
+    expect(headers.get("Authorization")).toBe("Bearer p.admin-token");
+    expect(headers.get("Content-Type")).toBe("application/json");
+
+    const body = JSON.parse(String(init.body)) as {
+      name: string;
+      scopes: Array<{ type: string; resource: string }>;
+      limits?: { rps?: number };
+    };
+    expect(body).toEqual({
+      name: "user_token",
+      scopes: [{ type: "PIPES:READ", resource: "analytics_pipe" }],
+    });
+  });
+
+  it("sends full JWT payload when limits and scope fields are provided", async () => {
+    const customFetch = vi.fn().mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ token: "jwt-token" }),
+    });
+
+    const client = new TinybirdClient({
+      baseUrl: "https://api.tinybird.co",
+      token: "p.admin-token",
+      fetch: customFetch as typeof fetch,
+    });
+
+    await client.tokens.createJWT({
+      name: "tenant_token",
+      expiresAt: 1700000000,
+      scopes: [
+        {
+          type: "PIPES:READ",
+          resource: "analytics_pipe",
+          fixed_params: { tenant_id: 123 },
+        },
+      ],
+      limits: { rps: 10 },
+    });
+
+    const [, init] = customFetch.mock.calls[0] as [string, RequestInit];
+    const body = JSON.parse(String(init.body)) as {
+      name: string;
+      scopes: Array<{
+        type: string;
+        resource: string;
+        fixed_params?: Record<string, unknown>;
+      }>;
+      limits?: { rps?: number };
+    };
+
+    expect(body).toEqual({
+      name: "tenant_token",
+      scopes: [
+        {
+          type: "PIPES:READ",
+          resource: "analytics_pipe",
+          fixed_params: { tenant_id: 123 },
+        },
+      ],
+      limits: { rps: 10 },
+    });
+  });
+});

package/src/client/tokens.ts

@@ -0,0 +1,69 @@
+/**
+ * Token operations namespace for TinybirdClient
+ */
+
+import type { CreateJWTOptions, CreateJWTResult } from "../api/tokens.js";
+import { createJWT as apiCreateJWT, TokenApiError } from "../api/tokens.js";
+import { TinybirdError } from "./types.js";
+
+/**
+ * Token operations namespace for TinybirdClient
+ */
+export class TokensNamespace {
+  constructor(
+    private readonly getToken: () => Promise<string>,
+    private readonly baseUrl: string,
+    private readonly fetchFn?: typeof globalThis.fetch,
+    private readonly timeout?: number
+  ) {}
+
+  /**
+   * Create a JWT token
+   *
+   * Creates a short-lived JWT token with specific scopes for secure,
+   * time-limited access to pipes and datasources.
+   *
+   * @param options - JWT creation options
+   * @returns The created JWT token
+   *
+   * @example
+   * ```ts
+   * const result = await client.tokens.createJWT({
+   *   name: "user_123_token",
+   *   expiresAt: new Date(Date.now() + 3600 * 1000), // 1 hour
+   *   scopes: [
+   *     {
+   *       type: "PIPES:READ",
+   *       resource: "user_analytics",
+   *       fixed_params: { user_id: 123 },
+   *     },
+   *   ],
+   * });
+   *
+   * console.log(result.token); // "eyJ..."
+   * ```
+   */
+  async createJWT(options: CreateJWTOptions): Promise<CreateJWTResult> {
+    const token = await this.getToken();
+
+    try {
+      return await apiCreateJWT(
+        {
+          baseUrl: this.baseUrl,
+          token,
+          fetch: this.fetchFn,
+          timeout: this.timeout,
+        },
+        options
+      );
+    } catch (error) {
+      if (error instanceof TokenApiError) {
+        throw new TinybirdError(error.message, error.status, {
+          error: error.message,
+          status: error.status,
+        });
+      }
+      throw error;
+    }
+  }
+}

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,7 +230,12 @@ export type {
   TinybirdApiConfig,
   TinybirdApiQueryOptions,
   TinybirdApiIngestOptions,
+  TinybirdApiAppendOptions,
   TinybirdApiRequestInit,
+  TinybirdApiTokenScope,
+  TinybirdApiCreateTokenRequest,
+  TinybirdApiCreateTokenOptions,
+  TinybirdApiCreateTokenResult,
 } from "./api/api.js";
 
 // ============ Preview Environment ============
@@ -246,6 +255,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,11 +86,43 @@ 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", () => {
+      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", () => {
@@ -113,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'
       );
@@ -246,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() },
       });
@@ -262,11 +294,47 @@ 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", () => {
+      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", () => {
@@ -281,7 +349,6 @@ describe("Project Schema", () => {
         devMode: true,
       });
 
-      expect(clientWithDevMode.query).toBeDefined();
       expect(clientWithDevMode.ingest).toBeDefined();
 
       const clientWithoutDevMode = createTinybirdClient({
@@ -290,7 +357,6 @@ describe("Project Schema", () => {
         devMode: false,
       });
 
-      expect(clientWithoutDevMode.query).toBeDefined();
       expect(clientWithoutDevMode.ingest).toBeDefined();
     });
 
@@ -309,7 +375,6 @@ describe("Project Schema", () => {
         devMode: true,
       });
 
-      expect(client.query).toBeDefined();
       expect(client.ingest).toBeDefined();
     });