@tinybirdco/sdk 0.0.35 → 0.0.37

package/src/cli/commands/init.ts

@@ -17,11 +17,11 @@ import {
 } from "../config.js";
 import { browserLogin } from "../auth.js";
 import { saveTinybirdToken } from "../env.js";
+import { selectRegion } from "../region-selector.js";
 import { getGitRoot } from "../git.js";
 import { fetchAllResources } from "../../api/resources.js";
 import { generateCombinedFile } from "../../codegen/index.js";
 import { execSync } from "child_process";
-import { setTimeout as sleep } from "node:timers/promises";
 import {
   detectPackageManager,
   getPackageManagerAddCmd,
@@ -312,6 +312,8 @@ export interface InitOptions {
   includeCdWorkflow?: boolean;
   /** Git provider for workflow templates */
   workflowProvider?: "github" | "gitlab";
+  /** Skip auto-installing @tinybirdco/sdk dependency */
+  skipDependencyInstall?: boolean;
 }
 
 /**
@@ -414,6 +416,8 @@ export async function runInit(options: InitOptions = {}): Promise<InitResult> {
   const cwd = options.cwd ?? process.cwd();
   const force = options.force ?? false;
   const skipLogin = options.skipLogin ?? false;
+  const skipDependencyInstall =
+    options.skipDependencyInstall ?? Boolean(process.env.VITEST);
 
   const created: string[] = [];
   const skipped: string[] = [];
@@ -738,14 +742,13 @@ export async function runInit(options: InitOptions = {}): Promise<InitResult> {
   }
 
   // Install @tinybirdco/sdk if not already installed
-  if (!hasTinybirdSdkDependency(cwd)) {
+  if (!skipDependencyInstall && !hasTinybirdSdkDependency(cwd)) {
     const s = p.spinner();
     s.start("Installing dependencies");
     const packageManager = detectPackageManager(cwd);
     const addCmd = getPackageManagerAddCmd(packageManager);
     try {
       execSync(`${addCmd} @tinybirdco/sdk`, { cwd, stdio: "pipe" });
-      await sleep(1000);
       s.stop("Installed dependencies");
       created.push("@tinybirdco/sdk");
     } catch (error) {
@@ -893,7 +896,25 @@ export async function runInit(options: InitOptions = {}): Promise<InitResult> {
   if (!skipLogin && !hasValidToken(cwd)) {
     console.log("\nNo authentication found. Starting login flow...\n");
 
-    const authResult = await browserLogin();
+    // Select region before login (init creates fresh config, so always prompt)
+    const regionResult = await selectRegion();
+    if (!regionResult.success || !regionResult.apiHost) {
+      return {
+        success: true,
+        created,
+        skipped,
+        loggedIn: false,
+        devMode,
+        clientPath: relativeTinybirdDir,
+        existingDatafiles:
+          existingDatafiles.length > 0 ? existingDatafiles : undefined,
+        ciWorkflowCreated,
+        cdWorkflowCreated,
+        workflowProvider,
+      };
+    }
+
+    const authResult = await browserLogin({ apiHost: regionResult.apiHost });
 
     if (authResult.success && authResult.token) {
       // Save token to .env.local
@@ -903,13 +924,11 @@ export async function runInit(options: InitOptions = {}): Promise<InitResult> {
           created.push(".env.local");
         }
 
-        // If custom base URL, update config file
-        const baseUrl = authResult.baseUrl ?? "https://api.tinybird.co";
-        if (baseUrl !== "https://api.tinybird.co") {
-          const currentConfigPath = findExistingConfigPath(cwd);
-          if (currentConfigPath && currentConfigPath.endsWith(".json")) {
-            updateConfig(currentConfigPath, { baseUrl });
-          }
+        // Update config with selected region's baseUrl
+        const baseUrl = authResult.baseUrl ?? regionResult.apiHost;
+        const currentConfigPath = findExistingConfigPath(cwd);
+        if (currentConfigPath && currentConfigPath.endsWith(".json")) {
+          updateConfig(currentConfigPath, { baseUrl });
         }
 
         // Generate TypeScript from existing Tinybird resources if requested

package/src/cli/commands/login.test.ts

@@ -9,10 +9,17 @@ vi.mock("../auth.js", () => ({
   browserLogin: vi.fn(),
 }));
 
-// Import the mocked function
+// Mock the region-selector module to avoid interactive prompts
+vi.mock("../region-selector.js", () => ({
+  getApiHostWithRegionSelection: vi.fn(),
+}));
+
+// Import the mocked functions
 import { browserLogin } from "../auth.js";
+import { getApiHostWithRegionSelection } from "../region-selector.js";
 
 const mockedBrowserLogin = vi.mocked(browserLogin);
+const mockedGetApiHost = vi.mocked(getApiHostWithRegionSelection);
 
 describe("Login Command", () => {
   let tempDir: string;
@@ -20,6 +27,11 @@ describe("Login Command", () => {
   beforeEach(() => {
     tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "tinybird-login-test-"));
     vi.clearAllMocks();
+    // Default mock for region selection - returns a default apiHost
+    mockedGetApiHost.mockResolvedValue({
+      apiHost: "https://api.tinybird.co",
+      fromConfig: false,
+    });
   });
 
   afterEach(() => {

package/src/cli/commands/login.ts

@@ -6,6 +6,7 @@ import * as path from "path";
 import { browserLogin, type LoginOptions, type AuthResult } from "../auth.js";
 import { updateConfig, findConfigFile } from "../config.js";
 import { saveTinybirdToken } from "../env.js";
+import { getApiHostWithRegionSelection } from "../region-selector.js";
 
 /**
  * Login command options
@@ -57,11 +58,21 @@ export async function runLogin(options: RunLoginOptions = {}): Promise<LoginResu
   // Get the directory containing the config file for .env.local
   const configDir = path.dirname(configPath);
 
-  const loginOptions: LoginOptions = {};
-  if (options.apiHost) {
-    loginOptions.apiHost = options.apiHost;
+  // Determine API host: option > config baseUrl > region selection
+  let apiHost = options.apiHost;
+  if (!apiHost) {
+    const regionResult = await getApiHostWithRegionSelection(configPath);
+    if (!regionResult) {
+      return {
+        success: false,
+        error: "Region selection cancelled",
+      };
+    }
+    apiHost = regionResult.apiHost;
   }
 
+  const loginOptions: LoginOptions = { apiHost };
+
   // Perform browser login
   const authResult: AuthResult = await browserLogin(loginOptions);
 

package/src/cli/region-selector.test.ts

@@ -0,0 +1,227 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { selectRegion, getApiHostWithRegionSelection } from "./region-selector.js";
+
+// Mock the regions API
+vi.mock("../api/regions.js", () => ({
+  fetchRegions: vi.fn(),
+}));
+
+// Mock @clack/prompts
+vi.mock("@clack/prompts", () => ({
+  select: vi.fn(),
+  isCancel: vi.fn(),
+  cancel: vi.fn(),
+}));
+
+import { fetchRegions } from "../api/regions.js";
+import * as p from "@clack/prompts";
+
+const mockedFetchRegions = vi.mocked(fetchRegions);
+const mockedSelect = vi.mocked(p.select);
+const mockedIsCancel = vi.mocked(p.isCancel);
+
+describe("selectRegion", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockedIsCancel.mockReturnValue(false);
+  });
+
+  it("fetches regions and shows selection prompt with GCP first", async () => {
+    mockedFetchRegions.mockResolvedValue([
+      { name: "us-east-1", api_host: "https://api.us.tinybird.co", provider: "aws" },
+      { name: "europe-west3", api_host: "https://api.eu.tinybird.co", provider: "gcp" },
+    ]);
+    mockedSelect.mockResolvedValue("https://api.eu.tinybird.co");
+
+    const result = await selectRegion();
+
+    expect(result.success).toBe(true);
+    expect(result.apiHost).toBe("https://api.eu.tinybird.co");
+    expect(result.regionName).toBe("europe-west3");
+    // GCP regions should appear first, then AWS
+    expect(mockedSelect).toHaveBeenCalledWith({
+      message: "Select your Tinybird region",
+      options: [
+        { value: "https://api.eu.tinybird.co", label: "gcp | europe-west3", hint: "api.eu.tinybird.co" },
+        { value: "https://api.us.tinybird.co", label: "aws | us-east-1", hint: "api.us.tinybird.co" },
+      ],
+      initialValue: undefined,
+    });
+  });
+
+  it("uses fallback regions when API fails", async () => {
+    mockedFetchRegions.mockRejectedValue(new Error("Network error"));
+    mockedSelect.mockResolvedValue("https://api.europe-west2.gcp.tinybird.co");
+
+    const result = await selectRegion();
+
+    expect(result.success).toBe(true);
+    expect(result.apiHost).toBe("https://api.europe-west2.gcp.tinybird.co");
+    expect(mockedSelect).toHaveBeenCalled();
+  });
+
+  it("returns cancelled when user cancels", async () => {
+    mockedFetchRegions.mockResolvedValue([
+      { name: "EU", api_host: "https://api.eu.tinybird.co", provider: "gcp" },
+    ]);
+    mockedSelect.mockResolvedValue(Symbol("cancel"));
+    mockedIsCancel.mockReturnValue(true);
+
+    const result = await selectRegion();
+
+    expect(result.success).toBe(false);
+    expect(result.cancelled).toBe(true);
+  });
+
+  it("uses fallback regions when API returns empty array", async () => {
+    mockedFetchRegions.mockResolvedValue([]);
+    mockedSelect.mockResolvedValue("https://api.tinybird.co");
+
+    const result = await selectRegion();
+
+    expect(result.success).toBe(true);
+    // Should have used fallback regions
+    expect(mockedSelect).toHaveBeenCalled();
+  });
+
+  it("pre-selects region when defaultApiHost is provided", async () => {
+    mockedFetchRegions.mockResolvedValue([
+      { name: "EU", api_host: "https://api.eu.tinybird.co", provider: "gcp" },
+      { name: "US", api_host: "https://api.us.tinybird.co", provider: "aws" },
+    ]);
+    mockedSelect.mockResolvedValue("https://api.us.tinybird.co");
+
+    const result = await selectRegion("https://api.us.tinybird.co");
+
+    expect(result.success).toBe(true);
+    expect(mockedSelect).toHaveBeenCalledWith(
+      expect.objectContaining({
+        initialValue: "https://api.us.tinybird.co",
+      })
+    );
+  });
+
+  it("does not set initialValue when defaultApiHost does not match any region", async () => {
+    mockedFetchRegions.mockResolvedValue([
+      { name: "EU", api_host: "https://api.eu.tinybird.co", provider: "gcp" },
+    ]);
+    mockedSelect.mockResolvedValue("https://api.eu.tinybird.co");
+
+    await selectRegion("https://api.unknown.tinybird.co");
+
+    expect(mockedSelect).toHaveBeenCalledWith(
+      expect.objectContaining({
+        initialValue: undefined,
+      })
+    );
+  });
+});
+
+describe("getApiHostWithRegionSelection", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "region-selector-test-"));
+    vi.clearAllMocks();
+    mockedIsCancel.mockReturnValue(false);
+  });
+
+  afterEach(() => {
+    try {
+      fs.rmSync(tempDir, { recursive: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  it("pre-selects baseUrl from config when present", async () => {
+    const configPath = path.join(tempDir, "tinybird.config.json");
+    fs.writeFileSync(
+      configPath,
+      JSON.stringify({ baseUrl: "https://api.us-east.tinybird.co" })
+    );
+
+    mockedFetchRegions.mockResolvedValue([
+      { name: "EU", api_host: "https://api.eu.tinybird.co", provider: "gcp" },
+      { name: "US East", api_host: "https://api.us-east.tinybird.co", provider: "aws" },
+    ]);
+    mockedSelect.mockResolvedValue("https://api.us-east.tinybird.co");
+
+    const result = await getApiHostWithRegionSelection(configPath);
+
+    expect(result).toEqual({
+      apiHost: "https://api.us-east.tinybird.co",
+      fromConfig: false,
+    });
+    // Should have called select with initialValue
+    expect(mockedSelect).toHaveBeenCalledWith(
+      expect.objectContaining({
+        initialValue: "https://api.us-east.tinybird.co",
+      })
+    );
+  });
+
+  it("prompts for region when config has no baseUrl", async () => {
+    const configPath = path.join(tempDir, "tinybird.config.json");
+    fs.writeFileSync(configPath, JSON.stringify({ token: "test" }));
+
+    mockedFetchRegions.mockResolvedValue([
+      { name: "EU", api_host: "https://api.eu.tinybird.co", provider: "gcp" },
+    ]);
+    mockedSelect.mockResolvedValue("https://api.eu.tinybird.co");
+
+    const result = await getApiHostWithRegionSelection(configPath);
+
+    expect(result).toEqual({
+      apiHost: "https://api.eu.tinybird.co",
+      fromConfig: false,
+    });
+    expect(mockedSelect).toHaveBeenCalled();
+  });
+
+  it("prompts for region when config file is null", async () => {
+    mockedFetchRegions.mockResolvedValue([
+      { name: "EU", api_host: "https://api.eu.tinybird.co", provider: "gcp" },
+    ]);
+    mockedSelect.mockResolvedValue("https://api.eu.tinybird.co");
+
+    const result = await getApiHostWithRegionSelection(null);
+
+    expect(result).toEqual({
+      apiHost: "https://api.eu.tinybird.co",
+      fromConfig: false,
+    });
+  });
+
+  it("prompts for region when config is not JSON", async () => {
+    mockedFetchRegions.mockResolvedValue([
+      { name: "EU", api_host: "https://api.eu.tinybird.co", provider: "gcp" },
+    ]);
+    mockedSelect.mockResolvedValue("https://api.eu.tinybird.co");
+
+    const result = await getApiHostWithRegionSelection("/path/to/config.mjs");
+
+    expect(result).toEqual({
+      apiHost: "https://api.eu.tinybird.co",
+      fromConfig: false,
+    });
+  });
+
+  it("returns null when user cancels region selection", async () => {
+    const configPath = path.join(tempDir, "tinybird.config.json");
+    fs.writeFileSync(configPath, JSON.stringify({ token: "test" }));
+
+    mockedFetchRegions.mockResolvedValue([
+      { name: "EU", api_host: "https://api.eu.tinybird.co", provider: "gcp" },
+    ]);
+    mockedSelect.mockResolvedValue(Symbol("cancel"));
+    mockedIsCancel.mockReturnValue(true);
+
+    const result = await getApiHostWithRegionSelection(configPath);
+
+    expect(result).toBeNull();
+  });
+});

package/src/cli/region-selector.ts

@@ -0,0 +1,151 @@
+/**
+ * Region selection utility for CLI commands
+ *
+ * Provides interactive region selection using @clack/prompts
+ */
+
+import * as fs from "fs";
+import * as p from "@clack/prompts";
+import { fetchRegions, type TinybirdRegion } from "../api/regions.js";
+
+/**
+ * Default fallback regions if API call fails
+ */
+const FALLBACK_REGIONS: TinybirdRegion[] = [
+  {
+    name: "EU (GCP)",
+    api_host: "https://api.europe-west2.gcp.tinybird.co",
+    provider: "gcp",
+  },
+  {
+    name: "US East (AWS)",
+    api_host: "https://api.us-east.aws.tinybird.co",
+    provider: "aws",
+  },
+  {
+    name: "EU (Default)",
+    api_host: "https://api.tinybird.co",
+    provider: "gcp",
+  },
+];
+
+/**
+ * Result of region selection
+ */
+export interface RegionSelectionResult {
+  /** Whether selection was successful (not cancelled) */
+  success: boolean;
+  /** Selected API host URL */
+  apiHost?: string;
+  /** Selected region name (for display) */
+  regionName?: string;
+  /** Whether user cancelled */
+  cancelled?: boolean;
+}
+
+/**
+ * Prompt user to select a Tinybird region
+ *
+ * Fetches available regions from the API and presents an interactive selection.
+ * Falls back to hardcoded regions if the API call fails.
+ *
+ * @param defaultApiHost - Optional API host to pre-select in the prompt
+ * @returns Selected region info or cancellation result
+ */
+export async function selectRegion(
+  defaultApiHost?: string
+): Promise<RegionSelectionResult> {
+  let regions: TinybirdRegion[];
+
+  // Try to fetch regions from API
+  try {
+    regions = await fetchRegions();
+  } catch {
+    // Fall back to hardcoded regions
+    regions = FALLBACK_REGIONS;
+  }
+
+  // Ensure we have at least one region
+  if (regions.length === 0) {
+    regions = FALLBACK_REGIONS;
+  }
+
+  // Sort regions: GCP first, then AWS
+  regions.sort((a, b) => {
+    if (a.provider === b.provider) return 0;
+    return a.provider === "gcp" ? -1 : 1;
+  });
+
+  // Build options for p.select
+  const options = regions.map((region) => ({
+    value: region.api_host,
+    label: `${region.provider} | ${region.name}`,
+    hint: region.api_host.replace("https://", ""),
+  }));
+
+  // Find initial value if defaultApiHost is provided and matches a region
+  // Normalize URLs for comparison (remove trailing slashes, lowercase)
+  const normalizeUrl = (url: string) => url.toLowerCase().replace(/\/+$/, "");
+  const initialValue = defaultApiHost
+    ? regions.find(
+        (r) => normalizeUrl(r.api_host) === normalizeUrl(defaultApiHost)
+      )?.api_host
+    : undefined;
+
+  const selected = await p.select({
+    message: "Select your Tinybird region",
+    options,
+    initialValue,
+  });
+
+  if (p.isCancel(selected)) {
+    p.cancel("Operation cancelled");
+    return {
+      success: false,
+      cancelled: true,
+    };
+  }
+
+  const selectedRegion = regions.find((r) => r.api_host === selected);
+
+  return {
+    success: true,
+    apiHost: selected as string,
+    regionName: selectedRegion?.name,
+  };
+}
+
+/**
+ * Get API host from config file or prompt for region selection
+ *
+ * @param configPath - Path to config file (or null if no config)
+ * @returns API host URL and source, or null if cancelled
+ */
+export async function getApiHostWithRegionSelection(
+  configPath: string | null
+): Promise<{ apiHost: string; fromConfig: boolean } | null> {
+  let existingBaseUrl: string | undefined;
+
+  // If we have a JSON config file, try to read baseUrl from it
+  if (configPath && configPath.endsWith(".json")) {
+    try {
+      const content = fs.readFileSync(configPath, "utf-8");
+      const config = JSON.parse(content);
+      existingBaseUrl = config.baseUrl;
+    } catch {
+      // Ignore errors reading config
+    }
+  }
+
+  // Prompt for region selection, pre-selecting existing baseUrl if available
+  const result = await selectRegion(existingBaseUrl);
+
+  if (!result.success || !result.apiHost) {
+    return null;
+  }
+
+  return {
+    apiHost: result.apiHost,
+    fromConfig: false,
+  };
+}

package/src/client/base.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from "vitest";
 import { TinybirdClient, createClient } from "./base.js";
+import type { DatasourcesNamespace } from "./types.js";
 
 describe("TinybirdClient", () => {
   describe("constructor", () => {
@@ -137,4 +138,35 @@ describe("TinybirdClient", () => {
       expect(context.baseUrl).toBe("https://api.tinybird.co");
     });
   });
+
+  describe("datasources", () => {
+    it("exposes datasources namespace", () => {
+      const client = createClient({
+        baseUrl: "https://api.tinybird.co",
+        token: "test-token",
+      });
+
+      expect(client.datasources).toBeDefined();
+    });
+
+    it("datasources namespace has append method", () => {
+      const client = createClient({
+        baseUrl: "https://api.tinybird.co",
+        token: "test-token",
+      });
+
+      expect(typeof client.datasources.append).toBe("function");
+    });
+
+    it("datasources conforms to DatasourcesNamespace interface", () => {
+      const client = createClient({
+        baseUrl: "https://api.tinybird.co",
+        token: "test-token",
+      });
+
+      const datasources: DatasourcesNamespace = client.datasources;
+      expect(datasources).toBeDefined();
+      expect(typeof datasources.append).toBe("function");
+    });
+  });
 });

package/src/client/base.ts

@@ -3,8 +3,11 @@
  */
 
 import type {
+  AppendOptions,
+  AppendResult,
   ClientConfig,
   ClientContext,
+  DatasourcesNamespace,
   QueryResult,
   IngestResult,
   QueryOptions,
@@ -57,6 +60,11 @@ export class TinybirdClient {
   private contextPromise: Promise<ClientContext> | null = null;
   private resolvedContext: ClientContext | null = null;
 
+  /**
+   * Datasources namespace for import operations
+   */
+  readonly datasources: DatasourcesNamespace;
+
   constructor(config: ClientConfig) {
     // Validate required config
     if (!config.baseUrl) {
@@ -71,6 +79,46 @@ export class TinybirdClient {
       ...config,
       baseUrl: config.baseUrl.replace(/\/$/, ""),
     };
+
+    // Initialize datasources namespace
+    this.datasources = {
+      append: (datasourceName: string, options: AppendOptions): Promise<AppendResult> => {
+        return this.appendDatasource(datasourceName, options);
+      },
+    };
+  }
+
+  /**
+   * Append data to a datasource from a URL or local file
+   *
+   * @param datasourceName - Name of the datasource
+   * @param options - Append options including url or file source
+   * @returns Append result
+   *
+   * @example
+   * ```ts
+   * // Append from URL
+   * await client.datasources.append('events', {
+   *   url: 'https://example.com/data.csv',
+   * });
+   *
+   * // Append from local file
+   * await client.datasources.append('events', {
+   *   file: './data/events.ndjson',
+   * });
+   * ```
+   */
+  private async appendDatasource(
+    datasourceName: string,
+    options: AppendOptions
+  ): Promise<AppendResult> {
+    const token = await this.getToken();
+
+    try {
+      return await this.getApi(token).appendDatasource(datasourceName, options);
+    } catch (error) {
+      this.rethrowApiError(error);
+    }
   }
 
   /**