@superblocksteam/sdk-api 0.0.4

package/src/integrations/postgres/README.md

@@ -0,0 +1,393 @@
+# PostgreSQL Client
+
+Execute SQL queries and statements against PostgreSQL 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, postgres } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_POSTGRES = "a1b2c3d4-5678-90ab-cdef-111111111111";
+
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+  created_at: z.string(), // Timestamps returned as ISO strings
+});
+
+export default api({
+  name: "GetUsersByStatus",
+
+  // Declare integrations upfront
+  integrations: {
+    db: postgres(PROD_POSTGRES),
+  },
+
+  input: z.object({
+    status: z.string(),
+  }),
+  output: z.object({
+    users: z.array(UserSchema),
+  }),
+  async run(ctx, { status }) {
+    // ctx.integrations.db is fully typed as PostgresClient
+    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, postgres } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_POSTGRES = "a1b2c3d4-5678-90ab-cdef-111111111111";
+
+export default api({
+  name: "ManageUsers",
+
+  integrations: {
+    db: postgres(PROD_POSTGRES),
+  },
+
+  input: z.object({
+    userId: z.string(),
+    name: z.string(),
+    email: z.string(),
+  }),
+  output: z.object({ success: z.boolean() }),
+
+  async run(ctx, { userId, 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 id = $1",
+      [userId],
+    );
+    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 };
+  },
+});
+```
+
+### Array Parameters
+
+Use arrays with PostgreSQL's `ANY()` operator to filter by multiple values:
+
+```typescript
+// Filter by multiple IDs
+const items = await ctx.integrations.db.query(
+  "SELECT * FROM items WHERE id = ANY($1::int[])",
+  ItemSchema,
+  [[1, 2, 3]], // Array of integers
+);
+
+// Filter by multiple statuses
+const users = await ctx.integrations.db.query(
+  "SELECT * FROM users WHERE status = ANY($1::text[])",
+  UserSchema,
+  [["active", "pending"]], // Array of strings
+);
+
+// Multiple parameters including arrays
+const orders = await ctx.integrations.db.query(
+  "SELECT * FROM orders WHERE id = ANY($1::int[]) AND status = $2",
+  OrderSchema,
+  [[100, 101, 102], "shipped"], // Array + scalar
+);
+```
+
+Arrays are automatically serialized to PostgreSQL's `ARRAY[...]` syntax:
+
+- `[1, 2, 3]` → `ARRAY[1,2,3]`
+- `['a', 'b']` → `ARRAY['a','b']`
+- `[[1, 2], [3, 4]]` → `ARRAY[ARRAY[1,2],ARRAY[3,4]]` (nested arrays)
+
+### Query with JOIN and Complex Types
+
+```typescript
+const OrderWithCustomerSchema = z.object({
+  order_id: z.string(),
+  order_total: z.string(), // NUMERIC/DECIMAL returned as strings
+  customer_name: z.string(),
+  customer_email: z.string().email(),
+});
+
+const orders = await ctx.integrations.db.query(
+  `SELECT
+    o.id as order_id,
+    o.total as order_total,
+    c.name as customer_name,
+    c.email as customer_email
+  FROM orders o
+  JOIN customers c ON o.customer_id = c.id
+  WHERE o.status = $1`,
+  OrderWithCustomerSchema,
+  ["pending"],
+);
+```
+
+### Handling Nullable Columns
+
+```typescript
+const UserWithOptionalFieldsSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  bio: z.string().nullable(), // Column can be NULL
+  avatar_url: z.string().nullable(),
+});
+
+const users = await ctx.integrations.db.query(
+  "SELECT id, name, bio, avatar_url FROM users",
+  UserWithOptionalFieldsSchema,
+);
+```
+
+## 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",
+    description: "Paginated user list for dashboard",
+  },
+);
+
+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
+
+### Aggregate Functions (COUNT, SUM) Return Strings
+
+PostgreSQL aggregate functions like `COUNT(*)` return `BIGINT`, which is serialized as a string. Use `z.coerce.number()` to convert to a number:
+
+```typescript
+// Query: SELECT COUNT(*) as total FROM orders WHERE status = 'pending'
+
+// WRONG - COUNT returns a string, not a number
+const schema = z.object({
+  total: z.number(), // Fails validation
+});
+
+// CORRECT - Use z.coerce.number() to convert string to number
+const schema = z.object({
+  total: z.coerce.number(),
+});
+
+// Example usage
+const StatsSchema = z.object({
+  total_orders: z.coerce.number(),
+  total_revenue: z.coerce.number(), // SUM also returns string for BIGINT/NUMERIC
+});
+
+const stats = await ctx.integrations.db.query(
+  `SELECT
+    COUNT(*) as total_orders,
+    SUM(amount) as total_revenue
+  FROM orders
+  WHERE created_at > $1`,
+  StatsSchema,
+  [startDate],
+);
+```
+
+### BIGINT Values Returned as Strings
+
+PostgreSQL `BIGINT` columns (8-byte integers) are returned as strings in JavaScript because they can exceed `Number.MAX_SAFE_INTEGER` (2^53 - 1 = 9,007,199,254,740,991).
+
+```typescript
+// Schema for a table with: id BIGINT, count BIGINT
+
+// WRONG - Will fail validation for large values
+const schema = z.object({
+  id: z.number(),
+  count: z.number(),
+});
+
+// CORRECT - Handle as strings
+const schema = z.object({
+  id: z.string(),
+  count: z.string(),
+});
+
+// CORRECT - Coerce to number (safe for values < MAX_SAFE_INTEGER)
+const schema = z.object({
+  id: z.coerce.number(),
+  count: z.coerce.number(),
+});
+
+// CORRECT - Parse as BigInt for truly large values
+const schema = z.object({
+  id: z.string().transform((val) => BigInt(val)),
+  count: z.string().transform((val) => BigInt(val)),
+});
+```
+
+### NUMERIC/DECIMAL Values Returned as Strings
+
+Large `NUMERIC` and `DECIMAL` columns are also returned as strings to preserve precision:
+
+```typescript
+// For a column: price NUMERIC(10,2)
+
+// WRONG - May lose precision
+const schema = z.object({ price: z.number() });
+
+// CORRECT - Keep as string and parse when needed
+const schema = z.object({ price: z.string() });
+
+// CORRECT - Transform to number if precision loss is acceptable
+const schema = z.object({
+  price: z.string().transform((val) => parseFloat(val)),
+});
+```
+
+### Schema Parameter is Required
+
+The `query()` method requires a Zod schema for runtime validation. This is by design to ensure type safety.
+
+```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
+);
+```
+
+### Handling NULL Values
+
+PostgreSQL NULL values need explicit handling in your schema:
+
+```typescript
+// WRONG - Will fail if column contains NULL
+const schema = z.object({
+  name: z.string(),
+  bio: z.string(), // Fails if bio is NULL
+});
+
+// CORRECT - Mark nullable columns
+const schema = z.object({
+  name: z.string(),
+  bio: z.string().nullable(), // Accepts NULL
+});
+
+// CORRECT - Provide default for NULL
+const schema = z.object({
+  name: z.string(),
+  bio: z.string().nullable().default(""), // NULL becomes ""
+});
+```
+
+### Timestamp and Date Handling
+
+PostgreSQL timestamps are returned as ISO 8601 strings:
+
+```typescript
+const schema = z.object({
+  created_at: z.string(), // "2024-01-15T10:30:00.000Z"
+
+  // Or transform to Date object
+  updated_at: z.string().transform((val) => new Date(val)),
+
+  // Or use Zod's coerce
+  expires_at: z.coerce.date(),
+});
+```
+
+## Error Handling
+
+### QueryValidationError
+
+Thrown when query results fail schema validation. Contains details about which row failed and why:
+
+```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);
+  }
+}
+```
+
+## API Reference
+
+- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
+- [PostgreSQL Data Types](https://www.postgresql.org/docs/current/datatype.html)

package/src/integrations/postgres/client.ts

@@ -0,0 +1,145 @@
+/**
+ * PostgreSQL client implementation.
+ *
+ * Uses the proto-generated Plugin type from @superblocksteam/types
+ * for type-safe request building.
+ */
+
+import type { z } from "zod";
+import type { PartialMessage } from "@bufbuild/protobuf";
+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 { describeType } from "../utils.js";
+/**
+ * PostgreSQL request type derived from proto definition.
+ * Using PartialMessage allows optional fields.
+ */
+export type PostgresRequest = PartialMessage<PostgresPlugin>;
+
+/**
+ * Internal implementation of PostgresClient.
+ *
+ * This implementation communicates with the orchestrator to execute queries.
+ * At runtime, the orchestrator injects the actual database connection and
+ * handles authentication.
+ */
+export class PostgresClientImpl
+  implements PostgresClient, IntegrationClientImpl
+{
+  readonly name: string;
+  readonly pluginId: string;
+  readonly config: IntegrationConfig;
+
+  private readonly executeQuery: QueryExecutor;
+
+  constructor(config: IntegrationConfig, executeQuery: QueryExecutor) {
+    this.name = config.name;
+    this.pluginId = config.pluginId;
+    this.config = config;
+    this.executeQuery = executeQuery;
+  }
+
+  /**
+   * Builds a PostgreSQL plugin request object.
+   *
+   * When params are provided, the SQL body is sent with placeholders intact
+   * (e.g. $1, $2) and the parameter values are passed via the `parameters`
+   * field as a JSON-stringified array. The server performs the actual
+   * parameter binding, avoiding client-side SQL interpolation.
+   *
+   * @param sql - The SQL query to execute (with $1, $2 placeholders when parameterized)
+   * @param params - Optional query parameters for server-side binding
+   * @returns The plugin request object matching the proto schema
+   */
+  private buildRequest(sql: string, params?: unknown[]): PostgresRequest {
+    const hasParams = params && params.length > 0;
+
+    return {
+      body: sql,
+      parameters: hasParams ? JSON.stringify(params) : undefined,
+    };
+  }
+
+  async query<T>(
+    sql: string,
+    schema: z.ZodSchema<T>,
+    params?: unknown[],
+    metadata?: TraceMetadata,
+  ): Promise<T[]> {
+    const request = this.buildRequest(sql, params);
+
+    try {
+      const result = await this.executeQuery(request, undefined, metadata);
+
+      if (!Array.isArray(result)) {
+        throw new IntegrationError(
+          this.config.name,
+          "query",
+          `Expected array result from Postgres query, got: ${describeType(result)}`,
+        );
+      }
+
+      const validated: T[] = [];
+      for (let i = 0; i < result.length; i++) {
+        const row = result[i];
+        const parseResult = schema.safeParse(row);
+
+        if (!parseResult.success) {
+          throw new QueryValidationError(
+            `Row ${i} failed validation: ${parseResult.error.message}`,
+            {
+              rowIndex: i,
+              errors: parseResult.error.errors,
+              row,
+            },
+          );
+        }
+
+        validated.push(parseResult.data);
+      }
+
+      return validated;
+    } catch (error) {
+      if (
+        error instanceof QueryValidationError ||
+        error instanceof IntegrationError
+      ) {
+        throw error;
+      }
+
+      throw new IntegrationError(this.config.name, "query", error);
+    }
+  }
+
+  async execute(
+    sql: string,
+    params?: unknown[],
+    metadata?: TraceMetadata,
+  ): Promise<{ rowCount: number }> {
+    const request = this.buildRequest(sql, params);
+
+    try {
+      const result = await this.executeQuery(request, undefined, metadata);
+
+      if (
+        typeof result === "object" &&
+        result !== null &&
+        "rowCount" in result
+      ) {
+        return { rowCount: Number(result.rowCount) || 0 };
+      }
+
+      if (Array.isArray(result)) {
+        return { rowCount: result.length };
+      }
+
+      return { rowCount: 0 };
+    } catch (error) {
+      throw new IntegrationError(this.config.name, "execute", error);
+    }
+  }
+}

package/src/integrations/postgres/index.ts

@@ -0,0 +1,6 @@
+/**
+ * PostgreSQL integration module.
+ */
+
+export type { PostgresClient } from "./types.js";
+export { PostgresClientImpl } from "./client.js";

package/src/integrations/postgres/types.ts

@@ -0,0 +1,106 @@
+/**
+ * PostgreSQL client types.
+ */
+
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
+
+/**
+ * PostgreSQL client for database operations.
+ *
+ * Provides typed methods for executing SQL queries and statements
+ * against a PostgreSQL database.
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * // Declare in api(): integrations: { db: postgres(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.db
+ *
+ * // Query with runtime validation
+ * const UserSchema = z.object({
+ *   id: z.string(),
+ *   name: z.string(),
+ *   email: z.string().email(),
+ * });
+ *
+ * const users = await ctx.integrations.db.query(
+ *   'SELECT * FROM users WHERE status = $1',
+ *   UserSchema,
+ *   ['active']
+ * );
+ * // Type is automatically inferred: Array<{ id: string; name: string; email: string }>
+ *
+ * // Execute a statement (no validation needed)
+ * const result = await ctx.integrations.db.execute(
+ *   'UPDATE users SET last_login = NOW() WHERE id = $1',
+ *   [userId]
+ * );
+ * console.log(`Updated ${result.rowCount} rows`);
+ * ```
+ */
+export interface PostgresClient extends BaseIntegrationClient {
+  /**
+   * Execute a SQL query and return validated typed results.
+   *
+   * Type parameter T is automatically inferred from the schema.
+   * All query results are validated at runtime against the provided Zod schema.
+   *
+   * Use parameterized queries with $1, $2, etc. placeholders
+   * to prevent SQL injection.
+   *
+   * @param sql - The SQL query to execute
+   * @param schema - Zod schema for runtime validation (REQUIRED)
+   * @param params - Optional array of parameter values
+   * @returns Array of validated result rows
+   * @throws {QueryValidationError} If any row fails schema validation
+   *
+   * @example
+   * ```typescript
+   * import { z } from 'zod';
+   *
+   * const UserSchema = z.object({
+   *   id: z.number(),
+   *   email: z.string().email(),
+   * });
+   *
+   * const users = await ctx.integrations.db.query(
+   *   'SELECT * FROM users WHERE email = $1',
+   *   UserSchema,
+   *   ['user@example.com']
+   * );
+   * // Type is automatically z.infer<typeof UserSchema>[]
+   * ```
+   */
+  query<T>(
+    sql: string,
+    schema: z.ZodSchema<T>,
+    params?: unknown[],
+    metadata?: TraceMetadata,
+  ): Promise<T[]>;
+
+  /**
+   * Execute a SQL statement (INSERT, UPDATE, DELETE) and return affected row count.
+   *
+   * Use this method when you don't need the returned data, only the count
+   * of affected rows.
+   *
+   * @param sql - The SQL statement to execute
+   * @param params - Optional array of parameter values
+   * @returns Object with the count of affected rows
+   *
+   * @example
+   * ```typescript
+   * const result = await ctx.integrations.db.execute(
+   *   'DELETE FROM sessions WHERE expires_at < NOW()'
+   * );
+   * console.log(`Deleted ${result.rowCount} expired sessions`);
+   * ```
+   */
+  execute(
+    sql: string,
+    params?: unknown[],
+    metadata?: TraceMetadata,
+  ): Promise<{ rowCount: number }>;
+}