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

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";
@@ -325,7 +362,7 @@ const myApi = api({
 
 The `run` function receives two arguments:
 
-1. **`ctx`** - Context object with integrations, logging, and environment
+1. **`ctx`** - Context object with integrations, logging, environment, and user information
 2. **`input`** - Typed, validated input data matching your input schema
 
 ```typescript
@@ -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.
@@ -407,6 +456,248 @@ async run(ctx, { userId }) {
 }
 ```
 
+#### `ctx.env`
+
+Access environment variables configured for the application.
+
+```typescript
+async run(ctx) {
+  const apiKey = ctx.env.EXTERNAL_API_KEY;
+  if (!apiKey) {
+    throw new Error("EXTERNAL_API_KEY environment variable is not configured");
+  }
+  const environment = ctx.env.NODE_ENV;
+}
+```
+
+#### `ctx.user`
+
+User information extracted from the Superblocks JWT. This is the **secure, server-side** way to access the current user's identity in API implementations. Never pass user information from the frontend as API input — always use `ctx.user` instead.
+
+```typescript
+interface ApiUser {
+  /** Unique user identifier from JWT */
+  readonly userId: string;
+
+  /** User's email address (if available) */
+  readonly email?: string;
+
+  /** User's display name (if available) */
+  readonly name?: string;
+
+  /** User's group memberships from JWT */
+  readonly groups: readonly string[];
+
+  /** Custom claims from JWT */
+  readonly customClaims: Readonly<Record<string, unknown>>;
+}
+```
+
+##### Basic Usage
+
+```typescript
+import { api, z, postgres } from "@superblocksteam/sdk-api";
+
+const PROD_POSTGRES = "a1b2c3d4-5678-90ab-cdef-ghijklmnopqr";
+
+export default api({
+  name: "GetMyProfile",
+  integrations: { db: postgres(PROD_POSTGRES) },
+  input: z.object({}),
+  output: z.object({
+    email: z.string(),
+    name: z.string(),
+  }),
+
+  async run(ctx) {
+    // Access user identity securely from the JWT — no frontend input needed
+    ctx.log.info("Fetching profile", { userId: ctx.user.userId });
+
+    const rows = await ctx.integrations.db.query(
+      "SELECT email, display_name FROM users WHERE id = $1",
+      z.object({ email: z.string(), display_name: z.string() }),
+      [ctx.user.userId],
+    );
+
+    if (rows.length === 0) {
+      throw new Error("User not found");
+    }
+
+    return { email: rows[0].email, name: rows[0].display_name };
+  },
+});
+```
+
+##### Role-Based Access Control with Groups
+
+Use `ctx.user.groups` to restrict API access based on the user's group memberships. Groups are populated from the user's identity provider (e.g., Okta, Azure AD) via the JWT.
+
+```typescript
+import { api, z, postgres } from "@superblocksteam/sdk-api";
+
+const PROD_POSTGRES = "a1b2c3d4-5678-90ab-cdef-ghijklmnopqr";
+
+export default api({
+  name: "GetAdminDashboard",
+  integrations: { db: postgres(PROD_POSTGRES) },
+  input: z.object({}),
+  output: z.object({
+    stats: z.object({
+      totalUsers: z.number(),
+      activeUsers: z.number(),
+    }),
+  }),
+
+  async run(ctx) {
+    // Check group membership for authorization
+    if (!ctx.user.groups.includes("admin")) {
+      throw new Error("Access denied: admin group membership required");
+    }
+
+    const stats = await ctx.integrations.db.query(
+      `SELECT
+        COUNT(*) as total_users,
+        COUNT(*) FILTER (WHERE status = 'active') as active_users
+      FROM users`,
+      z.object({ total_users: z.number(), active_users: z.number() }),
+    );
+
+    return {
+      stats: {
+        totalUsers: stats[0].total_users,
+        activeUsers: stats[0].active_users,
+      },
+    };
+  },
+});
+```
+
+##### Custom Claims
+
+`ctx.user.customClaims` contains additional claims from the JWT, such as department, role, or tenant information configured in your identity provider.
+
+**Important limitations:**
+
+- Custom claims are only available when the user is in an **enterprise account that uses SSO**, OR when the application is **deployed and uses embed tokens with SSO claims**.
+- In the editor, custom claims will be empty for non-SSO users.
+- Always write defensive code that handles missing custom claims gracefully.
+
+```typescript
+import { api, z, postgres } from "@superblocksteam/sdk-api";
+
+const PROD_POSTGRES = "a1b2c3d4-5678-90ab-cdef-ghijklmnopqr";
+
+export default api({
+  name: "GetTenantData",
+  integrations: { db: postgres(PROD_POSTGRES) },
+  input: z.object({}),
+  output: z.object({
+    tenantName: z.string(),
+    records: z.array(z.object({ id: z.string(), value: z.string() })),
+  }),
+
+  async run(ctx) {
+    // Access custom claims from the JWT — handle missing claims defensively
+    const tenantId = ctx.user.customClaims["tenant_id"];
+    if (typeof tenantId !== "string") {
+      throw new Error(
+        "Missing tenant_id claim. Custom claims require enterprise SSO or embed tokens with SSO claims.",
+      );
+    }
+
+    const department = ctx.user.customClaims["department"] as
+      | string
+      | undefined;
+
+    ctx.log.info("Fetching tenant data", {
+      userId: ctx.user.userId,
+      tenantId,
+      department: department ?? "unknown",
+    });
+
+    const records = await ctx.integrations.db.query(
+      "SELECT id, value FROM tenant_data WHERE tenant_id = $1",
+      z.object({ id: z.string(), value: z.string() }),
+      [tenantId],
+    );
+
+    const tenantNames = await ctx.integrations.db.query(
+      "SELECT name FROM tenants WHERE id = $1",
+      z.object({ name: z.string() }),
+      [tenantId],
+    );
+
+    return {
+      tenantName: tenantNames[0]?.name ?? "Unknown Tenant",
+      records,
+    };
+  },
+});
+```
+
+##### Combining User Context for Row-Level Security
+
+```typescript
+import { api, z, postgres } from "@superblocksteam/sdk-api";
+
+const PROD_POSTGRES = "a1b2c3d4-5678-90ab-cdef-ghijklmnopqr";
+
+export default api({
+  name: "GetMyOrders",
+  integrations: { db: postgres(PROD_POSTGRES) },
+  input: z.object({
+    status: z.enum(["pending", "completed", "cancelled"]).optional(),
+  }),
+  output: z.object({
+    orders: z.array(
+      z.object({
+        id: z.string(),
+        total: z.number(),
+        status: z.string(),
+        createdAt: z.string(),
+      }),
+    ),
+  }),
+
+  async run(ctx, { status }) {
+    // Use ctx.user for row-level security — users can only see their own orders
+    if (!ctx.user.email) {
+      throw new Error("User email is required to filter orders");
+    }
+    const params: unknown[] = [ctx.user.email];
+    let query =
+      "SELECT id, total, status, created_at FROM orders WHERE user_email = $1";
+
+    if (status) {
+      query += " AND status = $2";
+      params.push(status);
+    }
+
+    query += " ORDER BY created_at DESC LIMIT 50";
+
+    const orders = await ctx.integrations.db.query(
+      query,
+      z.object({
+        id: z.string(),
+        total: z.number(),
+        status: z.string(),
+        created_at: z.string(),
+      }),
+      params,
+    );
+
+    return {
+      orders: orders.map((o) => ({
+        id: o.id,
+        total: o.total,
+        status: o.status,
+        createdAt: o.created_at,
+      })),
+    };
+  },
+});
+```
+
 ## Integration Clients
 
 ### Integration Client Methods Reference
@@ -415,48 +706,73 @@ 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                                |
+| **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 +794,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 +837,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 +902,50 @@ 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
+
 #### 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 +976,6 @@ export default api({
     });
 
     const PostMessageResponseSchema = z.object({
-      ok: z.boolean(),
       ts: z.string(),
       channel: z.string(),
     });
@@ -644,7 +996,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 };
   },
 });
@@ -711,7 +1067,7 @@ const result = await ctx.integrations.slack.apiRequest(
   { label: "Send alert to Slack" },
 );
 
-// Other clients (MongoDB, Redis, S3, etc.)
+// Other clients (MongoDB, S3, etc.)
 const doc = await ctx.integrations.mongo.run(
   "users",
   "findOne",
@@ -719,10 +1075,6 @@ const doc = await ctx.integrations.mongo.run(
   { filter: { _id: userId } },
   { label: "Look up user by ID" },
 );
-
-await ctx.integrations.cache.get("session:" + sessionId, {
-  label: "Check session cache",
-});
 ```
 
 ### When to Use
@@ -746,6 +1098,7 @@ import {
   QueryValidationError,
   RestApiValidationError,
   IntegrationNotFoundError,
+  IntegrationError,
   ExecutionError,
   ErrorCode,
 } from "@superblocksteam/sdk-api";
@@ -788,7 +1141,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 +1431,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 +1487,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 +1540,6 @@ const CustomerSchema = z.object({
 });
 
 const SlackPostMessageResponseSchema = z.object({
-  ok: z.boolean(),
   ts: z.string().optional(),
 });
 
@@ -1250,7 +1596,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 +1608,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: [