@tinybirdco/sdk 0.0.10 → 0.0.12

package/src/api/branches.test.ts

@@ -7,6 +7,7 @@ import {
   deleteBranch,
   branchExists,
   getOrCreateBranch,
+  clearBranch,
   type BranchApiConfig,
 } from "./branches.js";
 
@@ -271,16 +272,39 @@ describe("Branch API client", () => {
 
   describe("deleteBranch", () => {
     it("deletes a branch successfully", async () => {
+      const mockBranch = {
+        id: "branch-123",
+        name: "my-feature",
+        token: "p.branch-token",
+        created_at: "2024-01-01T00:00:00Z",
+      };
+
+      // 1. getBranch to get the ID
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve(mockBranch),
+      });
+
+      // 2. DELETE the branch by ID
       mockFetch.mockResolvedValueOnce({
         ok: true,
       });
 
       await deleteBranch(config, "my-feature");
 
-      const [url, init] = mockFetch.mock.calls[0];
-      const parsed = expectFromParam(url);
-      expect(parsed.pathname).toBe("/v1/environments/my-feature");
-      expect(init).toEqual({
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+
+      // First call: get branch
+      const [getUrl, getInit] = mockFetch.mock.calls[0];
+      const getParsed = expectFromParam(getUrl);
+      expect(getParsed.pathname).toBe("/v0/environments/my-feature");
+      expect(getInit.method).toBe("GET");
+
+      // Second call: delete branch by ID
+      const [deleteUrl, deleteInit] = mockFetch.mock.calls[1];
+      const deleteParsed = expectFromParam(deleteUrl);
+      expect(deleteParsed.pathname).toBe("/v0/environments/branch-123");
+      expect(deleteInit).toEqual({
         method: "DELETE",
         headers: {
           Authorization: "Bearer p.test-token",
@@ -382,4 +406,92 @@ describe("Branch API client", () => {
       expect(mockFetch).toHaveBeenCalledTimes(4);
     });
   });
+
+  describe("clearBranch", () => {
+    it("clears a branch by deleting and recreating it", async () => {
+      const existingBranch = {
+        id: "branch-old",
+        name: "my-feature",
+        token: "p.old-token",
+        created_at: "2024-01-01T00:00:00Z",
+      };
+
+      const newBranch = {
+        id: "branch-new",
+        name: "my-feature",
+        token: "p.new-token",
+        created_at: "2024-01-02T00:00:00Z",
+      };
+
+      // 1. GET branch to get ID (for delete)
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve(existingBranch),
+      });
+
+      // 2. DELETE branch by ID
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+      });
+
+      // 3. POST to /v1/environments returns a job
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({
+          job: { id: "job-789", status: "waiting" },
+          workspace: { id: "ws-789" },
+        }),
+      });
+
+      // 4. Poll job - done
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ id: "job-789", status: "done" }),
+      });
+
+      // 5. Get branch with token (after create)
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve(newBranch),
+      });
+
+      const result = await clearBranch(config, "my-feature");
+
+      expect(mockFetch).toHaveBeenCalledTimes(5);
+
+      // Verify get was called first
+      const [getUrl, getInit] = mockFetch.mock.calls[0];
+      const getParsed = expectFromParam(getUrl);
+      expect(getParsed.pathname).toBe("/v0/environments/my-feature");
+      expect(getInit.method).toBe("GET");
+
+      // Verify delete was called with ID
+      const [deleteUrl, deleteInit] = mockFetch.mock.calls[1];
+      const deleteParsed = expectFromParam(deleteUrl);
+      expect(deleteParsed.pathname).toBe("/v0/environments/branch-old");
+      expect(deleteInit.method).toBe("DELETE");
+
+      // Verify create was called
+      const [createUrl, createInit] = mockFetch.mock.calls[2];
+      const createParsed = expectFromParam(createUrl);
+      expect(createParsed.pathname).toBe("/v1/environments");
+      expect(createParsed.searchParams.get("name")).toBe("my-feature");
+      expect(createInit.method).toBe("POST");
+
+      expect(result).toEqual(newBranch);
+    });
+
+    it("throws BranchApiError when branch does not exist", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        statusText: "Not Found",
+        text: () => Promise.resolve("Branch not found"),
+      });
+
+      await expect(clearBranch(config, "nonexistent")).rejects.toThrow(
+        BranchApiError
+      );
+    });
+  });
 });

package/src/api/branches.ts

@@ -264,7 +264,10 @@ export async function getBranch(
 
 /**
  * Delete a branch
- * DELETE /v1/environments/{name}
+ * DELETE /v0/environments/{id}
+ *
+ * Note: The API requires the branch ID, not name. This function first
+ * fetches the branch to get its ID, then deletes it.
  *
  * @param config - API configuration
  * @param name - Branch name to delete
@@ -273,7 +276,10 @@ export async function deleteBranch(
   config: BranchApiConfig,
   name: string
 ): Promise<void> {
-  const url = new URL(`/v1/environments/${encodeURIComponent(name)}`, config.baseUrl);
+  // First get the branch to find its ID
+  const branch = await getBranch(config, name);
+
+  const url = new URL(`/v0/environments/${branch.id}`, config.baseUrl);
 
   const response = await tinybirdFetch(url.toString(), {
     method: "DELETE",
@@ -334,3 +340,23 @@ export async function getOrCreateBranch(
     throw error;
   }
 }
+
+/**
+ * Clear a branch by deleting and recreating it
+ *
+ * @param config - API configuration
+ * @param name - Branch name to clear
+ * @returns The recreated branch with token
+ */
+export async function clearBranch(
+  config: BranchApiConfig,
+  name: string
+): Promise<TinybirdBranch> {
+  // Delete the branch
+  await deleteBranch(config, name);
+
+  // Recreate the branch
+  const branch = await createBranch(config, name);
+
+  return branch;
+}

package/src/api/local.test.ts

@@ -6,6 +6,8 @@ import {
   listLocalWorkspaces,
   createLocalWorkspace,
   getOrCreateLocalWorkspace,
+  deleteLocalWorkspace,
+  clearLocalWorkspace,
   isLocalRunning,
   getLocalWorkspaceName,
   LocalNotRunningError,
@@ -259,4 +261,108 @@ describe("Local API", () => {
       expect(name1).not.toBe(name2);
     });
   });
+
+  describe("deleteLocalWorkspace", () => {
+    it("deletes a workspace successfully", async () => {
+      server.use(
+        http.delete(`${LOCAL_BASE_URL}/v1/workspaces/ws-123`, () => {
+          return new HttpResponse(null, { status: 204 });
+        })
+      );
+
+      await deleteLocalWorkspace("user-token", "ws-123");
+      // No error means success
+    });
+
+    it("throws LocalApiError on failure", async () => {
+      server.use(
+        http.delete(`${LOCAL_BASE_URL}/v1/workspaces/ws-123`, () => {
+          return new HttpResponse("Not found", { status: 404 });
+        })
+      );
+
+      await expect(deleteLocalWorkspace("user-token", "ws-123")).rejects.toThrow(
+        LocalApiError
+      );
+    });
+  });
+
+  describe("clearLocalWorkspace", () => {
+    const tokens = {
+      user_token: "user-token",
+      admin_token: "admin-token",
+      workspace_admin_token: "default-token",
+    };
+
+    it("clears a workspace by deleting and recreating it", async () => {
+      let deleteCount = 0;
+      let createCount = 0;
+
+      server.use(
+        http.get(`${LOCAL_BASE_URL}/v1/user/workspaces`, () => {
+          // First call: workspace exists
+          // Second call: workspace deleted
+          // Third call: workspace recreated
+          if (deleteCount === 0) {
+            return HttpResponse.json({
+              organization_id: "org-123",
+              workspaces: [
+                { id: "ws-123", name: "MyWorkspace", token: "old-token" },
+              ],
+            });
+          } else if (createCount === 0) {
+            return HttpResponse.json({
+              organization_id: "org-123",
+              workspaces: [],
+            });
+          } else {
+            return HttpResponse.json({
+              organization_id: "org-123",
+              workspaces: [
+                { id: "ws-456", name: "MyWorkspace", token: "new-token" },
+              ],
+            });
+          }
+        }),
+        http.delete(`${LOCAL_BASE_URL}/v1/workspaces/ws-123`, () => {
+          deleteCount++;
+          return new HttpResponse(null, { status: 204 });
+        }),
+        http.post(`${LOCAL_BASE_URL}/v1/workspaces`, () => {
+          createCount++;
+          return HttpResponse.json({
+            id: "ws-456",
+            name: "MyWorkspace",
+            token: "new-token",
+          });
+        })
+      );
+
+      const result = await clearLocalWorkspace(tokens, "MyWorkspace");
+
+      expect(deleteCount).toBe(1);
+      expect(createCount).toBe(1);
+      expect(result.id).toBe("ws-456");
+      expect(result.name).toBe("MyWorkspace");
+      expect(result.token).toBe("new-token");
+    });
+
+    it("throws LocalApiError when workspace not found", async () => {
+      server.use(
+        http.get(`${LOCAL_BASE_URL}/v1/user/workspaces`, () => {
+          return HttpResponse.json({
+            organization_id: "org-123",
+            workspaces: [],
+          });
+        })
+      );
+
+      await expect(clearLocalWorkspace(tokens, "NonExistent")).rejects.toThrow(
+        LocalApiError
+      );
+      await expect(clearLocalWorkspace(tokens, "NonExistent")).rejects.toThrow(
+        "Workspace 'NonExistent' not found"
+      );
+    });
+  });
 });

package/src/api/local.ts

@@ -269,3 +269,80 @@ export function getLocalWorkspaceName(
   const hash = crypto.createHash("sha256").update(cwd).digest("hex");
   return `Build_${hash.substring(0, 16)}`;
 }
+
+/**
+ * Delete a workspace in local Tinybird
+ *
+ * @param userToken - User token from getLocalTokens()
+ * @param workspaceId - ID of the workspace to delete
+ */
+export async function deleteLocalWorkspace(
+  userToken: string,
+  workspaceId: string
+): Promise<void> {
+  const url = `${LOCAL_BASE_URL}/v1/workspaces/${workspaceId}?hard_delete_confirmation=yes`;
+
+  const response = await tinybirdFetch(url, {
+    method: "DELETE",
+    headers: {
+      Authorization: `Bearer ${userToken}`,
+    },
+  });
+
+  if (!response.ok) {
+    const responseBody = await response.text();
+    throw new LocalApiError(
+      `Failed to delete local workspace: ${response.status} ${response.statusText}`,
+      response.status,
+      responseBody
+    );
+  }
+}
+
+/**
+ * Clear a workspace in local Tinybird by deleting and recreating it
+ *
+ * @param tokens - Tokens from getLocalTokens()
+ * @param workspaceName - Name of the workspace to clear
+ * @returns The recreated workspace
+ */
+export async function clearLocalWorkspace(
+  tokens: LocalTokens,
+  workspaceName: string
+): Promise<LocalWorkspace> {
+  // List existing workspaces to find the one to clear
+  const { workspaces, organizationId } = await listLocalWorkspaces(tokens.admin_token);
+
+  // Find the workspace by name
+  const workspace = workspaces.find((ws) => ws.name === workspaceName);
+  if (!workspace) {
+    throw new LocalApiError(`Workspace '${workspaceName}' not found`);
+  }
+
+  // Delete the workspace
+  await deleteLocalWorkspace(tokens.user_token, workspace.id);
+
+  // Verify it was deleted
+  const { workspaces: afterDelete } = await listLocalWorkspaces(tokens.admin_token);
+  const stillExists = afterDelete.find((ws) => ws.name === workspaceName);
+  if (stillExists) {
+    throw new LocalApiError(
+      `Workspace '${workspaceName}' was not deleted properly. Please try again.`
+    );
+  }
+
+  // Recreate the workspace
+  await createLocalWorkspace(tokens.user_token, workspaceName, organizationId);
+
+  // Fetch the workspace again to get the token
+  const { workspaces: afterCreate } = await listLocalWorkspaces(tokens.admin_token);
+  const newWorkspace = afterCreate.find((ws) => ws.name === workspaceName);
+
+  if (!newWorkspace) {
+    throw new LocalApiError(
+      `Workspace '${workspaceName}' was not recreated properly. Please try again.`
+    );
+  }
+
+  return newWorkspace;
+}

package/src/cli/commands/clear.ts

@@ -0,0 +1,194 @@
+/**
+ * Clear command - clears a local workspace or branch by deleting and recreating it
+ */
+
+import { loadConfig, type ResolvedConfig, type DevMode } from "../config.js";
+import {
+  getLocalTokens,
+  clearLocalWorkspace,
+  getLocalWorkspaceName,
+  LocalNotRunningError,
+  LocalApiError,
+} from "../../api/local.js";
+import {
+  clearBranch,
+  BranchApiError,
+} from "../../api/branches.js";
+import {
+  setBranchToken,
+  removeBranch as removeCachedBranch,
+} from "../branch-store.js";
+import { getWorkspace } from "../../api/workspaces.js";
+
+/**
+ * Clear command options
+ */
+export interface ClearCommandOptions {
+  /** Working directory (defaults to cwd) */
+  cwd?: string;
+  /** Override the dev mode from config */
+  devModeOverride?: DevMode;
+}
+
+/**
+ * Result of clearing a workspace or branch
+ */
+export interface ClearResult {
+  /** Whether the operation was successful */
+  success: boolean;
+  /** Name of the cleared workspace or branch */
+  name?: string;
+  /** Whether local mode was used */
+  isLocal?: boolean;
+  /** Error message if failed */
+  error?: string;
+}
+
+/**
+ * Clear a local workspace or branch by deleting and recreating it
+ *
+ * In local mode: deletes and recreates the local workspace
+ * In branch mode: deletes and recreates the Tinybird branch
+ *
+ * @param options - Command options
+ * @returns Clear result
+ */
+export async function runClear(
+  options: ClearCommandOptions = {}
+): Promise<ClearResult> {
+  const cwd = options.cwd ?? process.cwd();
+
+  let config: ResolvedConfig;
+  try {
+    config = loadConfig(cwd);
+  } catch (error) {
+    return {
+      success: false,
+      error: (error as Error).message,
+    };
+  }
+
+  // Determine dev mode
+  const devMode = options.devModeOverride ?? config.devMode;
+
+  if (devMode === "local") {
+    return clearLocal(config);
+  } else {
+    return clearCloudBranch(config);
+  }
+}
+
+/**
+ * Clear a local workspace
+ */
+async function clearLocal(config: ResolvedConfig): Promise<ClearResult> {
+  // Get workspace name from git branch or path hash
+  const workspaceName = getLocalWorkspaceName(config.tinybirdBranch, config.cwd);
+
+  try {
+    // Get local tokens
+    const tokens = await getLocalTokens();
+
+    // Clear the workspace
+    await clearLocalWorkspace(tokens, workspaceName);
+
+    return {
+      success: true,
+      name: workspaceName,
+      isLocal: true,
+    };
+  } catch (error) {
+    if (error instanceof LocalNotRunningError) {
+      return {
+        success: false,
+        error: error.message,
+      };
+    }
+
+    if (error instanceof LocalApiError) {
+      return {
+        success: false,
+        error: error.message,
+      };
+    }
+
+    return {
+      success: false,
+      error: (error as Error).message,
+    };
+  }
+}
+
+/**
+ * Clear a cloud branch
+ */
+async function clearCloudBranch(config: ResolvedConfig): Promise<ClearResult> {
+  // Must be on a non-main branch to clear
+  if (config.isMainBranch) {
+    return {
+      success: false,
+      error: "Cannot clear the main branch. Use 'tinybird deploy' to manage the main workspace.",
+    };
+  }
+
+  const branchName = config.tinybirdBranch;
+  if (!branchName) {
+    return {
+      success: false,
+      error: "Could not detect git branch. Make sure you are in a git repository.",
+    };
+  }
+
+  try {
+    // Get workspace ID for cache management
+    const workspace = await getWorkspace({
+      baseUrl: config.baseUrl,
+      token: config.token,
+    });
+
+    // Clear the branch (delete and recreate)
+    const newBranch = await clearBranch(
+      {
+        baseUrl: config.baseUrl,
+        token: config.token,
+      },
+      branchName
+    );
+
+    // Update the cached token with the new branch token
+    if (newBranch.token) {
+      setBranchToken(workspace.id, branchName, {
+        token: newBranch.token,
+        id: newBranch.id,
+        createdAt: newBranch.created_at,
+      });
+    } else {
+      // If no token in response, remove cached token
+      removeCachedBranch(workspace.id, branchName);
+    }
+
+    return {
+      success: true,
+      name: branchName,
+      isLocal: false,
+    };
+  } catch (error) {
+    if (error instanceof BranchApiError) {
+      if (error.status === 404) {
+        return {
+          success: false,
+          error: `Branch '${branchName}' does not exist. Run 'npx tinybird dev' to create it first.`,
+        };
+      }
+      return {
+        success: false,
+        error: error.message,
+      };
+    }
+
+    return {
+      success: false,
+      error: (error as Error).message,
+    };
+  }
+}

package/src/cli/index.ts

@@ -24,6 +24,7 @@ import {
   runBranchStatus,
   runBranchDelete,
 } from "./commands/branch.js";
+import { runClear } from "./commands/clear.js";
 import {
   detectPackageManagerInstallCmd,
   detectPackageManagerRunCmd,
@@ -532,6 +533,61 @@ function createCli(): Command {
 
   program.addCommand(branchCommand);
 
+  // Clear command
+  program
+    .command("clear")
+    .description("Clear the workspace or branch by deleting and recreating it")
+    .option("-y, --yes", "Skip confirmation prompt")
+    .option("--local", "Use local Tinybird container")
+    .option("--branch", "Use Tinybird cloud with branches")
+    .action(async (options) => {
+      // Determine devMode override
+      let devModeOverride: DevMode | undefined;
+      if (options.local) {
+        devModeOverride = "local";
+      } else if (options.branch) {
+        devModeOverride = "branch";
+      }
+
+      const modeLabel = devModeOverride === "local" ? "local workspace" : "branch";
+
+      // Confirmation prompt unless --yes is passed
+      if (!options.yes) {
+        const readline = await import("readline");
+        const rl = readline.createInterface({
+          input: process.stdin,
+          output: process.stdout,
+        });
+
+        const answer = await new Promise<string>((resolve) => {
+          rl.question(
+            `Are you sure you want to clear the ${modeLabel}? This will delete all resources. [y/N]: `,
+            (ans) => {
+              rl.close();
+              resolve(ans);
+            }
+          );
+        });
+
+        if (answer.toLowerCase() !== "y" && answer.toLowerCase() !== "yes") {
+          console.log("Aborted.");
+          return;
+        }
+      }
+
+      console.log(`Clearing ${modeLabel}...`);
+
+      const result = await runClear({ devModeOverride });
+
+      if (!result.success) {
+        console.error(`Error: ${result.error}`);
+        process.exit(1);
+      }
+
+      const typeLabel = result.isLocal ? "Workspace" : "Branch";
+      console.log(`${typeLabel} '${result.name}' cleared successfully.`);
+    });
+
   return program;
 }