@superblocksteam/sdk-api 2.0.89-next.0

package/src/integrations/mongodb/README.md

@@ -0,0 +1,203 @@
+# MongoDB Client
+
+Execute MongoDB operations with full type safety and runtime validation.
+
+## Methods
+
+| Method | Description |
+| ------ | ----------- |
+| `run(collection, action, schema, params)` | 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 } 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({
+  name: "MongoDBExample",
+  input: z.object({
+    status: z.string(),
+  }),
+  output: z.object({
+    users: UserSchema,
+  }),
+  async run(ctx, { status }) {
+    const mongodb = ctx.mongodb(PROD_MONGODB);
+
+    const users = await 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 mongodb.run("users", "findOne", UserSchema, {
+  query: { _id: userId },
+});
+```
+
+### Insert Document
+
+```typescript
+const InsertResultSchema = z.object({
+  insertedId: z.string(),
+});
+
+const result = await 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 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 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 mongodb.run("orders", "aggregate", AggregateResultSchema, {
+  pipeline: [
+    { $match: { status: "completed" } },
+    {
+      $group: {
+        _id: "$customerId",
+        count: { $sum: 1 },
+        totalAmount: { $sum: "$amount" },
+      },
+    },
+  ],
+});
+```
+
+### Count Documents
+
+```typescript
+const count = await mongodb.run("users", "count", z.number(), {
+  query: { status: "active" },
+});
+```
+
+### Find with Projection and Sort
+
+```typescript
+const users = await 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 |
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError, IntegrationError } from "@superblocksteam/sdk-api";
+
+try {
+  const users = await 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,132 @@
+/**
+ * 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 } 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,
+  ): Promise<T> {
+    const request = this.buildRequest(collection, action, params);
+
+    try {
+      const result = await this.executeQuery(request as Record<string, unknown>);
+
+      // 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,102 @@
+/**
+ * MongoDB client types.
+ */
+
+import type { z } from 'zod';
+import type { BaseIntegrationClient } from '../../types.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
+ * const mongodb = ctx.mongodb('Production 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,
+  ): Promise<T>;
+}

package/src/integrations/mssql/README.md

@@ -0,0 +1,151 @@
+# 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?)` | Execute a SELECT query and return validated, typed results |
+| `execute(sql, params?)` | Execute a statement (INSERT, UPDATE, DELETE) and return affected row count |
+
+## Usage
+
+### Basic Query with Schema Validation
+
+```typescript
+import { api, z } 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({
+  name: "MSSQLExample",
+  input: z.object({
+    status: z.string(),
+  }),
+  output: z.object({
+    users: z.array(UserSchema),
+  }),
+  async run(ctx, { status }) {
+    const mssql = ctx.mssql(PROD_MSSQL);
+
+    const users = await mssql.query(
+      "SELECT id, name, email, created_at FROM users WHERE status = $1",
+      UserSchema,
+      [status]
+    );
+
+    return { users };
+  },
+});
+```
+
+### Executing INSERT, UPDATE, DELETE Statements
+
+```typescript
+const mssql = ctx.mssql(PROD_MSSQL);
+
+// INSERT
+await mssql.execute(
+  "INSERT INTO users (name, email) VALUES ($1, $2)",
+  ["John Doe", "john@example.com"]
+);
+
+// UPDATE
+const updateResult = await mssql.execute(
+  "UPDATE users SET last_login = GETDATE() WHERE id = $1",
+  [userId]
+);
+console.log(`Updated ${updateResult.rowCount} rows`);
+
+// DELETE
+const deleteResult = await 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 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
+);
+```
+
+## 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 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 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)