@tinybirdco/sdk 0.0.39 → 0.0.41

package/src/cli/commands/init.ts

@@ -21,7 +21,7 @@ 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 { execSync, spawn } from "child_process";
 import {
   detectPackageManager,
   getPackageManagerAddCmd,
@@ -286,6 +286,8 @@ function createDefaultConfig(
   };
 }
 
+type InstallTool = "skills" | "syntax-highlighting";
+
 /**
  * Init command options
  */
@@ -314,6 +316,12 @@ export interface InitOptions {
   workflowProvider?: "github" | "gitlab";
   /** Skip auto-installing @tinybirdco/sdk dependency */
   skipDependencyInstall?: boolean;
+  /** Skip install tools prompt */
+  skipToolsPrompt?: boolean;
+  /** Install selected tools */
+  installTools?: InstallTool[];
+  /** Skip selected tool installation */
+  skipToolsInstall?: boolean;
 }
 
 /**
@@ -346,6 +354,10 @@ export interface InitResult {
   cdWorkflowCreated?: boolean;
   /** Git provider used for workflow templates */
   workflowProvider?: "github" | "gitlab";
+  /** Selected install tools */
+  installTools?: InstallTool[];
+  /** Installed tools */
+  installedTools?: string[];
 }
 
 /**
@@ -418,14 +430,18 @@ export async function runInit(options: InitOptions = {}): Promise<InitResult> {
   const skipLogin = options.skipLogin ?? false;
   const skipDependencyInstall =
     options.skipDependencyInstall ?? Boolean(process.env.VITEST);
+  const skipToolsInstall =
+    options.skipToolsInstall ?? Boolean(process.env.VITEST);
 
   const created: string[] = [];
   const skipped: string[] = [];
+  const installedTools: string[] = [];
   let didPrompt = false;
   let existingDatafiles: string[] = [];
   let ciWorkflowCreated = false;
   let cdWorkflowCreated = false;
   let workflowProvider = options.workflowProvider;
+  let installTools: InstallTool[] = options.installTools ?? [];
 
   // Check for existing .datasource and .pipe files
   const foundDatafiles = findExistingDatafiles(cwd);
@@ -540,6 +556,44 @@ export async function runInit(options: InitOptions = {}): Promise<InitResult> {
     workflowProvider = "github";
   }
 
+  const skipToolsPrompt =
+    options.skipToolsPrompt ??
+    (options.devMode !== undefined || options.clientPath !== undefined);
+  const shouldPromptTools =
+    !skipToolsPrompt && options.installTools === undefined;
+
+  if (shouldPromptTools) {
+    const toolsChoice = await p.multiselect({
+      message: "Install extra tools",
+      options: [
+        {
+          value: "skills",
+          label: "Agent skills",
+          hint: "Manual: npx skills add tinybirdco/tinybird-agent-skills --skill tinybird --skill tinybird-typescript-sdk-guidelines",
+        },
+        {
+          value: "syntax-highlighting",
+          label: "Syntax highlighting (Cursor/VS Code)",
+          hint: "Installs Tinybird SQL highlighting extension",
+        },
+      ],
+      required: false,
+    });
+
+    if (p.isCancel(toolsChoice)) {
+      p.cancel("Operation cancelled");
+      return {
+        success: false,
+        created: [],
+        skipped: [],
+        error: "Cancelled by user",
+      };
+    }
+
+    didPrompt = true;
+    installTools = toolsChoice as InstallTool[];
+  }
+
   // Ask about existing datafiles if found
   let datafileAction: DatafileAction = "skip";
   if (foundDatafiles.length > 0 && !options.skipDatafilePrompt) {
@@ -575,12 +629,17 @@ export async function runInit(options: InitOptions = {}): Promise<InitResult> {
     if (includeCiWorkflow || includeCdWorkflow) {
       cicdSummary = workflowProvider === "gitlab" ? "GitLab" : "GitHub";
     }
+    const toolsSummary =
+      installTools.length > 0
+        ? installTools.map(getInstallToolLabel).join(", ")
+        : "none selected";
 
     const summaryLines = [
       `Mode: ${devModeLabel}`,
       `Folder: ${relativeTinybirdDir}/`,
       `Existing datafiles: ${datafileSummary}`,
       `CI/CD: ${cicdSummary}`,
+      `Tools: ${toolsSummary}`,
     ];
 
     p.note(summaryLines.join("\n"), "Installation Summary");
@@ -748,7 +807,9 @@ export async function runInit(options: InitOptions = {}): Promise<InitResult> {
     const packageManager = detectPackageManager(cwd);
     const addCmd = getPackageManagerAddCmd(packageManager);
     try {
-      execSync(`${addCmd} @tinybirdco/sdk`, { cwd, stdio: "pipe" });
+      await flushSpinnerRender();
+      const { command, args } = splitCommandPrefix(addCmd);
+      await runCommand(command, [...args, "@tinybirdco/sdk"], cwd);
       s.stop("Installed dependencies");
       created.push("@tinybirdco/sdk");
     } catch (error) {
@@ -761,6 +822,16 @@ export async function runInit(options: InitOptions = {}): Promise<InitResult> {
     }
   }
 
+  if (installTools.length > 0 && !skipToolsInstall) {
+    await installSelectedTools(
+      cwd,
+      installTools,
+      created,
+      skipped,
+      installedTools
+    );
+  }
+
   // Use git root for workflow files, fallback to cwd if not in a git repo
   const projectRoot = getGitRoot() ?? cwd;
   const githubWorkflowsDir = path.join(projectRoot, ".github", "workflows");
@@ -911,6 +982,8 @@ export async function runInit(options: InitOptions = {}): Promise<InitResult> {
         ciWorkflowCreated,
         cdWorkflowCreated,
         workflowProvider,
+        installTools: installTools.length > 0 ? installTools : undefined,
+        installedTools: installedTools.length > 0 ? installedTools : undefined,
       };
     }
 
@@ -958,6 +1031,9 @@ export async function runInit(options: InitOptions = {}): Promise<InitResult> {
           ciWorkflowCreated,
           cdWorkflowCreated,
           workflowProvider,
+          installTools: installTools.length > 0 ? installTools : undefined,
+          installedTools:
+            installedTools.length > 0 ? installedTools : undefined,
         };
       } catch (error) {
         // Login succeeded but saving credentials failed
@@ -976,6 +1052,9 @@ export async function runInit(options: InitOptions = {}): Promise<InitResult> {
           ciWorkflowCreated,
           cdWorkflowCreated,
           workflowProvider,
+          installTools: installTools.length > 0 ? installTools : undefined,
+          installedTools:
+            installedTools.length > 0 ? installedTools : undefined,
         };
       }
     } else {
@@ -992,6 +1071,8 @@ export async function runInit(options: InitOptions = {}): Promise<InitResult> {
         ciWorkflowCreated,
         cdWorkflowCreated,
         workflowProvider,
+        installTools: installTools.length > 0 ? installTools : undefined,
+        installedTools: installedTools.length > 0 ? installedTools : undefined,
       };
     }
   }
@@ -1032,11 +1113,228 @@ export async function runInit(options: InitOptions = {}): Promise<InitResult> {
     ciWorkflowCreated,
     cdWorkflowCreated,
     workflowProvider,
+    installTools: installTools.length > 0 ? installTools : undefined,
+    installedTools: installedTools.length > 0 ? installedTools : undefined,
   };
 }
 
 type DatafileAction = "include" | "codegen" | "skip";
 
+const SKILLS_INSTALL_COMMAND = "npx";
+const SKILLS_INSTALL_ARGS = [
+  "skills",
+  "add",
+  "tinybirdco/tinybird-agent-skills",
+  "--skill",
+  "tinybird",
+  "--skill",
+  "tinybird-typescript-sdk-guidelines",
+  "--yes",
+];
+const SYNTAX_EXTENSION_DIR = path.join("extension");
+const SYNTAX_EXTENSION_PREFIX = "tinybird-ts-sdk-extension";
+
+async function installSelectedTools(
+  cwd: string,
+  installTools: InstallTool[],
+  created: string[],
+  skipped: string[],
+  installedTools: string[]
+): Promise<void> {
+  const s = p.spinner();
+  const installedBefore = installedTools.length;
+  s.start("Installing tools");
+  await flushSpinnerRender();
+
+  if (installTools.includes("skills")) {
+    await installSkills(cwd, created, skipped, installedTools);
+  }
+
+  if (installTools.includes("syntax-highlighting")) {
+    await installSyntaxHighlighting(cwd, created, skipped, installedTools);
+  }
+
+  const installedCount = installedTools.length - installedBefore;
+  if (installedCount > 0) {
+    s.stop("Installed tools");
+  } else {
+    s.stop("No tools installed");
+  }
+}
+
+async function flushSpinnerRender(): Promise<void> {
+  // Yield once so terminal UI can paint before child process work starts.
+  await new Promise<void>((resolve) => setTimeout(resolve, 20));
+}
+
+async function installSkills(
+  cwd: string,
+  created: string[],
+  skipped: string[],
+  installedTools: string[]
+): Promise<void> {
+  try {
+    const installCwd = resolveRepoRoot(cwd);
+    await runCommand(SKILLS_INSTALL_COMMAND, SKILLS_INSTALL_ARGS, installCwd);
+    created.push("agent skills (tinybird, tinybird-typescript-sdk-guidelines)");
+    installedTools.push("agent-skills");
+  } catch (error) {
+    skipped.push("agent skills (installation failed)");
+    console.error(
+      `Warning: Failed to install Tinybird agent skills: ${(error as Error).message}`
+    );
+  }
+}
+
+function getInstallToolLabel(tool: InstallTool): string {
+  if (tool === "skills") {
+    return "agent skills";
+  }
+
+  return "syntax highlighting";
+}
+
+async function installSyntaxHighlighting(
+  cwd: string,
+  created: string[],
+  skipped: string[],
+  installedTools: string[]
+): Promise<void> {
+  const editors = [
+    { command: "cursor", label: "Cursor" },
+    { command: "code", label: "VS Code" },
+  ].filter((editor) => isCommandAvailable(editor.command));
+
+  if (editors.length === 0) {
+    skipped.push("syntax highlighting (Cursor/VS Code CLI not found)");
+    return;
+  }
+
+  const vsixPath = findSyntaxHighlightingVsix(cwd);
+  if (!vsixPath) {
+    skipped.push("syntax highlighting (VSIX not found)");
+    return;
+  }
+
+  for (const editor of editors) {
+    try {
+      await runCommand(
+        editor.command,
+        ["--install-extension", vsixPath, "--force"],
+        cwd
+      );
+      created.push(`syntax highlighting (${editor.label})`);
+      installedTools.push(`syntax-highlighting:${editor.command}`);
+    } catch (error) {
+      skipped.push(`syntax highlighting (${editor.label}, install failed)`);
+      console.error(
+        `Warning: Failed to install syntax highlighting in ${editor.label}: ${
+          (error as Error).message
+        }`
+      );
+    }
+  }
+}
+
+function resolveRepoRoot(cwd: string): string {
+  try {
+    return execSync("git rev-parse --show-toplevel", {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+  } catch {
+    return cwd;
+  }
+}
+
+function runCommand(command: string, args: string[], cwd: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      stdio: "ignore",
+    });
+
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+
+      reject(
+        new Error(
+          `Command failed (${code ?? "unknown"}): ${command} ${args.join(" ")}`
+        )
+      );
+    });
+  });
+}
+
+function splitCommandPrefix(commandPrefix: string): {
+  command: string;
+  args: string[];
+} {
+  const parts = commandPrefix.trim().split(/\s+/).filter(Boolean);
+  if (parts.length === 0) {
+    throw new Error("Invalid command prefix");
+  }
+  return {
+    command: parts[0],
+    args: parts.slice(1),
+  };
+}
+
+function isCommandAvailable(command: string): boolean {
+  try {
+    execSync(`command -v ${command}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function findSyntaxHighlightingVsix(cwd: string): string | undefined {
+  const searchRoots = new Set<string>();
+  const gitRoot = getGitRoot();
+  if (gitRoot) {
+    searchRoots.add(gitRoot);
+  }
+
+  let current = path.resolve(cwd);
+  while (true) {
+    searchRoots.add(current);
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+
+  for (const root of searchRoots) {
+    const extensionDir = path.join(root, SYNTAX_EXTENSION_DIR);
+    if (!fs.existsSync(extensionDir)) {
+      continue;
+    }
+
+    try {
+      const files = fs
+        .readdirSync(extensionDir)
+        .filter(
+          (file) =>
+            file.endsWith(".vsix") && file.startsWith(SYNTAX_EXTENSION_PREFIX)
+        )
+        .sort();
+
+      if (files.length > 0) {
+        return path.join(extensionDir, files[files.length - 1]);
+      }
+    } catch {
+      // Ignore unreadable directories
+    }
+  }
+
+  return undefined;
+}
+
 /**
  * Generate TypeScript files from Tinybird workspace resources
  * Only generates for resources that match the local datafiles

package/src/cli/config-types.ts

@@ -16,7 +16,7 @@ export type DevMode = "branch" | "local";
  * Tinybird configuration file structure
  */
 export interface TinybirdConfig {
-  /** Array of TypeScript files to scan for datasources and pipes */
+  /** Array of file paths or glob patterns to scan for TypeScript/resources */
   include?: string[];
   /** @deprecated Use `include` instead. Path to the TypeScript schema entry point */
   schema?: string;

package/src/cli/config.ts

@@ -14,7 +14,7 @@ import type { DevMode, TinybirdConfig } from "./config-types.js";
  * Resolved configuration with all values expanded
  */
 export interface ResolvedConfig {
-  /** Array of TypeScript files to scan for datasources and pipes */
+  /** Array of file paths or glob patterns to scan for datasources and pipes */
   include: string[];
   /** Resolved API token (workspace main token) */
   token: string;

package/src/client/base.test.ts

@@ -149,13 +149,15 @@ describe("TinybirdClient", () => {
       expect(client.datasources).toBeDefined();
     });
 
-    it("datasources namespace has append method", () => {
+    it("datasources namespace has ingest/append/replace/delete/truncate methods", () => {
       const client = createClient({
         baseUrl: "https://api.tinybird.co",
         token: "test-token",
       });
 
+      expect(typeof client.datasources.ingest).toBe("function");
       expect(typeof client.datasources.append).toBe("function");
+      expect(typeof client.datasources.replace).toBe("function");
       expect(typeof client.datasources.delete).toBe("function");
       expect(typeof client.datasources.truncate).toBe("function");
     });
@@ -168,7 +170,9 @@ describe("TinybirdClient", () => {
 
       const datasources: DatasourcesNamespace = client.datasources;
       expect(datasources).toBeDefined();
+      expect(typeof datasources.ingest).toBe("function");
       expect(typeof datasources.append).toBe("function");
+      expect(typeof datasources.replace).toBe("function");
       expect(typeof datasources.delete).toBe("function");
       expect(typeof datasources.truncate).toBe("function");
     });

package/src/client/base.ts

@@ -66,7 +66,7 @@ export class TinybirdClient {
   private resolvedContext: ClientContext | null = null;
 
   /**
-   * Datasources namespace for import operations
+   * Datasources namespace for ingest and import operations
    */
   readonly datasources: DatasourcesNamespace;
 
@@ -90,9 +90,19 @@ export class TinybirdClient {
 
     // Initialize datasources namespace
     this.datasources = {
+      ingest: <T extends Record<string, unknown>>(
+        datasourceName: string,
+        event: T,
+        options: IngestOptions = {}
+      ): Promise<IngestResult> => {
+        return this.ingestDatasource(datasourceName, event, options);
+      },
       append: (datasourceName: string, options: AppendOptions): Promise<AppendResult> => {
         return this.appendDatasource(datasourceName, options);
       },
+      replace: (datasourceName: string, options: AppendOptions): Promise<AppendResult> => {
+        return this.replaceDatasource(datasourceName, options);
+      },
       delete: (datasourceName: string, options: DeleteOptions): Promise<DeleteResult> => {
         return this.deleteDatasource(datasourceName, options);
       },
@@ -146,6 +156,28 @@ export class TinybirdClient {
     }
   }
 
+  /**
+   * Replace datasource rows from a URL or local file
+   *
+   * @param datasourceName - Name of the datasource
+   * @param options - Replace options including url or file source
+   * @returns Append-style result
+   */
+  private async replaceDatasource(
+    datasourceName: string,
+    options: AppendOptions
+  ): Promise<AppendResult> {
+    const token = await this.getToken();
+
+    try {
+      return await this.getApi(token).appendDatasource(datasourceName, options, {
+        mode: "replace",
+      });
+    } catch (error) {
+      this.rethrowApiError(error);
+    }
+  }
+
   /**
    * Delete rows from a datasource using a SQL condition
    *
@@ -186,6 +218,28 @@ export class TinybirdClient {
     }
   }
 
+  /**
+   * Ingest a single event to a datasource
+   *
+   * @param datasourceName - Name of the datasource
+   * @param event - Event data to ingest
+   * @param options - Additional request options
+   * @returns Ingest result
+   */
+  private async ingestDatasource<T extends Record<string, unknown>>(
+    datasourceName: string,
+    event: T,
+    options: IngestOptions = {}
+  ): Promise<IngestResult> {
+    const token = await this.getToken();
+
+    try {
+      return await this.getApi(token).ingestBatch(datasourceName, [event], options);
+    } catch (error) {
+      this.rethrowApiError(error);
+    }
+  }
+
   /**
    * Get the effective token, resolving branch token in dev mode if needed
    */
@@ -351,7 +405,7 @@ export class TinybirdClient {
     event: T,
     options: IngestOptions = {}
   ): Promise<IngestResult> {
-    return this.ingestBatch(datasourceName, [event], options);
+    return this.datasources.ingest(datasourceName, event, options);
   }
 
   /**

package/src/client/types.ts

@@ -290,8 +290,16 @@ export interface TruncateResult {
  * Datasources namespace interface for raw client
  */
 export interface DatasourcesNamespace {
+  /** Ingest a single event into a datasource */
+  ingest<T extends Record<string, unknown>>(
+    datasourceName: string,
+    event: T,
+    options?: IngestOptions
+  ): Promise<IngestResult>;
   /** Append data to a datasource from a URL or file */
   append(datasourceName: string, options: AppendOptions): Promise<AppendResult>;
+  /** Replace all datasource rows with data from a URL or file */
+  replace(datasourceName: string, options: AppendOptions): Promise<AppendResult>;
   /** Delete rows from a datasource using a SQL condition */
   delete(datasourceName: string, options: DeleteOptions): Promise<DeleteResult>;
   /** Truncate all rows from a datasource */