@tinybirdco/sdk 0.0.37 → 0.0.38

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/client/base.ts

@@ -15,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
@@ -65,6 +66,9 @@ export class TinybirdClient {
    */
   readonly datasources: DatasourcesNamespace;
 
+  /** Token operations (JWT creation, etc.) */
+  public readonly tokens: TokensNamespace;
+
   constructor(config: ClientConfig) {
     // Validate required config
     if (!config.baseUrl) {
@@ -86,6 +90,14 @@ export class TinybirdClient {
         return this.appendDatasource(datasourceName, options);
       },
     };
+
+    // Initialize tokens namespace
+    this.tokens = new TokensNamespace(
+      () => this.getToken(),
+      this.config.baseUrl,
+      this.config.fetch,
+      this.config.timeout
+    );
   }
 
   /**

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/index.ts

@@ -232,6 +232,10 @@ export type {
   TinybirdApiIngestOptions,
   TinybirdApiAppendOptions,
   TinybirdApiRequestInit,
+  TinybirdApiTokenScope,
+  TinybirdApiCreateTokenRequest,
+  TinybirdApiCreateTokenOptions,
+  TinybirdApiCreateTokenResult,
 } from "./api/api.js";
 
 // ============ Preview Environment ============
@@ -251,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";