@tinybirdco/sdk 0.0.1

package/dist/test/handlers.js

@@ -0,0 +1,62 @@
+/**
+ * MSW handlers for API mocking in tests
+ */
+import { http, HttpResponse } from "msw";
+export const BASE_URL = "https://api.tinybird.co";
+/**
+ * Create build success response
+ */
+export function createBuildSuccessResponse(options) {
+    return {
+        result: "success",
+        build: {
+            id: options?.buildId ?? "build-123",
+            changed_pipe_names: options?.changedPipes ?? [],
+            new_pipe_names: options?.newPipes ?? [],
+            deleted_pipe_names: options?.deletedPipes ?? [],
+            changed_datasource_names: options?.changedDatasources ?? [],
+            new_datasource_names: options?.newDatasources ?? [],
+            deleted_datasource_names: options?.deletedDatasources ?? [],
+        },
+    };
+}
+/**
+ * Create build failure response
+ */
+export function createBuildFailureResponse(error) {
+    return {
+        result: "failed",
+        error,
+    };
+}
+/**
+ * Create build failure response with multiple errors
+ */
+export function createBuildMultipleErrorsResponse(errors) {
+    return {
+        result: "failed",
+        errors,
+    };
+}
+/**
+ * Create no changes response
+ */
+export function createNoChangesResponse() {
+    return {
+        result: "no_changes",
+    };
+}
+/**
+ * Default handlers for build and deploy endpoints
+ */
+export const handlers = [
+    // Build endpoint - success by default
+    http.post(`${BASE_URL}/v1/build`, () => {
+        return HttpResponse.json(createBuildSuccessResponse());
+    }),
+    // Deploy endpoint - success by default
+    http.post(`${BASE_URL}/v1/deploy`, () => {
+        return HttpResponse.json(createBuildSuccessResponse());
+    }),
+];
+//# sourceMappingURL=handlers.js.map

package/dist/test/handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../src/test/handlers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,KAAK,CAAC;AAEzC,MAAM,CAAC,MAAM,QAAQ,GAAG,yBAAyB,CAAC;AAElD;;GAEG;AACH,MAAM,UAAU,0BAA0B,CAAC,OAQ1C;IACC,OAAO;QACL,MAAM,EAAE,SAAS;QACjB,KAAK,EAAE;YACL,EAAE,EAAE,OAAO,EAAE,OAAO,IAAI,WAAW;YACnC,kBAAkB,EAAE,OAAO,EAAE,YAAY,IAAI,EAAE;YAC/C,cAAc,EAAE,OAAO,EAAE,QAAQ,IAAI,EAAE;YACvC,kBAAkB,EAAE,OAAO,EAAE,YAAY,IAAI,EAAE;YAC/C,wBAAwB,EAAE,OAAO,EAAE,kBAAkB,IAAI,EAAE;YAC3D,oBAAoB,EAAE,OAAO,EAAE,cAAc,IAAI,EAAE;YACnD,wBAAwB,EAAE,OAAO,EAAE,kBAAkB,IAAI,EAAE;SAC5D;KACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,0BAA0B,CAAC,KAAa;IACtD,OAAO;QACL,MAAM,EAAE,QAAQ;QAChB,KAAK;KACN,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iCAAiC,CAC/C,MAAmD;IAEnD,OAAO;QACL,MAAM,EAAE,QAAQ;QAChB,MAAM;KACP,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO;QACL,MAAM,EAAE,YAAY;KACrB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,sCAAsC;IACtC,IAAI,CAAC,IAAI,CAAC,GAAG,QAAQ,WAAW,EAAE,GAAG,EAAE;QACrC,OAAO,YAAY,CAAC,IAAI,CAAC,0BAA0B,EAAE,CAAC,CAAC;IACzD,CAAC,CAAC;IAEF,uCAAuC;IACvC,IAAI,CAAC,IAAI,CAAC,GAAG,QAAQ,YAAY,EAAE,GAAG,EAAE;QACtC,OAAO,YAAY,CAAC,IAAI,CAAC,0BAA0B,EAAE,CAAC,CAAC;IACzD,CAAC,CAAC;CACH,CAAC"}

package/dist/test/setup.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Test setup file for MSW
+ */
+export declare const server: import("msw/node").SetupServerApi;
+//# sourceMappingURL=setup.d.ts.map

package/dist/test/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/test/setup.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,eAAO,MAAM,MAAM,mCAA2B,CAAC"}

package/dist/test/setup.js

@@ -0,0 +1,11 @@
+/**
+ * Test setup file for MSW
+ */
+import { beforeAll, afterEach, afterAll } from "vitest";
+import { setupServer } from "msw/node";
+import { handlers } from "./handlers.js";
+export const server = setupServer(...handlers);
+beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+//# sourceMappingURL=setup.js.map

package/dist/test/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../src/test/setup.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,MAAM,CAAC,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,QAAQ,CAAC,CAAC;AAE/C,SAAS,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,kBAAkB,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;AAChE,SAAS,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC,CAAC;AACxC,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@tinybirdco/sdk",
+  "version": "0.0.1",
+  "description": "TypeScript SDK for Tinybird Forward - define datasources and pipes as TypeScript",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "tinybird": "./bin/tinybird.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "src"
+  ],
+  "keywords": [
+    "tinybird",
+    "analytics",
+    "typescript",
+    "sdk",
+    "clickhouse",
+    "cli"
+  ],
+  "author": "Tinybird",
+  "license": "MIT",
+  "dependencies": {
+    "chokidar": "^4.0.0",
+    "commander": "^12.0.0",
+    "esbuild": "^0.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "msw": "^2.12.7",
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/src/api/branches.test.ts

@@ -0,0 +1,377 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import {
+  BranchApiError,
+  createBranch,
+  listBranches,
+  getBranch,
+  deleteBranch,
+  branchExists,
+  getOrCreateBranch,
+  type BranchApiConfig,
+} from "./branches.js";
+
+// Mock fetch globally
+const mockFetch = vi.fn();
+global.fetch = mockFetch;
+
+describe("Branch API client", () => {
+  const config: BranchApiConfig = {
+    baseUrl: "https://api.tinybird.co",
+    token: "p.test-token",
+  };
+
+  beforeEach(() => {
+    mockFetch.mockReset();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe("createBranch", () => {
+    it("creates a branch and returns it", async () => {
+      const mockBranch = {
+        id: "branch-123",
+        name: "my-feature",
+        token: "p.branch-token",
+        created_at: "2024-01-01T00:00:00Z",
+      };
+
+      // 1. POST to /v1/environments returns a job
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({
+          job: { id: "job-123", status: "waiting" },
+          workspace: { id: "ws-123" },
+        }),
+      });
+
+      // 2. Poll job - returns done
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ id: "job-123", status: "done" }),
+      });
+
+      // 3. Get branch with token
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve(mockBranch),
+      });
+
+      const result = await createBranch(config, "my-feature");
+
+      expect(mockFetch).toHaveBeenCalledTimes(3);
+      expect(mockFetch).toHaveBeenNthCalledWith(
+        1,
+        "https://api.tinybird.co/v1/environments?name=my-feature",
+        {
+          method: "POST",
+          headers: {
+            Authorization: "Bearer p.test-token",
+          },
+        }
+      );
+      expect(mockFetch).toHaveBeenNthCalledWith(
+        2,
+        "https://api.tinybird.co/v0/jobs/job-123",
+        {
+          method: "GET",
+          headers: {
+            Authorization: "Bearer p.test-token",
+          },
+        }
+      );
+      expect(mockFetch).toHaveBeenNthCalledWith(
+        3,
+        "https://api.tinybird.co/v0/environments/my-feature?with_token=true",
+        {
+          method: "GET",
+          headers: {
+            Authorization: "Bearer p.test-token",
+          },
+        }
+      );
+      expect(result).toEqual(mockBranch);
+    });
+
+    it("polls job until done", async () => {
+      const mockBranch = {
+        id: "branch-123",
+        name: "my-feature",
+        token: "p.branch-token",
+        created_at: "2024-01-01T00:00:00Z",
+      };
+
+      // 1. POST to /v1/environments returns a job
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({
+          job: { id: "job-123", status: "waiting" },
+          workspace: { id: "ws-123" },
+        }),
+      });
+
+      // 2. Poll job - waiting
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ id: "job-123", status: "waiting" }),
+      });
+
+      // 3. Poll job - working
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ id: "job-123", status: "working" }),
+      });
+
+      // 4. Poll job - done
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ id: "job-123", status: "done" }),
+      });
+
+      // 5. Get branch with token
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve(mockBranch),
+      });
+
+      // Start the async operation
+      const promise = createBranch(config, "my-feature");
+
+      // Advance timers and run all pending promises
+      await vi.runAllTimersAsync();
+
+      const result = await promise;
+
+      expect(mockFetch).toHaveBeenCalledTimes(5);
+      expect(result).toEqual(mockBranch);
+    });
+
+    it("throws BranchApiError on job error", async () => {
+      // 1. POST to /v1/environments returns a job
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({
+          job: { id: "job-123", status: "waiting" },
+        }),
+      });
+
+      // 2. Poll job - error
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ id: "job-123", status: "error", error: "Something went wrong" }),
+      });
+
+      await expect(createBranch(config, "my-feature")).rejects.toThrow(
+        BranchApiError
+      );
+    });
+
+    it("throws BranchApiError on failure", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 400,
+        statusText: "Bad Request",
+        text: () => Promise.resolve("Branch already exists"),
+      });
+
+      await expect(createBranch(config, "existing")).rejects.toThrow(
+        BranchApiError
+      );
+    });
+  });
+
+  describe("listBranches", () => {
+    it("returns array of branches", async () => {
+      const mockBranches = [
+        { id: "1", name: "feature-a", created_at: "2024-01-01T00:00:00Z" },
+        { id: "2", name: "feature-b", created_at: "2024-01-02T00:00:00Z" },
+      ];
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ environments: mockBranches }),
+      });
+
+      const result = await listBranches(config);
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        "https://api.tinybird.co/v1/environments",
+        {
+          method: "GET",
+          headers: {
+            Authorization: "Bearer p.test-token",
+          },
+        }
+      );
+      expect(result).toEqual(mockBranches);
+    });
+
+    it("returns empty array when no branches", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ environments: undefined }),
+      });
+
+      const result = await listBranches(config);
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe("getBranch", () => {
+    it("returns branch with token", async () => {
+      const mockBranch = {
+        id: "branch-123",
+        name: "my-feature",
+        token: "p.branch-token",
+        created_at: "2024-01-01T00:00:00Z",
+      };
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve(mockBranch),
+      });
+
+      const result = await getBranch(config, "my-feature");
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        "https://api.tinybird.co/v0/environments/my-feature?with_token=true",
+        {
+          method: "GET",
+          headers: {
+            Authorization: "Bearer p.test-token",
+          },
+        }
+      );
+      expect(result).toEqual(mockBranch);
+    });
+
+    it("throws BranchApiError when branch not found", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        statusText: "Not Found",
+        text: () => Promise.resolve("Branch not found"),
+      });
+
+      await expect(getBranch(config, "nonexistent")).rejects.toThrow(
+        BranchApiError
+      );
+    });
+  });
+
+  describe("deleteBranch", () => {
+    it("deletes a branch successfully", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+      });
+
+      await deleteBranch(config, "my-feature");
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        "https://api.tinybird.co/v1/environments/my-feature",
+        {
+          method: "DELETE",
+          headers: {
+            Authorization: "Bearer p.test-token",
+          },
+        }
+      );
+    });
+  });
+
+  describe("branchExists", () => {
+    it("returns true when branch exists", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            environments: [
+              { id: "1", name: "my-feature", created_at: "2024-01-01" },
+            ],
+          }),
+      });
+
+      const result = await branchExists(config, "my-feature");
+      expect(result).toBe(true);
+    });
+
+    it("returns false when branch does not exist", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ environments: [] }),
+      });
+
+      const result = await branchExists(config, "nonexistent");
+      expect(result).toBe(false);
+    });
+
+    it("throws on API error", async () => {
+      mockFetch.mockRejectedValueOnce(new Error("Network error"));
+
+      await expect(branchExists(config, "any")).rejects.toThrow("Network error");
+    });
+  });
+
+  describe("getOrCreateBranch", () => {
+    it("returns existing branch if found", async () => {
+      const mockBranch = {
+        id: "branch-123",
+        name: "existing-feature",
+        token: "p.branch-token",
+        created_at: "2024-01-01T00:00:00Z",
+      };
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve(mockBranch),
+      });
+
+      const result = await getOrCreateBranch(config, "existing-feature");
+      expect(result).toEqual({ ...mockBranch, wasCreated: false });
+    });
+
+    it("creates branch if not found", async () => {
+      const newBranch = {
+        id: "branch-456",
+        name: "new-feature",
+        token: "p.new-token",
+        created_at: "2024-01-02T00:00:00Z",
+      };
+
+      // 1. getBranch returns 404
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        statusText: "Not Found",
+        text: () => Promise.resolve("Not found"),
+      });
+
+      // 2. createBranch: POST to /v1/environments returns a job
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({
+          job: { id: "job-456", status: "waiting" },
+          workspace: { id: "ws-456" },
+        }),
+      });
+
+      // 3. Poll job - done
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ id: "job-456", status: "done" }),
+      });
+
+      // 4. Get branch with token
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve(newBranch),
+      });
+
+      const result = await getOrCreateBranch(config, "new-feature");
+      expect(result).toEqual({ ...newBranch, wasCreated: true });
+      expect(mockFetch).toHaveBeenCalledTimes(4);
+    });
+  });
+});