@superblocksteam/sdk-api 2.0.102 → 2.0.103

package/src/integrations/gcs/client.ts

@@ -4,13 +4,15 @@
  * Uses the native GCS plugin type from @superblocksteam/types.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as GCSPlugin } from "@superblocksteam/types/dist/src/plugins/gcs/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { RestApiValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import type {
   GCSClient,
   GCSAction,

package/src/integrations/gcs/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 

package/src/integrations/graphql/types.ts

@@ -2,9 +2,10 @@
  * GraphQL client types.
  */
 
+import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
-import type { z } from "zod";
 
 /**
  * GraphQL client for executing queries and mutations.

package/src/integrations/gsheets/client.ts

@@ -4,13 +4,15 @@
  * Uses the native Google Sheets plugin type from @superblocksteam/types.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as GSheetsPlugin } from "@superblocksteam/types/dist/src/plugins/gsheets/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { RestApiValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import type {
   GoogleSheetsClient,
   GoogleSheetsAction,

package/src/integrations/gsheets/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 

package/src/integrations/kafka/client.ts

@@ -5,10 +5,11 @@
  */
 
 import type { z } from "zod";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { RestApiValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import type {
   KafkaClient,
   KafkaConsumeParams,

package/src/integrations/kafka/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 

package/src/integrations/kinesis/client.ts

@@ -5,9 +5,9 @@
  * Supports PUT (write records) and GET (read records) operations.
  */
 
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import type {
   KinesisClient,
   KinesisPutParams,

package/src/integrations/lakebase/README.md

@@ -0,0 +1,242 @@
+# Lakebase Client
+
+Execute SQL queries and statements against Lakebase databases with full type safety and runtime validation.
+
+## Methods
+
+| Method                                      | Description                                                                |
+| ------------------------------------------- | -------------------------------------------------------------------------- |
+| `query<T>(sql, schema, params?, metadata?)` | Execute a SELECT query and return validated, typed results                 |
+| `execute(sql, params?, metadata?)`          | Execute a statement (INSERT, UPDATE, DELETE) and return affected row count |
+
+## Usage
+
+### Basic Query with Schema Validation
+
+```typescript
+import { api, z, lakebase } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const LAKEBASE_DB = "a1b2c3d4-5678-90ab-cdef-111111111111";
+
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string(),
+  created_at: z.string(),
+});
+
+export default api({
+  name: "GetUsers",
+  integrations: {
+    db: lakebase(LAKEBASE_DB),
+  },
+  input: z.object({
+    status: z.string(),
+  }),
+  output: z.object({
+    users: z.array(UserSchema),
+  }),
+  async run(ctx, { status }) {
+    const users = await ctx.integrations.db.query(
+      "SELECT id, name, email, created_at FROM users WHERE status = $1",
+      UserSchema,
+      [status],
+    );
+
+    return { users };
+  },
+});
+```
+
+### Executing INSERT, UPDATE, DELETE Statements
+
+```typescript
+import { api, z, lakebase } from "@superblocksteam/sdk-api";
+
+const LAKEBASE_DB = "a1b2c3d4-5678-90ab-cdef-111111111111";
+
+export default api({
+  name: "ManageUsers",
+  integrations: {
+    db: lakebase(LAKEBASE_DB),
+  },
+  input: z.object({
+    name: z.string(),
+    email: z.string(),
+  }),
+  output: z.object({ success: z.boolean() }),
+
+  async run(ctx, { name, email }) {
+    // INSERT
+    await ctx.integrations.db.execute(
+      "INSERT INTO users (name, email) VALUES ($1, $2)",
+      [name, email],
+    );
+
+    // UPDATE
+    const updateResult = await ctx.integrations.db.execute(
+      "UPDATE users SET last_login = NOW() WHERE email = $1",
+      [email],
+    );
+    console.log(`Updated ${updateResult.rowCount} rows`);
+
+    // DELETE
+    const deleteResult = await ctx.integrations.db.execute(
+      "DELETE FROM sessions WHERE expires_at < NOW()",
+    );
+    console.log(`Deleted ${deleteResult.rowCount} expired sessions`);
+
+    return { success: true };
+  },
+});
+```
+
+### Query with JOIN
+
+```typescript
+const OrderSchema = z.object({
+  order_id: z.string(),
+  customer_name: z.string(),
+  total: z.string(), // NUMERIC as string
+});
+
+const orders = await ctx.integrations.db.query(
+  `SELECT o.id as order_id, c.name as customer_name, o.total
+   FROM orders o
+   JOIN customers c ON o.customer_id = c.id
+   WHERE o.status = $1`,
+  OrderSchema,
+  ["pending"],
+);
+```
+
+## Trace Metadata
+
+All methods accept an optional `metadata` parameter as the last argument for diagnostics labeling:
+
+```typescript
+const users = await ctx.integrations.db.query(
+  "SELECT * FROM users WHERE status = $1",
+  UserSchema,
+  ["active"],
+  { label: "Fetch active users" },
+);
+
+await ctx.integrations.db.execute(
+  "DELETE FROM sessions WHERE expires_at < NOW()",
+  undefined, // no params
+  { label: "Clean expired sessions" },
+);
+```
+
+When `includeDiagnostics` is enabled, `label` and `description` appear in the trace view. See the [root SDK README](../../../README.md#trace-metadata) for details.
+
+## Common Pitfalls
+
+### Uses `$1` Placeholders (PostgreSQL-Style)
+
+Lakebase uses `$1, $2, ...` for parameter placeholders, following PostgreSQL conventions:
+
+```typescript
+// WRONG - Question-mark placeholders
+const users = await ctx.integrations.db.query(
+  "SELECT * FROM users WHERE name = ? AND status = ?",
+  UserSchema,
+  [name, status],
+);
+
+// CORRECT - Use $1, $2, ... placeholders
+const users = await ctx.integrations.db.query(
+  "SELECT * FROM users WHERE name = $1 AND status = $2",
+  UserSchema,
+  [name, status],
+);
+```
+
+### Schema Parameter is Required
+
+The `query()` method requires a Zod schema for runtime validation:
+
+```typescript
+// WRONG - Missing schema parameter
+const users = await ctx.integrations.db.query(
+  "SELECT * FROM users",
+  [
+    /* params */
+  ], // This is wrong - params are 3rd argument
+);
+
+// CORRECT - Schema is the second parameter
+const users = await ctx.integrations.db.query(
+  "SELECT * FROM users WHERE id = $1",
+  UserSchema, // Schema is required
+  [userId], // Params are optional, third argument
+);
+```
+
+### Use Parameterized Queries to Prevent SQL Injection
+
+Always use `$1, $2, ...` placeholders instead of string interpolation:
+
+```typescript
+// WRONG - SQL injection vulnerability
+const users = await ctx.integrations.db.query(
+  `SELECT * FROM users WHERE name = '${userName}'`, // DANGEROUS!
+  UserSchema,
+);
+
+// CORRECT - Use parameterized queries
+const users = await ctx.integrations.db.query(
+  "SELECT * FROM users WHERE name = $1",
+  UserSchema,
+  [userName], // Safe - value is escaped
+);
+```
+
+### NUMERIC/DECIMAL Values Returned as Strings
+
+Large `NUMERIC` and `DECIMAL` columns are returned as strings to preserve precision:
+
+```typescript
+// WRONG - May lose precision
+const schema = z.object({ price: z.number() });
+
+// CORRECT - Keep as string or transform
+const schema = z.object({
+  price: z.string().transform((val) => parseFloat(val)),
+});
+```
+
+### Handling NULL Values
+
+```typescript
+// WRONG - Will fail if column contains NULL
+const schema = z.object({ bio: z.string() });
+
+// CORRECT - Mark nullable columns
+const schema = z.object({ bio: z.string().nullable() });
+```
+
+## Error Handling
+
+### QueryValidationError
+
+Thrown when query results fail schema validation:
+
+```typescript
+import { QueryValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const users = await ctx.integrations.db.query(
+    "SELECT * FROM users",
+    UserSchema,
+  );
+} catch (error) {
+  if (error instanceof QueryValidationError) {
+    console.error("Row index:", error.details.rowIndex);
+    console.error("Validation errors:", error.details.errors);
+    console.error("Actual row data:", error.details.row);
+  }
+}
+```

package/src/integrations/lakebase/client.ts

@@ -5,15 +5,17 @@
  * Supports server-side parameterized SQL queries via the `parameters` field.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as LakebasePlugin } from "@superblocksteam/types/dist/src/plugins/lakebase/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
-import type { LakebaseClient } from "./types.js";
+
 import { QueryValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import { describeType } from "../utils.js";
+import type { LakebaseClient } from "./types.js";
 
 /**
  * Lakebase request type derived from proto definition.

package/src/integrations/lakebase/types.ts

@@ -6,6 +6,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 

package/src/integrations/mariadb/client.ts

@@ -5,13 +5,15 @@
  * runtime validation using Zod schemas.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as MariaDBPlugin } from "@superblocksteam/types/dist/src/plugins/mariadb/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { QueryValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import { describeType } from "../utils.js";
 import type { MariaDBClient } from "./types.js";
 

package/src/integrations/mariadb/types.ts

@@ -5,6 +5,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 

package/src/integrations/mongodb/client.ts

@@ -4,13 +4,15 @@
  * Uses the native MongoDB plugin type from @superblocksteam/types.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as MongoDBPlugin } from "@superblocksteam/types/dist/src/plugins/mongodb/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { RestApiValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import type { MongoDBClient, MongoDBAction, MongoDBParams } from "./types.js";
 
 /**

package/src/integrations/mongodb/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 

package/src/integrations/mssql/client.ts

@@ -5,13 +5,15 @@
  * runtime validation using Zod schemas.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as MSSQLPlugin } from "@superblocksteam/types/dist/src/plugins/mssql/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { QueryValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import { describeType } from "../utils.js";
 import type { MSSQLClient } from "./types.js";
 

package/src/integrations/mssql/types.ts

@@ -5,6 +5,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 

package/src/integrations/mysql/client.ts

@@ -5,13 +5,15 @@
  * runtime validation using Zod schemas.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as MySQLPlugin } from "@superblocksteam/types/dist/src/plugins/mysql/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { QueryValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import { describeType } from "../utils.js";
 import type { MySQLClient } from "./types.js";
 

package/src/integrations/mysql/types.ts

@@ -5,6 +5,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 

package/src/integrations/oracledb/client.ts

@@ -5,13 +5,15 @@
  * runtime validation using Zod schemas.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as OracleDBPlugin } from "@superblocksteam/types/dist/src/plugins/oracledb/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { QueryValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import { describeType } from "../utils.js";
 import type { OracleDBClient } from "./types.js";
 

package/src/integrations/oracledb/types.ts

@@ -5,6 +5,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 

package/src/integrations/postgres/client.ts

@@ -5,15 +5,17 @@
  * for type-safe request building.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as PostgresPlugin } from "@superblocksteam/types/dist/src/plugins/postgresql/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
-import type { PostgresClient } from "./types.js";
+
 import { QueryValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import { describeType } from "../utils.js";
+import type { PostgresClient } from "./types.js";
 /**
  * PostgreSQL request type derived from proto definition.
  * Using PartialMessage allows optional fields.

package/src/integrations/postgres/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 

package/src/integrations/python/client.test.ts

@@ -4,9 +4,10 @@
 
 import { describe, it, expect, vi } from "vitest";
 import { z } from "zod";
-import { PythonClientImpl } from "./client.js";
-import type { IntegrationConfig } from "../types.js";
+
 import type { QueryExecutor } from "../registry.js";
+import type { IntegrationConfig } from "../types.js";
+import { PythonClientImpl } from "./client.js";
 
 /** Helper to compute expected base64-encoded json.loads preamble. */
 function expectedBindingsLine(bindings: Record<string, unknown>): string {

package/src/integrations/python/client.ts

@@ -4,13 +4,15 @@
  * Executes Python code via the orchestrator with type-safe bindings.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as PythonPlugin } from "@superblocksteam/types/dist/src/plugins/python/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
+
+import { CodeExecutionError } from "../../errors.js";
 import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import type { PythonClient } from "./types.js";
-import { CodeExecutionError } from "../../errors.js";
 
 /**
  * Python plugin request type derived from proto definition.

package/src/integrations/python/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 

package/src/integrations/redis/client.ts

@@ -11,10 +11,11 @@
  */
 
 import type { z } from "zod";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { RestApiValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import type { RedisClient } from "./types.js";
 
 /**

package/src/integrations/redis/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 

package/src/integrations/redshift/client.ts

@@ -5,13 +5,15 @@
  * runtime validation using Zod schemas.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as RedshiftPlugin } from "@superblocksteam/types/dist/src/plugins/redshift/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { QueryValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import { describeType } from "../utils.js";
 import type { RedshiftClient } from "./types.js";
 

package/src/integrations/redshift/types.ts

@@ -5,6 +5,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 

package/src/integrations/registry.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
+
 import {
   createClient,
   isPluginSupported,