@tinybirdco/sdk 0.0.47 → 0.0.48

package/src/migrate/emit-ts.ts

@@ -13,6 +13,79 @@ function escapeString(value: string): string {
   return JSON.stringify(value);
 }
 
+function emitObjectKey(key: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : escapeString(key);
+}
+
+interface ParsedSecretTemplate {
+  name: string;
+  defaultValue?: string;
+}
+
+function parseTbSecretTemplate(value: string): ParsedSecretTemplate | null {
+  const trimmed = value.trim();
+  const regex =
+    /^\{\{\s*tb_secret\(\s*["']([^"']+)["'](?:\s*,\s*["']([^"']*)["'])?\s*\)\s*\}\}$/;
+  const match = trimmed.match(regex);
+  if (!match) {
+    return null;
+  }
+  return {
+    name: match[1] ?? "",
+    defaultValue: match[2],
+  };
+}
+
+function emitStringOrSecret(value: string): string {
+  const parsed = parseTbSecretTemplate(value);
+  if (!parsed) {
+    return escapeString(value);
+  }
+  if (parsed.defaultValue !== undefined) {
+    return `secret(${escapeString(parsed.name)}, ${escapeString(parsed.defaultValue)})`;
+  }
+  return `secret(${escapeString(parsed.name)})`;
+}
+
+function hasSecretTemplate(resources: ParsedResource[]): boolean {
+  const values: string[] = [];
+
+  for (const resource of resources) {
+    if (resource.kind === "connection") {
+      if (resource.connectionType === "kafka") {
+        values.push(resource.bootstrapServers);
+        if (resource.key) values.push(resource.key);
+        if (resource.secret) values.push(resource.secret);
+        if (resource.sslCaPem) values.push(resource.sslCaPem);
+        if (resource.schemaRegistryUrl) values.push(resource.schemaRegistryUrl);
+      } else {
+        values.push(resource.region);
+        if (resource.arn) values.push(resource.arn);
+        if (resource.accessKey) values.push(resource.accessKey);
+        if (resource.secret) values.push(resource.secret);
+      }
+      continue;
+    }
+
+    if (resource.kind === "datasource") {
+      if (resource.description) values.push(resource.description);
+      if (resource.kafka) {
+        values.push(resource.kafka.topic);
+        if (resource.kafka.groupId) values.push(resource.kafka.groupId);
+        if (resource.kafka.autoOffsetReset) values.push(resource.kafka.autoOffsetReset);
+      }
+      if (resource.s3) {
+        values.push(resource.s3.bucketUri);
+        if (resource.s3.schedule) values.push(resource.s3.schedule);
+        if (resource.s3.fromTimestamp) values.push(resource.s3.fromTimestamp);
+      }
+      continue;
+    }
+  }
+
+  return values.some((value) => parseTbSecretTemplate(value) !== null);
+}
+
 function normalizedBaseType(type: string): string {
   let current = type.trim();
   let updated = true;
@@ -141,6 +214,9 @@ function emitEngineOptions(ds: DatasourceModel): string {
   if (engine.ver) {
     options.push(`ver: ${escapeString(engine.ver)}`);
   }
+  if (engine.isDeleted) {
+    options.push(`isDeleted: ${escapeString(engine.isDeleted)}`);
+  }
   if (engine.sign) {
     options.push(`sign: ${escapeString(engine.sign)}`);
   }
@@ -170,13 +246,6 @@ function emitDatasource(ds: DatasourceModel): string {
   const variableName = toCamelCase(ds.name);
   const lines: string[] = [];
   const hasJsonPath = ds.columns.some((column) => column.jsonPath !== undefined);
-  const hasMissingJsonPath = ds.columns.some((column) => column.jsonPath === undefined);
-
-  if (hasJsonPath && hasMissingJsonPath) {
-    throw new Error(
-      `Datasource "${ds.name}" has mixed json path usage. This is not representable in strict mode.`
-    );
-  }
 
   if (ds.description) {
     lines.push("/**");
@@ -188,7 +257,7 @@ function emitDatasource(ds: DatasourceModel): string {
 
   lines.push(`export const ${variableName} = defineDatasource(${escapeString(ds.name)}, {`);
   if (ds.description) {
-    lines.push(`  description: ${escapeString(ds.description)},`);
+    lines.push(`  description: ${emitStringOrSecret(ds.description)},`);
   }
   if (!hasJsonPath) {
     lines.push("  jsonPaths: false,");
@@ -197,6 +266,7 @@ function emitDatasource(ds: DatasourceModel): string {
   lines.push("  schema: {");
   for (const column of ds.columns) {
     let validator = strictColumnTypeToValidator(column.type);
+    const columnKey = emitObjectKey(column.name);
 
     if (column.defaultExpression !== undefined) {
       const parsedDefault = parseLiteralFromDatafile(column.defaultExpression);
@@ -220,12 +290,9 @@ function emitDatasource(ds: DatasourceModel): string {
     }
 
     if (column.jsonPath) {
-      lines.push(
-        `    ${column.name}: column(${validator}, { jsonPath: ${escapeString(column.jsonPath)} }),`
-      );
-    } else {
-      lines.push(`    ${column.name}: ${validator},`);
+      validator += `.jsonPath(${escapeString(column.jsonPath)})`;
     }
+    lines.push(`    ${columnKey}: ${validator},`);
   }
   lines.push("  },");
   lines.push(`  engine: ${emitEngineOptions(ds)},`);
@@ -234,12 +301,15 @@ function emitDatasource(ds: DatasourceModel): string {
     const connectionVar = toCamelCase(ds.kafka.connectionName);
     lines.push("  kafka: {");
     lines.push(`    connection: ${connectionVar},`);
-    lines.push(`    topic: ${escapeString(ds.kafka.topic)},`);
+    lines.push(`    topic: ${emitStringOrSecret(ds.kafka.topic)},`);
     if (ds.kafka.groupId) {
-      lines.push(`    groupId: ${escapeString(ds.kafka.groupId)},`);
+      lines.push(`    groupId: ${emitStringOrSecret(ds.kafka.groupId)},`);
     }
     if (ds.kafka.autoOffsetReset) {
-      lines.push(`    autoOffsetReset: ${escapeString(ds.kafka.autoOffsetReset)},`);
+      lines.push(`    autoOffsetReset: ${emitStringOrSecret(ds.kafka.autoOffsetReset)},`);
+    }
+    if (ds.kafka.storeRawValue !== undefined) {
+      lines.push(`    storeRawValue: ${ds.kafka.storeRawValue},`);
     }
     lines.push("  },");
   }
@@ -248,12 +318,12 @@ function emitDatasource(ds: DatasourceModel): string {
     const connectionVar = toCamelCase(ds.s3.connectionName);
     lines.push("  s3: {");
     lines.push(`    connection: ${connectionVar},`);
-    lines.push(`    bucketUri: ${escapeString(ds.s3.bucketUri)},`);
+    lines.push(`    bucketUri: ${emitStringOrSecret(ds.s3.bucketUri)},`);
     if (ds.s3.schedule) {
-      lines.push(`    schedule: ${escapeString(ds.s3.schedule)},`);
+      lines.push(`    schedule: ${emitStringOrSecret(ds.s3.schedule)},`);
     }
     if (ds.s3.fromTimestamp) {
-      lines.push(`    fromTimestamp: ${escapeString(ds.s3.fromTimestamp)},`);
+      lines.push(`    fromTimestamp: ${emitStringOrSecret(ds.s3.fromTimestamp)},`);
     }
     lines.push("  },");
   }
@@ -293,21 +363,24 @@ function emitConnection(connection: KafkaConnectionModel | S3ConnectionModel): s
     lines.push(
       `export const ${variableName} = defineKafkaConnection(${escapeString(connection.name)}, {`
     );
-    lines.push(`  bootstrapServers: ${escapeString(connection.bootstrapServers)},`);
+    lines.push(`  bootstrapServers: ${emitStringOrSecret(connection.bootstrapServers)},`);
     if (connection.securityProtocol) {
-      lines.push(`  securityProtocol: ${escapeString(connection.securityProtocol)},`);
+      lines.push(`  securityProtocol: ${emitStringOrSecret(connection.securityProtocol)},`);
     }
     if (connection.saslMechanism) {
-      lines.push(`  saslMechanism: ${escapeString(connection.saslMechanism)},`);
+      lines.push(`  saslMechanism: ${emitStringOrSecret(connection.saslMechanism)},`);
     }
     if (connection.key) {
-      lines.push(`  key: ${escapeString(connection.key)},`);
+      lines.push(`  key: ${emitStringOrSecret(connection.key)},`);
     }
     if (connection.secret) {
-      lines.push(`  secret: ${escapeString(connection.secret)},`);
+      lines.push(`  secret: ${emitStringOrSecret(connection.secret)},`);
+    }
+    if (connection.schemaRegistryUrl) {
+      lines.push(`  schemaRegistryUrl: ${emitStringOrSecret(connection.schemaRegistryUrl)},`);
     }
     if (connection.sslCaPem) {
-      lines.push(`  sslCaPem: ${escapeString(connection.sslCaPem)},`);
+      lines.push(`  sslCaPem: ${emitStringOrSecret(connection.sslCaPem)},`);
     }
     lines.push("});");
     lines.push("");
@@ -317,15 +390,15 @@ function emitConnection(connection: KafkaConnectionModel | S3ConnectionModel): s
   lines.push(
     `export const ${variableName} = defineS3Connection(${escapeString(connection.name)}, {`
   );
-  lines.push(`  region: ${escapeString(connection.region)},`);
+  lines.push(`  region: ${emitStringOrSecret(connection.region)},`);
   if (connection.arn) {
-    lines.push(`  arn: ${escapeString(connection.arn)},`);
+    lines.push(`  arn: ${emitStringOrSecret(connection.arn)},`);
   }
   if (connection.accessKey) {
-    lines.push(`  accessKey: ${escapeString(connection.accessKey)},`);
+    lines.push(`  accessKey: ${emitStringOrSecret(connection.accessKey)},`);
   }
   if (connection.secret) {
-    lines.push(`  secret: ${escapeString(connection.secret)},`);
+    lines.push(`  secret: ${emitStringOrSecret(connection.secret)},`);
   }
   lines.push("});");
   lines.push("");
@@ -368,7 +441,7 @@ function emitPipe(pipe: PipeModel): string {
           param.required,
           param.defaultValue
         );
-        lines.push(`    ${param.name}: ${validator},`);
+        lines.push(`    ${emitObjectKey(param.name)}: ${validator},`);
       }
       lines.push("  },");
     }
@@ -413,7 +486,7 @@ function emitPipe(pipe: PipeModel): string {
     }
     lines.push("  output: {");
     for (const columnName of endpointOutputColumns) {
-      lines.push(`    ${columnName}: t.string(),`);
+      lines.push(`    ${emitObjectKey(columnName)}: t.string(),`);
     }
     lines.push("  },");
   }
@@ -443,10 +516,8 @@ export function emitMigrationFileContent(resources: ParsedResource[]): string {
     (resource): resource is PipeModel => resource.kind === "pipe"
   );
 
-  const needsColumn = datasources.some((ds) =>
-    ds.columns.some((column) => column.jsonPath !== undefined)
-  );
   const needsParams = pipes.some((pipe) => pipe.params.length > 0);
+  const needsSecret = hasSecretTemplate(resources);
 
   const imports = new Set<string>([
     "defineDatasource",
@@ -463,12 +534,12 @@ export function emitMigrationFileContent(resources: ParsedResource[]): string {
   if (connections.some((connection) => connection.connectionType === "s3")) {
     imports.add("defineS3Connection");
   }
-  if (needsColumn) {
-    imports.add("column");
-  }
   if (needsParams) {
     imports.add("p");
   }
+  if (needsSecret) {
+    imports.add("secret");
+  }
 
   const orderedImports = [
     "defineKafkaConnection",
@@ -480,7 +551,7 @@ export function emitMigrationFileContent(resources: ParsedResource[]): string {
     "node",
     "t",
     "engine",
-    "column",
+    "secret",
     "p",
   ].filter((name) => imports.has(name));
 

package/src/migrate/parse-connection.ts

@@ -27,6 +27,7 @@ export function parseConnectionFile(
     | undefined;
   let key: string | undefined;
   let secret: string | undefined;
+  let schemaRegistryUrl: string | undefined;
   let sslCaPem: string | undefined;
 
   let region: string | undefined;
@@ -36,7 +37,7 @@ export function parseConnectionFile(
 
   for (const rawLine of lines) {
     const line = rawLine.trim();
-    if (isBlank(line)) {
+    if (isBlank(line) || line.startsWith("#")) {
       continue;
     }
 
@@ -81,6 +82,9 @@ export function parseConnectionFile(
       case "KAFKA_SECRET":
         secret = value;
         break;
+      case "KAFKA_SCHEMA_REGISTRY_URL":
+        schemaRegistryUrl = value;
+        break;
       case "KAFKA_SSL_CA_PEM":
         sslCaPem = value;
         break;
@@ -144,12 +148,21 @@ export function parseConnectionFile(
       saslMechanism,
       key,
       secret,
+      schemaRegistryUrl,
       sslCaPem,
     };
   }
 
   if (connectionType === "s3") {
-    if (bootstrapServers || securityProtocol || saslMechanism || key || secret || sslCaPem) {
+    if (
+      bootstrapServers ||
+      securityProtocol ||
+      saslMechanism ||
+      key ||
+      secret ||
+      schemaRegistryUrl ||
+      sslCaPem
+    ) {
       throw new MigrationParseError(
         resource.filePath,
         "connection",

package/src/migrate/parse-datasource.ts

@@ -95,9 +95,19 @@ function parseColumnLine(filePath: string, resourceName: string, rawLine: string
     );
   }
 
-  const columnName = line.slice(0, firstSpace).trim();
+  const rawColumnName = line.slice(0, firstSpace).trim();
+  const columnName = normalizeColumnName(rawColumnName);
   let rest = line.slice(firstSpace + 1).trim();
 
+  if (!columnName) {
+    throw new MigrationParseError(
+      filePath,
+      "datasource",
+      resourceName,
+      `Invalid schema column name: "${rawLine}"`
+    );
+  }
+
   const codecMatch = rest.match(/\s+CODEC\((.+)\)\s*$/);
   const codec = codecMatch ? codecMatch[1].trim() : undefined;
   if (codecMatch?.index !== undefined) {
@@ -136,6 +146,17 @@ function parseColumnLine(filePath: string, resourceName: string, rawLine: string
   };
 }
 
+function normalizeColumnName(value: string): string {
+  const trimmed = value.trim();
+  if (
+    (trimmed.startsWith("`") && trimmed.endsWith("`")) ||
+    (trimmed.startsWith('"') && trimmed.endsWith('"'))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
 function parseEngineSettings(value: string): Record<string, string | number | boolean> {
   const raw = parseQuotedValue(value);
   const parts = splitTopLevelComma(raw);
@@ -223,6 +244,7 @@ export function parseDatasourceFile(resource: ResourceFile): DatasourceModel {
   let primaryKey: string[] | undefined;
   let ttl: string | undefined;
   let ver: string | undefined;
+  let isDeleted: string | undefined;
   let sign: string | undefined;
   let version: string | undefined;
   let summingColumns: string[] | undefined;
@@ -232,6 +254,7 @@ export function parseDatasourceFile(resource: ResourceFile): DatasourceModel {
   let kafkaTopic: string | undefined;
   let kafkaGroupId: string | undefined;
   let kafkaAutoOffsetReset: "earliest" | "latest" | undefined;
+  let kafkaStoreRawValue: boolean | undefined;
 
   let importConnectionName: string | undefined;
   let importBucketUri: string | undefined;
@@ -242,7 +265,7 @@ export function parseDatasourceFile(resource: ResourceFile): DatasourceModel {
   while (i < lines.length) {
     const rawLine = lines[i] ?? "";
     const line = rawLine.trim();
-    if (!line) {
+    if (!line || line.startsWith("#")) {
       i += 1;
       continue;
     }
@@ -273,7 +296,7 @@ export function parseDatasourceFile(resource: ResourceFile): DatasourceModel {
         );
       }
       for (const schemaLine of block.lines) {
-        if (isBlank(schemaLine)) {
+        if (isBlank(schemaLine) || schemaLine.trim().startsWith("#")) {
           continue;
         }
         columns.push(parseColumnLine(resource.filePath, resource.name, schemaLine));
@@ -329,6 +352,9 @@ export function parseDatasourceFile(resource: ResourceFile): DatasourceModel {
       case "ENGINE_VER":
         ver = parseQuotedValue(value);
         break;
+      case "ENGINE_IS_DELETED":
+        isDeleted = parseQuotedValue(value);
+        break;
       case "ENGINE_SIGN":
         sign = parseQuotedValue(value);
         break;
@@ -370,6 +396,23 @@ export function parseDatasourceFile(resource: ResourceFile): DatasourceModel {
         }
         kafkaAutoOffsetReset = value;
         break;
+      case "KAFKA_STORE_RAW_VALUE": {
+        const normalized = value.toLowerCase();
+        if (normalized === "true" || normalized === "1") {
+          kafkaStoreRawValue = true;
+          break;
+        }
+        if (normalized === "false" || normalized === "0") {
+          kafkaStoreRawValue = false;
+          break;
+        }
+        throw new MigrationParseError(
+          resource.filePath,
+          "datasource",
+          resource.name,
+          `Invalid KAFKA_STORE_RAW_VALUE value: "${value}"`
+        );
+      }
       case "IMPORT_CONNECTION_NAME":
         importConnectionName = parseQuotedValue(value);
         break;
@@ -425,12 +468,17 @@ export function parseDatasourceFile(resource: ResourceFile): DatasourceModel {
   }
 
   const kafka =
-    kafkaConnectionName || kafkaTopic || kafkaGroupId || kafkaAutoOffsetReset
+    kafkaConnectionName ||
+    kafkaTopic ||
+    kafkaGroupId ||
+    kafkaAutoOffsetReset ||
+    kafkaStoreRawValue !== undefined
       ? {
           connectionName: kafkaConnectionName ?? "",
           topic: kafkaTopic ?? "",
           groupId: kafkaGroupId,
           autoOffsetReset: kafkaAutoOffsetReset,
+          storeRawValue: kafkaStoreRawValue,
         }
       : undefined;
 
@@ -484,6 +532,7 @@ export function parseDatasourceFile(resource: ResourceFile): DatasourceModel {
       primaryKey,
       ttl,
       ver,
+      isDeleted,
       sign,
       version,
       summingColumns,

package/src/migrate/parse-pipe.ts

@@ -45,7 +45,10 @@ function readIndentedBlock(lines: string[], startIndex: number): BlockReadResult
 
 function nextNonBlank(lines: string[], startIndex: number): number {
   let i = startIndex;
-  while (i < lines.length && isBlank(lines[i] ?? "")) {
+  while (
+    i < lines.length &&
+    (isBlank(lines[i] ?? "") || (lines[i] ?? "").trim().startsWith("#"))
+  ) {
     i += 1;
   }
   return i;
@@ -267,7 +270,7 @@ export function parsePipeFile(resource: ResourceFile): PipeModel {
   let i = 0;
   while (i < lines.length) {
     const line = (lines[i] ?? "").trim();
-    if (!line) {
+    if (!line || line.startsWith("#")) {
       i += 1;
       continue;
     }
@@ -515,4 +518,3 @@ export function parsePipeFile(resource: ResourceFile): PipeModel {
     inferredOutputColumns,
   };
 }
-

package/src/migrate/types.ts

@@ -30,6 +30,7 @@ export interface DatasourceEngineModel {
   primaryKey?: string[];
   ttl?: string;
   ver?: string;
+  isDeleted?: string;
   sign?: string;
   version?: string;
   summingColumns?: string[];
@@ -41,6 +42,7 @@ export interface DatasourceKafkaModel {
   topic: string;
   groupId?: string;
   autoOffsetReset?: "earliest" | "latest";
+  storeRawValue?: boolean;
 }
 
 export interface DatasourceS3Model {
@@ -117,6 +119,7 @@ export interface KafkaConnectionModel {
   saslMechanism?: "PLAIN" | "SCRAM-SHA-256" | "SCRAM-SHA-512" | "OAUTHBEARER";
   key?: string;
   secret?: string;
+  schemaRegistryUrl?: string;
   sslCaPem?: string;
 }
 

package/src/schema/connection.ts

@@ -31,6 +31,8 @@ export interface KafkaConnectionOptions {
   key?: string;
   /** Kafka secret/password - can use {{ tb_secret(...) }} */
   secret?: string;
+  /** Schema Registry URL (optionally with embedded auth credentials) */
+  schemaRegistryUrl?: string;
   /** SSL CA certificate PEM - for private CA certs */
   sslCaPem?: string;
 }

package/src/schema/datasource.test.ts

@@ -169,6 +169,22 @@ describe("Datasource Schema", () => {
 
       expect(result).toBeUndefined();
     });
+
+    it("returns jsonPath from validator modifier", () => {
+      const validator = t.string().jsonPath("$.user.id");
+      const result = getColumnJsonPath(validator);
+
+      expect(result).toBe("$.user.id");
+    });
+
+    it("prefers column definition jsonPath over validator modifier", () => {
+      const col = column(t.string().jsonPath("$.from_validator"), {
+        jsonPath: "$.from_column",
+      });
+      const result = getColumnJsonPath(col);
+
+      expect(result).toBe("$.from_column");
+    });
   });
 
   describe("getColumnNames", () => {

package/src/schema/datasource.ts

@@ -3,7 +3,7 @@
  * Define table schemas as TypeScript with full type safety
  */
 
-import type { AnyTypeValidator } from "./types.js";
+import { getModifiers, isTypeValidator, type AnyTypeValidator } from "./types.js";
 import type { EngineConfig } from "./engines.js";
 import type { KafkaConnectionDefinition, S3ConnectionDefinition } from "./connection.js";
 import type { TokenDefinition, DatasourceTokenScope } from "./token.js";
@@ -66,6 +66,8 @@ export interface KafkaConfig {
   groupId?: string;
   /** Where to start reading: 'earliest' or 'latest' (default: 'latest') */
   autoOffsetReset?: "earliest" | "latest";
+  /** Whether to store the raw Kafka value payload */
+  storeRawValue?: boolean;
 }
 
 /**
@@ -207,9 +209,18 @@ export function getColumnType(column: AnyTypeValidator | ColumnDefinition): AnyT
  * Get the JSON path for a column if defined
  */
 export function getColumnJsonPath(column: AnyTypeValidator | ColumnDefinition): string | undefined {
-  if ("jsonPath" in column) {
+  if (isTypeValidator(column)) {
+    return getModifiers(column).jsonPath;
+  }
+
+  if (column.jsonPath !== undefined) {
     return column.jsonPath;
   }
+
+  if (isTypeValidator(column.type)) {
+    return getModifiers(column.type).jsonPath;
+  }
+
   return undefined;
 }
 

package/src/schema/engines.test.ts

@@ -44,6 +44,14 @@ describe('Engine Configurations', () => {
       });
       expect(config.ver).toBe('updated_at');
     });
+
+    it('supports isDeleted column', () => {
+      const config = engine.replacingMergeTree({
+        sortingKey: ['id'],
+        isDeleted: '_is_deleted',
+      });
+      expect(config.isDeleted).toBe('_is_deleted');
+    });
   });
 
   describe('SummingMergeTree', () => {
@@ -138,6 +146,16 @@ describe('Engine Configurations', () => {
       expect(clause).toContain('ENGINE_VER "updated_at"');
     });
 
+    it('includes ReplacingMergeTree isDeleted column', () => {
+      const config = engine.replacingMergeTree({
+        sortingKey: ['id'],
+        isDeleted: '_is_deleted',
+      });
+      const clause = getEngineClause(config);
+      expect(clause).toContain('ENGINE "ReplacingMergeTree"');
+      expect(clause).toContain('ENGINE_IS_DELETED "_is_deleted"');
+    });
+
     it('includes SummingMergeTree columns', () => {
       const config = engine.summingMergeTree({
         sortingKey: ['date'],

package/src/schema/engines.ts

@@ -241,6 +241,9 @@ export function getEngineClause(config: EngineConfig): string {
   if (config.type === "ReplacingMergeTree" && config.ver) {
     parts.push(`ENGINE_VER "${config.ver}"`);
   }
+  if (config.type === "ReplacingMergeTree" && config.isDeleted) {
+    parts.push(`ENGINE_IS_DELETED "${config.isDeleted}"`);
+  }
 
   if (config.type === "CollapsingMergeTree" || config.type === "VersionedCollapsingMergeTree") {
     parts.push(`ENGINE_SIGN "${config.sign}"`);

package/src/schema/secret.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { secret } from "./secret.js";
+
+describe("secret helper", () => {
+  it("creates a secret template without default", () => {
+    expect(secret("KAFKA_KEY")).toBe('{{ tb_secret("KAFKA_KEY") }}');
+  });
+
+  it("creates a secret template with default", () => {
+    expect(secret("KAFKA_GROUP_ID", "events_group")).toBe(
+      '{{ tb_secret("KAFKA_GROUP_ID", "events_group") }}'
+    );
+  });
+
+  it("throws on empty secret name", () => {
+    expect(() => secret("")).toThrow("Secret name must be a non-empty string.");
+  });
+});
+

package/src/schema/secret.ts

@@ -0,0 +1,16 @@
+/**
+ * Secret template helper.
+ * Produces Tinybird-compatible `tb_secret(...)` template strings.
+ */
+export function secret(name: string, defaultValue?: string): string {
+  if (!name || name.trim().length === 0) {
+    throw new Error("Secret name must be a non-empty string.");
+  }
+
+  if (defaultValue === undefined) {
+    return `{{ tb_secret("${name}") }}`;
+  }
+
+  return `{{ tb_secret("${name}", "${defaultValue}") }}`;
+}
+

package/src/schema/types.test.ts

@@ -115,6 +115,20 @@ describe('Type Validators (t.*)', () => {
     });
   });
 
+  describe('jsonPath modifier', () => {
+    it('sets jsonPath in modifiers', () => {
+      const type = t.string().jsonPath('$.payload.id');
+      expect(type._modifiers.jsonPath).toBe('$.payload.id');
+    });
+
+    it('supports chaining with other modifiers', () => {
+      const type = t.string().nullable().jsonPath('$.user.name');
+      expect(type._tinybirdType).toBe('Nullable(String)');
+      expect(type._modifiers.nullable).toBe(true);
+      expect(type._modifiers.jsonPath).toBe('$.user.name');
+    });
+  });
+
   describe('Complex types', () => {
     it('generates Array type', () => {
       const type = t.array(t.string());