@tinybirdco/sdk 0.0.1

package/src/api/build.ts

@@ -0,0 +1,266 @@
+/**
+ * Build and deploy resources to Tinybird API
+ * Uses the /v1/build endpoint to deploy all resources at once
+ */
+
+import type { GeneratedResources } from "../generator/index.js";
+
+/**
+ * Configuration for building/deploying to Tinybird
+ */
+export interface BuildConfig {
+  /** Tinybird API base URL */
+  baseUrl: string;
+  /** API token for authentication */
+  token: string;
+}
+
+/**
+ * Resource info in the build response
+ */
+export interface ResourceInfo {
+  name: string;
+  type: string;
+}
+
+/**
+ * Error details from the build endpoint
+ */
+export interface BuildError {
+  filename?: string;
+  type?: string;
+  error: string;
+}
+
+/**
+ * Build response from the /v1/build endpoint
+ */
+export interface BuildResponse {
+  /** Result status */
+  result: "success" | "failed" | "no_changes";
+  /** Error message if failed (simple error) */
+  error?: string;
+  /** Array of errors if multiple (validation errors) */
+  errors?: BuildError[];
+  /** Build details */
+  build?: {
+    id: string;
+    datasources?: ResourceInfo[];
+    pipes?: ResourceInfo[];
+    /** Names of pipes that were changed in this build */
+    changed_pipe_names?: string[];
+    /** Names of newly created pipes in this build */
+    new_pipe_names?: string[];
+    /** Names of pipes that were deleted in this build */
+    deleted_pipe_names?: string[];
+    /** Names of datasources that were changed in this build */
+    changed_datasource_names?: string[];
+    /** Names of newly created datasources in this build */
+    new_datasource_names?: string[];
+    /** Names of datasources that were deleted in this build */
+    deleted_datasource_names?: string[];
+  };
+}
+
+/**
+ * Resource changes in a build
+ */
+export interface ResourceChanges {
+  /** Names of resources that were changed */
+  changed: string[];
+  /** Names of newly created resources */
+  created: string[];
+  /** Names of resources that were deleted */
+  deleted: string[];
+}
+
+/**
+ * Build result with additional metadata
+ */
+export interface BuildApiResult {
+  /** Whether the build was successful */
+  success: boolean;
+  /** Result status from API */
+  result: "success" | "failed" | "no_changes";
+  /** Error message if failed */
+  error?: string;
+  /** Number of datasources deployed */
+  datasourceCount: number;
+  /** Number of pipes deployed */
+  pipeCount: number;
+  /** Build ID if successful */
+  buildId?: string;
+  /** Pipe changes in this build */
+  pipes?: ResourceChanges;
+  /** Datasource changes in this build */
+  datasources?: ResourceChanges;
+  /** @deprecated Use pipes.changed instead */
+  changedPipeNames?: string[];
+  /** @deprecated Use pipes.created instead */
+  newPipeNames?: string[];
+}
+
+/**
+ * Build and deploy generated resources to Tinybird API
+ *
+ * Uses the /v1/build endpoint which accepts all resources in a single
+ * multipart form request.
+ *
+ * @param config - Build configuration with API URL and token
+ * @param resources - Generated resources to deploy
+ * @returns Build result
+ *
+ * @example
+ * ```ts
+ * const result = await buildToTinybird(
+ *   {
+ *     baseUrl: 'https://api.tinybird.co',
+ *     token: 'p.xxx',
+ *   },
+ *   {
+ *     datasources: [{ name: 'events', content: '...' }],
+ *     pipes: [{ name: 'top_events', content: '...' }],
+ *   }
+ * );
+ *
+ * if (result.success) {
+ *   console.log('Build deployed successfully!');
+ * }
+ * ```
+ */
+export async function buildToTinybird(
+  config: BuildConfig,
+  resources: GeneratedResources,
+  options?: { debug?: boolean }
+): Promise<BuildApiResult> {
+  const debug = options?.debug ?? !!process.env.TINYBIRD_DEBUG;
+  const formData = new FormData();
+
+  // Add datasources
+  for (const ds of resources.datasources) {
+    const fieldName = `data_project://`;
+    const fileName = `${ds.name}.datasource`;
+    if (debug) {
+      console.log(`[debug] Adding datasource: ${fieldName} (filename: ${fileName})`);
+      console.log(`[debug] Content:\n${ds.content}\n`);
+    }
+    formData.append(
+      fieldName,
+      new Blob([ds.content], { type: "text/plain" }),
+      fileName
+    );
+  }
+
+  // Add pipes
+  for (const pipe of resources.pipes) {
+    const fieldName = `data_project://`;
+    const fileName = `${pipe.name}.pipe`;
+    if (debug) {
+      console.log(`[debug] Adding pipe: ${fieldName} (filename: ${fileName})`);
+      console.log(`[debug] Content:\n${pipe.content}\n`);
+    }
+    formData.append(
+      fieldName,
+      new Blob([pipe.content], { type: "text/plain" }),
+      fileName
+    );
+  }
+
+  // Make the request
+  const url = `${config.baseUrl.replace(/\/$/, "")}/v1/build`;
+
+  if (debug) {
+    console.log(`[debug] POST ${url}`);
+  }
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${config.token}`,
+    },
+    body: formData,
+  });
+
+  // Parse response
+  let body: BuildResponse;
+  const rawBody = await response.text();
+
+  if (debug) {
+    console.log(`[debug] Response status: ${response.status}`);
+    console.log(`[debug] Response body: ${rawBody}`);
+  }
+
+  try {
+    body = JSON.parse(rawBody) as BuildResponse;
+  } catch {
+    throw new Error(
+      `Failed to parse response from Tinybird API: ${response.status} ${response.statusText}\nBody: ${rawBody}`
+    );
+  }
+
+  // Helper to format errors
+  const formatErrors = (): string => {
+    if (body.errors && body.errors.length > 0) {
+      return body.errors.map(e => {
+        const prefix = e.filename ? `[${e.filename}] ` : '';
+        return `${prefix}${e.error}`;
+      }).join('\n');
+    }
+    return body.error || `HTTP ${response.status}: ${response.statusText}`;
+  };
+
+  // Handle non-OK responses
+  if (!response.ok) {
+    return {
+      success: false,
+      result: "failed",
+      error: formatErrors(),
+      datasourceCount: resources.datasources.length,
+      pipeCount: resources.pipes.length,
+    };
+  }
+
+  // Handle API result
+  if (body.result === "failed") {
+    return {
+      success: false,
+      result: "failed",
+      error: formatErrors(),
+      datasourceCount: resources.datasources.length,
+      pipeCount: resources.pipes.length,
+    };
+  }
+
+  return {
+    success: true,
+    result: body.result,
+    datasourceCount: resources.datasources.length,
+    pipeCount: resources.pipes.length,
+    buildId: body.build?.id,
+    pipes: {
+      changed: body.build?.changed_pipe_names ?? [],
+      created: body.build?.new_pipe_names ?? [],
+      deleted: body.build?.deleted_pipe_names ?? [],
+    },
+    datasources: {
+      changed: body.build?.changed_datasource_names ?? [],
+      created: body.build?.new_datasource_names ?? [],
+      deleted: body.build?.deleted_datasource_names ?? [],
+    },
+    // Keep deprecated fields for backwards compatibility
+    changedPipeNames: body.build?.changed_pipe_names ?? [],
+    newPipeNames: body.build?.new_pipe_names ?? [],
+  };
+}
+
+/**
+ * Validate that the configuration is complete
+ */
+export function validateBuildConfig(config: Partial<BuildConfig>): asserts config is BuildConfig {
+  if (!config.baseUrl) {
+    throw new Error("Missing baseUrl in configuration");
+  }
+  if (!config.token) {
+    throw new Error("Missing token in configuration");
+  }
+}

package/src/api/deploy.test.ts

@@ -0,0 +1,193 @@
+import { describe, it, expect, beforeAll, afterEach, afterAll } from "vitest";
+import { setupServer } from "msw/node";
+import { http, HttpResponse } from "msw";
+import { deployToMain } from "./deploy.js";
+import 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("Deploy API", () => {
+  const config: BuildConfig = {
+    baseUrl: BASE_URL,
+    token: "p.test-token",
+  };
+
+  const resources: GeneratedResources = {
+    datasources: [
+      { name: "events", content: "SCHEMA > timestamp DateTime" },
+    ],
+    pipes: [
+      { name: "top_events", content: "NODE main\nSQL > SELECT * FROM events" },
+    ],
+  };
+
+  describe("deployToMain", () => {
+    it("successfully deploys resources", async () => {
+      server.use(
+        http.post(`${BASE_URL}/v1/deploy`, () => {
+          return HttpResponse.json(
+            createBuildSuccessResponse({
+              buildId: "deploy-abc",
+              newPipes: ["top_events"],
+              newDatasources: ["events"],
+            })
+          );
+        })
+      );
+
+      const result = await deployToMain(config, resources);
+
+      expect(result.success).toBe(true);
+      expect(result.result).toBe("success");
+      expect(result.buildId).toBe("deploy-abc");
+      expect(result.datasourceCount).toBe(1);
+      expect(result.pipeCount).toBe(1);
+      expect(result.pipes?.created).toEqual(["top_events"]);
+      expect(result.datasources?.created).toEqual(["events"]);
+    });
+
+    it("handles no changes response", async () => {
+      server.use(
+        http.post(`${BASE_URL}/v1/deploy`, () => {
+          return HttpResponse.json(createNoChangesResponse());
+        })
+      );
+
+      const result = await deployToMain(config, resources);
+
+      expect(result.success).toBe(true);
+      expect(result.result).toBe("no_changes");
+    });
+
+    it("handles deploy failure with single error", async () => {
+      server.use(
+        http.post(`${BASE_URL}/v1/deploy`, () => {
+          return HttpResponse.json(
+            createBuildFailureResponse("Permission denied"),
+            { status: 200 }
+          );
+        })
+      );
+
+      const result = await deployToMain(config, resources);
+
+      expect(result.success).toBe(false);
+      expect(result.result).toBe("failed");
+      expect(result.error).toBe("Permission denied");
+    });
+
+    it("handles deploy failure with multiple errors", async () => {
+      server.use(
+        http.post(`${BASE_URL}/v1/deploy`, () => {
+          return HttpResponse.json(
+            createBuildMultipleErrorsResponse([
+              { filename: "events.datasource", error: "Schema mismatch" },
+              { error: "General error without filename" },
+            ]),
+            { status: 200 }
+          );
+        })
+      );
+
+      const result = await deployToMain(config, resources);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("[events.datasource] Schema mismatch");
+      expect(result.error).toContain("General error without filename");
+    });
+
+    it("handles HTTP error responses", async () => {
+      server.use(
+        http.post(`${BASE_URL}/v1/deploy`, () => {
+          return HttpResponse.json(
+            { result: "failed", error: "Forbidden" },
+            { status: 403 }
+          );
+        })
+      );
+
+      const result = await deployToMain(config, resources);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe("Forbidden");
+    });
+
+    it("handles malformed JSON response", async () => {
+      server.use(
+        http.post(`${BASE_URL}/v1/deploy`, () => {
+          return new HttpResponse("invalid json {", {
+            status: 200,
+            headers: { "Content-Type": "text/plain" },
+          });
+        })
+      );
+
+      await expect(deployToMain(config, resources)).rejects.toThrow(
+        "Failed to parse response"
+      );
+    });
+
+    it("uses /v1/deploy endpoint (not /v1/build)", async () => {
+      let capturedUrl: string | null = null;
+
+      server.use(
+        http.post(`${BASE_URL}/v1/deploy`, ({ request }) => {
+          capturedUrl = request.url;
+          return HttpResponse.json(createBuildSuccessResponse());
+        })
+      );
+
+      await deployToMain(config, resources);
+
+      expect(capturedUrl).toBe(`${BASE_URL}/v1/deploy`);
+    });
+
+    it("tracks changed and deleted resources", async () => {
+      server.use(
+        http.post(`${BASE_URL}/v1/deploy`, () => {
+          return HttpResponse.json(
+            createBuildSuccessResponse({
+              changedPipes: ["top_events"],
+              deletedDatasources: ["old_ds"],
+            })
+          );
+        })
+      );
+
+      const result = await deployToMain(config, resources);
+
+      expect(result.pipes?.changed).toEqual(["top_events"]);
+      expect(result.datasources?.deleted).toEqual(["old_ds"]);
+    });
+
+    it("normalizes baseUrl with trailing slash", async () => {
+      let capturedUrl: string | null = null;
+
+      server.use(
+        http.post(`${BASE_URL}/v1/deploy`, ({ request }) => {
+          capturedUrl = request.url;
+          return HttpResponse.json(createBuildSuccessResponse());
+        })
+      );
+
+      await deployToMain(
+        { ...config, baseUrl: `${BASE_URL}/` },
+        resources
+      );
+
+      expect(capturedUrl).toBe(`${BASE_URL}/v1/deploy`);
+    });
+  });
+});

package/src/api/deploy.ts

@@ -0,0 +1,163 @@
+/**
+ * Deploy resources to Tinybird main workspace
+ * Uses the /v1/deploy endpoint (same payload format as /v1/build)
+ */
+
+import type { GeneratedResources } from "../generator/index.js";
+import type { BuildConfig, BuildApiResult, BuildResponse } from "./build.js";
+
+/**
+ * Deploy generated resources to Tinybird main workspace
+ *
+ * Uses the /v1/deploy endpoint which accepts all resources in a single
+ * multipart form request. This is used for deploying to the main workspace
+ * (not branches).
+ *
+ * @param config - Build configuration with API URL and token
+ * @param resources - Generated resources to deploy
+ * @returns Build result
+ *
+ * @example
+ * ```ts
+ * const result = await deployToMain(
+ *   {
+ *     baseUrl: 'https://api.tinybird.co',
+ *     token: 'p.xxx',
+ *   },
+ *   {
+ *     datasources: [{ name: 'events', content: '...' }],
+ *     pipes: [{ name: 'top_events', content: '...' }],
+ *   }
+ * );
+ *
+ * if (result.success) {
+ *   console.log('Deployed to main workspace!');
+ * }
+ * ```
+ */
+export async function deployToMain(
+  config: BuildConfig,
+  resources: GeneratedResources,
+  options?: { debug?: boolean }
+): Promise<BuildApiResult> {
+  const debug = options?.debug ?? !!process.env.TINYBIRD_DEBUG;
+  const formData = new FormData();
+
+  // Add datasources
+  for (const ds of resources.datasources) {
+    const fieldName = `data_project://`;
+    const fileName = `${ds.name}.datasource`;
+    if (debug) {
+      console.log(`[debug] Adding datasource: ${fieldName} (filename: ${fileName})`);
+      console.log(`[debug] Content:\n${ds.content}\n`);
+    }
+    formData.append(
+      fieldName,
+      new Blob([ds.content], { type: "text/plain" }),
+      fileName
+    );
+  }
+
+  // Add pipes
+  for (const pipe of resources.pipes) {
+    const fieldName = `data_project://`;
+    const fileName = `${pipe.name}.pipe`;
+    if (debug) {
+      console.log(`[debug] Adding pipe: ${fieldName} (filename: ${fileName})`);
+      console.log(`[debug] Content:\n${pipe.content}\n`);
+    }
+    formData.append(
+      fieldName,
+      new Blob([pipe.content], { type: "text/plain" }),
+      fileName
+    );
+  }
+
+  // Make the request to /v1/deploy (instead of /v1/build)
+  const url = `${config.baseUrl.replace(/\/$/, "")}/v1/deploy`;
+
+  if (debug) {
+    console.log(`[debug] POST ${url}`);
+  }
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${config.token}`,
+    },
+    body: formData,
+  });
+
+  // Parse response
+  let body: BuildResponse;
+  const rawBody = await response.text();
+
+  if (debug) {
+    console.log(`[debug] Response status: ${response.status}`);
+    console.log(`[debug] Response body: ${rawBody}`);
+  }
+
+  try {
+    body = JSON.parse(rawBody) as BuildResponse;
+  } catch {
+    throw new Error(
+      `Failed to parse response from Tinybird API: ${response.status} ${response.statusText}\nBody: ${rawBody}`
+    );
+  }
+
+  // Helper to format errors
+  const formatErrors = (): string => {
+    if (body.errors && body.errors.length > 0) {
+      return body.errors
+        .map((e) => {
+          const prefix = e.filename ? `[${e.filename}] ` : "";
+          return `${prefix}${e.error}`;
+        })
+        .join("\n");
+    }
+    return body.error || `HTTP ${response.status}: ${response.statusText}`;
+  };
+
+  // Handle non-OK responses
+  if (!response.ok) {
+    return {
+      success: false,
+      result: "failed",
+      error: formatErrors(),
+      datasourceCount: resources.datasources.length,
+      pipeCount: resources.pipes.length,
+    };
+  }
+
+  // Handle API result
+  if (body.result === "failed") {
+    return {
+      success: false,
+      result: "failed",
+      error: formatErrors(),
+      datasourceCount: resources.datasources.length,
+      pipeCount: resources.pipes.length,
+    };
+  }
+
+  return {
+    success: true,
+    result: body.result,
+    datasourceCount: resources.datasources.length,
+    pipeCount: resources.pipes.length,
+    buildId: body.build?.id,
+    pipes: {
+      changed: body.build?.changed_pipe_names ?? [],
+      created: body.build?.new_pipe_names ?? [],
+      deleted: body.build?.deleted_pipe_names ?? [],
+    },
+    datasources: {
+      changed: body.build?.changed_datasource_names ?? [],
+      created: body.build?.new_datasource_names ?? [],
+      deleted: body.build?.deleted_datasource_names ?? [],
+    },
+    // Keep deprecated fields for backwards compatibility
+    changedPipeNames: body.build?.changed_pipe_names ?? [],
+    newPipeNames: body.build?.new_pipe_names ?? [],
+  };
+}

package/src/api/workspaces.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  getWorkspace,
+  WorkspaceApiError,
+  type WorkspaceApiConfig,
+} from "./workspaces.js";
+
+// Mock fetch globally
+const mockFetch = vi.fn();
+global.fetch = mockFetch;
+
+describe("Workspace API client", () => {
+  const config: WorkspaceApiConfig = {
+    baseUrl: "https://api.tinybird.co",
+    token: "p.test-token",
+  };
+
+  beforeEach(() => {
+    mockFetch.mockReset();
+  });
+
+  describe("getWorkspace", () => {
+    it("returns workspace information", async () => {
+      const mockWorkspace = {
+        id: "9f42135e-3434-4d89-a90f-cb9cf74ce311",
+        name: "ts_client",
+        releases: [],
+        user_id: "412571dd-d2e6-4b3c-87b5-b29320414e22",
+        user_email: "user@example.com",
+        scope: "user",
+        main: null,
+      };
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve(mockWorkspace),
+      });
+
+      const result = await getWorkspace(config);
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        "https://api.tinybird.co/v1/workspace",
+        {
+          method: "GET",
+          headers: {
+            Authorization: "Bearer p.test-token",
+          },
+        }
+      );
+      expect(result).toEqual(mockWorkspace);
+    });
+
+    it("throws WorkspaceApiError on failure", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 401,
+        statusText: "Unauthorized",
+        text: () => Promise.resolve("Invalid token"),
+      });
+
+      await expect(getWorkspace(config)).rejects.toThrow(WorkspaceApiError);
+    });
+
+    it("includes status code in error", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 403,
+        statusText: "Forbidden",
+        text: () => Promise.resolve("Access denied"),
+      });
+
+      try {
+        await getWorkspace(config);
+        expect.fail("Should have thrown");
+      } catch (error) {
+        expect(error).toBeInstanceOf(WorkspaceApiError);
+        expect((error as WorkspaceApiError).status).toBe(403);
+      }
+    });
+  });
+});