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

package/src/integrations/cosmosdb/README.md

@@ -4,8 +4,8 @@ Interact with Azure CosmosDB with full type safety and runtime validation.
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                          |
+| ----------------------------- | ---------------------------------------------------- |
 | `apiRequest(options, schema)` | Make any CosmosDB API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Interact with Azure CosmosDB with full type safety and runtime validation.
 ### Query Documents
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, cosmosdb } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_COSMOSDB = "a1b2c3d4-5678-90ab-cdef-cosmosdb0001";
@@ -24,27 +24,30 @@ const QueryResponseSchema = z.object({
       id: z.string(),
       name: z.string(),
       email: z.string(),
-    })
+    }),
   ),
   _count: z.number(),
 });
 
 export default api({
   name: "CosmosDBExample",
+  integrations: {
+    cosmosdb: cosmosdb(PROD_COSMOSDB),
+  },
   input: z.object({
     status: z.string(),
   }),
   output: z.object({
-    users: z.array(z.object({
-      id: z.string(),
-      name: z.string(),
-      email: z.string(),
-    })),
+    users: z.array(
+      z.object({
+        id: z.string(),
+        name: z.string(),
+        email: z.string(),
+      }),
+    ),
   }),
   async run(ctx, { status }) {
-    const cosmosdb = ctx.cosmosdb(PROD_COSMOSDB);
-
-    const result = await cosmosdb.apiRequest(
+    const result = await ctx.integrations.cosmosdb.apiRequest(
       {
         method: "POST",
         path: "/dbs/mydb/colls/users/docs",
@@ -56,7 +59,7 @@ export default api({
           parameters: [{ name: "@status", value: status }],
         },
       },
-      { response: QueryResponseSchema }
+      { response: QueryResponseSchema },
     );
 
     return { users: result.Documents };
@@ -73,7 +76,7 @@ const GetDocumentResponseSchema = z.object({
   email: z.string(),
 });
 
-const result = await cosmosdb.apiRequest(
+const result = await ctx.integrations.cosmosdb.apiRequest(
   {
     method: "GET",
     path: `/dbs/mydb/colls/users/docs/${documentId}`,
@@ -81,7 +84,7 @@ const result = await cosmosdb.apiRequest(
       "x-ms-documentdb-partitionkey": `["${partitionKey}"]`,
     },
   },
-  { response: GetDocumentResponseSchema }
+  { response: GetDocumentResponseSchema },
 );
 ```
 
@@ -94,7 +97,7 @@ const CreateResponseSchema = z.object({
   _etag: z.string(),
 });
 
-const result = await cosmosdb.apiRequest(
+const result = await ctx.integrations.cosmosdb.apiRequest(
   {
     method: "POST",
     path: "/dbs/mydb/colls/users/docs",
@@ -108,7 +111,7 @@ const result = await cosmosdb.apiRequest(
       partitionKey: partitionKey,
     },
   },
-  { response: CreateResponseSchema }
+  { response: CreateResponseSchema },
 );
 ```
 
@@ -120,7 +123,7 @@ const ReplaceResponseSchema = z.object({
   _etag: z.string(),
 });
 
-const result = await cosmosdb.apiRequest(
+const result = await ctx.integrations.cosmosdb.apiRequest(
   {
     method: "PUT",
     path: `/dbs/mydb/colls/users/docs/${documentId}`,
@@ -134,7 +137,7 @@ const result = await cosmosdb.apiRequest(
       partitionKey: partitionKey,
     },
   },
-  { response: ReplaceResponseSchema }
+  { response: ReplaceResponseSchema },
 );
 ```
 
@@ -143,7 +146,7 @@ const result = await cosmosdb.apiRequest(
 ```typescript
 const DeleteResponseSchema = z.object({}).passthrough();
 
-await cosmosdb.apiRequest(
+await ctx.integrations.cosmosdb.apiRequest(
   {
     method: "DELETE",
     path: `/dbs/mydb/colls/users/docs/${documentId}`,
@@ -151,7 +154,7 @@ await cosmosdb.apiRequest(
       "x-ms-documentdb-partitionkey": `["${partitionKey}"]`,
     },
   },
-  { response: DeleteResponseSchema }
+  { response: DeleteResponseSchema },
 );
 ```
 
@@ -181,7 +184,7 @@ headers: {
 
 ```typescript
 // CORRECT - Response schema is required
-await cosmosdb.apiRequest(
+await ctx.integrations.cosmosdb.apiRequest(
   { method: "POST", path: "/...", body: { ... } },
   { response: ResponseSchema }
 );
@@ -193,7 +196,7 @@ await cosmosdb.apiRequest(
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await cosmosdb.apiRequest(
+  const result = await ctx.integrations.cosmosdb.apiRequest(
     { method: "POST", path: "/...", body: { ... } },
     { response: ResponseSchema }
   );

package/src/integrations/cosmosdb/client.ts

@@ -6,14 +6,14 @@
  * upsert, delete) against CosmosDB containers.
  */
 
-import type { z } from 'zod';
-import type { PartialMessage } from '@bufbuild/protobuf';
-import type { Plugin as CosmosDBPlugin } from '@superblocksteam/types/dist/src/plugins/cosmosdb/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 { CosmosDBClient, CosmosDBQueryOptions } from './types.js';
+import type { z } from "zod";
+import type { PartialMessage } from "@bufbuild/protobuf";
+import type { Plugin as CosmosDBPlugin } from "@superblocksteam/types/dist/src/plugins/cosmosdb/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 { CosmosDBClient, CosmosDBQueryOptions } from "./types.js";
 
 /**
  * CosmosDB request type derived from proto definition.
@@ -26,7 +26,9 @@ type CosmosDBRequest = PartialMessage<CosmosDBPlugin>;
  * Communicates with the orchestrator using the native CosmosDB plugin
  * proto format, supporting SQL queries and point operations.
  */
-export class CosmosDBClientImpl implements CosmosDBClient, IntegrationClientImpl {
+export class CosmosDBClientImpl
+  implements CosmosDBClient, IntegrationClientImpl
+{
   readonly config: IntegrationConfig;
   private readonly executeQuery: QueryExecutor;
 
@@ -91,10 +93,10 @@ export class CosmosDBClientImpl implements CosmosDBClient, IntegrationClientImpl
   ): Promise<T> {
     const request: CosmosDBRequest = {
       cosmosdbAction: {
-        case: 'sql',
+        case: "sql",
         value: {
           action: {
-            case: 'singleton',
+            case: "singleton",
             value: {
               containerId,
               query: sql,
@@ -106,7 +108,7 @@ export class CosmosDBClientImpl implements CosmosDBClient, IntegrationClientImpl
       },
     };
 
-    const result = await this.exec(request, 'query');
+    const result = await this.exec(request, "query");
     return this.validate(result, schema);
   }
 
@@ -118,18 +120,18 @@ export class CosmosDBClientImpl implements CosmosDBClient, IntegrationClientImpl
   ): Promise<T> {
     const request: CosmosDBRequest = {
       cosmosdbAction: {
-        case: 'pointOperation',
+        case: "pointOperation",
         value: {
           containerId,
           action: {
-            case: 'read',
+            case: "read",
             value: { id, partitionKey },
           },
         },
       },
     };
 
-    const result = await this.exec(request, 'read');
+    const result = await this.exec(request, "read");
     return this.validate(result, schema);
   }
 
@@ -140,13 +142,13 @@ export class CosmosDBClientImpl implements CosmosDBClient, IntegrationClientImpl
   ): Promise<unknown> {
     const request: CosmosDBRequest = {
       cosmosdbAction: {
-        case: 'pointOperation',
+        case: "pointOperation",
         value: {
           containerId,
           action: {
-            case: 'create',
+            case: "create",
             value: {
-              body: typeof body === 'string' ? body : JSON.stringify(body),
+              body: typeof body === "string" ? body : JSON.stringify(body),
               partitionKey,
             },
           },
@@ -154,7 +156,7 @@ export class CosmosDBClientImpl implements CosmosDBClient, IntegrationClientImpl
       },
     };
 
-    return this.exec(request, 'create');
+    return this.exec(request, "create");
   }
 
   async replace(
@@ -164,13 +166,13 @@ export class CosmosDBClientImpl implements CosmosDBClient, IntegrationClientImpl
   ): Promise<unknown> {
     const request: CosmosDBRequest = {
       cosmosdbAction: {
-        case: 'pointOperation',
+        case: "pointOperation",
         value: {
           containerId,
           action: {
-            case: 'replace',
+            case: "replace",
             value: {
-              body: typeof body === 'string' ? body : JSON.stringify(body),
+              body: typeof body === "string" ? body : JSON.stringify(body),
               partitionKey,
             },
           },
@@ -178,7 +180,7 @@ export class CosmosDBClientImpl implements CosmosDBClient, IntegrationClientImpl
       },
     };
 
-    return this.exec(request, 'replace');
+    return this.exec(request, "replace");
   }
 
   async upsert(
@@ -188,13 +190,13 @@ export class CosmosDBClientImpl implements CosmosDBClient, IntegrationClientImpl
   ): Promise<unknown> {
     const request: CosmosDBRequest = {
       cosmosdbAction: {
-        case: 'pointOperation',
+        case: "pointOperation",
         value: {
           containerId,
           action: {
-            case: 'upsert',
+            case: "upsert",
             value: {
-              body: typeof body === 'string' ? body : JSON.stringify(body),
+              body: typeof body === "string" ? body : JSON.stringify(body),
               partitionKey,
             },
           },
@@ -202,7 +204,7 @@ export class CosmosDBClientImpl implements CosmosDBClient, IntegrationClientImpl
       },
     };
 
-    return this.exec(request, 'upsert');
+    return this.exec(request, "upsert");
   }
 
   async deleteItem(
@@ -212,17 +214,17 @@ export class CosmosDBClientImpl implements CosmosDBClient, IntegrationClientImpl
   ): Promise<unknown> {
     const request: CosmosDBRequest = {
       cosmosdbAction: {
-        case: 'pointOperation',
+        case: "pointOperation",
         value: {
           containerId,
           action: {
-            case: 'delete',
+            case: "delete",
             value: { id, partitionKey },
           },
         },
       },
     };
 
-    return this.exec(request, 'delete');
+    return this.exec(request, "delete");
   }
 }

package/src/integrations/cosmosdb/index.ts

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

package/src/integrations/cosmosdb/types.ts

@@ -2,8 +2,8 @@
  * CosmosDB client types.
  */
 
-import type { z } from 'zod';
-import type { BaseIntegrationClient } from '../../types.js';
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
 
 /**
  * Options for CosmosDB SQL queries.
@@ -23,7 +23,8 @@ export interface CosmosDBQueryOptions {
  *
  * @example
  * ```typescript
- * const cosmos = ctx.cosmosdb('Production CosmosDB');
+ * // Declare in api(): integrations: { cosmos: cosmosdb(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.cosmos
  *
  * // SQL query
  * const users = await cosmos.query(

package/src/integrations/couchbase/README.md

@@ -4,19 +4,19 @@ Interact with Couchbase databases with full type safety and runtime validation.
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                                | Description                                  |
+| ------------------------------------- | -------------------------------------------- |
 | `query(bucket, sql, schema, params?)` | Execute a SQL++ query with schema validation |
-| `insert(key, value, identifier)` | Insert a document into a collection |
-| `get(key, schema, identifier)` | Get a document by key with schema validation |
-| `remove(key, identifier)` | Remove a document by key |
+| `insert(key, value, identifier)`      | Insert a document into a collection          |
+| `get(key, schema, identifier)`        | Get a document by key with schema validation |
+| `remove(key, identifier)`             | Remove a document by key                     |
 
 ## Usage
 
 ### SQL++ Query
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, couchbase } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_COUCHBASE = "a1b2c3d4-5678-90ab-cdef-couchbase001";
@@ -29,6 +29,9 @@ const UserSchema = z.object({
 
 export default api({
   name: "CouchbaseExample",
+  integrations: {
+    cb: couchbase(PROD_COUCHBASE),
+  },
   input: z.object({
     status: z.string(),
   }),
@@ -36,9 +39,7 @@ export default api({
     users: z.array(UserSchema),
   }),
   async run(ctx, { status }) {
-    const cb = ctx.couchbase(PROD_COUCHBASE);
-
-    const users = await cb.query(
+    const users = await ctx.integrations.cb.query(
       "my-bucket",
       `SELECT META().id, name, email FROM bucket WHERE status = "${status}"`,
       UserSchema,
@@ -52,7 +53,7 @@ export default api({
 ### Parameterized Query
 
 ```typescript
-const users = await cb.query(
+const users = await ctx.integrations.cb.query(
   "my-bucket",
   "SELECT META().id, name, email FROM bucket WHERE status = $1",
   UserSchema,
@@ -63,7 +64,7 @@ const users = await cb.query(
 ### Insert Document
 
 ```typescript
-await cb.insert(
+await ctx.integrations.cb.insert(
   "user::123",
   { name: "Alice", email: "alice@example.com", status: "active" },
   { bucket: "my-bucket", scope: "_default", collection: "_default" },
@@ -79,33 +80,46 @@ const UserSchema = z.object({
   status: z.string(),
 });
 
-const user = await cb.get(
-  "user::123",
-  UserSchema,
-  { bucket: "my-bucket", scope: "_default", collection: "_default" },
-);
+const user = await ctx.integrations.cb.get("user::123", UserSchema, {
+  bucket: "my-bucket",
+  scope: "_default",
+  collection: "_default",
+});
 ```
 
 ### Remove Document
 
 ```typescript
-await cb.remove(
-  "user::123",
-  { bucket: "my-bucket", scope: "_default", collection: "_default" },
-);
+await ctx.integrations.cb.remove("user::123", {
+  bucket: "my-bucket",
+  scope: "_default",
+  collection: "_default",
+});
 ```
 
 ## Error Handling
 
 ```typescript
-import { QueryValidationError, RestApiValidationError } from "@superblocksteam/sdk-api";
+import {
+  QueryValidationError,
+  RestApiValidationError,
+} from "@superblocksteam/sdk-api";
 
 try {
-  const users = await cb.query("my-bucket", "SELECT * FROM bucket", UserSchema);
+  const users = await ctx.integrations.cb.query(
+    "my-bucket",
+    "SELECT * FROM bucket",
+    UserSchema,
+  );
 } catch (error) {
   if (error instanceof QueryValidationError) {
     // Query result row failed schema validation
-    console.error("Row", error.details.rowIndex, "failed:", error.details.errors);
+    console.error(
+      "Row",
+      error.details.rowIndex,
+      "failed:",
+      error.details.errors,
+    );
   }
   if (error instanceof RestApiValidationError) {
     // Document get result failed schema validation

package/src/integrations/couchbase/client.ts

@@ -6,15 +6,15 @@
  * get, and remove operations against Couchbase buckets.
  */
 
-import type { z } from 'zod';
-import type { PartialMessage } from '@bufbuild/protobuf';
-import type { Plugin as CouchbasePlugin } from '@superblocksteam/types/dist/src/plugins/couchbase/v1/plugin_pb';
-import type { IntegrationConfig, IntegrationClientImpl } from '../types.js';
-import type { QueryExecutor } from '../registry.js';
-import { QueryValidationError, RestApiValidationError } from '../../errors.js';
-import { IntegrationError } from '../../runtime/errors.js';
-import { describeType } from '../utils.js';
-import type { CouchbaseClient, CouchbaseIdentifier } from './types.js';
+import type { z } from "zod";
+import type { PartialMessage } from "@bufbuild/protobuf";
+import type { Plugin as CouchbasePlugin } from "@superblocksteam/types/dist/src/plugins/couchbase/v1/plugin_pb";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
+import type { QueryExecutor } from "../registry.js";
+import { QueryValidationError, RestApiValidationError } from "../../errors.js";
+import { IntegrationError } from "../../runtime/errors.js";
+import { describeType } from "../utils.js";
+import type { CouchbaseClient, CouchbaseIdentifier } from "./types.js";
 
 /**
  * Couchbase request type derived from proto definition.
@@ -28,7 +28,9 @@ type CouchbaseRequest = PartialMessage<CouchbasePlugin>;
  * proto format, supporting SQL++ queries and key-value document operations.
  * All operations require a bucket name.
  */
-export class CouchbaseClientImpl implements CouchbaseClient, IntegrationClientImpl {
+export class CouchbaseClientImpl
+  implements CouchbaseClient, IntegrationClientImpl
+{
   readonly config: IntegrationConfig;
   private readonly executeQuery: QueryExecutor;
 
@@ -55,7 +57,7 @@ export class CouchbaseClientImpl implements CouchbaseClient, IntegrationClientIm
     const request: CouchbaseRequest = {
       bucketName: bucket,
       couchbaseAction: {
-        case: 'runSql',
+        case: "runSql",
         value: {
           sqlBody: sql,
           parameters: hasParams ? JSON.stringify(params) : undefined,
@@ -64,12 +66,14 @@ export class CouchbaseClientImpl implements CouchbaseClient, IntegrationClientIm
     };
 
     try {
-      const result = await this.executeQuery(request as Record<string, unknown>);
+      const result = await this.executeQuery(
+        request as Record<string, unknown>,
+      );
 
       if (!Array.isArray(result)) {
         throw new IntegrationError(
           this.config.name,
-          'query',
+          "query",
           `Expected array result from Couchbase query, got: ${describeType(result)}`,
         );
       }
@@ -102,7 +106,7 @@ export class CouchbaseClientImpl implements CouchbaseClient, IntegrationClientIm
         throw error;
       }
 
-      throw new IntegrationError(this.config.name, 'query', error);
+      throw new IntegrationError(this.config.name, "query", error);
     }
   }
 
@@ -114,10 +118,10 @@ export class CouchbaseClientImpl implements CouchbaseClient, IntegrationClientIm
     const request: CouchbaseRequest = {
       bucketName: identifier.bucket,
       couchbaseAction: {
-        case: 'insert',
+        case: "insert",
         value: {
           key,
-          value: typeof value === 'string' ? value : JSON.stringify(value),
+          value: typeof value === "string" ? value : JSON.stringify(value),
           identifier: {
             scope: identifier.scope,
             collection: identifier.collection,
@@ -133,7 +137,7 @@ export class CouchbaseClientImpl implements CouchbaseClient, IntegrationClientIm
         throw error;
       }
 
-      throw new IntegrationError(this.config.name, 'insert', error);
+      throw new IntegrationError(this.config.name, "insert", error);
     }
   }
 
@@ -145,7 +149,7 @@ export class CouchbaseClientImpl implements CouchbaseClient, IntegrationClientIm
     const request: CouchbaseRequest = {
       bucketName: identifier.bucket,
       couchbaseAction: {
-        case: 'get',
+        case: "get",
         value: {
           key,
           identifier: {
@@ -157,7 +161,9 @@ export class CouchbaseClientImpl implements CouchbaseClient, IntegrationClientIm
     };
 
     try {
-      const result = await this.executeQuery(request as Record<string, unknown>);
+      const result = await this.executeQuery(
+        request as Record<string, unknown>,
+      );
 
       const parseResult = schema.safeParse(result);
 
@@ -180,7 +186,7 @@ export class CouchbaseClientImpl implements CouchbaseClient, IntegrationClientIm
         throw error;
       }
 
-      throw new IntegrationError(this.config.name, 'get', error);
+      throw new IntegrationError(this.config.name, "get", error);
     }
   }
 
@@ -188,7 +194,7 @@ export class CouchbaseClientImpl implements CouchbaseClient, IntegrationClientIm
     const request: CouchbaseRequest = {
       bucketName: identifier.bucket,
       couchbaseAction: {
-        case: 'remove',
+        case: "remove",
         value: {
           key,
           identifier: {
@@ -206,7 +212,7 @@ export class CouchbaseClientImpl implements CouchbaseClient, IntegrationClientIm
         throw error;
       }
 
-      throw new IntegrationError(this.config.name, 'remove', error);
+      throw new IntegrationError(this.config.name, "remove", error);
     }
   }
 }

package/src/integrations/couchbase/index.ts

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