@tinybirdco/sdk 0.0.1

package/src/api/branches.ts

@@ -0,0 +1,334 @@
+/**
+ * Tinybird Branch (Environment) API client
+ * Uses the /v1/environments endpoints (Forward API)
+ */
+
+/**
+ * Branch information from Tinybird API
+ */
+export interface TinybirdBranch {
+  /** Branch ID */
+  id: string;
+  /** Branch name */
+  name: string;
+  /** Branch token (only present when requested with with_token=true) */
+  token?: string;
+  /** When the branch was created */
+  created_at: string;
+}
+
+/**
+ * Result of getOrCreateBranch operation
+ */
+export interface GetOrCreateBranchResult extends TinybirdBranch {
+  /** Whether the branch was newly created (vs already existed) */
+  wasCreated: boolean;
+}
+
+/**
+ * API configuration for branch operations
+ */
+export interface BranchApiConfig {
+  /** Tinybird API base URL */
+  baseUrl: string;
+  /** Parent workspace token (used to create/manage branches) */
+  token: string;
+}
+
+/**
+ * Job response from async operations
+ */
+interface JobResponse {
+  job: {
+    id: string;
+    status: string;
+    job_url?: string;
+  };
+  workspace?: {
+    id: string;
+  };
+}
+
+/**
+ * Job status response
+ */
+interface JobStatusResponse {
+  id: string;
+  status: "waiting" | "working" | "done" | "error";
+  error?: string;
+}
+
+/**
+ * Error thrown by branch API operations
+ */
+export class BranchApiError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+    public readonly body?: unknown
+  ) {
+    super(message);
+    this.name = "BranchApiError";
+  }
+}
+
+/**
+ * Poll a job until it completes
+ *
+ * @param config - API configuration
+ * @param jobId - Job ID to poll
+ * @param maxAttempts - Maximum polling attempts (default: 120, i.e. 2 minutes)
+ * @param intervalMs - Polling interval in milliseconds (default: 1000)
+ * @returns Job status when complete
+ */
+async function pollJob(
+  config: BranchApiConfig,
+  jobId: string,
+  maxAttempts = 120,
+  intervalMs = 1000
+): Promise<JobStatusResponse> {
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const url = new URL(`/v0/jobs/${jobId}`, config.baseUrl);
+
+    const response = await fetch(url.toString(), {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${config.token}`,
+      },
+    });
+
+    if (!response.ok) {
+      const body = await response.text();
+      throw new BranchApiError(
+        `Failed to poll job '${jobId}': ${response.status} ${response.statusText}\nAPI response: ${body}`,
+        response.status,
+        body
+      );
+    }
+
+    const jobStatus = (await response.json()) as JobStatusResponse;
+
+    if (jobStatus.status === "done") {
+      return jobStatus;
+    }
+
+    if (jobStatus.status === "error") {
+      throw new BranchApiError(
+        `Job '${jobId}' failed: ${jobStatus.error ?? "Unknown error"}`,
+        500,
+        jobStatus
+      );
+    }
+
+    // Wait before next poll
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+
+  throw new BranchApiError(
+    `Job '${jobId}' timed out after ${maxAttempts} attempts`,
+    408
+  );
+}
+
+/**
+ * Create a new branch
+ * POST /v1/environments?name={name}
+ *
+ * This is an async operation that returns a job. We poll the job until
+ * it completes, then fetch the branch with its token.
+ *
+ * @param config - API configuration
+ * @param name - Branch name to create
+ * @returns The created branch with token
+ */
+export async function createBranch(
+  config: BranchApiConfig,
+  name: string
+): Promise<TinybirdBranch> {
+  const url = new URL("/v1/environments", config.baseUrl);
+  url.searchParams.set("name", name);
+
+  const response = await fetch(url.toString(), {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${config.token}`,
+    },
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+
+    // Provide helpful error message for common cases, but include raw response for debugging
+    let message = `Failed to create branch '${name}': ${response.status} ${response.statusText}`;
+    if (response.status === 403) {
+      message = `Permission denied creating branch '${name}'. ` +
+        `Make sure TINYBIRD_TOKEN is a workspace admin token (not a branch token). ` +
+        `Branch tokens cannot create new branches.\n` +
+        `API response: ${body}`;
+    } else if (response.status === 409) {
+      message = `Branch '${name}' already exists.`;
+    } else {
+      message += `\nAPI response: ${body}`;
+    }
+
+    throw new BranchApiError(message, response.status, body);
+  }
+
+  // Parse the job response
+  const jobResponse = (await response.json()) as JobResponse;
+
+  if (!jobResponse.job?.id) {
+    throw new BranchApiError(
+      `Unexpected response from branch creation: no job ID returned`,
+      500,
+      jobResponse
+    );
+  }
+
+  // Poll the job until it completes
+  await pollJob(config, jobResponse.job.id);
+
+  // Now fetch the branch with its token using the branch name
+  const branch = await getBranch(config, name);
+  return branch;
+}
+
+/**
+ * List all branches in the workspace
+ * GET /v1/environments
+ *
+ * @param config - API configuration
+ * @returns Array of branches
+ */
+export async function listBranches(
+  config: BranchApiConfig
+): Promise<TinybirdBranch[]> {
+  const url = new URL("/v1/environments", config.baseUrl);
+
+  const response = await fetch(url.toString(), {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${config.token}`,
+    },
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new BranchApiError(
+      `Failed to list branches: ${response.status} ${response.statusText}`,
+      response.status,
+      body
+    );
+  }
+
+  const data = (await response.json()) as { environments: TinybirdBranch[] };
+  return data.environments ?? [];
+}
+
+/**
+ * Get a branch by name with its token
+ * GET /v0/environments/{name}?with_token=true
+ *
+ * @param config - API configuration
+ * @param name - Branch name
+ * @returns Branch with token
+ */
+export async function getBranch(
+  config: BranchApiConfig,
+  name: string
+): Promise<TinybirdBranch> {
+  const url = new URL(`/v0/environments/${encodeURIComponent(name)}`, config.baseUrl);
+  url.searchParams.set("with_token", "true");
+
+  const response = await fetch(url.toString(), {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${config.token}`,
+    },
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new BranchApiError(
+      `Failed to get branch '${name}': ${response.status} ${response.statusText}`,
+      response.status,
+      body
+    );
+  }
+
+  const data = (await response.json()) as TinybirdBranch;
+  return data;
+}
+
+/**
+ * Delete a branch
+ * DELETE /v1/environments/{name}
+ *
+ * @param config - API configuration
+ * @param name - Branch name to delete
+ */
+export async function deleteBranch(
+  config: BranchApiConfig,
+  name: string
+): Promise<void> {
+  const url = new URL(`/v1/environments/${encodeURIComponent(name)}`, config.baseUrl);
+
+  const response = await fetch(url.toString(), {
+    method: "DELETE",
+    headers: {
+      Authorization: `Bearer ${config.token}`,
+    },
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new BranchApiError(
+      `Failed to delete branch '${name}': ${response.status} ${response.statusText}`,
+      response.status,
+      body
+    );
+  }
+}
+
+/**
+ * Check if a branch exists
+ *
+ * @param config - API configuration
+ * @param name - Branch name to check
+ * @returns true if branch exists, false if not
+ * @throws BranchApiError on API/network/auth failures
+ */
+export async function branchExists(
+  config: BranchApiConfig,
+  name: string
+): Promise<boolean> {
+  const branches = await listBranches(config);
+  return branches.some((b) => b.name === name);
+}
+
+/**
+ * Get or create a branch
+ * If the branch exists, returns it with token.
+ * If it doesn't exist, creates it.
+ *
+ * @param config - API configuration
+ * @param name - Branch name
+ * @returns Branch with token
+ */
+export async function getOrCreateBranch(
+  config: BranchApiConfig,
+  name: string
+): Promise<GetOrCreateBranchResult> {
+  // First try to get the existing branch
+  try {
+    const branch = await getBranch(config, name);
+    return { ...branch, wasCreated: false };
+  } catch (error) {
+    // If it's a 404, create the branch
+    if (error instanceof BranchApiError && error.status === 404) {
+      const branch = await createBranch(config, name);
+      return { ...branch, wasCreated: true };
+    }
+    throw error;
+  }
+}

package/src/api/build.test.ts

@@ -0,0 +1,216 @@
+import { describe, it, expect, beforeAll, afterEach, afterAll } from "vitest";
+import { setupServer } from "msw/node";
+import { http, HttpResponse } from "msw";
+import { buildToTinybird, validateBuildConfig, type BuildConfig } from "./build.js";
+import {
+  BASE_URL,
+  createBuildSuccessResponse,
+  createBuildFailureResponse,
+  createBuildMultipleErrorsResponse,
+  createNoChangesResponse,
+} from "../test/handlers.js";
+import type { GeneratedResources } from "../generator/index.js";
+
+const server = setupServer();
+
+beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+
+describe("Build API", () => {
+  const config: BuildConfig = {
+    baseUrl: BASE_URL,
+    token: "p.test-token",
+  };
+
+  const resources: GeneratedResources = {
+    datasources: [
+      { name: "events", content: "SCHEMA > timestamp DateTime" },
+      { name: "users", content: "SCHEMA > id String" },
+    ],
+    pipes: [
+      { name: "top_events", content: "NODE main\nSQL > SELECT * FROM events" },
+    ],
+  };
+
+  describe("buildToTinybird", () => {
+    it("successfully builds resources", async () => {
+      server.use(
+        http.post(`${BASE_URL}/v1/build`, () => {
+          return HttpResponse.json(
+            createBuildSuccessResponse({
+              buildId: "build-abc",
+              newPipes: ["top_events"],
+              newDatasources: ["events", "users"],
+            })
+          );
+        })
+      );
+
+      const result = await buildToTinybird(config, resources);
+
+      expect(result.success).toBe(true);
+      expect(result.result).toBe("success");
+      expect(result.buildId).toBe("build-abc");
+      expect(result.datasourceCount).toBe(2);
+      expect(result.pipeCount).toBe(1);
+      expect(result.pipes?.created).toEqual(["top_events"]);
+      expect(result.datasources?.created).toEqual(["events", "users"]);
+    });
+
+    it("handles no changes response", async () => {
+      server.use(
+        http.post(`${BASE_URL}/v1/build`, () => {
+          return HttpResponse.json(createNoChangesResponse());
+        })
+      );
+
+      const result = await buildToTinybird(config, resources);
+
+      expect(result.success).toBe(true);
+      expect(result.result).toBe("no_changes");
+    });
+
+    it("handles build failure with single error", async () => {
+      server.use(
+        http.post(`${BASE_URL}/v1/build`, () => {
+          return HttpResponse.json(
+            createBuildFailureResponse("Invalid SQL syntax"),
+            { status: 200 }
+          );
+        })
+      );
+
+      const result = await buildToTinybird(config, resources);
+
+      expect(result.success).toBe(false);
+      expect(result.result).toBe("failed");
+      expect(result.error).toBe("Invalid SQL syntax");
+    });
+
+    it("handles build failure with multiple errors", async () => {
+      server.use(
+        http.post(`${BASE_URL}/v1/build`, () => {
+          return HttpResponse.json(
+            createBuildMultipleErrorsResponse([
+              { filename: "events.datasource", error: "Invalid schema" },
+              { filename: "top_events.pipe", error: "Unknown column" },
+            ]),
+            { status: 200 }
+          );
+        })
+      );
+
+      const result = await buildToTinybird(config, resources);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("[events.datasource] Invalid schema");
+      expect(result.error).toContain("[top_events.pipe] Unknown column");
+    });
+
+    it("handles HTTP error responses", async () => {
+      server.use(
+        http.post(`${BASE_URL}/v1/build`, () => {
+          return HttpResponse.json(
+            { result: "failed", error: "Unauthorized" },
+            { status: 401 }
+          );
+        })
+      );
+
+      const result = await buildToTinybird(config, resources);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe("Unauthorized");
+    });
+
+    it("handles malformed JSON response", async () => {
+      server.use(
+        http.post(`${BASE_URL}/v1/build`, () => {
+          return new HttpResponse("not json", {
+            status: 200,
+            headers: { "Content-Type": "text/plain" },
+          });
+        })
+      );
+
+      await expect(buildToTinybird(config, resources)).rejects.toThrow(
+        "Failed to parse response"
+      );
+    });
+
+    it("tracks changed pipes and datasources", async () => {
+      server.use(
+        http.post(`${BASE_URL}/v1/build`, () => {
+          return HttpResponse.json(
+            createBuildSuccessResponse({
+              changedPipes: ["top_events"],
+              changedDatasources: ["events"],
+              deletedPipes: ["old_pipe"],
+            })
+          );
+        })
+      );
+
+      const result = await buildToTinybird(config, resources);
+
+      expect(result.pipes?.changed).toEqual(["top_events"]);
+      expect(result.pipes?.deleted).toEqual(["old_pipe"]);
+      expect(result.datasources?.changed).toEqual(["events"]);
+      // Deprecated fields should still work
+      expect(result.changedPipeNames).toEqual(["top_events"]);
+    });
+
+    it("sends correct authorization header", async () => {
+      let capturedAuth: string | null = null;
+
+      server.use(
+        http.post(`${BASE_URL}/v1/build`, ({ request }) => {
+          capturedAuth = request.headers.get("Authorization");
+          return HttpResponse.json(createBuildSuccessResponse());
+        })
+      );
+
+      await buildToTinybird(config, resources);
+
+      expect(capturedAuth).toBe("Bearer p.test-token");
+    });
+
+    it("sends resources as multipart form data", async () => {
+      let capturedFormData: FormData | null = null;
+
+      server.use(
+        http.post(`${BASE_URL}/v1/build`, async ({ request }) => {
+          capturedFormData = await request.formData();
+          return HttpResponse.json(createBuildSuccessResponse());
+        })
+      );
+
+      await buildToTinybird(config, resources);
+
+      expect(capturedFormData).not.toBeNull();
+      // FormData has 3 entries: 2 datasources + 1 pipe
+      // Use getAll since FormData.entries() is not available in Node.js types
+      const allValues = capturedFormData!.getAll("data_project://");
+      expect(allValues.length).toBe(3);
+    });
+  });
+
+  describe("validateBuildConfig", () => {
+    it("passes with valid config", () => {
+      expect(() => validateBuildConfig(config)).not.toThrow();
+    });
+
+    it("throws on missing baseUrl", () => {
+      expect(() =>
+        validateBuildConfig({ token: "test" })
+      ).toThrow("Missing baseUrl");
+    });
+
+    it("throws on missing token", () => {
+      expect(() =>
+        validateBuildConfig({ baseUrl: "https://api.tinybird.co" })
+      ).toThrow("Missing token");
+    });
+  });
+});