@tinybirdco/sdk 0.0.36 → 0.0.38

package/src/api/api.ts

@@ -1,5 +1,7 @@
 import { createTinybirdFetcher, type TinybirdFetch } from "./fetcher.js";
 import type {
+  AppendOptions,
+  AppendResult,
   IngestOptions,
   IngestResult,
   QueryOptions,
@@ -41,6 +43,59 @@ export interface TinybirdApiIngestOptions extends IngestOptions {
   token?: string;
 }
 
+export interface TinybirdApiAppendOptions extends Omit<AppendOptions, 'url' | 'file'> {
+  /** Optional token override for this request */
+  token?: string;
+}
+
+/**
+ * Scope definition for token creation APIs
+ */
+export interface TinybirdApiTokenScope {
+  type: string;
+  resource?: string;
+  fixed_params?: Record<string, string | number | boolean>;
+  filter?: string;
+}
+
+/**
+ * Request body for creating Tinybird tokens.
+ * Supports JWT-style scopes and static-token scope strings.
+ */
+export interface TinybirdApiCreateTokenRequest {
+  /** Token name/identifier */
+  name: string;
+  /** JWT-style scopes */
+  scopes?: TinybirdApiTokenScope[];
+  /** Static-token scope strings */
+  scope?: string | string[];
+  /** Optional rate-limiting config */
+  limits?: {
+    rps?: number;
+  };
+}
+
+/**
+ * Options for token creation requests
+ */
+export interface TinybirdApiCreateTokenOptions {
+  /** Optional expiration time for JWT tokens */
+  expirationTime?: number;
+  /** Optional token override for this request */
+  token?: string;
+  /** Request timeout in milliseconds */
+  timeout?: number;
+  /** AbortController signal for cancellation */
+  signal?: AbortSignal;
+}
+
+/**
+ * Result of token creation
+ */
+export interface TinybirdApiCreateTokenResult {
+  token: string;
+}
+
 /**
  * Error thrown by TinybirdApi when a response is not OK
  */
@@ -242,6 +297,147 @@ export class TinybirdApi {
     return (await response.json()) as QueryResult<T>;
   }
 
+  /**
+   * Append data to a datasource from a URL or local file
+   */
+  async appendDatasource(
+    datasourceName: string,
+    options: AppendOptions,
+    apiOptions: TinybirdApiAppendOptions = {}
+  ): Promise<AppendResult> {
+    const { url: sourceUrl, file: filePath } = options;
+
+    if (!sourceUrl && !filePath) {
+      throw new Error("Either 'url' or 'file' must be provided in options");
+    }
+
+    if (sourceUrl && filePath) {
+      throw new Error("Only one of 'url' or 'file' can be provided, not both");
+    }
+
+    const url = new URL("/v0/datasources", `${this.baseUrl}/`);
+    url.searchParams.set("name", datasourceName);
+    url.searchParams.set("mode", "append");
+
+    // Auto-detect format from file/url extension
+    const format = this.detectFormat(sourceUrl ?? filePath!);
+    if (format) {
+      url.searchParams.set("format", format);
+    }
+
+    // Add CSV dialect options if applicable
+    if (options.csvDialect) {
+      if (options.csvDialect.delimiter) {
+        url.searchParams.set("dialect_delimiter", options.csvDialect.delimiter);
+      }
+      if (options.csvDialect.newLine) {
+        url.searchParams.set("dialect_new_line", options.csvDialect.newLine);
+      }
+      if (options.csvDialect.escapeChar) {
+        url.searchParams.set("dialect_escapechar", options.csvDialect.escapeChar);
+      }
+    }
+
+    let response: Response;
+
+    if (sourceUrl) {
+      // Remote URL: send as form-urlencoded with url parameter
+      response = await this.request(url.toString(), {
+        method: "POST",
+        token: apiOptions.token,
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: `url=${encodeURIComponent(sourceUrl)}`,
+        signal: this.createAbortSignal(options.timeout ?? apiOptions.timeout, options.signal ?? apiOptions.signal),
+      });
+    } else {
+      // Local file: send as multipart form data
+      const formData = await this.createFileFormData(filePath!);
+      response = await this.request(url.toString(), {
+        method: "POST",
+        token: apiOptions.token,
+        body: formData,
+        signal: this.createAbortSignal(options.timeout ?? apiOptions.timeout, options.signal ?? apiOptions.signal),
+      });
+    }
+
+    if (!response.ok) {
+      await this.handleErrorResponse(response);
+    }
+
+    return (await response.json()) as AppendResult;
+  }
+
+  /**
+   * Create a token using Tinybird Token API.
+   * Supports both static and JWT token payloads.
+   */
+  async createToken(
+    body: TinybirdApiCreateTokenRequest,
+    options: TinybirdApiCreateTokenOptions = {}
+  ): Promise<TinybirdApiCreateTokenResult> {
+    const url = new URL("/v0/tokens/", `${this.baseUrl}/`);
+
+    if (options.expirationTime !== undefined) {
+      url.searchParams.set("expiration_time", String(options.expirationTime));
+    }
+
+    const response = await this.request(url.toString(), {
+      method: "POST",
+      token: options.token,
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+      signal: this.createAbortSignal(options.timeout, options.signal),
+    });
+
+    if (!response.ok) {
+      await this.handleErrorResponse(response);
+    }
+
+    return (await response.json()) as TinybirdApiCreateTokenResult;
+  }
+
+  /**
+   * Detect format from file path or URL extension
+   */
+  private detectFormat(source: string): "csv" | "ndjson" | "parquet" | undefined {
+    // Remove query string if present
+    const pathOnly = source.split("?")[0];
+    const extension = pathOnly.split(".").pop()?.toLowerCase();
+
+    switch (extension) {
+      case "csv":
+        return "csv";
+      case "ndjson":
+      case "jsonl":
+        return "ndjson";
+      case "parquet":
+        return "parquet";
+      default:
+        return undefined;
+    }
+  }
+
+  /**
+   * Create FormData for file upload
+   */
+  private async createFileFormData(filePath: string): Promise<FormData> {
+    // Dynamic import for Node.js fs module (browser-safe)
+    const fs = await import("node:fs");
+    const path = await import("node:path");
+
+    const fileContent = await fs.promises.readFile(filePath);
+    const fileName = path.basename(filePath);
+
+    const formData = new FormData();
+    formData.append("csv", new Blob([fileContent]), fileName);
+
+    return formData;
+  }
+
   private createAbortSignal(
     timeout?: number,
     existingSignal?: AbortSignal

package/src/api/tokens.test.ts

@@ -0,0 +1,253 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  createJWT,
+  TokenApiError,
+  type TokenApiConfig,
+} from "./tokens.js";
+
+// Mock fetch globally
+const mockFetch = vi.fn();
+global.fetch = mockFetch;
+
+function expectFromParam(url: string) {
+  const parsed = new URL(url);
+  expect(parsed.searchParams.get("from")).toBe("ts-sdk");
+  return parsed;
+}
+
+describe("Token API client", () => {
+  const config: TokenApiConfig = {
+    baseUrl: "https://api.tinybird.co",
+    token: "p.admin-token",
+  };
+
+  beforeEach(() => {
+    mockFetch.mockReset();
+  });
+
+  describe("createJWT", () => {
+    it("creates a JWT token with scopes", async () => {
+      const mockResponse = { token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.test" };
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve(mockResponse),
+      });
+
+      const result = await createJWT(config, {
+        name: "user_token",
+        expiresAt: 1700000000,
+        scopes: [
+          {
+            type: "PIPES:READ",
+            resource: "analytics_pipe",
+            fixed_params: { user_id: 123 },
+          },
+        ],
+      });
+
+      expect(result.token).toBe(mockResponse.token);
+
+      const [url, init] = mockFetch.mock.calls[0];
+      const parsed = expectFromParam(url);
+      expect(parsed.pathname).toBe("/v0/tokens/");
+      expect(parsed.searchParams.get("expiration_time")).toBe("1700000000");
+      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(init.body);
+      expect(body.name).toBe("user_token");
+      expect(body.scopes).toHaveLength(1);
+      expect(body.scopes[0].type).toBe("PIPES:READ");
+      expect(body.scopes[0].resource).toBe("analytics_pipe");
+      expect(body.scopes[0].fixed_params).toEqual({ user_id: 123 });
+    });
+
+    it("converts Date to Unix timestamp", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ token: "jwt-token" }),
+      });
+
+      const expirationDate = new Date("2024-01-01T00:00:00Z");
+      await createJWT(config, {
+        name: "test",
+        expiresAt: expirationDate,
+        scopes: [{ type: "PIPES:READ", resource: "pipe" }],
+      });
+
+      const [url] = mockFetch.mock.calls[0];
+      const parsed = new URL(url);
+      expect(parsed.searchParams.get("expiration_time")).toBe("1704067200");
+    });
+
+    it("converts ISO string to Unix timestamp", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ token: "jwt-token" }),
+      });
+
+      await createJWT(config, {
+        name: "test",
+        expiresAt: "2024-01-01T00:00:00Z",
+        scopes: [{ type: "PIPES:READ", resource: "pipe" }],
+      });
+
+      const [url] = mockFetch.mock.calls[0];
+      const parsed = new URL(url);
+      expect(parsed.searchParams.get("expiration_time")).toBe("1704067200");
+    });
+
+    it("includes limits when provided", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ token: "jwt-token" }),
+      });
+
+      await createJWT(config, {
+        name: "rate_limited_token",
+        expiresAt: 1700000000,
+        scopes: [{ type: "PIPES:READ", resource: "pipe" }],
+        limits: { rps: 100 },
+      });
+
+      const [, init] = mockFetch.mock.calls[0];
+      const body = JSON.parse(init.body);
+      expect(body.limits).toEqual({ rps: 100 });
+    });
+
+    it("uses custom fetch implementation when provided", async () => {
+      const customFetch = vi.fn().mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ token: "jwt-token" }),
+      });
+
+      await createJWT(
+        {
+          ...config,
+          fetch: customFetch as typeof fetch,
+        },
+        {
+          name: "custom_fetch_token",
+          expiresAt: 1700000000,
+          scopes: [{ type: "PIPES:READ", resource: "pipe" }],
+        }
+      );
+
+      expect(customFetch).toHaveBeenCalledTimes(1);
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+
+    it("supports datasource scope with filter", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ token: "jwt-token" }),
+      });
+
+      await createJWT(config, {
+        name: "filtered_token",
+        expiresAt: 1700000000,
+        scopes: [
+          {
+            type: "DATASOURCES:READ",
+            resource: "events",
+            filter: "org_id = 'acme'",
+          },
+        ],
+      });
+
+      const [, init] = mockFetch.mock.calls[0];
+      const body = JSON.parse(init.body);
+      expect(body.scopes[0].filter).toBe("org_id = 'acme'");
+    });
+
+    it("throws TokenApiError on 403 with helpful message", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 403,
+        statusText: "Forbidden",
+        text: () => Promise.resolve("Insufficient permissions"),
+      });
+
+      await expect(
+        createJWT(config, {
+          name: "test",
+          expiresAt: 1700000000,
+          scopes: [],
+        })
+      ).rejects.toThrow(TokenApiError);
+
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 403,
+        statusText: "Forbidden",
+        text: () => Promise.resolve("Insufficient permissions"),
+      });
+
+      try {
+        await createJWT(config, {
+          name: "test",
+          expiresAt: 1700000000,
+          scopes: [],
+        });
+      } catch (error) {
+        expect((error as TokenApiError).status).toBe(403);
+        expect((error as TokenApiError).message).toContain("TOKENS or ADMIN scope");
+      }
+    });
+
+    it("throws TokenApiError on 400 with validation error", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 400,
+        statusText: "Bad Request",
+        text: () => Promise.resolve('{"error": "Invalid scope type"}'),
+      });
+
+      await expect(
+        createJWT(config, {
+          name: "test",
+          expiresAt: 1700000000,
+          scopes: [],
+        })
+      ).rejects.toThrow(TokenApiError);
+
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 400,
+        statusText: "Bad Request",
+        text: () => Promise.resolve('{"error": "Invalid scope type"}'),
+      });
+
+      try {
+        await createJWT(config, {
+          name: "test",
+          expiresAt: 1700000000,
+          scopes: [],
+        });
+      } catch (error) {
+        expect((error as TokenApiError).status).toBe(400);
+        expect((error as TokenApiError).message).toContain("Invalid scope type");
+      }
+    });
+
+    it("does not include limits if not provided", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ token: "jwt-token" }),
+      });
+
+      await createJWT(config, {
+        name: "simple_token",
+        expiresAt: 1700000000,
+        scopes: [{ type: "PIPES:READ", resource: "pipe" }],
+      });
+
+      const [, init] = mockFetch.mock.calls[0];
+      const body = JSON.parse(init.body);
+      expect(body.limits).toBeUndefined();
+    });
+  });
+});

package/src/api/tokens.ts

@@ -0,0 +1,169 @@
+/**
+ * Tinybird Token API client
+ */
+
+import {
+  createTinybirdApi,
+  TinybirdApiError,
+} from "./api.js";
+
+/**
+ * API configuration for token operations.
+ * Requires a token with TOKENS or ADMIN scope.
+ */
+export interface TokenApiConfig {
+  /** Tinybird API base URL */
+  baseUrl: string;
+  /** Workspace token with TOKENS or ADMIN scope */
+  token: string;
+  /** Custom fetch implementation (optional, defaults to global fetch) */
+  fetch?: typeof fetch;
+  /** Default timeout in milliseconds (optional) */
+  timeout?: number;
+}
+
+/**
+ * Error thrown by token API operations
+ */
+export class TokenApiError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+    public readonly body?: unknown
+  ) {
+    super(message);
+    this.name = "TokenApiError";
+  }
+}
+
+/**
+ * Scope type for JWT tokens
+ */
+export type JWTScopeType =
+  | "PIPES:READ"
+  | "DATASOURCES:READ"
+  | "DATASOURCES:APPEND";
+
+/**
+ * A scope definition for JWT tokens
+ */
+export interface JWTScope {
+  /** The type of access being granted */
+  type: JWTScopeType;
+  /** The resource name (pipe or datasource) */
+  resource: string;
+  /** Fixed parameters embedded in the JWT (for pipes) */
+  fixed_params?: Record<string, string | number | boolean>;
+  /** SQL filter expression (for datasources) */
+  filter?: string;
+}
+
+/**
+ * Rate limiting configuration for JWT tokens
+ */
+export interface JWTLimits {
+  /** Requests per second limit */
+  rps?: number;
+}
+
+/**
+ * Options for creating a JWT token
+ */
+export interface CreateJWTOptions {
+  /** Token name/identifier */
+  name: string;
+  /** Expiration time as Date, Unix timestamp (number), or ISO string */
+  expiresAt: Date | number | string;
+  /** Array of scopes defining access permissions */
+  scopes: JWTScope[];
+  /** Optional rate limiting configuration */
+  limits?: JWTLimits;
+}
+
+/**
+ * Result of creating a JWT token
+ */
+export interface CreateJWTResult {
+  /** The generated JWT token string */
+  token: string;
+}
+
+/**
+ * Request body for creating a JWT token
+ */
+interface CreateJWTRequestBody {
+  name: string;
+  scopes: JWTScope[];
+  limits?: JWTLimits;
+}
+
+/**
+ * Convert expiration input to Unix timestamp
+ */
+function toUnixTimestamp(expiresAt: Date | number | string): number {
+  if (typeof expiresAt === "number") {
+    return expiresAt;
+  }
+  if (expiresAt instanceof Date) {
+    return Math.floor(expiresAt.getTime() / 1000);
+  }
+  return Math.floor(new Date(expiresAt).getTime() / 1000);
+}
+
+/**
+ * Create a JWT token
+ * POST /v0/tokens/?expiration_time={unix_timestamp}
+ *
+ * @param config - API configuration (requires TOKENS or ADMIN scope)
+ * @param options - JWT creation options
+ * @returns The created JWT token
+ */
+export async function createJWT(
+  config: TokenApiConfig,
+  options: CreateJWTOptions
+): Promise<CreateJWTResult> {
+  const expirationTime = toUnixTimestamp(options.expiresAt);
+
+  const body: CreateJWTRequestBody = {
+    name: options.name,
+    scopes: options.scopes,
+  };
+
+  if (options.limits) {
+    body.limits = options.limits;
+  }
+
+  const api = createTinybirdApi({
+    baseUrl: config.baseUrl,
+    token: config.token,
+    fetch: config.fetch,
+    timeout: config.timeout,
+  });
+
+  try {
+    const result = await api.createToken(body, {
+      expirationTime,
+    });
+    return { token: result.token };
+  } catch (error) {
+    if (!(error instanceof TinybirdApiError)) {
+      throw error;
+    }
+
+    const responseBody = error.responseBody ?? error.message;
+    let message: string;
+
+    if (error.statusCode === 403) {
+      message =
+        `Permission denied creating JWT token. ` +
+        `Make sure the token has TOKENS or ADMIN scope. ` +
+        `API response: ${responseBody}`;
+    } else if (error.statusCode === 400) {
+      message = `Invalid JWT token request: ${responseBody}`;
+    } else {
+      message = `Failed to create JWT token: ${error.statusCode}. API response: ${responseBody}`;
+    }
+
+    throw new TokenApiError(message, error.statusCode, responseBody);
+  }
+}

package/src/cli/commands/init.ts

@@ -22,7 +22,6 @@ import { getGitRoot } from "../git.js";
 import { fetchAllResources } from "../../api/resources.js";
 import { generateCombinedFile } from "../../codegen/index.js";
 import { execSync } from "child_process";
-import { setTimeout as sleep } from "node:timers/promises";
 import {
   detectPackageManager,
   getPackageManagerAddCmd,
@@ -313,6 +312,8 @@ export interface InitOptions {
   includeCdWorkflow?: boolean;
   /** Git provider for workflow templates */
   workflowProvider?: "github" | "gitlab";
+  /** Skip auto-installing @tinybirdco/sdk dependency */
+  skipDependencyInstall?: boolean;
 }
 
 /**
@@ -415,6 +416,8 @@ export async function runInit(options: InitOptions = {}): Promise<InitResult> {
   const cwd = options.cwd ?? process.cwd();
   const force = options.force ?? false;
   const skipLogin = options.skipLogin ?? false;
+  const skipDependencyInstall =
+    options.skipDependencyInstall ?? Boolean(process.env.VITEST);
 
   const created: string[] = [];
   const skipped: string[] = [];
@@ -739,14 +742,13 @@ export async function runInit(options: InitOptions = {}): Promise<InitResult> {
   }
 
   // Install @tinybirdco/sdk if not already installed
-  if (!hasTinybirdSdkDependency(cwd)) {
+  if (!skipDependencyInstall && !hasTinybirdSdkDependency(cwd)) {
     const s = p.spinner();
     s.start("Installing dependencies");
     const packageManager = detectPackageManager(cwd);
     const addCmd = getPackageManagerAddCmd(packageManager);
     try {
       execSync(`${addCmd} @tinybirdco/sdk`, { cwd, stdio: "pipe" });
-      await sleep(1000);
       s.stop("Installed dependencies");
       created.push("@tinybirdco/sdk");
     } catch (error) {