@superblocksteam/sdk-api 0.0.4

package/src/integrations/mssql/client.ts

@@ -0,0 +1,138 @@
+/**
+ * MSSQL (Microsoft SQL Server) integration client implementation.
+ *
+ * Executes MSSQL queries through the Superblocks orchestrator with
+ * runtime validation using Zod schemas.
+ */
+
+import type { z } from "zod";
+import type { PartialMessage } from "@bufbuild/protobuf";
+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 { describeType } from "../utils.js";
+import type { MSSQLClient } from "./types.js";
+
+/**
+ * Internal implementation of the MSSQL client.
+ */
+export class MSSQLClientImpl implements MSSQLClient, IntegrationClientImpl {
+  readonly config: IntegrationConfig;
+  private readonly executeQuery: QueryExecutor;
+
+  constructor(config: IntegrationConfig, executeQuery: QueryExecutor) {
+    this.config = config;
+    this.executeQuery = executeQuery;
+  }
+
+  get name(): string {
+    return this.config.name;
+  }
+
+  get pluginId(): string {
+    return this.config.pluginId;
+  }
+
+  /**
+   * Builds a MSSQL request object from SQL and parameters.
+   *
+   * When params are provided, the SQL body is sent with placeholders intact
+   * (e.g. @PARAM_1, @PARAM_2) and the parameter values are passed via the
+   * `parameters` field as a JSON-stringified array for server-side binding.
+   *
+   * @param sql - The SQL query with optional @PARAM_N placeholders
+   * @param params - Optional array of parameter values for server-side binding
+   * @returns The plugin request object
+   */
+  private buildRequest(
+    sql: string,
+    params?: unknown[],
+  ): PartialMessage<MSSQLPlugin> {
+    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 MSSQL 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} validation failed: ${parseResult.error.message}`,
+            {
+              rowIndex: i,
+              errors: parseResult.error.errors.map((err) => ({
+                path: err.path,
+                message: err.message,
+              })),
+              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 };
+      }
+
+      return { rowCount: 0 };
+    } catch (error) {
+      throw new IntegrationError(this.config.name, "execute", error);
+    }
+  }
+}

package/src/integrations/mssql/index.ts

@@ -0,0 +1,8 @@
+/**
+ * MSSQL (Microsoft SQL Server) integration client.
+ *
+ * @module
+ */
+
+export type { MSSQLClient } from "./types.js";
+export { MSSQLClientImpl } from "./client.js";

package/src/integrations/mssql/types.ts

@@ -0,0 +1,64 @@
+/**
+ * MSSQL (Microsoft SQL Server) integration client types.
+ *
+ * Provides typed methods for executing MSSQL queries with runtime validation.
+ */
+
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
+
+/**
+ * Client for executing MSSQL queries with type-safe validation.
+ *
+ * @example
+ * ```typescript
+ * // Declare in api(): integrations: { mssql: mssql(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.mssql
+ *
+ * // Query with validation
+ * const UserSchema = z.object({
+ *   id: z.number(),
+ *   name: z.string(),
+ *   email: z.string().email(),
+ * });
+ *
+ * const users = await mssql.query(
+ *   'SELECT * FROM users WHERE status = $1',
+ *   UserSchema,
+ *   ['active']
+ * );
+ * ```
+ */
+export interface MSSQLClient extends BaseIntegrationClient {
+  /**
+   * Execute a SQL query and validate results against a Zod schema.
+   *
+   * @param sql - SQL query string (use $1, $2, etc. for parameters)
+   * @param schema - Zod schema to validate the query results
+   * @param params - Optional query parameters
+   * @returns Promise resolving to validated query results
+   *
+   * @throws {QueryValidationError} If results don't match schema
+   * @throws {IntegrationError} If query execution fails
+   */
+  query<T>(
+    sql: string,
+    schema: z.ZodSchema<T>,
+    params?: unknown[],
+    metadata?: TraceMetadata,
+  ): Promise<T[]>;
+
+  /**
+   * Execute a SQL statement (INSERT, UPDATE, DELETE) without output validation.
+   *
+   * @param sql - The SQL statement to execute
+   * @param params - Optional parameters for prepared statements
+   * @returns Promise resolving to execution result with row count
+   */
+  execute(
+    sql: string,
+    params?: unknown[],
+    metadata?: TraceMetadata,
+  ): Promise<{ rowCount: number }>;
+}

package/src/integrations/mysql/README.md

@@ -0,0 +1,169 @@
+# MySQL Client
+
+Execute SQL queries and statements against MySQL 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, mysql } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_MYSQL = "a1b2c3d4-5678-90ab-cdef-mysql0000001";
+
+const UserSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  email: z.string().email(),
+  created_at: z.string(),
+});
+
+export default api({
+  integrations: {
+    mysql: mysql(PROD_MYSQL),
+  },
+  name: "MySQLExample",
+  input: z.object({
+    status: z.string(),
+  }),
+  output: z.object({
+    users: z.array(UserSchema),
+  }),
+  async run(ctx, { status }) {
+    const users = await ctx.integrations.mysql.query(
+      "SELECT id, name, email, created_at FROM users WHERE status = $1",
+      UserSchema,
+      [status],
+    );
+
+    return { users };
+  },
+});
+```
+
+### Executing INSERT, UPDATE, DELETE Statements
+
+```typescript
+// INSERT
+await ctx.integrations.mysql.execute(
+  "INSERT INTO users (name, email) VALUES ($1, $2)",
+  ["John Doe", "john@example.com"],
+);
+
+// UPDATE
+const updateResult = await ctx.integrations.mysql.execute(
+  "UPDATE users SET last_login = NOW() WHERE id = $1",
+  [userId],
+);
+console.log(`Updated ${updateResult.rowCount} rows`);
+
+// DELETE
+const deleteResult = await ctx.integrations.mysql.execute(
+  "DELETE FROM sessions WHERE expires_at < NOW()",
+);
+console.log(`Deleted ${deleteResult.rowCount} expired sessions`);
+```
+
+### Query with JOIN
+
+```typescript
+const OrderWithCustomerSchema = z.object({
+  order_id: z.number(),
+  order_total: z.string(),
+  customer_name: z.string(),
+  customer_email: z.string().email(),
+});
+
+const orders = await ctx.integrations.mysql.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"],
+);
+```
+
+## Trace Metadata
+
+All methods accept an optional `metadata` parameter as the last argument for diagnostics labeling. See the [root SDK README](../../../README.md#trace-metadata) for details.
+
+## Common Pitfalls
+
+### BIGINT Values Returned as Strings
+
+MySQL `BIGINT` columns may be returned as strings to preserve precision:
+
+```typescript
+// CORRECT - Handle as strings or coerce
+const schema = z.object({
+  id: z.coerce.number(),
+  count: z.coerce.number(),
+});
+```
+
+### DECIMAL Values Returned as Strings
+
+```typescript
+// For a column: price DECIMAL(10,2)
+const schema = z.object({
+  price: z.string().transform((val) => parseFloat(val)),
+});
+```
+
+### Schema Parameter is Required
+
+```typescript
+// WRONG - Missing schema
+const users = await ctx.integrations.mysql.query("SELECT * FROM users");
+
+// CORRECT - Schema is required
+const users = await ctx.integrations.mysql.query(
+  "SELECT * FROM users",
+  UserSchema,
+);
+```
+
+### NULL Handling
+
+```typescript
+const schema = z.object({
+  name: z.string(),
+  bio: z.string().nullable(), // Column can be NULL
+});
+```
+
+## Error Handling
+
+```typescript
+import { QueryValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const users = await ctx.integrations.mysql.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);
+  }
+}
+```
+
+## API Reference
+
+- [MySQL Documentation](https://dev.mysql.com/doc/)
+- [MySQL Data Types](https://dev.mysql.com/doc/refman/8.0/en/data-types.html)

package/src/integrations/mysql/client.ts

@@ -0,0 +1,138 @@
+/**
+ * MySQL integration client implementation.
+ *
+ * Executes MySQL queries through the Superblocks orchestrator with
+ * runtime validation using Zod schemas.
+ */
+
+import type { z } from "zod";
+import type { PartialMessage } from "@bufbuild/protobuf";
+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 { describeType } from "../utils.js";
+import type { MySQLClient } from "./types.js";
+
+/**
+ * Internal implementation of the MySQL client.
+ */
+export class MySQLClientImpl implements MySQLClient, IntegrationClientImpl {
+  readonly config: IntegrationConfig;
+  private readonly executeQuery: QueryExecutor;
+
+  constructor(config: IntegrationConfig, executeQuery: QueryExecutor) {
+    this.config = config;
+    this.executeQuery = executeQuery;
+  }
+
+  get name(): string {
+    return this.config.name;
+  }
+
+  get pluginId(): string {
+    return this.config.pluginId;
+  }
+
+  /**
+   * Builds a MySQL request object from SQL and parameters.
+   *
+   * When params are provided, the SQL body is sent with placeholders intact
+   * (e.g. ?) and the parameter values are passed via the `parameters` field
+   * as a JSON-stringified array for server-side binding.
+   *
+   * @param sql - The SQL query with optional ? placeholders
+   * @param params - Optional array of parameter values for server-side binding
+   * @returns The plugin request object
+   */
+  private buildRequest(
+    sql: string,
+    params?: unknown[],
+  ): PartialMessage<MySQLPlugin> {
+    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 MySQL 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} validation failed: ${parseResult.error.message}`,
+            {
+              rowIndex: i,
+              errors: parseResult.error.errors.map((err) => ({
+                path: err.path,
+                message: err.message,
+              })),
+              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 };
+      }
+
+      return { rowCount: 0 };
+    } catch (error) {
+      throw new IntegrationError(this.config.name, "execute", error);
+    }
+  }
+}

package/src/integrations/mysql/index.ts

@@ -0,0 +1,8 @@
+/**
+ * MySQL integration client.
+ *
+ * @module
+ */
+
+export type { MySQLClient } from "./types.js";
+export { MySQLClientImpl } from "./client.js";

package/src/integrations/mysql/types.ts

@@ -0,0 +1,88 @@
+/**
+ * MySQL integration client types.
+ *
+ * Provides typed methods for executing MySQL queries with runtime validation.
+ */
+
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
+
+/**
+ * Client for executing MySQL queries with type-safe validation.
+ *
+ * @example
+ * ```typescript
+ * // Declare in api(): integrations: { mysql: mysql(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.mysql
+ *
+ * // Query with validation
+ * const UserSchema = z.object({
+ *   id: z.number(),
+ *   name: z.string(),
+ *   email: z.string().email(),
+ * });
+ *
+ * const users = await mysql.query(
+ *   'SELECT * FROM users WHERE status = $1',
+ *   UserSchema,
+ *   ['active']
+ * );
+ * ```
+ */
+export interface MySQLClient extends BaseIntegrationClient {
+  /**
+   * Execute a SQL query and validate results against a Zod schema.
+   *
+   * @param sql - SQL query string (use $1, $2, etc. for parameters)
+   * @param schema - Zod schema to validate the query results
+   * @param params - Optional query parameters
+   * @returns Promise resolving to validated query results
+   *
+   * @throws {QueryValidationError} If results don't match schema
+   * @throws {IntegrationError} If query execution fails
+   *
+   * @example
+   * ```typescript
+   * const UserSchema = z.object({
+   *   id: z.number(),
+   *   name: z.string(),
+   *   email: z.string().email(),
+   * });
+   *
+   * const users = await mysql.query(
+   *   'SELECT * FROM users WHERE status = $1',
+   *   UserSchema,
+   *   ['active']
+   * );
+   * ```
+   */
+  query<T>(
+    sql: string,
+    schema: z.ZodSchema<T>,
+    params?: unknown[],
+    metadata?: TraceMetadata,
+  ): Promise<T[]>;
+
+  /**
+   * Execute a SQL statement (INSERT, UPDATE, DELETE) without output validation.
+   *
+   * @param sql - The SQL statement to execute
+   * @param params - Optional parameters for prepared statements
+   * @returns Promise resolving to execution result with row count
+   *
+   * @example
+   * ```typescript
+   * const result = await mysql.execute(
+   *   'UPDATE users SET last_login = NOW() WHERE id = $1',
+   *   [userId]
+   * );
+   * console.log(`Updated ${result.rowCount} rows`);
+   * ```
+   */
+  execute(
+    sql: string,
+    params?: unknown[],
+    metadata?: TraceMetadata,
+  ): Promise<{ rowCount: number }>;
+}