@superblocksteam/sdk-api 0.0.4

package/src/integrations/mongodb/README.md

@@ -0,0 +1,252 @@
+# MongoDB Client
+
+Execute MongoDB operations with full type safety and runtime validation.
+
+## Methods
+
+| Method                                               | Description                 |
+| ---------------------------------------------------- | --------------------------- |
+| `run(collection, action, schema, params, metadata?)` | Execute a MongoDB operation |
+
+## Actions
+
+| Action            | Description                 |
+| ----------------- | --------------------------- |
+| `find`            | Find multiple documents     |
+| `findOne`         | Find a single document      |
+| `insertOne`       | Insert a document           |
+| `insertMany`      | Insert multiple documents   |
+| `updateOne`       | Update a single document    |
+| `updateMany`      | Update multiple documents   |
+| `deleteOne`       | Delete a single document    |
+| `deleteMany`      | Delete multiple documents   |
+| `aggregate`       | Run an aggregation pipeline |
+| `count`           | Count documents             |
+| `distinct`        | Get distinct values         |
+| `listCollections` | List collections            |
+
+## Usage
+
+### Find Documents
+
+```typescript
+import { api, z, mongodb } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_MONGODB = "a1b2c3d4-5678-90ab-cdef-mongodb00001";
+
+const UserSchema = z.array(
+  z.object({
+    _id: z.string(),
+    name: z.string(),
+    email: z.string(),
+  }),
+);
+
+export default api({
+  integrations: {
+    mongodb: mongodb(PROD_MONGODB),
+  },
+  name: "MongoDBExample",
+  input: z.object({
+    status: z.string(),
+  }),
+  output: z.object({
+    users: UserSchema,
+  }),
+  async run(ctx, { status }) {
+    const users = await ctx.integrations.mongodb.run(
+      "users",
+      "find",
+      UserSchema,
+      {
+        query: { status: status },
+        limit: 10,
+      },
+    );
+
+    return { users };
+  },
+});
+```
+
+### Find One Document
+
+```typescript
+const UserSchema = z
+  .object({
+    _id: z.string(),
+    name: z.string(),
+    email: z.string(),
+  })
+  .nullable();
+
+const user = await ctx.integrations.mongodb.run(
+  "users",
+  "findOne",
+  UserSchema,
+  {
+    query: { _id: userId },
+  },
+);
+```
+
+### Insert Document
+
+```typescript
+const InsertResultSchema = z.object({
+  insertedId: z.string(),
+});
+
+const result = await ctx.integrations.mongodb.run(
+  "users",
+  "insertOne",
+  InsertResultSchema,
+  {
+    document: {
+      name: "John Doe",
+      email: "john@example.com",
+      createdAt: new Date().toISOString(),
+    },
+  },
+);
+```
+
+### Update Document
+
+```typescript
+const UpdateResultSchema = z.object({
+  matchedCount: z.number(),
+  modifiedCount: z.number(),
+});
+
+const result = await ctx.integrations.mongodb.run(
+  "users",
+  "updateOne",
+  UpdateResultSchema,
+  {
+    filter: { _id: userId },
+    update: {
+      $set: { status: "active", updatedAt: new Date().toISOString() },
+    },
+  },
+);
+```
+
+### Delete Document
+
+```typescript
+const DeleteResultSchema = z.object({
+  deletedCount: z.number(),
+});
+
+const result = await ctx.integrations.mongodb.run(
+  "users",
+  "deleteOne",
+  DeleteResultSchema,
+  {
+    filter: { _id: userId },
+  },
+);
+```
+
+### Aggregation Pipeline
+
+```typescript
+const AggregateResultSchema = z.array(
+  z.object({
+    _id: z.string(),
+    count: z.number(),
+    totalAmount: z.number(),
+  }),
+);
+
+const result = await ctx.integrations.mongodb.run(
+  "orders",
+  "aggregate",
+  AggregateResultSchema,
+  {
+    pipeline: [
+      { $match: { status: "completed" } },
+      {
+        $group: {
+          _id: "$customerId",
+          count: { $sum: 1 },
+          totalAmount: { $sum: "$amount" },
+        },
+      },
+    ],
+  },
+);
+```
+
+### Count Documents
+
+```typescript
+const count = await ctx.integrations.mongodb.run("users", "count", z.number(), {
+  query: { status: "active" },
+});
+```
+
+### Find with Projection and Sort
+
+```typescript
+const users = await ctx.integrations.mongodb.run("users", "find", UserSchema, {
+  query: { status: "active" },
+  projection: { name: 1, email: 1 },
+  sort: { createdAt: -1 },
+  limit: 10,
+  skip: 0,
+});
+```
+
+## Parameters
+
+| Parameter    | Type     | Description                  |
+| ------------ | -------- | ---------------------------- |
+| `query`      | `object` | Filter/query object          |
+| `filter`     | `object` | Alias for query              |
+| `document`   | `object` | Document to insert           |
+| `update`     | `object` | Update operations            |
+| `pipeline`   | `array`  | Aggregation pipeline         |
+| `projection` | `object` | Fields to include/exclude    |
+| `sort`       | `object` | Sort specification           |
+| `limit`      | `number` | Max documents to return      |
+| `skip`       | `number` | Documents to skip            |
+| `field`      | `string` | Field for distinct operation |
+
+## 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.
+
+## Error Handling
+
+```typescript
+import {
+  RestApiValidationError,
+  IntegrationError,
+} from "@superblocksteam/sdk-api";
+
+try {
+  const users = await ctx.integrations.mongodb.run(
+    "users",
+    "find",
+    UserSchema,
+    {
+      query: { status: "active" },
+    },
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  } else if (error instanceof IntegrationError) {
+    console.error("MongoDB error:", error.message);
+  }
+}
+```
+
+## API Reference
+
+- [MongoDB Manual](https://www.mongodb.com/docs/manual/)
+- [Query Operators](https://www.mongodb.com/docs/manual/reference/operator/query/)
+- [Aggregation](https://www.mongodb.com/docs/manual/aggregation/)

package/src/integrations/mongodb/client.ts

@@ -0,0 +1,137 @@
+/**
+ * MongoDB client implementation.
+ *
+ * Uses the native MongoDB plugin type from @superblocksteam/types.
+ */
+
+import type { z } from "zod";
+import type { PartialMessage } from "@bufbuild/protobuf";
+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 { MongoDBClient, MongoDBAction, MongoDBParams } from "./types.js";
+
+/**
+ * Internal implementation of MongoDBClient.
+ */
+export class MongoDBClientImpl implements MongoDBClient, 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;
+  }
+
+  private buildRequest(
+    collection: string,
+    action: MongoDBAction,
+    params?: MongoDBParams,
+  ): PartialMessage<MongoDBPlugin> {
+    const request: PartialMessage<MongoDBPlugin> = {
+      resource: collection,
+      action,
+    };
+
+    if (params) {
+      // Query/filter
+      if (params.query) {
+        request.query = JSON.stringify(params.query);
+      }
+      if (params.filter) {
+        request.filter = JSON.stringify(params.filter);
+      }
+
+      // Document operations
+      if (params.document) {
+        request.document = JSON.stringify(params.document);
+      }
+      if (params.update) {
+        request.update = JSON.stringify(params.update);
+      }
+
+      // Aggregation
+      if (params.pipeline) {
+        request.pipeline = JSON.stringify(params.pipeline);
+      }
+
+      // Query modifiers
+      if (params.projection) {
+        request.projection = JSON.stringify(params.projection);
+      }
+      if (params.sort) {
+        request.sortby = JSON.stringify(params.sort);
+      }
+      if (params.limit !== undefined) {
+        request.limit = String(params.limit);
+      }
+      if (params.skip !== undefined) {
+        request.skip = String(params.skip);
+      }
+
+      // Distinct field
+      if (params.field) {
+        request.field = params.field;
+      }
+
+      // Additional options
+      if (params.options) {
+        request.options = JSON.stringify(params.options);
+      }
+    }
+
+    return request;
+  }
+
+  async run<T>(
+    collection: string,
+    action: MongoDBAction,
+    schema: z.ZodSchema<T>,
+    params?: MongoDBParams,
+    metadata?: TraceMetadata,
+  ): Promise<T> {
+    const request = this.buildRequest(collection, action, params);
+
+    try {
+      const result = await this.executeQuery(
+        request as Record<string, unknown>,
+        undefined,
+        metadata,
+      );
+
+      // Validate result against schema
+      const parseResult = schema.safeParse(result);
+
+      if (!parseResult.success) {
+        throw new RestApiValidationError(
+          `Result validation failed: ${parseResult.error.message}`,
+          {
+            zodError: parseResult.error,
+            data: result,
+          },
+        );
+      }
+
+      return parseResult.data;
+    } catch (error) {
+      if (
+        error instanceof RestApiValidationError ||
+        error instanceof IntegrationError
+      ) {
+        throw error;
+      }
+
+      throw new IntegrationError(this.config.name, "run", error);
+    }
+  }
+}

package/src/integrations/mongodb/index.ts

@@ -0,0 +1,8 @@
+/**
+ * MongoDB integration client.
+ *
+ * @module
+ */
+
+export type { MongoDBClient, MongoDBAction, MongoDBParams } from "./types.js";
+export { MongoDBClientImpl } from "./client.js";

package/src/integrations/mongodb/types.ts

@@ -0,0 +1,105 @@
+/**
+ * MongoDB client types.
+ */
+
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
+
+/**
+ * MongoDB operation types.
+ */
+export type MongoDBAction =
+  | "aggregate"
+  | "count"
+  | "deleteOne"
+  | "deleteMany"
+  | "distinct"
+  | "find"
+  | "findOne"
+  | "insertOne"
+  | "insertMany"
+  | "listCollections"
+  | "replaceOne"
+  | "updateOne"
+  | "updateMany";
+
+/**
+ * Parameters for MongoDB operations.
+ */
+export interface MongoDBParams {
+  /** Filter/query object */
+  query?: Record<string, unknown>;
+  /** Filter object (alias for query) */
+  filter?: Record<string, unknown>;
+  /** Document to insert or replacement document */
+  document?: Record<string, unknown>;
+  /** Update operations */
+  update?: Record<string, unknown>;
+  /** Aggregation pipeline */
+  pipeline?: Record<string, unknown>[];
+  /** Fields to project */
+  projection?: Record<string, unknown>;
+  /** Sort specification */
+  sort?: Record<string, unknown>;
+  /** Maximum documents to return */
+  limit?: number;
+  /** Documents to skip */
+  skip?: number;
+  /** Field for distinct operation */
+  field?: string;
+  /** Additional options */
+  options?: Record<string, unknown>;
+}
+
+/**
+ * MongoDB client for database operations.
+ *
+ * Provides a generic run() method for executing any MongoDB operation.
+ *
+ * @example
+ * ```typescript
+ * // Declare in api(): integrations: { mongodb: mongodb(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.mongodb
+ *
+ * const UserSchema = z.object({
+ *   _id: z.string(),
+ *   name: z.string(),
+ *   email: z.string(),
+ * });
+ *
+ * // Find documents
+ * const users = await mongodb.run(
+ *   'users',
+ *   'find',
+ *   UserSchema,
+ *   { query: { active: true }, limit: 10 }
+ * );
+ *
+ * // Insert a document
+ * const result = await mongodb.run(
+ *   'users',
+ *   'insertOne',
+ *   z.object({ insertedId: z.string() }),
+ *   { document: { name: 'John', email: 'john@example.com' } }
+ * );
+ * ```
+ */
+export interface MongoDBClient extends BaseIntegrationClient {
+  /**
+   * Execute a MongoDB operation.
+   *
+   * @param collection - Collection name (use empty string for listCollections)
+   * @param action - The operation to perform
+   * @param schema - Zod schema for validating the result
+   * @param params - Operation parameters
+   * @returns The validated result
+   */
+  run<T>(
+    collection: string,
+    action: MongoDBAction,
+    schema: z.ZodSchema<T>,
+    params?: MongoDBParams,
+    metadata?: TraceMetadata,
+  ): Promise<T>;
+}

package/src/integrations/mssql/README.md

@@ -0,0 +1,160 @@
+# MSSQL (Microsoft SQL Server) Client
+
+Execute SQL queries and statements against Microsoft SQL Server 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, mssql } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_MSSQL = "a1b2c3d4-5678-90ab-cdef-mssql0000001";
+
+const UserSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  email: z.string().email(),
+  created_at: z.string(),
+});
+
+export default api({
+  integrations: {
+    mssql: mssql(PROD_MSSQL),
+  },
+  name: "MSSQLExample",
+  input: z.object({
+    status: z.string(),
+  }),
+  output: z.object({
+    users: z.array(UserSchema),
+  }),
+  async run(ctx, { status }) {
+    const users = await ctx.integrations.mssql.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.mssql.execute(
+  "INSERT INTO users (name, email) VALUES ($1, $2)",
+  ["John Doe", "john@example.com"],
+);
+
+// UPDATE
+const updateResult = await ctx.integrations.mssql.execute(
+  "UPDATE users SET last_login = GETDATE() WHERE id = $1",
+  [userId],
+);
+console.log(`Updated ${updateResult.rowCount} rows`);
+
+// DELETE
+const deleteResult = await ctx.integrations.mssql.execute(
+  "DELETE FROM sessions WHERE expires_at < GETDATE()",
+);
+console.log(`Deleted ${deleteResult.rowCount} expired sessions`);
+```
+
+### Using SQL Server-Specific Functions
+
+```typescript
+const AnalyticsSchema = z.object({
+  date: z.string(),
+  total_sales: z.string(),
+  order_count: z.coerce.number(),
+});
+
+const analytics = await ctx.integrations.mssql.query(
+  `SELECT
+    CONVERT(DATE, order_date) as date,
+    SUM(total) as total_sales,
+    COUNT(*) as order_count
+  FROM orders
+  WHERE order_date >= DATEADD(day, -30, GETDATE())
+  GROUP BY CONVERT(DATE, order_date)
+  ORDER BY date DESC`,
+  AnalyticsSchema,
+);
+```
+
+## 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
+
+```typescript
+const schema = z.object({
+  id: z.coerce.number(),
+  count: z.coerce.number(),
+});
+```
+
+### MONEY/DECIMAL Values Returned as Strings
+
+```typescript
+const schema = z.object({
+  price: z.string().transform((val) => parseFloat(val)),
+});
+```
+
+### Schema Parameter is Required
+
+```typescript
+// CORRECT - Schema is required
+const users = await ctx.integrations.mssql.query(
+  "SELECT * FROM users",
+  UserSchema,
+);
+```
+
+### NULL Handling
+
+```typescript
+const schema = z.object({
+  name: z.string(),
+  bio: z.string().nullable(),
+});
+```
+
+## Error Handling
+
+```typescript
+import { QueryValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const users = await ctx.integrations.mssql.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
+
+- [SQL Server Documentation](https://docs.microsoft.com/en-us/sql/sql-server/)
+- [SQL Server Data Types](https://docs.microsoft.com/en-us/sql/t-sql/data-types/data-types-transact-sql)