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

package/src/integrations/dynamodb/client.ts

@@ -6,12 +6,12 @@
  * which the orchestrator parses and forwards directly to the AWS SDK.
  */
 
-import type { z } from 'zod';
-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 { DynamoDBClient, DynamoDBAttributeValue } from './types.js';
+import type { z } from "zod";
+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 { DynamoDBClient, DynamoDBAttributeValue } from "./types.js";
 
 /**
  * Internal implementation of DynamoDBClient.
@@ -22,7 +22,9 @@ import type { DynamoDBClient, DynamoDBAttributeValue } from './types.js';
  *
  * All other proto fields (table, filterBy, newValues, etc.) are ignored.
  */
-export class DynamoDBClientImpl implements DynamoDBClient, IntegrationClientImpl {
+export class DynamoDBClientImpl
+  implements DynamoDBClient, IntegrationClientImpl
+{
   readonly config: IntegrationConfig;
   private readonly executeQuery: QueryExecutor;
 
@@ -58,7 +60,11 @@ export class DynamoDBClientImpl implements DynamoDBClient, IntegrationClientImpl
   /**
    * Validate a result against a schema.
    */
-  private validateResult<T>(result: unknown, schema: z.ZodSchema<T>, operation: string): T {
+  private validateResult<T>(
+    result: unknown,
+    schema: z.ZodSchema<T>,
+    operation: string,
+  ): T {
     const parseResult = schema.safeParse(result);
 
     if (!parseResult.success) {
@@ -106,9 +112,9 @@ export class DynamoDBClientImpl implements DynamoDBClient, IntegrationClientImpl
       body.Parameters = params;
     }
 
-    const request = this.buildRequest('executeStatement', body);
-    const result = await this.executeWithErrorHandling(request, 'query');
-    return this.validateResult(result, schema, 'query');
+    const request = this.buildRequest("executeStatement", body);
+    const result = await this.executeWithErrorHandling(request, "query");
+    return this.validateResult(result, schema, "query");
   }
 
   async getItem<T>(
@@ -116,23 +122,23 @@ export class DynamoDBClientImpl implements DynamoDBClient, IntegrationClientImpl
     key: Record<string, DynamoDBAttributeValue>,
     schema: z.ZodSchema<T>,
   ): Promise<T> {
-    const request = this.buildRequest('getItem', {
+    const request = this.buildRequest("getItem", {
       TableName: table,
       Key: key,
     });
-    const result = await this.executeWithErrorHandling(request, 'getItem');
-    return this.validateResult(result, schema, 'getItem');
+    const result = await this.executeWithErrorHandling(request, "getItem");
+    return this.validateResult(result, schema, "getItem");
   }
 
   async putItem(
     table: string,
     item: Record<string, DynamoDBAttributeValue>,
   ): Promise<unknown> {
-    const request = this.buildRequest('putItem', {
+    const request = this.buildRequest("putItem", {
       TableName: table,
       Item: item,
     });
-    return this.executeWithErrorHandling(request, 'putItem');
+    return this.executeWithErrorHandling(request, "putItem");
   }
 
   async updateItem(
@@ -153,19 +159,19 @@ export class DynamoDBClientImpl implements DynamoDBClient, IntegrationClientImpl
       params.ExpressionAttributeNames = expressionAttributeNames;
     }
 
-    const request = this.buildRequest('updateItem', params);
-    return this.executeWithErrorHandling(request, 'updateItem');
+    const request = this.buildRequest("updateItem", params);
+    return this.executeWithErrorHandling(request, "updateItem");
   }
 
   async deleteItem(
     table: string,
     key: Record<string, DynamoDBAttributeValue>,
   ): Promise<unknown> {
-    const request = this.buildRequest('deleteItem', {
+    const request = this.buildRequest("deleteItem", {
       TableName: table,
       Key: key,
     });
-    return this.executeWithErrorHandling(request, 'deleteItem');
+    return this.executeWithErrorHandling(request, "deleteItem");
   }
 
   async scan<T>(
@@ -189,9 +195,9 @@ export class DynamoDBClientImpl implements DynamoDBClient, IntegrationClientImpl
       params.ExpressionAttributeNames = expressionAttributeNames;
     }
 
-    const request = this.buildRequest('scan', params);
-    const result = await this.executeWithErrorHandling(request, 'scan');
-    return this.validateResult(result, schema, 'scan');
+    const request = this.buildRequest("scan", params);
+    const result = await this.executeWithErrorHandling(request, "scan");
+    return this.validateResult(result, schema, "scan");
   }
 
   async queryTable<T>(
@@ -211,38 +217,41 @@ export class DynamoDBClientImpl implements DynamoDBClient, IntegrationClientImpl
       params.ExpressionAttributeNames = expressionAttributeNames;
     }
 
-    const request = this.buildRequest('query', params);
-    const result = await this.executeWithErrorHandling(request, 'queryTable');
-    return this.validateResult(result, schema, 'queryTable');
+    const request = this.buildRequest("query", params);
+    const result = await this.executeWithErrorHandling(request, "queryTable");
+    return this.validateResult(result, schema, "queryTable");
   }
 
   async batchWriteItem(
     requestItems: Record<string, Array<Record<string, unknown>>>,
   ): Promise<unknown> {
-    const request = this.buildRequest('batchWriteItem', {
+    const request = this.buildRequest("batchWriteItem", {
       RequestItems: requestItems,
     });
-    return this.executeWithErrorHandling(request, 'batchWriteItem');
+    return this.executeWithErrorHandling(request, "batchWriteItem");
   }
 
   async listTables<T>(schema: z.ZodSchema<T>): Promise<T> {
-    const request = this.buildRequest('listTables', {});
-    const result = await this.executeWithErrorHandling(request, 'listTables');
-    return this.validateResult(result, schema, 'listTables');
+    const request = this.buildRequest("listTables", {});
+    const result = await this.executeWithErrorHandling(request, "listTables");
+    return this.validateResult(result, schema, "listTables");
   }
 
   async describeTable<T>(table: string, schema: z.ZodSchema<T>): Promise<T> {
-    const request = this.buildRequest('describeTable', {
+    const request = this.buildRequest("describeTable", {
       TableName: table,
     });
-    const result = await this.executeWithErrorHandling(request, 'describeTable');
-    return this.validateResult(result, schema, 'describeTable');
+    const result = await this.executeWithErrorHandling(
+      request,
+      "describeTable",
+    );
+    return this.validateResult(result, schema, "describeTable");
   }
 
   async deleteTable(table: string): Promise<unknown> {
-    const request = this.buildRequest('deleteTable', {
+    const request = this.buildRequest("deleteTable", {
       TableName: table,
     });
-    return this.executeWithErrorHandling(request, 'deleteTable');
+    return this.executeWithErrorHandling(request, "deleteTable");
   }
 }

package/src/integrations/dynamodb/index.ts

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

package/src/integrations/dynamodb/types.ts

@@ -5,8 +5,8 @@
  * Parameters are serialized as JSON and passed directly to the AWS SDK.
  */
 
-import type { z } from 'zod';
-import type { BaseIntegrationClient } from '../../types.js';
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
 
 /**
  * DynamoDB AttributeValue type descriptor.
@@ -43,27 +43,28 @@ export type DynamoDBAttributeValue =
  *
  * @example
  * ```typescript
- * const db = ctx.dynamodb('Production DynamoDB');
+ * // Declare in api(): integrations: { db: dynamodb(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.db
  *
  * // PartiQL query with typed parameters
- * const users = await db.query(
+ * const users = await ctx.integrations.db.query(
  *   'SELECT * FROM users WHERE status = ?',
  *   z.array(z.object({ id: z.string(), name: z.string() })),
  *   [{ S: 'active' }]
  * );
  *
  * // Get item by key
- * const user = await db.getItem('users', { id: { S: '123' } }, UserSchema);
+ * const user = await ctx.integrations.db.getItem('users', { id: { S: '123' } }, UserSchema);
  *
  * // Put item
- * await db.putItem('users', {
+ * await ctx.integrations.db.putItem('users', {
  *   id: { S: '123' },
  *   name: { S: 'Alice' },
  *   age: { N: '30' },
  * });
  *
  * // Update item
- * await db.updateItem(
+ * await ctx.integrations.db.updateItem(
  *   'users',
  *   { id: { S: '123' } },
  *   'SET #n = :name',
@@ -72,10 +73,10 @@ export type DynamoDBAttributeValue =
  * );
  *
  * // Delete item
- * await db.deleteItem('users', { id: { S: '123' } });
+ * await ctx.integrations.db.deleteItem('users', { id: { S: '123' } });
  *
  * // Scan with filter
- * const active = await db.scan(
+ * const active = await ctx.integrations.db.scan(
  *   'users',
  *   UsersSchema,
  *   'status = :s',

package/src/integrations/elasticsearch/README.md

@@ -4,8 +4,8 @@ Search, index, and manage documents in Elasticsearch clusters.
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                               |
+| ----------------------------- | --------------------------------------------------------- |
 | `apiRequest(options, schema)` | Make any Elasticsearch API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Search, index, and manage documents in Elasticsearch clusters.
 ### Search Documents
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, elasticsearch } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_ELASTICSEARCH = "a1b2c3d4-5678-90ab-cdef-elastic00001";
@@ -42,6 +42,9 @@ const SearchResponseSchema = z.object({
 
 export default api({
   name: "ElasticsearchExample",
+  integrations: {
+    es: elasticsearch(PROD_ELASTICSEARCH),
+  },
   input: z.object({
     index: z.string(),
     query: z.string(),
@@ -49,16 +52,16 @@ export default api({
   }),
   output: z.object({
     total: z.number(),
-    hits: z.array(z.object({
-      id: z.string(),
-      score: z.number().nullable(),
-      source: z.record(z.unknown()),
-    })),
+    hits: z.array(
+      z.object({
+        id: z.string(),
+        score: z.number().nullable(),
+        source: z.record(z.unknown()),
+      }),
+    ),
   }),
   async run(ctx, { index, query, size }) {
-    const es = ctx.elasticsearch(PROD_ELASTICSEARCH);
-
-    const result = await es.apiRequest(
+    const result = await ctx.integrations.es.apiRequest(
       {
         method: "POST",
         path: `/${index}/_search`,
@@ -77,7 +80,7 @@ export default api({
           },
         },
       },
-      { response: SearchResponseSchema }
+      { response: SearchResponseSchema },
     );
 
     return {
@@ -108,7 +111,7 @@ const IndexResponseSchema = z.object({
 });
 
 // Index with auto-generated ID
-const result = await es.apiRequest(
+const result = await ctx.integrations.es.apiRequest(
   {
     method: "POST",
     path: `/products/_doc`,
@@ -120,13 +123,13 @@ const result = await es.apiRequest(
       created_at: new Date().toISOString(),
     },
   },
-  { response: IndexResponseSchema }
+  { response: IndexResponseSchema },
 );
 
 console.log(`Indexed document: ${result._id}`);
 
 // Index with specific ID
-const resultWithId = await es.apiRequest(
+const resultWithId = await ctx.integrations.es.apiRequest(
   {
     method: "PUT",
     path: `/products/_doc/product_123`,
@@ -135,7 +138,7 @@ const resultWithId = await es.apiRequest(
       price: 149.99,
     },
   },
-  { response: IndexResponseSchema }
+  { response: IndexResponseSchema },
 );
 ```
 
@@ -150,12 +153,12 @@ const GetResponseSchema = z.object({
   _source: z.record(z.unknown()),
 });
 
-const doc = await es.apiRequest(
+const doc = await ctx.integrations.es.apiRequest(
   {
     method: "GET",
     path: `/products/_doc/${documentId}`,
   },
-  { response: GetResponseSchema }
+  { response: GetResponseSchema },
 );
 
 if (doc.found) {
@@ -174,7 +177,7 @@ const UpdateResponseSchema = z.object({
 });
 
 // Partial update
-const result = await es.apiRequest(
+const result = await ctx.integrations.es.apiRequest(
   {
     method: "POST",
     path: `/products/_update/${documentId}`,
@@ -185,11 +188,11 @@ const result = await es.apiRequest(
       },
     },
   },
-  { response: UpdateResponseSchema }
+  { response: UpdateResponseSchema },
 );
 
 // Update with script
-const scriptResult = await es.apiRequest(
+const scriptResult = await ctx.integrations.es.apiRequest(
   {
     method: "POST",
     path: `/products/_update/${documentId}`,
@@ -200,7 +203,7 @@ const scriptResult = await es.apiRequest(
       },
     },
   },
-  { response: UpdateResponseSchema }
+  { response: UpdateResponseSchema },
 );
 ```
 
@@ -214,12 +217,12 @@ const DeleteResponseSchema = z.object({
   result: z.string(), // deleted, not_found
 });
 
-const result = await es.apiRequest(
+const result = await ctx.integrations.es.apiRequest(
   {
     method: "DELETE",
     path: `/products/_doc/${documentId}`,
   },
-  { response: DeleteResponseSchema }
+  { response: DeleteResponseSchema },
 );
 ```
 
@@ -231,42 +234,51 @@ const BulkResponseSchema = z.object({
   errors: z.boolean(),
   items: z.array(
     z.object({
-      index: z.object({
-        _index: z.string(),
-        _id: z.string(),
-        status: z.number(),
-        result: z.string().optional(),
-        error: z.object({
-          type: z.string(),
-          reason: z.string(),
-        }).optional(),
-      }).optional(),
-      delete: z.object({
-        _index: z.string(),
-        _id: z.string(),
-        status: z.number(),
-        result: z.string().optional(),
-      }).optional(),
-    })
+      index: z
+        .object({
+          _index: z.string(),
+          _id: z.string(),
+          status: z.number(),
+          result: z.string().optional(),
+          error: z
+            .object({
+              type: z.string(),
+              reason: z.string(),
+            })
+            .optional(),
+        })
+        .optional(),
+      delete: z
+        .object({
+          _index: z.string(),
+          _id: z.string(),
+          status: z.number(),
+          result: z.string().optional(),
+        })
+        .optional(),
+    }),
   ),
 });
 
 // Bulk index
-const result = await es.apiRequest(
+const result = await ctx.integrations.es.apiRequest(
   {
     method: "POST",
     path: "/_bulk",
     headers: {
       "Content-Type": "application/x-ndjson",
     },
-    body: [
-      { index: { _index: "products", _id: "1" } },
-      { name: "Product 1", price: 10 },
-      { index: { _index: "products", _id: "2" } },
-      { name: "Product 2", price: 20 },
-    ].map(JSON.stringify).join("\n") + "\n",
+    body:
+      [
+        { index: { _index: "products", _id: "1" } },
+        { name: "Product 1", price: 10 },
+        { index: { _index: "products", _id: "2" } },
+        { name: "Product 2", price: 20 },
+      ]
+        .map(JSON.stringify)
+        .join("\n") + "\n",
   },
-  { response: BulkResponseSchema }
+  { response: BulkResponseSchema },
 );
 
 if (result.errors) {
@@ -281,7 +293,7 @@ if (result.errors) {
 ### Aggregations
 
 ```typescript
-const result = await es.apiRequest(
+const result = await ctx.integrations.es.apiRequest(
   {
     method: "POST",
     path: `/products/_search`,
@@ -302,17 +314,13 @@ const result = await es.apiRequest(
         price_ranges: {
           range: {
             field: "price",
-            ranges: [
-              { to: 50 },
-              { from: 50, to: 100 },
-              { from: 100 },
-            ],
+            ranges: [{ to: 50 }, { from: 50, to: 100 }, { from: 100 }],
           },
         },
       },
     },
   },
-  { response: SearchResponseSchema }
+  { response: SearchResponseSchema },
 );
 
 // Access aggregation results
@@ -329,7 +337,7 @@ const CreateIndexResponseSchema = z.object({
   index: z.string(),
 });
 
-const result = await es.apiRequest(
+const result = await ctx.integrations.es.apiRequest(
   {
     method: "PUT",
     path: "/products",
@@ -350,7 +358,7 @@ const result = await es.apiRequest(
       },
     },
   },
-  { response: CreateIndexResponseSchema }
+  { response: CreateIndexResponseSchema },
 );
 ```
 
@@ -358,12 +366,12 @@ const result = await es.apiRequest(
 
 ```typescript
 try {
-  await es.apiRequest(
+  await ctx.integrations.es.apiRequest(
     {
       method: "HEAD",
       path: "/products",
     },
-    { response: z.void() }
+    { response: z.void() },
   );
   console.log("Index exists");
 } catch (error) {
@@ -381,7 +389,7 @@ await es.search({ ... });
 await es.index({ ... });
 
 // CORRECT - Use apiRequest
-await es.apiRequest(
+await ctx.integrations.es.apiRequest(
   { method: "POST", path: "/products/_search", body: { ... } },
   { response: SearchResponseSchema }
 );
@@ -487,19 +495,13 @@ Bulk operations require NDJSON format:
 
 ```typescript
 // WRONG - Regular JSON array
-const body = [
-  { index: { _index: "products" } },
-  { name: "Product" },
-];
+const body = [{ index: { _index: "products" } }, { name: "Product" }];
 
 // CORRECT - Newline-delimited JSON
 const body = '{"index":{"_index":"products"}}\n{"name":"Product"}\n';
 
 // Or build programmatically
-const operations = [
-  { index: { _index: "products" } },
-  { name: "Product" },
-];
+const operations = [{ index: { _index: "products" } }, { name: "Product" }];
 const body = operations.map(JSON.stringify).join("\n") + "\n";
 ```
 
@@ -573,7 +575,7 @@ const body = {
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await es.apiRequest(
+  const result = await ctx.integrations.es.apiRequest(
     { method: "POST", path: "/products/_search", body: { ... } },
     { response: SearchResponseSchema }
   );

package/src/integrations/elasticsearch/client.ts

@@ -5,8 +5,8 @@
  * ElasticSearch integrations use the REST API Integration plugin under the hood.
  */
 
-import { RestApiIntegrationClient } from '../base/index.js';
-import type { ElasticSearchClient } from './types.js';
+import { RestApiIntegrationClient } from "../base/index.js";
+import type { ElasticSearchClient } from "./types.js";
 
 /**
  * Internal implementation of ElasticSearchClient.
@@ -16,6 +16,8 @@ import type { ElasticSearchClient } from './types.js';
  * ElasticSearch API calls. At runtime, the orchestrator handles authentication
  * and API request execution.
  */
-export class ElasticSearchClientImpl extends RestApiIntegrationClient implements ElasticSearchClient {
+export class ElasticSearchClientImpl
+  extends RestApiIntegrationClient
+  implements ElasticSearchClient {
   // Inherits: name, pluginId, config, executeQuery, apiRequest()
 }

package/src/integrations/elasticsearch/index.ts

@@ -1,2 +1,2 @@
-export { ElasticSearchClientImpl } from './client.js';
-export type { ElasticSearchClient } from './types.js';
+export { ElasticSearchClientImpl } from "./client.js";
+export type { ElasticSearchClient } from "./types.js";

package/src/integrations/elasticsearch/types.ts

@@ -2,8 +2,8 @@
  * ElasticSearch client types.
  */
 
-import type { BaseIntegrationClient } from '../../types.js';
-import type { SupportsApiRequest } from '../base/index.js';
+import type { BaseIntegrationClient } from "../../types.js";
+import type { SupportsApiRequest } from "../base/index.js";
 
 /**
  * ElasticSearch client for API interactions.
@@ -13,7 +13,8 @@ import type { SupportsApiRequest } from '../base/index.js';
  *
  * @example
  * ```typescript
- * const elasticsearch = ctx.elasticsearch('My ElasticSearch');
+ * // Declare in api(): integrations: { elasticsearch: elasticsearch(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.elasticsearch
  *
  * // Make API requests
  * const ResponseSchema = z.object({
@@ -29,6 +30,7 @@ import type { SupportsApiRequest } from '../base/index.js';
  * );
  * ```
  */
-export interface ElasticSearchClient extends BaseIntegrationClient, SupportsApiRequest {
+export interface ElasticSearchClient
+  extends BaseIntegrationClient, SupportsApiRequest {
   // apiRequest() method inherited from SupportsApiRequest
 }