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

package/src/integrations/dropbox/README.md

@@ -4,8 +4,8 @@ Upload, download, and manage files in Dropbox.
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                         |
+| ----------------------------- | --------------------------------------------------- |
 | `apiRequest(options, schema)` | Make any Dropbox API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Upload, download, and manage files in Dropbox.
 ### List Files in a Folder
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, dropbox } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_DROPBOX = "a1b2c3d4-5678-90ab-cdef-dropbox00001";
@@ -38,21 +38,24 @@ const ListFolderResponseSchema = z.object({
 
 export default api({
   name: "DropboxExample",
+  integrations: {
+    dropbox: dropbox(PROD_DROPBOX),
+  },
   input: z.object({
     path: z.string().default(""),
   }),
   output: z.object({
-    files: z.array(z.object({
-      name: z.string(),
-      path: z.string(),
-      type: z.string(),
-      size: z.number().optional(),
-    })),
+    files: z.array(
+      z.object({
+        name: z.string(),
+        path: z.string(),
+        type: z.string(),
+        size: z.number().optional(),
+      }),
+    ),
   }),
   async run(ctx, { path }) {
-    const dropbox = ctx.dropbox(PROD_DROPBOX);
-
-    const result = await dropbox.apiRequest(
+    const result = await ctx.integrations.dropbox.apiRequest(
       {
         method: "POST",
         path: "/2/files/list_folder",
@@ -64,7 +67,7 @@ export default api({
           limit: 100,
         },
       },
-      { response: ListFolderResponseSchema }
+      { response: ListFolderResponseSchema },
     );
 
     return {
@@ -82,7 +85,7 @@ export default api({
 ### Get File Metadata
 
 ```typescript
-const metadata = await dropbox.apiRequest(
+const metadata = await ctx.integrations.dropbox.apiRequest(
   {
     method: "POST",
     path: "/2/files/get_metadata",
@@ -93,7 +96,7 @@ const metadata = await dropbox.apiRequest(
       include_has_explicit_shared_members: true,
     },
   },
-  { response: FileMetadataSchema }
+  { response: FileMetadataSchema },
 );
 
 console.log(`File: ${metadata.name}, Size: ${metadata.size} bytes`);
@@ -106,7 +109,7 @@ const DownloadResponseSchema = z.object({
   content: z.string(), // Base64 encoded or raw content
 });
 
-const result = await dropbox.apiRequest(
+const result = await ctx.integrations.dropbox.apiRequest(
   {
     method: "POST",
     path: "/2/files/download",
@@ -116,7 +119,7 @@ const result = await dropbox.apiRequest(
       }),
     },
   },
-  { response: DownloadResponseSchema }
+  { response: DownloadResponseSchema },
 );
 ```
 
@@ -134,7 +137,7 @@ const UploadResponseSchema = z.object({
   content_hash: z.string(),
 });
 
-const result = await dropbox.apiRequest(
+const result = await ctx.integrations.dropbox.apiRequest(
   {
     method: "POST",
     path: "/2/files/upload",
@@ -149,7 +152,7 @@ const result = await dropbox.apiRequest(
     },
     body: "File content here",
   },
-  { response: UploadResponseSchema }
+  { response: UploadResponseSchema },
 );
 
 console.log(`Uploaded: ${result.path_display}`);
@@ -167,7 +170,7 @@ const CreateFolderResponseSchema = z.object({
   }),
 });
 
-const result = await dropbox.apiRequest(
+const result = await ctx.integrations.dropbox.apiRequest(
   {
     method: "POST",
     path: "/2/files/create_folder_v2",
@@ -176,7 +179,7 @@ const result = await dropbox.apiRequest(
       autorename: false,
     },
   },
-  { response: CreateFolderResponseSchema }
+  { response: CreateFolderResponseSchema },
 );
 ```
 
@@ -187,7 +190,7 @@ const MoveResponseSchema = z.object({
   metadata: FileMetadataSchema,
 });
 
-const result = await dropbox.apiRequest(
+const result = await ctx.integrations.dropbox.apiRequest(
   {
     method: "POST",
     path: "/2/files/move_v2",
@@ -198,7 +201,7 @@ const result = await dropbox.apiRequest(
       allow_ownership_transfer: false,
     },
   },
-  { response: MoveResponseSchema }
+  { response: MoveResponseSchema },
 );
 ```
 
@@ -209,7 +212,7 @@ const CopyResponseSchema = z.object({
   metadata: FileMetadataSchema,
 });
 
-const result = await dropbox.apiRequest(
+const result = await ctx.integrations.dropbox.apiRequest(
   {
     method: "POST",
     path: "/2/files/copy_v2",
@@ -219,7 +222,7 @@ const result = await dropbox.apiRequest(
       autorename: true,
     },
   },
-  { response: CopyResponseSchema }
+  { response: CopyResponseSchema },
 );
 ```
 
@@ -230,7 +233,7 @@ const DeleteResponseSchema = z.object({
   metadata: FileMetadataSchema,
 });
 
-const result = await dropbox.apiRequest(
+const result = await ctx.integrations.dropbox.apiRequest(
   {
     method: "POST",
     path: "/2/files/delete_v2",
@@ -238,7 +241,7 @@ const result = await dropbox.apiRequest(
       path: "/Documents/file-to-delete.txt",
     },
   },
-  { response: DeleteResponseSchema }
+  { response: DeleteResponseSchema },
 );
 ```
 
@@ -259,7 +262,7 @@ const SearchResponseSchema = z.object({
   cursor: z.string().optional(),
 });
 
-const result = await dropbox.apiRequest(
+const result = await ctx.integrations.dropbox.apiRequest(
   {
     method: "POST",
     path: "/2/files/search_v2",
@@ -273,7 +276,7 @@ const result = await dropbox.apiRequest(
       },
     },
   },
-  { response: SearchResponseSchema }
+  { response: SearchResponseSchema },
 );
 
 result.matches.forEach((match) => {
@@ -294,7 +297,7 @@ const SharedLinkSchema = z.object({
   }),
 });
 
-const result = await dropbox.apiRequest(
+const result = await ctx.integrations.dropbox.apiRequest(
   {
     method: "POST",
     path: "/2/sharing/create_shared_link_with_settings",
@@ -307,7 +310,7 @@ const result = await dropbox.apiRequest(
       },
     },
   },
-  { response: SharedLinkSchema }
+  { response: SharedLinkSchema },
 );
 
 console.log(`Share URL: ${result.url}`);
@@ -323,7 +326,7 @@ await dropbox.listFolder({ ... });
 await dropbox.uploadFile({ ... });
 
 // CORRECT - Use apiRequest
-await dropbox.apiRequest(
+await ctx.integrations.dropbox.apiRequest(
   { method: "POST", path: "/2/files/list_folder", body: { ... } },
   { response: ListFolderResponseSchema }
 );
@@ -335,13 +338,13 @@ Unlike REST conventions, Dropbox uses POST for most read operations:
 
 ```typescript
 // WRONG - Using GET
-await dropbox.apiRequest(
+await ctx.integrations.dropbox.apiRequest(
   { method: "GET", path: "/2/files/list_folder", ... },
   { response: ListFolderResponseSchema }
 );
 
 // CORRECT - Use POST
-await dropbox.apiRequest(
+await ctx.integrations.dropbox.apiRequest(
   { method: "POST", path: "/2/files/list_folder", body: { ... } },
   { response: ListFolderResponseSchema }
 );
@@ -418,26 +421,26 @@ async function listAllFiles(dropbox: DropboxClient, path: string) {
   const allEntries: FileMetadata[] = [];
 
   // Initial request
-  let result = await dropbox.apiRequest(
+  let result = await ctx.integrations.dropbox.apiRequest(
     {
       method: "POST",
       path: "/2/files/list_folder",
       body: { path },
     },
-    { response: ListFolderResponseSchema }
+    { response: ListFolderResponseSchema },
   );
 
   allEntries.push(...result.entries);
 
   // Continue with cursor
   while (result.has_more) {
-    result = await dropbox.apiRequest(
+    result = await ctx.integrations.dropbox.apiRequest(
       {
         method: "POST",
         path: "/2/files/list_folder/continue",
         body: { cursor: result.cursor },
       },
-      { response: ListFolderResponseSchema }
+      { response: ListFolderResponseSchema },
     );
     allEntries.push(...result.entries);
   }
@@ -484,7 +487,7 @@ if (file1.path_lower === file2.path_lower) {
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await dropbox.apiRequest(
+  const result = await ctx.integrations.dropbox.apiRequest(
     { method: "POST", path: "/2/files/list_folder", body: { ... } },
     { response: ListFolderResponseSchema }
   );

package/src/integrations/dropbox/client.ts

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

package/src/integrations/dropbox/index.ts

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

package/src/integrations/dropbox/types.ts

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

package/src/integrations/dynamodb/README.md

@@ -4,31 +4,47 @@ Execute operations against Amazon DynamoDB with full type safety and runtime val
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
-| `query(statement, schema, params?)` | Execute a PartiQL statement |
-| `getItem(table, key, schema)` | Get an item by key |
-| `putItem(table, item)` | Insert or replace an item |
-| `updateItem(table, key, expr, values, names?)` | Update an existing item |
-| `deleteItem(table, key)` | Delete an item by key |
-| `scan(table, schema, filter?, values?, names?)` | Scan a table |
-| `queryTable(table, keyExpr, values, schema, names?)` | Query by key condition |
-| `batchWriteItem(requestItems)` | Batch write multiple items |
-| `listTables(schema)` | List all tables |
-| `describeTable(table, schema)` | Describe a table's structure |
-| `deleteTable(table)` | Delete a table |
+| Method                                               | Description                  |
+| ---------------------------------------------------- | ---------------------------- |
+| `query(statement, schema, params?)`                  | Execute a PartiQL statement  |
+| `getItem(table, key, schema)`                        | Get an item by key           |
+| `putItem(table, item)`                               | Insert or replace an item    |
+| `updateItem(table, key, expr, values, names?)`       | Update an existing item      |
+| `deleteItem(table, key)`                             | Delete an item by key        |
+| `scan(table, schema, filter?, values?, names?)`      | Scan a table                 |
+| `queryTable(table, keyExpr, values, schema, names?)` | Query by key condition       |
+| `batchWriteItem(requestItems)`                       | Batch write multiple items   |
+| `listTables(schema)`                                 | List all tables              |
+| `describeTable(table, schema)`                       | Describe a table's structure |
+| `deleteTable(table)`                                 | Delete a table               |
 
 ## DynamoDB AttributeValue Format
 
 All values use DynamoDB's native type descriptors:
 
 ```typescript
-{ S: "hello" }       // String
-{ N: "42" }          // Number (always a string)
-{ BOOL: true }       // Boolean
-{ NULL: true }       // Null
-{ L: [{ S: "a" }] } // List
-{ M: { k: { S: "v" } } } // Map
+{
+  S: "hello";
+} // String
+{
+  N: "42";
+} // Number (always a string)
+{
+  BOOL: true;
+} // Boolean
+{
+  NULL: true;
+} // Null
+{
+  L: [{ S: "a" }];
+} // List
+{
+  M: {
+    k: {
+      S: "v";
+    }
+  }
+} // Map
 ```
 
 ## Usage
@@ -36,19 +52,24 @@ All values use DynamoDB's native type descriptors:
 ### PartiQL Query
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, dynamodb } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_DYNAMODB = "a1b2c3d4-5678-90ab-cdef-dynamodb0001";
 
-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({
   name: "DynamoDBExample",
+  integrations: {
+    dynamodb: dynamodb(PROD_DYNAMODB),
+  },
   input: z.object({
     status: z.string(),
   }),
@@ -56,12 +77,10 @@ export default api({
     users: UserSchema,
   }),
   async run(ctx, { status }) {
-    const dynamodb = ctx.dynamodb(PROD_DYNAMODB);
-
-    const users = await dynamodb.query(
+    const users = await ctx.integrations.dynamodb.query(
       "SELECT * FROM users WHERE status = ?",
       UserSchema,
-      [{ S: status }]
+      [{ S: status }],
     );
 
     return { users };
@@ -72,17 +91,17 @@ export default api({
 ### Get Item by Key
 
 ```typescript
-const user = await dynamodb.getItem(
+const user = await ctx.integrations.dynamodb.getItem(
   "users",
   { id: { S: "user-123" } },
-  z.object({ id: z.string(), name: z.string(), email: z.string() })
+  z.object({ id: z.string(), name: z.string(), email: z.string() }),
 );
 ```
 
 ### Put Item
 
 ```typescript
-await dynamodb.putItem("users", {
+await ctx.integrations.dynamodb.putItem("users", {
   id: { S: "user-456" },
   name: { S: "John Doe" },
   email: { S: "john@example.com" },
@@ -93,7 +112,7 @@ await dynamodb.putItem("users", {
 ### Update Item
 
 ```typescript
-await dynamodb.updateItem(
+await ctx.integrations.dynamodb.updateItem(
   "users",
   { id: { S: "user-123" } },
   "SET #n = :name, email = :email",
@@ -101,49 +120,49 @@ await dynamodb.updateItem(
     ":name": { S: "Jane Doe" },
     ":email": { S: "jane@example.com" },
   },
-  { "#n": "name" }  // name is a reserved word in DynamoDB
+  { "#n": "name" }, // name is a reserved word in DynamoDB
 );
 ```
 
 ### Delete Item
 
 ```typescript
-await dynamodb.deleteItem("users", { id: { S: "user-123" } });
+await ctx.integrations.dynamodb.deleteItem("users", { id: { S: "user-123" } });
 ```
 
 ### Scan Table
 
 ```typescript
 // Full scan
-const allUsers = await dynamodb.scan(
+const allUsers = await ctx.integrations.dynamodb.scan(
   "users",
-  z.array(z.object({ id: z.string(), name: z.string() }))
+  z.array(z.object({ id: z.string(), name: z.string() })),
 );
 
 // With filter expression
-const activeUsers = await dynamodb.scan(
+const activeUsers = await ctx.integrations.dynamodb.scan(
   "users",
   z.array(z.object({ id: z.string(), name: z.string() })),
   "status = :s",
-  { ":s": { S: "active" } }
+  { ":s": { S: "active" } },
 );
 ```
 
 ### Query Table by Key Condition
 
 ```typescript
-const userOrders = await dynamodb.queryTable(
+const userOrders = await ctx.integrations.dynamodb.queryTable(
   "orders",
   "userId = :uid",
   { ":uid": { S: "user-123" } },
-  z.array(z.object({ orderId: z.string(), total: z.number() }))
+  z.array(z.object({ orderId: z.string(), total: z.number() })),
 );
 ```
 
 ### Batch Write Items
 
 ```typescript
-await dynamodb.batchWriteItem({
+await ctx.integrations.dynamodb.batchWriteItem({
   users: [
     { PutRequest: { Item: { id: { S: "user-1" }, name: { S: "Alice" } } } },
     { PutRequest: { Item: { id: { S: "user-2" }, name: { S: "Bob" } } } },
@@ -155,33 +174,35 @@ await dynamodb.batchWriteItem({
 ### List Tables
 
 ```typescript
-const tables = await dynamodb.listTables(
-  z.object({ TableNames: z.array(z.string()) })
+const tables = await ctx.integrations.dynamodb.listTables(
+  z.object({ TableNames: z.array(z.string()) }),
 );
 ```
 
 ### Describe Table
 
 ```typescript
-const description = await dynamodb.describeTable(
+const description = await ctx.integrations.dynamodb.describeTable(
   "users",
   z.object({
     Table: z.object({
       TableName: z.string(),
-      KeySchema: z.array(z.object({
-        AttributeName: z.string(),
-        KeyType: z.string(),
-      })),
+      KeySchema: z.array(
+        z.object({
+          AttributeName: z.string(),
+          KeyType: z.string(),
+        }),
+      ),
       ItemCount: z.number(),
     }),
-  })
+  }),
 );
 ```
 
 ### Delete Table
 
 ```typescript
-await dynamodb.deleteTable("temp-table");
+await ctx.integrations.dynamodb.deleteTable("temp-table");
 ```
 
 ## Common Pitfalls
@@ -192,16 +213,16 @@ Always use `?` placeholders with typed parameters:
 
 ```typescript
 // CORRECT - parameterized with AttributeValue types
-await dynamodb.query(
+await ctx.integrations.dynamodb.query(
   "SELECT * FROM users WHERE id = ?",
   schema,
-  [{ S: userId }]
+  [{ S: userId }],
 );
 
 // AVOID - string interpolation (potential injection)
-await dynamodb.query(
+await ctx.integrations.dynamodb.query(
   `SELECT * FROM users WHERE id = '${userId}'`,
-  schema
+  schema,
 );
 ```
 
@@ -211,22 +232,33 @@ DynamoDB represents numbers as strings in the wire format:
 
 ```typescript
 // CORRECT
-{ age: { N: "30" } }
+{
+  age: {
+    N: "30";
+  }
+}
 
 // WRONG - N must be a string
-{ age: { N: 30 } }
+{
+  age: {
+    N: 30;
+  }
+}
 ```
 
 ## Error Handling
 
 ```typescript
-import { RestApiValidationError, IntegrationError } from "@superblocksteam/sdk-api";
+import {
+  RestApiValidationError,
+  IntegrationError,
+} from "@superblocksteam/sdk-api";
 
 try {
-  const users = await dynamodb.query(
+  const users = await ctx.integrations.dynamodb.query(
     "SELECT * FROM users WHERE status = ?",
     UserSchema,
-    [{ S: "active" }]
+    [{ S: "active" }],
   );
 } catch (error) {
   if (error instanceof RestApiValidationError) {