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

package/src/integrations/mongodb/README.md

@@ -4,44 +4,49 @@ Execute MongoDB operations with full type safety and runtime validation.
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| 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 |
+| 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";
+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(),
-}));
+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(),
@@ -50,12 +55,15 @@ export default api({
     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,
-    });
+    const users = await ctx.integrations.mongodb.run(
+      "users",
+      "find",
+      UserSchema,
+      {
+        query: { status: status },
+        limit: 10,
+      },
+    );
 
     return { users };
   },
@@ -65,15 +73,22 @@ export default api({
 ### 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 },
-});
+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
@@ -83,13 +98,18 @@ 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(),
+const result = await ctx.integrations.mongodb.run(
+  "users",
+  "insertOne",
+  InsertResultSchema,
+  {
+    document: {
+      name: "John Doe",
+      email: "john@example.com",
+      createdAt: new Date().toISOString(),
+    },
   },
-});
+);
 ```
 
 ### Update Document
@@ -100,12 +120,17 @@ const UpdateResultSchema = z.object({
   modifiedCount: z.number(),
 });
 
-const result = await mongodb.run("users", "updateOne", UpdateResultSchema, {
-  filter: { _id: userId },
-  update: {
-    $set: { status: "active", updatedAt: new Date().toISOString() },
+const result = await ctx.integrations.mongodb.run(
+  "users",
+  "updateOne",
+  UpdateResultSchema,
+  {
+    filter: { _id: userId },
+    update: {
+      $set: { status: "active", updatedAt: new Date().toISOString() },
+    },
   },
-});
+);
 ```
 
 ### Delete Document
@@ -115,38 +140,50 @@ const DeleteResultSchema = z.object({
   deletedCount: z.number(),
 });
 
-const result = await mongodb.run("users", "deleteOne", DeleteResultSchema, {
-  filter: { _id: userId },
-});
+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 mongodb.run("orders", "aggregate", AggregateResultSchema, {
-  pipeline: [
-    { $match: { status: "completed" } },
-    {
-      $group: {
-        _id: "$customerId",
-        count: { $sum: 1 },
-        totalAmount: { $sum: "$amount" },
+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 mongodb.run("users", "count", z.number(), {
+const count = await ctx.integrations.mongodb.run("users", "count", z.number(), {
   query: { status: "active" },
 });
 ```
@@ -154,7 +191,7 @@ const count = await mongodb.run("users", "count", z.number(), {
 ### Find with Projection and Sort
 
 ```typescript
-const users = await mongodb.run("users", "find", UserSchema, {
+const users = await ctx.integrations.mongodb.run("users", "find", UserSchema, {
   query: { status: "active" },
   projection: { name: 1, email: 1 },
   sort: { createdAt: -1 },
@@ -165,28 +202,36 @@ const users = await mongodb.run("users", "find", UserSchema, {
 
 ## 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 |
+| 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";
+import {
+  RestApiValidationError,
+  IntegrationError,
+} from "@superblocksteam/sdk-api";
 
 try {
-  const users = await mongodb.run("users", "find", UserSchema, {
-    query: { status: "active" },
-  });
+  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);

package/src/integrations/mongodb/client.ts

@@ -4,14 +4,14 @@
  * 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';
+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.
@@ -102,7 +102,9 @@ export class MongoDBClientImpl implements MongoDBClient, IntegrationClientImpl {
     const request = this.buildRequest(collection, action, params);
 
     try {
-      const result = await this.executeQuery(request as Record<string, unknown>);
+      const result = await this.executeQuery(
+        request as Record<string, unknown>,
+      );
 
       // Validate result against schema
       const parseResult = schema.safeParse(result);
@@ -126,7 +128,7 @@ export class MongoDBClientImpl implements MongoDBClient, IntegrationClientImpl {
         throw error;
       }
 
-      throw new IntegrationError(this.config.name, 'run', error);
+      throw new IntegrationError(this.config.name, "run", error);
     }
   }
 }

package/src/integrations/mongodb/index.ts

@@ -4,5 +4,5 @@
  * @module
  */
 
-export type { MongoDBClient, MongoDBAction, MongoDBParams } from './types.js';
-export { MongoDBClientImpl } from './client.js';
+export type { MongoDBClient, MongoDBAction, MongoDBParams } from "./types.js";
+export { MongoDBClientImpl } from "./client.js";

package/src/integrations/mongodb/types.ts

@@ -2,26 +2,26 @@
  * MongoDB client types.
  */
 
-import type { z } from 'zod';
-import type { BaseIntegrationClient } from '../../types.js';
+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';
+  | "aggregate"
+  | "count"
+  | "deleteOne"
+  | "deleteMany"
+  | "distinct"
+  | "find"
+  | "findOne"
+  | "insertOne"
+  | "insertMany"
+  | "listCollections"
+  | "replaceOne"
+  | "updateOne"
+  | "updateMany";
 
 /**
  * Parameters for MongoDB operations.
@@ -58,7 +58,8 @@ export interface MongoDBParams {
  *
  * @example
  * ```typescript
- * const mongodb = ctx.mongodb('Production MongoDB');
+ * // Declare in api(): integrations: { mongodb: mongodb(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.mongodb
  *
  * const UserSchema = z.object({
  *   _id: z.string(),

package/src/integrations/mssql/README.md

@@ -4,17 +4,17 @@ Execute SQL queries and statements against Microsoft SQL Server databases with f
 
 ## 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
 
 ### Basic Query with Schema Validation
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, mssql } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_MSSQL = "a1b2c3d4-5678-90ab-cdef-mssql0000001";
@@ -27,6 +27,9 @@ const UserSchema = z.object({
 });
 
 export default api({
+  integrations: {
+    mssql: mssql(PROD_MSSQL),
+  },
   name: "MSSQLExample",
   input: z.object({
     status: z.string(),
@@ -35,12 +38,10 @@ export default api({
     users: z.array(UserSchema),
   }),
   async run(ctx, { status }) {
-    const mssql = ctx.mssql(PROD_MSSQL);
-
-    const users = await mssql.query(
+    const users = await ctx.integrations.mssql.query(
       "SELECT id, name, email, created_at FROM users WHERE status = $1",
       UserSchema,
-      [status]
+      [status],
     );
 
     return { users };
@@ -51,24 +52,22 @@ export default api({
 ### Executing INSERT, UPDATE, DELETE Statements
 
 ```typescript
-const mssql = ctx.mssql(PROD_MSSQL);
-
 // INSERT
-await mssql.execute(
+await ctx.integrations.mssql.execute(
   "INSERT INTO users (name, email) VALUES ($1, $2)",
-  ["John Doe", "john@example.com"]
+  ["John Doe", "john@example.com"],
 );
 
 // UPDATE
-const updateResult = await mssql.execute(
+const updateResult = await ctx.integrations.mssql.execute(
   "UPDATE users SET last_login = GETDATE() WHERE id = $1",
-  [userId]
+  [userId],
 );
 console.log(`Updated ${updateResult.rowCount} rows`);
 
 // DELETE
-const deleteResult = await mssql.execute(
-  "DELETE FROM sessions WHERE expires_at < GETDATE()"
+const deleteResult = await ctx.integrations.mssql.execute(
+  "DELETE FROM sessions WHERE expires_at < GETDATE()",
 );
 console.log(`Deleted ${deleteResult.rowCount} expired sessions`);
 ```
@@ -82,7 +81,7 @@ const AnalyticsSchema = z.object({
   order_count: z.coerce.number(),
 });
 
-const analytics = await mssql.query(
+const analytics = await ctx.integrations.mssql.query(
   `SELECT
     CONVERT(DATE, order_date) as date,
     SUM(total) as total_sales,
@@ -91,7 +90,7 @@ const analytics = await mssql.query(
   WHERE order_date >= DATEADD(day, -30, GETDATE())
   GROUP BY CONVERT(DATE, order_date)
   ORDER BY date DESC`,
-  AnalyticsSchema
+  AnalyticsSchema,
 );
 ```
 
@@ -118,7 +117,10 @@ const schema = z.object({
 
 ```typescript
 // CORRECT - Schema is required
-const users = await mssql.query("SELECT * FROM users", UserSchema);
+const users = await ctx.integrations.mssql.query(
+  "SELECT * FROM users",
+  UserSchema,
+);
 ```
 
 ### NULL Handling
@@ -136,7 +138,10 @@ const schema = z.object({
 import { QueryValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const users = await mssql.query("SELECT * FROM users", UserSchema);
+  const users = await ctx.integrations.mssql.query(
+    "SELECT * FROM users",
+    UserSchema,
+  );
 } catch (error) {
   if (error instanceof QueryValidationError) {
     console.error("Row index:", error.details.rowIndex);

package/src/integrations/mssql/client.ts

@@ -5,15 +5,15 @@
  * 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 } 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';
+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 } 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.
@@ -71,7 +71,7 @@ export class MSSQLClientImpl implements MSSQLClient, IntegrationClientImpl {
       if (!Array.isArray(result)) {
         throw new IntegrationError(
           this.config.name,
-          'query',
+          "query",
           `Expected array result from MSSQL query, got: ${describeType(result)}`,
         );
       }
@@ -107,27 +107,30 @@ export class MSSQLClientImpl implements MSSQLClient, 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 };
       }
 
       return { rowCount: 0 };
     } catch (error) {
-      throw new IntegrationError(this.config.name, 'execute', error);
+      throw new IntegrationError(this.config.name, "execute", error);
     }
   }
 }

package/src/integrations/mssql/index.ts

@@ -4,5 +4,5 @@
  * @module
  */
 
-export type { MSSQLClient } from './types.js';
-export { MSSQLClientImpl } from './client.js';
+export type { MSSQLClient } from "./types.js";
+export { MSSQLClientImpl } from "./client.js";

package/src/integrations/mssql/types.ts

@@ -4,15 +4,16 @@
  * Provides typed methods for executing MSSQL queries with runtime validation.
  */
 
-import type { z } from 'zod';
-import type { BaseIntegrationClient } from '../../types.js';
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
 
 /**
  * Client for executing MSSQL queries with type-safe validation.
  *
  * @example
  * ```typescript
- * const mssql = ctx.mssql('Production SQL Server');
+ * // Declare in api(): integrations: { mssql: mssql(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.mssql
  *
  * // Query with validation
  * const UserSchema = z.object({
@@ -40,7 +41,11 @@ export interface MSSQLClient extends BaseIntegrationClient {
    * @throws {QueryValidationError} If results don't match schema
    * @throws {IntegrationError} If query execution fails
    */
-  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) without output validation.