@superblocksteam/sdk-api 0.0.5 → 0.0.7

package/README.md

@@ -83,12 +83,12 @@ type Output = z.infer<typeof myApi.outputSchema>; // { users: { id: string }[] }
 
 ### How APIs are Executed
 
-The `execute()` function runs a compiled API with the required inputs:
+The `executeApi()` function runs a compiled API with the required inputs:
 
 ```typescript
-import { execute } from '@superblocksteam/sdk-api';
+import { executeApi } from '@superblocksteam/sdk-api';
 
-const response = await execute(myApi, {
+const response = await executeApi(myApi, {
   // Raw input data (will be validated against inputSchema)
   input: { limit: 10 },
 
@@ -158,33 +158,12 @@ This architecture means:
 - **Authentication is centralized** - The runtime handles all credentials
 - **Operations are auditable** - The runtime can log/trace all operations
 
-#### `executeStreamingQuery` Callback
-
-For streaming APIs (e.g., LLM token streaming), there's an additional callback:
-
-```typescript
-// Inside AnthropicClient.streamApiRequest():
-const stream = executeStreamingQuery(
-  'prod-anthropic-id',
-  {
-    method: 'POST',
-    path: '/v1/messages',
-    body: { model: 'claude-3-5-sonnet', stream: true, messages: [...] }
-  }
-);
-
-// Returns AsyncIterable<unknown> - each chunk is validated against the chunk schema
-for await (const chunk of stream) {
-  yield transformChunk(chunk);
-}
-```
-
 ### Execution Request Interface
 
-The complete request interface for `execute()`:
+The complete request interface for `executeApi()`:
 
 ```typescript
-interface UnifiedExecuteApiRequest {
+interface ExecuteApiRequest {
   /** Raw input data to be validated */
   input: unknown;
 
@@ -204,23 +183,14 @@ interface UnifiedExecuteApiRequest {
   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>;
-
-  /**
-   * Callback for streaming operations (optional).
-   * Only needed for streaming APIs that use streaming integrations.
-   */
-  executeStreamingQuery?: (
-    integrationId: string,
-    request: Record<string, unknown>,
-  ) => AsyncIterable<unknown>;
 }
 ```
 
 ### Execution Response
 
-Regular APIs return a discriminated union:
+`executeApi()` returns a discriminated union:
 
 ```typescript
 type ExecuteApiResponse<TOutput> =
@@ -231,17 +201,6 @@ type ExecuteApiResponse<TOutput> =
     };
 ```
 
-Streaming APIs return an `AsyncGenerator`:
-
-```typescript
-const stream: AsyncGenerator<TChunk> = execute(streamingApi, request);
-
-for await (const chunk of stream) {
-  // Each chunk is validated against the chunk schema
-  console.log(chunk);
-}
-```
-
 ### Integration Configuration
 
 Each integration in the `integrations` array has this structure:
@@ -317,23 +276,58 @@ 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)`
 
 Defines a TypeScript-based API with input/output validation. Returns a complete result when the `run` function completes.
 
-For streaming responses (e.g., LLM token streaming), see [`streamingApi()`](#streamingapiconfig) below.
-
 #### 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";
@@ -364,87 +358,11 @@ const myApi = api({
 });
 ```
 
-### `streamingApi(config)`
-
-Defines a streaming API that yields chunks as they're generated. Ideal for LLM token streaming, real-time data feeds, and progressive responses.
-
-```typescript
-import { streamingApi, z, anthropic } from "@superblocksteam/sdk-api";
-
-// Integration ID from the integrations panel
-const PROD_ANTHROPIC = "e5f6g7h8-1234-56ab-cdef-ghijklmnopqr";
-
-// Define the schema for each streamed chunk
-const TextChunkSchema = z.object({
-  type: z.literal("text"),
-  text: z.string(),
-});
-
-export default streamingApi({
-  name: "StreamChatResponse",
-
-  integrations: {
-    ai: anthropic(PROD_ANTHROPIC),
-  },
-
-  input: z.object({
-    prompt: z.string(),
-  }),
-
-  // Schema for each yielded chunk (not the final output)
-  chunk: TextChunkSchema,
-
-  // Generator function that yields chunks
-  async *run(ctx, { prompt }) {
-    // Use streamApiRequest for streaming HTTP responses
-    const stream = ctx.integrations.ai.streamApiRequest(
-      {
-        method: "POST",
-        path: "/v1/messages",
-        body: {
-          model: "claude-3-5-sonnet-20241022",
-          max_tokens: 1024,
-          stream: true, // Enable streaming
-          messages: [{ role: "user", content: prompt }],
-        },
-      },
-      { chunk: AnthropicStreamEventSchema },
-    );
-
-    // Process and yield each chunk
-    for await (const event of stream) {
-      if (
-        event.type === "content_block_delta" &&
-        event.delta?.type === "text_delta"
-      ) {
-        yield { type: "text" as const, text: event.delta.text };
-      }
-    }
-  },
-});
-```
-
-#### Streaming API Configuration
-
-| Property       | Type                                       | Description                                     |
-| -------------- | ------------------------------------------ | ----------------------------------------------- |
-| `integrations` | `Record<string, IntegrationRef>`           | Integration declarations (same as `api()`)      |
-| `input`        | `z.ZodType`                                | Zod schema for input validation                 |
-| `chunk`        | `z.ZodType`                                | Zod schema for each yielded chunk               |
-| `run`          | `(ctx, input) => AsyncIterable<ChunkType>` | Generator function that yields validated chunks |
-
-#### Key Differences from `api()`
-
-- Uses `chunk` schema instead of `output` schema
-- The `run` function is a generator (`async *run`) that uses `yield`
-- Each yielded value is validated against the `chunk` schema
-- No final return value - all data is streamed via `yield`
-
 ### Context (`ctx`) and Input
 
 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
@@ -459,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";
@@ -469,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",
@@ -494,9 +411,6 @@ export default api({
 
     // Productivity
     wiki: notion(PROD_NOTION),
-
-    // Code Execution
-    runtime: python(PYTHON_RUNTIME),
   },
 
   input: z.object({ userId: z.string() }),
@@ -513,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.
@@ -526,55 +456,253 @@ 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
 
-**IMPORTANT:** Before using any integration client, verify available methods below. Do NOT assume methods exist based on the external service's API.
-
-#### 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)`, `streamApiRequest(options, schema)`             | Supports streaming for real-time token output          |
-| **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)`, `streamApiRequest(options, schema)`             | Supports streaming for real-time token output          |
-| **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                                |
+**IMPORTANT:** Before using any integration client, verify available methods. Do NOT assume methods exist based on the external service's API.
 
 #### Common Mistakes to Avoid
 
@@ -588,6 +716,7 @@ await openai.createChatCompletion({ ... });
 await anthropic.createMessage({ ... });
 await stripe.createCustomer({ ... });
 await github.createIssue({ ... });
+await myApi.request({ ... }); // .request() does NOT exist on any client
 ```
 
 **CORRECT - Use apiRequest:**
@@ -595,7 +724,7 @@ await github.createIssue({ ... });
 ```typescript
 // Use the generic apiRequest method
 await openai.apiRequest(
-  { method: 'POST', path: '/v1/chat/completions', body: { ... } },
+  { method: 'POST', path: '/chat/completions', body: { ... } },
   { response: ResponseSchema }
 );
 ```
@@ -623,89 +752,9 @@ const users = await ctx.integrations.db.query(
 );
 ```
 
-#### Finding Type Definitions
-
-To verify available methods and signatures:
-
-- **README**: This document contains complete method signatures for all clients
-- **Type files**: Check `node_modules/@superblocksteam/sdk-api/src/integrations/<client>/types.ts`
-- **API Context**: See `node_modules/@superblocksteam/sdk-api/src/types.ts` for the ApiContext interface
-
-### Integration Documentation
-
-Each integration client has detailed documentation with examples and common pitfalls. Click on an integration below for its full README:
-
-#### SQL Databases
-
-- [PostgreSQL](./src/integrations/postgres/README.md) - Query PostgreSQL databases with schema validation
-- [Snowflake](./src/integrations/snowflake/README.md) - Query Snowflake data warehouses
-
-#### GraphQL
-
-- [GraphQL](./src/integrations/graphql/README.md) - Execute queries and mutations against GraphQL endpoints
-
-#### AI/LLM
-
-- [OpenAI](./src/integrations/openai_v2/README.md) - Chat completions, embeddings, DALL-E, and more
-- [Anthropic](./src/integrations/anthropic/README.md) - Claude models for chat and analysis
-- [Cohere](./src/integrations/cohere/README.md) - Text generation, embeddings, classification
-- [Gemini](./src/integrations/gemini/README.md) - Google's multimodal AI models
-- [Groq](./src/integrations/groq/README.md) - Fast inference for LLM completions
-- [Mistral](./src/integrations/mistral/README.md) - Open-weight language models
-- [Perplexity](./src/integrations/perplexity/README.md) - Search-augmented AI responses
-- [Fireworks](./src/integrations/fireworks/README.md) - Fast model inference
-
-#### Messaging & Communication
-
-- [Slack](./src/integrations/slack/README.md) - Send messages, manage channels, Block Kit
-- [Twilio](./src/integrations/twilio/README.md) - SMS, voice calls, phone lookups
-- [SendGrid](./src/integrations/sendgrid/README.md) - Transactional and marketing emails
-- [Intercom](./src/integrations/intercom/README.md) - Customer messaging and support
-- [Front](./src/integrations/front/README.md) - Shared inbox and team communication
-
-#### Productivity & Collaboration
+### Streaming / SSE
 
-- [Notion](./src/integrations/notion/README.md) - Databases, pages, and blocks
-- [Airtable](./src/integrations/airtable/README.md) - Spreadsheet-database hybrid
-- [Asana](./src/integrations/asana/README.md) - Project and task management
-- [Jira](./src/integrations/jira/README.md) - Issue tracking and project management
-- [Confluence](./src/integrations/confluence/README.md) - Team wikis and documentation
-- [Zoom](./src/integrations/zoom/README.md) - Video meetings and webinars
-
-#### Developer Tools
-
-- [GitHub](./src/integrations/github/README.md) - Repositories, issues, pull requests
-- [Bitbucket](./src/integrations/bitbucket/README.md) - Git repositories and pipelines
-- [CircleCI](./src/integrations/circleci/README.md) - CI/CD pipelines and jobs
-
-#### Business & Enterprise
-
-- [Stripe](./src/integrations/stripe/README.md) - Payments, subscriptions, invoicing
-- [HubSpot](./src/integrations/hubspot/README.md) - CRM, contacts, deals
-- [Zendesk](./src/integrations/zendesk/README.md) - Support tickets and customer service
-- [PagerDuty](./src/integrations/pagerduty/README.md) - Incident management and on-call
-- [LaunchDarkly](./src/integrations/launchdarkly/README.md) - Feature flags and experimentation
-
-#### Analytics & Monitoring
-
-- [Google Analytics](./src/integrations/googleanalytics/README.md) - GA4 reports and real-time data
-- [Datadog](./src/integrations/datadog/README.md) - Metrics, monitors, and logs
-- [Segment](./src/integrations/segment/README.md) - Customer data platform
-
-#### Cloud Storage
-
-- [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
-
-#### Other
-
-- [Elasticsearch](./src/integrations/elasticsearch/README.md) - Search and analytics engine
-- [Stability AI](./src/integrations/stabilityai/README.md) - Image generation and editing
+> **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
 
@@ -736,7 +785,6 @@ export default api({
     });
 
     const PostMessageResponseSchema = z.object({
-      ok: z.boolean(),
       ts: z.string(),
       channel: z.string(),
     });
@@ -757,7 +805,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 };
   },
 });
@@ -780,99 +832,6 @@ export default api({
 | `body?`    | `z.ZodSchema<TBody>`     | Optional Zod schema for request body validation (required if body is provided) |
 | `response` | `z.ZodSchema<TResponse>` | **Required** Zod schema for response validation                                |
 
-## Streaming API Requests
-
-For real-time streaming responses (e.g., LLM token streaming), use `streamApiRequest()`. This method returns an `AsyncIterable` that yields validated chunks as they arrive.
-
-```typescript
-import { streamingApi, z, anthropic } from "@superblocksteam/sdk-api";
-
-// Integration ID from the integrations panel
-const PROD_ANTHROPIC = "d4e5f6g7-8901-23ab-cdef-ghijklmnopqr";
-
-// Define schema for Anthropic SSE events
-const AnthropicStreamEventSchema = z.discriminatedUnion("type", [
-  z.object({
-    type: z.literal("content_block_delta"),
-    index: z.number(),
-    delta: z.object({
-      type: z.literal("text_delta"),
-      text: z.string(),
-    }),
-  }),
-  z.object({ type: z.literal("message_start"), message: z.any() }),
-  z.object({
-    type: z.literal("content_block_start"),
-    index: z.number(),
-    content_block: z.any(),
-  }),
-  z.object({ type: z.literal("content_block_stop"), index: z.number() }),
-  z.object({
-    type: z.literal("message_delta"),
-    delta: z.any(),
-    usage: z.any(),
-  }),
-  z.object({ type: z.literal("message_stop") }),
-  z.object({ type: z.literal("ping") }),
-]);
-
-export default streamingApi({
-  name: "StreamAnthropicChat",
-
-  integrations: {
-    ai: anthropic(PROD_ANTHROPIC),
-  },
-
-  input: z.object({ prompt: z.string() }),
-  chunk: z.object({ type: z.literal("text"), text: z.string() }),
-
-  async *run(ctx, { prompt }) {
-    const stream = ctx.integrations.ai.streamApiRequest(
-      {
-        method: "POST",
-        path: "/v1/messages",
-        body: {
-          model: "claude-3-5-sonnet-20241022",
-          max_tokens: 1024,
-          stream: true,
-          messages: [{ role: "user", content: prompt }],
-        },
-      },
-      { chunk: AnthropicStreamEventSchema },
-    );
-
-    for await (const event of stream) {
-      if (event.type === "content_block_delta") {
-        yield { type: "text" as const, text: event.delta.text };
-      }
-    }
-  },
-});
-```
-
-### StreamApiRequestOptions
-
-Same as `ApiRequestOptions` - see above.
-
-### StreamApiRequestSchema
-
-| Property | Type                  | Description                                                                    |
-| -------- | --------------------- | ------------------------------------------------------------------------------ |
-| `body?`  | `z.ZodSchema<TBody>`  | Optional Zod schema for request body validation (required if body is provided) |
-| `chunk`  | `z.ZodSchema<TChunk>` | **Required** Zod schema for validating each streamed chunk                     |
-
-### Supported Integrations
-
-Streaming is supported by REST API-based integrations that connect to services with SSE (Server-Sent Events) endpoints:
-
-- **AnthropicClient** - Claude streaming messages
-- **OpenAIClient** - GPT streaming chat completions
-- **CohereClient** - Streaming text generation
-- **GroqClient** - Streaming completions
-- **MistralClient** - Streaming chat
-- **FireworksClient** - Streaming inference
-- **PerplexityClient** - Streaming search responses
-
 ## Trace Metadata
 
 All integration client methods accept an optional `metadata` parameter as their last argument. When `includeDiagnostics` is enabled, this metadata is captured in the trace view alongside timing and request/response data.
@@ -910,14 +869,14 @@ await ctx.integrations.db.execute(
   { label: "Update last login" },
 );
 
-// REST API clients (apiRequest, streamApiRequest)
+// REST API clients (apiRequest)
 const result = await ctx.integrations.slack.apiRequest(
   { method: "POST", path: "/chat.postMessage", body: { channel, text } },
   { body: BodySchema, response: ResponseSchema },
   { 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",
@@ -925,10 +884,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
@@ -951,23 +906,22 @@ import {
   OutputValidationError,
   QueryValidationError,
   RestApiValidationError,
-  StreamChunkValidationError,
   IntegrationNotFoundError,
+  IntegrationError,
   ExecutionError,
   ErrorCode,
 } from "@superblocksteam/sdk-api";
 ```
 
-| Error Type                   | Code                    | Description                                        |
-| ---------------------------- | ----------------------- | -------------------------------------------------- |
-| `InputValidationError`       | `INPUT_VALIDATION`      | Input failed Zod validation                        |
-| `OutputValidationError`      | `OUTPUT_VALIDATION`     | Output failed Zod validation                       |
-| `QueryValidationError`       | N/A                     | Database query result validation failed (Postgres) |
-| `RestApiValidationError`     | N/A                     | REST API request/response validation failed        |
-| `StreamChunkValidationError` | N/A                     | Streaming chunk failed schema validation           |
-| `IntegrationNotFoundError`   | `INTEGRATION_NOT_FOUND` | Integration not configured                         |
-| `IntegrationError`           | `INTEGRATION_ERROR`     | Integration operation failed                       |
-| `ExecutionError`             | `EXECUTION_ERROR`       | User code threw an error                           |
+| Error Type                 | Code                    | Description                                        |
+| -------------------------- | ----------------------- | -------------------------------------------------- |
+| `InputValidationError`     | `INPUT_VALIDATION`      | Input failed Zod validation                        |
+| `OutputValidationError`    | `OUTPUT_VALIDATION`     | Output failed Zod validation                       |
+| `QueryValidationError`     | N/A                     | Database query result validation failed (Postgres) |
+| `RestApiValidationError`   | N/A                     | REST API request/response validation failed        |
+| `IntegrationNotFoundError` | `INTEGRATION_NOT_FOUND` | Integration not configured                         |
+| `IntegrationError`         | `INTEGRATION_ERROR`     | Integration operation failed                       |
+| `ExecutionError`           | `EXECUTION_ERROR`       | User code threw an error                           |
 
 ### QueryValidationError (Postgres)
 
@@ -996,7 +950,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) {
@@ -1024,33 +978,6 @@ The `RestApiValidationError` provides complete context for debugging:
 - **The actual data** that failed validation
 - **Utility methods** like `format()` and `flatten()` for different error representations
 
-### StreamChunkValidationError
-
-Thrown when a streamed chunk fails schema validation. Includes the chunk index, the raw chunk data, and the Zod error.
-
-```typescript
-import { execute, StreamChunkValidationError } from "@superblocksteam/sdk-api";
-
-try {
-  // execute() returns an AsyncGenerator for streaming APIs
-  for await (const chunk of execute(streamingApi, request)) {
-    // Process chunk
-  }
-} catch (error) {
-  if (error instanceof StreamChunkValidationError) {
-    console.error("Chunk index:", error.details.chunkIndex);
-    console.error("Raw chunk:", error.details.chunk);
-    console.error("Validation error:", error.details.zodError);
-  }
-}
-```
-
-The `StreamChunkValidationError` provides:
-
-- **Chunk index** (`chunkIndex`) - Which chunk in the stream failed
-- **Raw chunk data** (`chunk`) - The actual data that failed validation
-- **Full Zod error** (`zodError`) - Complete validation error details
-
 ## Best Practices
 
 ### Push Filtering Down to the Data Source
@@ -1313,28 +1240,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:
@@ -1377,13 +1296,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
@@ -1428,7 +1349,6 @@ const CustomerSchema = z.object({
 });
 
 const SlackPostMessageResponseSchema = z.object({
-  ok: z.boolean(),
   ts: z.string().optional(),
 });
 
@@ -1485,7 +1405,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",
@@ -1497,13 +1417,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: [