@superblocksteam/sdk-api 2.0.105-next.0 → 2.0.105-next.2

package/README.md

@@ -183,7 +183,7 @@ interface ExecuteApiRequest {
   executeQuery: (
     integrationId: string,
     request: Record<string, unknown>, // Plugin-specific request matching protobuf schema
-    bindings?: Record<string, unknown>, // For language plugins (Python/JavaScript)
+    bindings?: Record<string, unknown>, // For language plugins (JavaScript)
   ) => Promise<unknown>;
 }
 ```
@@ -276,6 +276,42 @@ export default api({
 });
 ```
 
+### Export style (default vs named exports)
+
+**Default export** — one API per file. **Named exports** — several `api({ ... })` values in one module; import them by name into `server/apis/index.ts`. `useApi("X")` matches the **key** on the registry object; align `api({ name: "X" })` with that when practical.
+
+```typescript
+// server/apis/users/pair.ts
+import { api, z } from "@superblocksteam/sdk-api";
+
+export const ListProfiles = api({
+  name: "ListProfiles",
+  input: z.object({ orgId: z.string() }),
+  output: z.object({ profiles: z.array(z.object({ id: z.string() })) }),
+  async run() {
+    return { profiles: [] };
+  },
+});
+
+export const UpdateProfile = api({
+  name: "UpdateProfile",
+  input: z.object({ userId: z.string() }),
+  output: z.object({ ok: z.literal(true) }),
+  async run() {
+    return { ok: true as const };
+  },
+});
+```
+
+```typescript
+// server/apis/index.ts
+import { ListProfiles, UpdateProfile } from "./users/pair.js";
+
+const apis = { ListProfiles, UpdateProfile } as const;
+export default apis;
+export type ApiRegistry = typeof apis;
+```
+
 ## API Reference
 
 ### `api(config)`
@@ -284,13 +320,14 @@ Defines a TypeScript-based API with input/output validation. Returns a complete
 
 #### Required Fields
 
-| Field          | Type                              | Description                                    |
-| -------------- | --------------------------------- | ---------------------------------------------- |
-| `name`         | `string`                          | **Required.** Unique identifier for the API    |
-| `input`        | `z.ZodType`                       | **Required.** Zod schema for input validation  |
-| `output`       | `z.ZodType`                       | **Required.** Zod schema for output validation |
-| `run`          | `(ctx, input) => Promise<Output>` | **Required.** The implementation function      |
-| `integrations` | `Record<string, IntegrationRef>`  | Optional. Integration declarations for the API |
+| Field          | Type                              | Description                                                                                                                                            |
+| -------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `name`         | `string`                          | **Required.** Unique identifier for the API                                                                                                            |
+| `description`  | `string`                          | Optional. Plain-language summary of what this API does and which integrations it uses. Auto-generated by the AI agent when creating or editing an API. |
+| `input`        | `z.ZodType`                       | **Required.** Zod schema for input validation                                                                                                          |
+| `output`       | `z.ZodType`                       | **Required.** Zod schema for output validation                                                                                                         |
+| `run`          | `(ctx, input) => Promise<Output>` | **Required.** The implementation function                                                                                                              |
+| `integrations` | `Record<string, IntegrationRef>`  | Optional. Integration declarations for the API                                                                                                         |
 
 ```typescript
 import { api, z } from "@superblocksteam/sdk-api";
@@ -340,7 +377,7 @@ async run(ctx, { userId, options }) {
 Access typed integration clients via the **name (key)** you declared in the API config: `ctx.integrations.<name>`. For example, if you declared `integrations: { db: postgres(...), notifier: slack(...) }`, use `ctx.integrations.db` and `ctx.integrations.notifier` in your `run` function. Integrations must be declared upfront to enable type-safe access and pre-authentication.
 
 ```typescript
-import { api, z, postgres, slack, openai, anthropic, stripe, github, notion, python } from "@superblocksteam/sdk-api";
+import { api, z, postgres, slack, openai, anthropic, stripe, github, notion } from "@superblocksteam/sdk-api";
 
 // Integration IDs from the integrations panel - store in constants
 const PROD_POSTGRES = "a1b2c3d4-5678-90ab-cdef-ghijklmnopqr";
@@ -350,7 +387,6 @@ const PROD_ANTHROPIC = "d4e5f6g7-8901-23ab-cdef-ghijklmnopqr";
 const PROD_STRIPE = "e5f6g7h8-9012-34ab-cdef-ghijklmnopqr";
 const PROD_GITHUB = "f6g7h8i9-0123-45ab-cdef-ghijklmnopqr";
 const PROD_NOTION = "g7h8i9j0-1234-56ab-cdef-ghijklmnopqr";
-const PYTHON_RUNTIME = "h8i9j0k1-2345-67ab-cdef-ghijklmnopqr";
 
 export default api({
   name: "ProcessUserWorkflow",
@@ -375,9 +411,6 @@ export default api({
 
     // Productivity
     wiki: notion(PROD_NOTION),
-
-    // Code Execution
-    runtime: python(PYTHON_RUNTIME),
   },
 
   input: z.object({ userId: z.string() }),
@@ -394,6 +427,22 @@ export default api({
 });
 ```
 
+#### `ctx.user`
+
+Access the current user's identity (from the Superblocks JWT). This is the server-side equivalent of the `Global` object available in the frontend.
+
+```typescript
+async run(ctx, input) {
+  const userId = ctx.user.userId;
+  const email = ctx.user.email;       // may be undefined
+  const name = ctx.user.name;         // may be undefined
+  const groups = ctx.user.groups;     // readonly string[]
+  const claims = ctx.user.customClaims; // custom JWT claims
+
+  ctx.log.info('Request from user', { userId, email });
+}
+```
+
 #### `ctx.log`
 
 Structured logging utilities.
@@ -415,48 +464,74 @@ async run(ctx, { userId }) {
 
 #### Method Availability by Client
 
-| Client                             | Available Methods                                                              | Notes                                                              |
-| ---------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
-| **PostgresClient**                 | `query<T>(sql, schema, params?)`, `execute(sql, params?)`                      | Schema parameter is REQUIRED for query()                           |
-| **SnowflakeClient**                | `query<T>(sql, schema, params?)`, `execute(sql, params?)`                      | Schema parameter is REQUIRED for query()                           |
-| **PythonClient**                   | `run<T>(code, schema, bindings?)`                                              | Schema parameter is REQUIRED, bindings via {{}} syntax             |
-| **AirtableClient**                 | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **AnthropicClient**                | `apiRequest(options, schema)`                                                  | Claude AI models                                                   |
-| **AsanaClient**                    | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **BitbucketClient**                | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **BoxClient**                      | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **CircleCIClient**                 | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **CohereClient**                   | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **ConfluenceClient**               | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **DatadogClient**                  | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **DropboxClient**                  | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **ElasticSearchClient**            | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **FireworksClient**                | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **FrontClient**                    | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **GeminiClient**                   | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **GitHubClient**                   | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest - no createIssue, etc.                     |
-| **GoogleAnalyticsClient**          | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **GoogleDriveClient**              | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **GraphQLClient**                  | `query(query, variables?, schema?)`, `mutation(mutation, variables?, schema?)` | GraphQL-specific methods                                           |
-| **GroqClient**                     | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **HubSpotClient**                  | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **IntercomClient**                 | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **JiraClient**                     | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **LaunchDarklyClient**             | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **MistralClient**                  | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **NotionClient**                   | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest - no queryDatabase, etc.                   |
-| **OpenAIClient**                   | `apiRequest(options, schema)`                                                  | GPT AI models                                                      |
-| **PagerDutyClient**                | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **PerplexityClient**               | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **SegmentClient**                  | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **SendGridClient**                 | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **SlackClient**                    | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest - no specialized methods                   |
-| **StabilityAIClient**              | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **StripeClient**                   | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest - no createCustomer, etc.                  |
-| **TwilioClient**                   | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **ZendeskClient**                  | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **ZoomClient**                     | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                            |
-| **RestApiIntegrationPluginClient** | `apiRequest(options, schema)`                                                  | Generic REST API Integration - works with any configured HTTP API. |
+| Client                             | Available Methods                                                                                                                                                                                                                                                               | Notes                                                              |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| **PostgresClient**                 | `query<T>(sql, schema, params?)`, `execute(sql, params?)`                                                                                                                                                                                                                       | Schema parameter is REQUIRED for query()                           |
+| **SnowflakeClient**                | `query<T>(sql, schema, params?)`, `execute(sql, params?)`                                                                                                                                                                                                                       | Schema parameter is REQUIRED for query()                           |
+| **AirtableClient**                 | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **AnthropicClient**                | `apiRequest(options, schema)`                                                                                                                                                                                                                                                   | Claude AI models (see [Streaming note](#streaming--sse))           |
+| **AsanaClient**                    | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **BitbucketClient**                | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **BoxClient**                      | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **CircleCIClient**                 | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **CohereClient**                   | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **ConfluenceClient**               | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **DatadogClient**                  | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **DropboxClient**                  | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **ElasticSearchClient**            | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **FireworksClient**                | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **FrontClient**                    | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **GeminiClient**                   | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **GitHubClient**                   | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest - no createIssue, etc.                     |
+| **GoogleAnalyticsClient**          | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **GoogleDriveClient**              | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **GraphQLClient**                  | `query<T>(query, schema, variables?, metadata?)`, `mutation<T>(mutation, schema, variables?, metadata?)`                                                                                                                                                                        | GraphQL-specific methods                                           |
+| **GroqClient**                     | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **HubSpotClient**                  | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **IntercomClient**                 | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **JiraClient**                     | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **LaunchDarklyClient**             | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **MistralClient**                  | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **NotionClient**                   | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest - no queryDatabase, etc.                   |
+| **OpenAIClient**                   | `apiRequest(options, schema)`                                                                                                                                                                                                                                                   | GPT AI models (see [Streaming note](#streaming--sse))              |
+| **PagerDutyClient**                | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **PerplexityClient**               | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **SegmentClient**                  | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **SendGridClient**                 | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **SlackClient**                    | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest - no specialized methods                   |
+| **StabilityAIClient**              | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **StripeClient**                   | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest - no createCustomer, etc.                  |
+| **TwilioClient**                   | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **ZendeskClient**                  | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **ZoomClient**                     | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | ONLY generic apiRequest                                            |
+| **MySQLClient**                    | `query<T>(sql, schema, params?)`, `execute(sql, params?)`                                                                                                                                                                                                                       | Schema parameter is REQUIRED for query()                           |
+| **MariaDBClient**                  | `query<T>(sql, schema, params?)`, `execute(sql, params?)`                                                                                                                                                                                                                       | Schema parameter is REQUIRED for query()                           |
+| **MSSQLClient**                    | `query<T>(sql, schema, params?)`, `execute(sql, params?)`                                                                                                                                                                                                                       | Uses `@PARAM_1` placeholder syntax                                 |
+| **CockroachDBClient**              | `query<T>(sql, schema, params?)`, `execute(sql, params?)`                                                                                                                                                                                                                       | Schema parameter is REQUIRED for query()                           |
+| **OracleDBClient**                 | `query<T>(sql, schema, params?)`, `execute(sql, params?)`                                                                                                                                                                                                                       | Uses `:PARAM_1` placeholder syntax                                 |
+| **RedshiftClient**                 | `query<T>(sql, schema, params?)`, `execute(sql, params?)`                                                                                                                                                                                                                       | Schema parameter is REQUIRED for query()                           |
+| **AthenaClient**                   | `query<T>(sql, schema, params?)`, `execute(sql, params?)`                                                                                                                                                                                                                       | Uses `?` placeholder syntax                                        |
+| **DatabricksClient**               | `query<T>(sql, schema, params?)`, `execute(sql, params?)`                                                                                                                                                                                                                       | Uses `:param` placeholder syntax                                   |
+| **BigQueryClient**                 | `query<T>(sql, schema, params?)`, `execute(sql, params?)`                                                                                                                                                                                                                       | Uses `@param` placeholder syntax                                   |
+| **LakebaseClient**                 | `query<T>(sql, schema, params?)`, `execute(sql, params?)`                                                                                                                                                                                                                       | Schema parameter is REQUIRED for query()                           |
+| **SnowflakePostgresClient**        | `query<T>(sql, schema, params?)`, `execute(sql, params?)`                                                                                                                                                                                                                       | Schema parameter is REQUIRED for query()                           |
+| **MongoDBClient**                  | `run(collection, action, schema, params, metadata?)`                                                                                                                                                                                                                            | 13 actions (find, insertOne, updateOne, etc.)                      |
+| **DynamoDBClient**                 | `query<T>(sql, schema)`, `getItem(params, schema)`, `putItem(params)`, `updateItem(params)`, `deleteItem(params)`, `scan(params, schema)`, `queryTable(params, schema)`, `batchWriteItem(params)`, `listTables(schema)`, `describeTable(params, schema)`, `deleteTable(params)` | 11 methods — supports both PartiQL and native CRUD                 |
+| **CosmosDBClient**                 | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | Azure Cosmos DB — use custom headers for queries                   |
+| **CouchbaseClient**                | `query<T>(bucket, sql, schema, params?)`, `insert(key, value, identifier)`, `get<T>(key, schema, identifier)`, `remove(key, identifier)`                                                                                                                                        | N1QL queries + key-value operations                                |
+| **RedisClient**                    | `command(command, schema, metadata?)`                                                                                                                                                                                                                                           | Execute raw Redis commands                                         |
+| **S3Client**                       | `listBuckets(schema)`, `listObjects(params, schema)`, `getObject(params, schema)`, `deleteObject(params)`, `uploadObject(params)`, `uploadMultipleObjects(params)`, `generatePresignedUrl(params, schema)`                                                                      | 7 methods for AWS S3 bucket/object operations                      |
+| **GCSClient**                      | `listBuckets(schema)`, `listObjects(params, schema)`, `getObject(params, schema)`, `deleteObject(params)`, `uploadObject(params)`, `uploadMultipleObjects(params)`, `generateSignedUrl(params, schema)`                                                                         | 7 methods for Google Cloud Storage operations                      |
+| **SalesforceClient**               | `query<T>(soql, schema)`, `create(params)`, `read(params, schema)`, `update(params)`, `remove(params)`, `bulkCreate(params)`, `bulkUpdate(params)`, `bulkDelete(params)`, `bulkUpsert(params)`                                                                                  | 9 methods — SOQL queries + CRUD + bulk operations                  |
+| **KinesisClient**                  | `putRecord(params)`, `getRecords(params)`                                                                                                                                                                                                                                       | AWS Kinesis stream put/get                                         |
+| **GoogleSheetsClient**             | `run(action, schema, params, metadata?)`                                                                                                                                                                                                                                        | 6 actions (READ_SPREADSHEET, APPEND, etc.)                         |
+| **KafkaClient**                    | `consume(schema, params, metadata?)`, `produce(schema, params, metadata?)`                                                                                                                                                                                                      | Kafka message consumption and production                           |
+| **ConfluentClient**                | `consume(schema, params, metadata?)`, `produce(schema, params, metadata?)`                                                                                                                                                                                                      | Confluent Kafka — same API as KafkaClient                          |
+| **RedpandaClient**                 | `consume(schema, params, metadata?)`, `produce(schema, params, metadata?)`                                                                                                                                                                                                      | Redpanda — same API as KafkaClient                                 |
+| **SmtpClient**                     | `send(params)`                                                                                                                                                                                                                                                                  | Send emails via SMTP                                               |
+| **SuperblocksOCRClient**           | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | OCR document processing                                            |
+| **SnowflakeCortexClient**          | `apiRequest(options, schema?)`                                                                                                                                                                                                                                                  | Snowflake Cortex AI                                                |
+| **RestApiIntegrationPluginClient** | `apiRequest(options, schema)`                                                                                                                                                                                                                                                   | Generic REST API Integration - works with any configured HTTP API. |
 
 #### Common Mistakes to Avoid
 
@@ -478,7 +553,7 @@ await myApi.request({ ... }); // .request() does NOT exist on any client
 ```typescript
 // Use the generic apiRequest method
 await openai.apiRequest(
-  { method: 'POST', path: '/v1/chat/completions', body: { ... } },
+  { method: 'POST', path: '/chat/completions', body: { ... } },
   { response: ResponseSchema }
 );
 ```
@@ -521,7 +596,18 @@ Each integration client has detailed documentation with examples and common pitf
 #### SQL Databases
 
 - [PostgreSQL](./src/integrations/postgres/README.md) - Query PostgreSQL databases with schema validation
+- [MySQL](./src/integrations/mysql/README.md) - Query MySQL databases
+- [MariaDB](./src/integrations/mariadb/README.md) - Query MariaDB databases
+- [MSSQL](./src/integrations/mssql/README.md) - Query Microsoft SQL Server databases
+- [CockroachDB](./src/integrations/cockroachdb/README.md) - Query CockroachDB databases
+- [OracleDB](./src/integrations/oracledb/README.md) - Query Oracle databases
 - [Snowflake](./src/integrations/snowflake/README.md) - Query Snowflake data warehouses
+- [Redshift](./src/integrations/redshift/README.md) - Query Amazon Redshift
+- [BigQuery](./src/integrations/bigquery/README.md) - Query Google BigQuery
+- [Databricks](./src/integrations/databricks/README.md) - Query Databricks SQL warehouses
+- [Athena](./src/integrations/athena/README.md) - Query Amazon Athena
+- [Lakebase](./src/integrations/lakebase/README.md) - Query Lakebase databases
+- [SnowflakePostgres](./src/integrations/snowflakepostgres/README.md) - Query Snowflake via Postgres protocol
 
 #### GraphQL
 
@@ -575,24 +661,51 @@ Each integration client has detailed documentation with examples and common pitf
 - [Datadog](./src/integrations/datadog/README.md) - Metrics, monitors, and logs
 - [Segment](./src/integrations/segment/README.md) - Customer data platform
 
+#### NoSQL Databases
+
+- [MongoDB](./src/integrations/mongodb/README.md) - Document database with 13 actions (find, insertOne, updateOne, etc.)
+- [DynamoDB](./src/integrations/dynamodb/README.md) - AWS DynamoDB with PartiQL and native CRUD
+- [CosmosDB](./src/integrations/cosmosdb/README.md) - Azure Cosmos DB via apiRequest
+- [Couchbase](./src/integrations/couchbase/README.md) - N1QL queries and key-value operations
+- [Redis](./src/integrations/redis/README.md) - Execute raw Redis commands
+
 #### Cloud Storage
 
+- [S3](./src/integrations/s3/README.md) - AWS S3 bucket and object operations
+- [GCS](./src/integrations/gcs/README.md) - Google Cloud Storage operations
 - [Google Drive](./src/integrations/googledrive/README.md) - Files, folders, and sharing
 - [Dropbox](./src/integrations/dropbox/README.md) - Cloud file storage
 - [Box](./src/integrations/box/README.md) - Enterprise content management
 
-#### Code Execution
-
-- [Python](./src/integrations/python/README.md) - Execute Python scripts with type-safe inputs and outputs
-
 #### Generic HTTP
 
 - [REST API Integration](./src/integrations/restapiintegration/README.md) - Make HTTP requests to any configured REST API
 
+#### CRM
+
+- [Salesforce](./src/integrations/salesforce/README.md) - SOQL queries, CRUD, and bulk operations
+
+#### Event Streaming
+
+- [Kafka](./src/integrations/kafka/README.md) - Consume and produce Kafka messages
+- [Kinesis](./src/integrations/kinesis/README.md) - AWS Kinesis stream put/get
+- Confluent — same API as [Kafka](./src/integrations/kafka/README.md)
+- Redpanda — same API as [Kafka](./src/integrations/kafka/README.md)
+
+#### Email
+
+- [SMTP](./src/integrations/smtp/README.md) - Send emails via SMTP
+
 #### Other
 
 - [Elasticsearch](./src/integrations/elasticsearch/README.md) - Search and analytics engine
 - [Stability AI](./src/integrations/stabilityai/README.md) - Image generation and editing
+- [Superblocks OCR](./src/integrations/superblocks-ocr/README.md) - OCR document processing
+- [Snowflake Cortex](./src/integrations/snowflakecortex/README.md) - Snowflake Cortex AI
+
+### Streaming / SSE
+
+> **Note:** The SDK's `apiRequest()` method does **not** support streaming or Server-Sent Events (SSE) responses. All AI provider calls (OpenAI, Anthropic, Gemini, Groq, Mistral, Cohere, Perplexity, Fireworks) return complete responses — the SDK waits for the full response before returning. If you are building a chat interface that needs real-time token streaming, you will need to handle streaming at the frontend/UI layer rather than through the SDK.
 
 ## Generic API Requests
 
@@ -623,7 +736,6 @@ export default api({
     });
 
     const PostMessageResponseSchema = z.object({
-      ok: z.boolean(),
       ts: z.string(),
       channel: z.string(),
     });
@@ -644,7 +756,11 @@ export default api({
       },
     );
 
-    // result is fully typed as PostMessageResponse
+    if (!result.ok) {
+      throw new Error(`Slack API error: ${result.error}`);
+    }
+
+    // result is fully typed as { ok: true } & PostMessageResponseSchema
     return { ts: result.ts };
   },
 });
@@ -720,9 +836,11 @@ const doc = await ctx.integrations.mongo.run(
   { label: "Look up user by ID" },
 );
 
-await ctx.integrations.cache.get("session:" + sessionId, {
-  label: "Check session cache",
-});
+await ctx.integrations.cache.command(
+  `GET session:${sessionId}`,
+  z.string().nullable(),
+  { label: "Check session cache" },
+);
 ```
 
 ### When to Use
@@ -746,6 +864,7 @@ import {
   QueryValidationError,
   RestApiValidationError,
   IntegrationNotFoundError,
+  IntegrationError,
   ExecutionError,
   ErrorCode,
 } from "@superblocksteam/sdk-api";
@@ -788,7 +907,7 @@ Thrown when REST API request bodies or responses fail schema validation. Include
 ```typescript
 try {
   const result = await ctx.integrations.ai.apiRequest(
-    { method: 'POST', path: '/v1/chat/completions', body: { ... } },
+    { method: 'POST', path: '/chat/completions', body: { ... } },
     { body: RequestSchema, response: ResponseSchema }
   );
 } catch (error) {
@@ -1078,28 +1197,20 @@ The app template provides automatic type inference for API calls using a tRPC-st
 
 ### Adding a New API (2 Steps)
 
-**Step 1**: Create your API file (e.g., `server/apis/GetUsers/api.ts`)
-
-**Step 2**: Add it to the registry at `server/apis/index.ts`:
+1. Add a module under `server/apis/` (any layout; see [export styles](#export-style-default-vs-named-exports)).
+2. Register it in `server/apis/index.ts` (`.js` specifiers for ESM):
 
 ```typescript
-import GetUsers from "./GetUsers/api.js";
-import CreateOrder from "./CreateOrder/api.js";
+import CreateOrder from "./orders/create-order.js";
+import GetUsers from "./users/get-users.js";
+import { ListProfiles, UpdateProfile } from "./users/pair.js";
 
-const apis = {
-  GetUsers,
-  CreateOrder,
-  // Add new APIs here
-} as const;
+const apis = { CreateOrder, GetUsers, ListProfiles, UpdateProfile } as const;
 
 export default apis;
 export type ApiRegistry = typeof apis;
 ```
 
-That's it! Types automatically flow to the frontend.
-
-> **Note**: Always use `.js` extension in imports (required for ESM module resolution).
-
 ### Calling APIs from React Components
 
 Import `useApi` from the template's pre-configured hook:
@@ -1142,13 +1253,15 @@ The hook uses `import type` to pull in only the type information from the regist
 
 ### Alternative: Explicit Type Parameter
 
-For testing or when the registry isn't available:
+When you cannot use the registry hook, pass the compiled API type:
 
 ```typescript
 import { useApi } from "@superblocksteam/library";
-import type GetUsersApi from "../../server/apis/GetUsers/api.js";
+import type GetUsersApi from "../../server/apis/users/get-users.js";
+import type { ListProfiles } from "../../server/apis/users/pair.js";
 
-const { run } = useApi<typeof GetUsersApi>("GetUsers");
+const getUsers = useApi<typeof GetUsersApi>("GetUsers");
+const listProfiles = useApi<typeof ListProfiles>("ListProfiles");
 ```
 
 ## Complete Example
@@ -1193,7 +1306,6 @@ const CustomerSchema = z.object({
 });
 
 const SlackPostMessageResponseSchema = z.object({
-  ok: z.boolean(),
   ts: z.string().optional(),
 });
 
@@ -1250,7 +1362,7 @@ export default api({
     const orderId = `ord_${Date.now()}`;
 
     // Notify via Slack
-    await ctx.integrations.notifier.apiRequest(
+    const slackResult = await ctx.integrations.notifier.apiRequest(
       {
         method: "POST",
         path: "/chat.postMessage",
@@ -1262,13 +1374,17 @@ export default api({
       { response: SlackPostMessageResponseSchema },
     );
 
+    if (!slackResult.ok) {
+      throw new Error(`Slack API error: ${slackResult.error}`);
+    }
+
     // Generate AI summary if requested
     let aiSummary: string | undefined;
     if (sendAiSummary) {
       const completion = await ctx.integrations.ai.apiRequest(
         {
           method: "POST",
-          path: "/v1/chat/completions",
+          path: "/chat/completions",
           body: {
             model: "gpt-4",
             messages: [

package/dist/api/definition.d.ts

@@ -39,9 +39,14 @@ export type ExtractApiInput<T> = T extends CompiledApi<infer TInput, any> ? TInp
 export type ExtractApiOutput<T> = T extends CompiledApi<any, infer TOutput> ? TOutput : never;
 import { type IntegrationDeclaration } from "../integrations/declarations.js";
 import type { ApiConfig, ApiContext, AnyIntegrationRef } from "../types.js";
-/** Called by the Vite plugin to set the entry point for the next api() call. */
+/** Called by the Vite plugin to set the entry point for api() calls in this file. */
 export declare function __setEntryPoint(entryPoint: string): void;
-export declare function consumeEntryPoint(): string | undefined;
+/**
+ * Returns the current pending entry point without clearing it.
+ * This allows multiple api() calls within the same file to share the same
+ * entry point (e.g. named exports from a single module).
+ */
+export declare function getEntryPoint(): string | undefined;
 /**
  * A compiled API definition ready for execution.
  *
@@ -134,10 +139,10 @@ export interface CompiledApi<TInput = unknown, TOutput = unknown> {
  *       throw new Error('User not found');
  *     }
  *
- *     await ctx.integrations.notifier.postMessage({
- *       channel: '#user-lookups',
- *       text: `Fetched user ${user.name}`,
- *     });
+ *     await ctx.integrations.notifier.apiRequest(
+ *       { method: 'POST', path: '/chat.postMessage', body: { channel: '#user-lookups', text: `Fetched user ${user.name}` } },
+ *       { response: z.object({ ok: z.boolean() }) }
+ *     );
  *
  *     return { user };
  *   },

package/dist/api/definition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/api/definition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAE3B,CAAC,SAAS,WAAW,CAAC,MAAM,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,GAAG,KAAK,CAAC;AAE5D;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAE5B,CAAC,SAAS,WAAW,CAAC,GAAG,EAAE,MAAM,OAAO,CAAC,GAAG,OAAO,GAAG,KAAK,CAAC;AAC9D,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAU5E,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAExD;AAED,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAItD;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC9D,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,mDAAmD;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,uCAAuC;IACvC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAExC,wCAAwC;IACxC,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAE1C;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,CACZ,GAAG,EAAE,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,EAClD,KAAK,EAAE,MAAM,KACV,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtB;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAC;CAC9D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,GAAG,CACjB,MAAM,SAAS,CAAC,CAAC,OAAO,EACxB,OAAO,SAAS,CAAC,CAAC,OAAO,EACzB,aAAa,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,MAAM,CAC9D,MAAM,EACN,KAAK,CACN,EAED,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC,GAChD,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAkBhD"}
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/api/definition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAE3B,CAAC,SAAS,WAAW,CAAC,MAAM,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,GAAG,KAAK,CAAC;AAE5D;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAE5B,CAAC,SAAS,WAAW,CAAC,GAAG,EAAE,MAAM,OAAO,CAAC,GAAG,OAAO,GAAG,KAAK,CAAC;AAC9D,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAc5E,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAExD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAElD;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC9D,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,mDAAmD;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,uCAAuC;IACvC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAExC,wCAAwC;IACxC,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAE1C;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,CACZ,GAAG,EAAE,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,EAClD,KAAK,EAAE,MAAM,KACV,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtB;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAC;CAC9D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,GAAG,CACjB,MAAM,SAAS,CAAC,CAAC,OAAO,EACxB,OAAO,SAAS,CAAC,CAAC,OAAO,EACzB,aAAa,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,MAAM,CAC9D,MAAM,EACN,KAAK,CACN,EAED,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC,GAChD,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAkBhD"}

package/dist/api/definition.js

@@ -7,18 +7,25 @@
 import { extractIntegrationDeclarations, } from "../integrations/declarations.js";
 // ---------------------------------------------------------------------------
 // Entry point setter — used by the Vite plugin to stamp the source file path
-// onto the next api() call. ESM top-level execution is
-// synchronous, so the prepended __setEntryPoint() always runs before api().
+// onto every api()/streamingApi() call in a module.  ESM top-level execution
+// is synchronous, so the prepended __setEntryPoint() always runs before any
+// api() call in the same file.  The value is intentionally NOT cleared after
+// the first read so that multiple named-exported api() calls in a single file
+// all receive the same entry point.  The next file's __setEntryPoint() call
+// naturally overwrites the value.
 // ---------------------------------------------------------------------------
 let __pendingEntryPoint;
-/** Called by the Vite plugin to set the entry point for the next api() call. */
+/** Called by the Vite plugin to set the entry point for api() calls in this file. */
 export function __setEntryPoint(entryPoint) {
     __pendingEntryPoint = entryPoint;
 }
-export function consumeEntryPoint() {
-    const ep = __pendingEntryPoint;
-    __pendingEntryPoint = undefined;
-    return ep;
+/**
+ * Returns the current pending entry point without clearing it.
+ * This allows multiple api() calls within the same file to share the same
+ * entry point (e.g. named exports from a single module).
+ */
+export function getEntryPoint() {
+    return __pendingEntryPoint;
 }
 /**
  * Define a TypeScript-based API with input/output validation.
@@ -64,10 +71,10 @@ export function consumeEntryPoint() {
  *       throw new Error('User not found');
  *     }
  *
- *     await ctx.integrations.notifier.postMessage({
- *       channel: '#user-lookups',
- *       text: `Fetched user ${user.name}`,
- *     });
+ *     await ctx.integrations.notifier.apiRequest(
+ *       { method: 'POST', path: '/chat.postMessage', body: { channel: '#user-lookups', text: `Fetched user ${user.name}` } },
+ *       { response: z.object({ ok: z.boolean() }) }
+ *     );
  *
  *     return { user };
  *   },
@@ -80,7 +87,7 @@ export function api(config) {
     const compiled = {
         name: config.name,
         description: config.description,
-        entryPoint: consumeEntryPoint(),
+        entryPoint: getEntryPoint(),
         inputSchema: config.input,
         outputSchema: config.output,
         run: config.run,

package/dist/api/definition.js.map

@@ -1 +1 @@
-{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../src/api/definition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyCH,OAAO,EACL,8BAA8B,GAE/B,MAAM,iCAAiC,CAAC;AAGzC,8EAA8E;AAC9E,6EAA6E;AAC7E,uDAAuD;AACvD,4EAA4E;AAC5E,8EAA8E;AAE9E,IAAI,mBAAuC,CAAC;AAE5C,gFAAgF;AAChF,MAAM,UAAU,eAAe,CAAC,UAAkB;IAChD,mBAAmB,GAAG,UAAU,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,MAAM,EAAE,GAAG,mBAAmB,CAAC;IAC/B,mBAAmB,GAAG,SAAS,CAAC;IAChC,OAAO,EAAE,CAAC;AACZ,CAAC;AA2DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,UAAU,GAAG,CAQjB,MAAiD;IAEjD,oDAAoD;IACpD,MAAM,YAAY,GAAG,8BAA8B,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAEzE,MAAM,QAAQ,GAAmD;QAC/D,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,UAAU,EAAE,iBAAiB,EAAE;QAC/B,WAAW,EAAE,MAAM,CAAC,KAAK;QACzB,YAAY,EAAE,MAAM,CAAC,MAAM;QAC3B,GAAG,EAAE,MAAM,CAAC,GAGkB;QAC9B,YAAY;KACb,CAAC;IAEF,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../src/api/definition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyCH,OAAO,EACL,8BAA8B,GAE/B,MAAM,iCAAiC,CAAC;AAGzC,8EAA8E;AAC9E,6EAA6E;AAC7E,6EAA6E;AAC7E,4EAA4E;AAC5E,6EAA6E;AAC7E,8EAA8E;AAC9E,4EAA4E;AAC5E,kCAAkC;AAClC,8EAA8E;AAE9E,IAAI,mBAAuC,CAAC;AAE5C,qFAAqF;AACrF,MAAM,UAAU,eAAe,CAAC,UAAkB;IAChD,mBAAmB,GAAG,UAAU,CAAC;AACnC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,mBAAmB,CAAC;AAC7B,CAAC;AA2DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,UAAU,GAAG,CAQjB,MAAiD;IAEjD,oDAAoD;IACpD,MAAM,YAAY,GAAG,8BAA8B,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAEzE,MAAM,QAAQ,GAAmD;QAC/D,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,UAAU,EAAE,aAAa,EAAE;QAC3B,WAAW,EAAE,MAAM,CAAC,KAAK;QACzB,YAAY,EAAE,MAAM,CAAC,MAAM;QAC3B,GAAG,EAAE,MAAM,CAAC,GAGkB;QAC9B,YAAY;KACb,CAAC;IAEF,OAAO,QAAQ,CAAC;AAClB,CAAC"}