@superblocksteam/sdk-api 2.0.93 → 2.0.94-next.0

package/src/integrations/postgres/README.md

@@ -4,10 +4,10 @@ Execute SQL queries and statements against PostgreSQL databases with full type s
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
-| `query<T>(sql, schema, params?)` | Execute a SELECT query and return validated, typed results |
-| `execute(sql, params?)` | Execute a statement (INSERT, UPDATE, DELETE) and return affected row count |
+| Method                           | Description                                                                |
+| -------------------------------- | -------------------------------------------------------------------------- |
+| `query<T>(sql, schema, params?)` | Execute a SELECT query and return validated, typed results                 |
+| `execute(sql, params?)`          | Execute a statement (INSERT, UPDATE, DELETE) and return affected row count |
 
 ## Usage
 
@@ -45,7 +45,7 @@ export default api({
     const users = await ctx.integrations.db.query(
       "SELECT id, name, email, created_at FROM users WHERE status = $1",
       UserSchema,
-      [status]
+      [status],
     );
 
     return { users };
@@ -79,19 +79,19 @@ export default api({
     // INSERT
     await ctx.integrations.db.execute(
       "INSERT INTO users (name, email) VALUES ($1, $2)",
-      [name, email]
+      [name, email],
     );
 
     // UPDATE
     const updateResult = await ctx.integrations.db.execute(
       "UPDATE users SET last_login = NOW() WHERE id = $1",
-      [userId]
+      [userId],
     );
     console.log(`Updated ${updateResult.rowCount} rows`);
 
     // DELETE
     const deleteResult = await ctx.integrations.db.execute(
-      "DELETE FROM sessions WHERE expires_at < NOW()"
+      "DELETE FROM sessions WHERE expires_at < NOW()",
     );
     console.log(`Deleted ${deleteResult.rowCount} expired sessions`);
 
@@ -109,25 +109,26 @@ Use arrays with PostgreSQL's `ANY()` operator to filter by multiple values:
 const items = await ctx.integrations.db.query(
   "SELECT * FROM items WHERE id = ANY($1::int[])",
   ItemSchema,
-  [[1, 2, 3]] // Array of integers
+  [[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
+  [["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
+  [[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)
@@ -152,7 +153,7 @@ const orders = await ctx.integrations.db.query(
   JOIN customers c ON o.customer_id = c.id
   WHERE o.status = $1`,
   OrderWithCustomerSchema,
-  ["pending"]
+  ["pending"],
 );
 ```
 
@@ -168,7 +169,7 @@ const UserWithOptionalFieldsSchema = z.object({
 
 const users = await ctx.integrations.db.query(
   "SELECT id, name, bio, avatar_url FROM users",
-  UserWithOptionalFieldsSchema
+  UserWithOptionalFieldsSchema,
 );
 ```
 
@@ -183,7 +184,7 @@ PostgreSQL aggregate functions like `COUNT(*)` return `BIGINT`, which is seriali
 
 // WRONG - COUNT returns a string, not a number
 const schema = z.object({
-  total: z.number(),  // Fails validation
+  total: z.number(), // Fails validation
 });
 
 // CORRECT - Use z.coerce.number() to convert string to number
@@ -194,7 +195,7 @@ const schema = z.object({
 // Example usage
 const StatsSchema = z.object({
   total_orders: z.coerce.number(),
-  total_revenue: z.coerce.number(),  // SUM also returns string for BIGINT/NUMERIC
+  total_revenue: z.coerce.number(), // SUM also returns string for BIGINT/NUMERIC
 });
 
 const stats = await ctx.integrations.db.query(
@@ -204,7 +205,7 @@ const stats = await ctx.integrations.db.query(
   FROM orders
   WHERE created_at > $1`,
   StatsSchema,
-  [startDate]
+  [startDate],
 );
 ```
 
@@ -267,14 +268,16 @@ The `query()` method requires a Zod schema for runtime validation. This is by de
 // WRONG - Missing schema parameter
 const users = await ctx.integrations.db.query(
   "SELECT * FROM users",
-  [/* params */]  // This is wrong - params are 3rd argument
+  [
+    /* 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
+  UserSchema, // Schema is required
+  [userId], // Params are optional, third argument
 );
 ```
 
@@ -285,15 +288,15 @@ 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
+  `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
+  [userName], // Safe - value is escaped
 );
 ```
 
@@ -305,19 +308,19 @@ PostgreSQL NULL values need explicit handling in your schema:
 // WRONG - Will fail if column contains NULL
 const schema = z.object({
   name: z.string(),
-  bio: z.string(),  // Fails if bio is NULL
+  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
+  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 ""
+  bio: z.string().nullable().default(""), // NULL becomes ""
 });
 ```
 
@@ -327,7 +330,7 @@ PostgreSQL timestamps are returned as ISO 8601 strings:
 
 ```typescript
 const schema = z.object({
-  created_at: z.string(),  // "2024-01-15T10:30:00.000Z"
+  created_at: z.string(), // "2024-01-15T10:30:00.000Z"
 
   // Or transform to Date object
   updated_at: z.string().transform((val) => new Date(val)),
@@ -349,7 +352,7 @@ import { QueryValidationError } from "@superblocksteam/sdk-api";
 try {
   const users = await ctx.integrations.db.query(
     "SELECT * FROM users",
-    UserSchema
+    UserSchema,
   );
 } catch (error) {
   if (error instanceof QueryValidationError) {

package/src/integrations/postgres/client.ts

@@ -5,15 +5,15 @@
  * 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 } 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';
+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 } 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.
@@ -27,7 +27,9 @@ export type PostgresRequest = PartialMessage<PostgresPlugin>;
  * At runtime, the orchestrator injects the actual database connection and
  * handles authentication.
  */
-export class PostgresClientImpl implements PostgresClient, IntegrationClientImpl {
+export class PostgresClientImpl
+  implements PostgresClient, IntegrationClientImpl
+{
   readonly name: string;
   readonly pluginId: string;
   readonly config: IntegrationConfig;
@@ -62,7 +64,11 @@ export class PostgresClientImpl implements PostgresClient, IntegrationClientImpl
     };
   }
 
-  async query<T>(sql: string, schema: z.ZodSchema<T>, params?: unknown[]): Promise<T[]> {
+  async query<T>(
+    sql: string,
+    schema: z.ZodSchema<T>,
+    params?: unknown[],
+  ): Promise<T[]> {
     const request = this.buildRequest(sql, params);
 
     try {
@@ -71,7 +77,7 @@ export class PostgresClientImpl implements PostgresClient, IntegrationClientImpl
       if (!Array.isArray(result)) {
         throw new IntegrationError(
           this.config.name,
-          'query',
+          "query",
           `Expected array result from Postgres query, got: ${describeType(result)}`,
         );
       }
@@ -88,7 +94,7 @@ export class PostgresClientImpl implements PostgresClient, IntegrationClientImpl
               rowIndex: i,
               errors: parseResult.error.errors,
               row,
-            }
+            },
           );
         }
 
@@ -104,20 +110,23 @@ export class PostgresClientImpl implements PostgresClient, IntegrationClientImpl
         throw error;
       }
 
-      throw new IntegrationError(this.config.name, 'query', error);
+      throw new IntegrationError(this.config.name, "query", error);
     }
   }
 
-  async execute(sql: string, params?: unknown[]): Promise<{ rowCount: number }> {
+  async execute(
+    sql: string,
+    params?: unknown[],
+  ): Promise<{ rowCount: number }> {
     const request = this.buildRequest(sql, params);
 
     try {
       const result = await this.executeQuery(request);
 
       if (
-        typeof result === 'object' &&
+        typeof result === "object" &&
         result !== null &&
-        'rowCount' in result
+        "rowCount" in result
       ) {
         return { rowCount: Number(result.rowCount) || 0 };
       }
@@ -128,7 +137,7 @@ export class PostgresClientImpl implements PostgresClient, IntegrationClientImpl
 
       return { rowCount: 0 };
     } catch (error) {
-      throw new IntegrationError(this.config.name, 'execute', error);
+      throw new IntegrationError(this.config.name, "execute", error);
     }
   }
 }

package/src/integrations/postgres/index.ts

@@ -2,5 +2,5 @@
  * PostgreSQL integration module.
  */
 
-export type { PostgresClient } from './types.js';
-export { PostgresClientImpl } from './client.js';
+export type { PostgresClient } from "./types.js";
+export { PostgresClientImpl } from "./client.js";

package/src/integrations/postgres/types.ts

@@ -2,8 +2,8 @@
  * PostgreSQL client types.
  */
 
-import type { z } from 'zod';
-import type { BaseIntegrationClient } from '../../types.js';
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
 
 /**
  * PostgreSQL client for database operations.
@@ -14,7 +14,8 @@ import type { BaseIntegrationClient } from '../../types.js';
  * @example
  * ```typescript
  * import { z } from 'zod';
- * const postgres = ctx.integration('Production Postgres');
+ * // Declare in api(): integrations: { db: postgres(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.db
  *
  * // Query with runtime validation
  * const UserSchema = z.object({
@@ -23,7 +24,7 @@ import type { BaseIntegrationClient } from '../../types.js';
  *   email: z.string().email(),
  * });
  *
- * const users = await postgres.query(
+ * const users = await ctx.integrations.db.query(
  *   'SELECT * FROM users WHERE status = $1',
  *   UserSchema,
  *   ['active']
@@ -31,7 +32,7 @@ import type { BaseIntegrationClient } from '../../types.js';
  * // Type is automatically inferred: Array<{ id: string; name: string; email: string }>
  *
  * // Execute a statement (no validation needed)
- * const result = await postgres.execute(
+ * const result = await ctx.integrations.db.execute(
  *   'UPDATE users SET last_login = NOW() WHERE id = $1',
  *   [userId]
  * );
@@ -63,7 +64,7 @@ export interface PostgresClient extends BaseIntegrationClient {
    *   email: z.string().email(),
    * });
    *
-   * const users = await postgres.query(
+   * const users = await ctx.integrations.db.query(
    *   'SELECT * FROM users WHERE email = $1',
    *   UserSchema,
    *   ['user@example.com']
@@ -71,7 +72,11 @@ export interface PostgresClient extends BaseIntegrationClient {
    * // Type is automatically z.infer<typeof UserSchema>[]
    * ```
    */
-  query<T>(sql: string, schema: z.ZodSchema<T>, params?: unknown[]): Promise<T[]>;
+  query<T>(
+    sql: string,
+    schema: z.ZodSchema<T>,
+    params?: unknown[],
+  ): Promise<T[]>;
 
   /**
    * Execute a SQL statement (INSERT, UPDATE, DELETE) and return affected row count.
@@ -85,7 +90,7 @@ export interface PostgresClient extends BaseIntegrationClient {
    *
    * @example
    * ```typescript
-   * const result = await postgres.execute(
+   * const result = await ctx.integrations.db.execute(
    *   'DELETE FROM sessions WHERE expires_at < NOW()'
    * );
    * console.log(`Deleted ${result.rowCount} expired sessions`);