@superblocksteam/sdk-api 0.0.13 → 0.0.14

package/README.md

@@ -1,13 +1,11 @@
 # @superblocksteam/sdk-api
 
-TypeScript SDK for defining Superblocks APIs as simple, type-safe functions.
-
 ## Overview
 
 This SDK enables writing Superblocks APIs as TypeScript functions with:
 
 - **Zod schemas** for input/output validation
-- **Typed integration clients** for Postgres, Slack, OpenAI, Anthropic, Stripe, GitHub, Notion, and more
+- **Typed integration clients** for Postgres, Slack, OpenAI, Anthropic, Stripe, and more
 - **Full type inference** for inputs, outputs, and integrations
 - **Upfront integration declarations** for type-safe access and pre-authentication
 - **Runtime schema validation** with detailed error information for debugging
@@ -329,35 +327,6 @@ Defines a TypeScript-based API with input/output validation. Returns a complete
 | `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";
-
-const myApi = api({
-  // REQUIRED: name is used for identification in logs and debugging
-  name: "GreetUser",
-
-  // REQUIRED: Zod schema for input validation
-  input: z.object({
-    name: z.string(),
-    count: z.number().int().positive(),
-  }),
-
-  // REQUIRED: Zod schema for output validation
-  output: z.object({
-    greeting: z.string(),
-    items: z.array(z.string()),
-  }),
-
-  // REQUIRED: API implementation
-  async run(ctx, { name, count }) {
-    return {
-      greeting: `Hello, ${name}!`,
-      items: Array(count).fill("item"),
-    };
-  },
-});
-```
-
 ### Context (`ctx`) and Input
 
 The `run` function receives two arguments:
@@ -377,52 +346,24 @@ 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 } from "@superblocksteam/sdk-api";
+import { api, postgres, slack, z } from "@superblocksteam/sdk-api";
 
 // Integration IDs from the integrations panel - store in constants
 const PROD_POSTGRES = "a1b2c3d4-5678-90ab-cdef-ghijklmnopqr";
 const OPS_SLACK = "b2c3d4e5-6789-01ab-cdef-ghijklmnopqr";
-const PROD_OPENAI = "c3d4e5f6-7890-12ab-cdef-ghijklmnopqr";
-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";
 
 export default api({
   name: "ProcessUserWorkflow",
-
-  // Declare all integrations you'll use
   integrations: {
-    // Database
     db: postgres(PROD_POSTGRES),
-
-    // Messaging
     notifier: slack(OPS_SLACK),
-
-    // AI/LLM
-    ai: openai(PROD_OPENAI),
-    claude: anthropic(PROD_ANTHROPIC),
-
-    // Payment Processing
-    payments: stripe(PROD_STRIPE),
-
-    // Developer Tools
-    repo: github(PROD_GITHUB),
-
-    // Productivity
-    wiki: notion(PROD_NOTION),
   },
-
   input: z.object({ userId: z.string() }),
   output: z.object({ success: z.boolean() }),
-
   async run(ctx, { userId }) {
-    // Each integration is fully typed based on its declaration
     const users = await ctx.integrations.db.query(...);
     await ctx.integrations.notifier.apiRequest(...);
-    const completion = await ctx.integrations.ai.apiRequest(...);
-
-    return { success: true };
+    return { success: users.length > 0 };
   },
 });
 ```
@@ -516,83 +457,14 @@ interface ApiUser {
 }
 ```
 
-##### 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,
-      },
-    };
-  },
-});
+if (!ctx.user.groups.includes("admin")) {
+  throw new Error("Access denied: admin group membership required");
+}
 ```
 
 ##### Custom Claims
@@ -606,120 +478,17 @@ export default api({
 - 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,
-    };
-  },
-});
+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.",
+  );
+}
 ```
 
 ##### 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,
-      })),
-    };
-  },
-});
-```
+Use `ctx.user.userId` or `ctx.user.email` in parameterized queries to scope rows to the current user. Never accept user identity through API input.
 
 ## Integration Clients
 
@@ -775,67 +544,31 @@ const users = await ctx.integrations.db.query(
 );
 ```
 
-### 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
 
 All REST API-based integration clients support the `apiRequest()` method for making custom API calls. **Response schema validation is required** for type safety.
 
 ```typescript
-import { api, z, slack } from "@superblocksteam/sdk-api";
-
-// Integration ID from the integrations panel
-const OPS_SLACK = "b2c3d4e5-6789-01ab-cdef-ghijklmnopqr";
-
-export default api({
-  name: "PostSlackMessage",
+const CreateTicketBodySchema = z.object({
+  title: z.string(),
+  priority: z.enum(["low", "high"]),
+});
+const CreateTicketResponseSchema = z.object({
+  id: z.string(),
+  createdAt: z.string(),
+});
 
-  integrations: {
-    notifier: slack(OPS_SLACK),
+const ticket = await ctx.integrations.ticketing.apiRequest(
+  {
+    method: "POST",
+    path: "/tickets",
+    body: { title: "Deployment failed", priority: "high" },
   },
-
-  input: z.object({}),
-  output: z.object({ ts: z.string() }),
-
-  async run(ctx) {
-    // Define request and response schemas
-    const PostMessageBodySchema = z.object({
-      channel: z.string(),
-      text: z.string(),
-      blocks: z.array(z.any()).optional(),
-    });
-
-    const PostMessageResponseSchema = z.object({
-      ts: z.string(),
-      channel: z.string(),
-    });
-
-    // Response schema is REQUIRED
-    const result = await ctx.integrations.notifier.apiRequest(
-      {
-        method: "POST",
-        path: "/chat.postMessage",
-        body: {
-          channel: "#alerts",
-          text: "Deployment completed!",
-        },
-      },
-      {
-        body: PostMessageBodySchema,
-        response: PostMessageResponseSchema, // Required!
-      },
-    );
-
-    if (!result.ok) {
-      throw new Error(`Slack API error: ${result.error}`);
-    }
-
-    // result is fully typed as { ok: true } & PostMessageResponseSchema
-    return { ts: result.ts };
+  {
+    body: CreateTicketBodySchema,
+    response: CreateTicketResponseSchema,
   },
-});
+);
 ```
 
 ### ApiRequestOptions
@@ -891,33 +624,11 @@ await ctx.integrations.db.execute(
   [userId],
   { label: "Update last login" },
 );
-
-// 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, S3, etc.)
-const doc = await ctx.integrations.mongo.run(
-  "users",
-  "findOne",
-  ResultSchema,
-  { filter: { _id: userId } },
-  { label: "Look up user by ID" },
-);
 ```
 
 ### When to Use
 
-Trace metadata is optional and purely for observability. Use it when:
-
-- You want labeled traces in the diagnostics panel for easier debugging
-- An API makes multiple calls to the same integration and you need to distinguish them
-- You want to document the intent of each integration call for your team
-
-Metadata has no effect on execution - it only appears in diagnostics when `includeDiagnostics` is enabled.
+Trace metadata is optional and has no effect on execution. When `includeDiagnostics` is enabled, use labels and descriptions to distinguish repeated integration calls in the diagnostics panel.
 
 ## Error Handling
 
@@ -984,47 +695,16 @@ try {
 
     // The actual data that failed validation
     console.error('Failed data:', error.details.data);
-
-    // Access Zod utility methods
-    const formatted = error.details.zodError.format();
-    const flattened = error.details.zodError.flatten();
   }
 }
 ```
 
-The `RestApiValidationError` provides complete context for debugging:
-
-- **Full Zod error object** (`zodError`) with all validation information
-- **Validation codes** (e.g., `"invalid_type"`, `"too_small"`, `"invalid_email"`)
-- **Expected vs received** values for type mismatches
-- **Constraint information** (e.g., minimum/maximum values)
-- **The actual data** that failed validation
-- **Utility methods** like `format()` and `flatten()` for different error representations
-
 ## Best Practices
 
 ### Push Filtering Down to the Data Source
 
 Always filter data at the source (database, API) rather than fetching everything and filtering in code. This reduces network transfer, memory usage, and processing time.
 
-**Inefficient - Fetching all rows and filtering in code:**
-
-```typescript
-const AllUsersSchema = z.array(
-  z.object({ id: z.string(), status: z.string(), region: z.string() }),
-);
-
-// Fetches ALL users, then filters - wasteful!
-async run(ctx, { region }) {
-  const allUsers = await ctx.integrations.db.query("SELECT * FROM users", AllUsersSchema);
-  const activeUsersInRegion = allUsers.filter(
-    (u) => u.status === "active" && u.region === region,
-  );
-}
-```
-
-**Efficient - Filtering in the database query:**
-
 ```typescript
 const UserSchema = z.object({
   id: z.string(),
@@ -1042,22 +722,7 @@ async run(ctx, { region }) {
 }
 ```
 
-The same principle applies to REST APIs - use query parameters to filter at the source:
-
-**Inefficient:**
-
-```typescript
-// Fetches all issues, then filters client-side
-const allIssues = await ctx.integrations.repo.apiRequest(
-  { method: "GET", path: "/repos/owner/repo/issues" },
-  { response: IssuesSchema },
-);
-const openBugs = allIssues.filter(
-  (i) => i.state === "open" && i.labels.includes("bug"),
-);
-```
-
-**Efficient:**
+Use query parameters to filter REST API responses at the source:
 
 ```typescript
 // API does the filtering - only matching issues returned
@@ -1075,20 +740,6 @@ const openBugs = await ctx.integrations.repo.apiRequest(
 
 Avoid `SELECT *` in database queries. Fetch only the columns you actually use to reduce data transfer and improve query performance.
 
-**Inefficient:**
-
-```typescript
-// Fetches all columns even though we only need id and email
-const users = await ctx.integrations.db.query(
-  "SELECT * FROM users WHERE status = $1",
-  UserSchema,
-  ["active"],
-);
-const emails = users.map((u) => u.email);
-```
-
-**Efficient:**
-
 ```typescript
 const UserEmailSchema = z.object({ id: z.string(), email: z.string() });
 
@@ -1135,28 +786,7 @@ while (hasMore) {
 
 ### Avoid N+1 Query Patterns
 
-Don't fetch related data one item at a time in a loop. Use JOINs or batch queries instead.
-
-**N+1 Problem - One query per order:**
-
-```typescript
-const orders = await ctx.integrations.db.query(
-  "SELECT * FROM orders",
-  OrderSchema,
-);
-
-// BAD: This makes N additional queries!
-for (const order of orders) {
-  const items = await ctx.integrations.db.query(
-    "SELECT * FROM order_items WHERE order_id = $1",
-    ItemSchema,
-    [order.id],
-  );
-  order.items = items;
-}
-```
-
-**Efficient - Single query with JOIN:**
+Don't fetch related data one item at a time in a loop (the N+1 problem: one query for the parent rows, then one more per row). Use JOINs or batch queries instead.
 
 ```typescript
 const OrderWithItemsSchema = z.object({
@@ -1177,66 +807,11 @@ const rows = await ctx.integrations.db.query(
 );
 ```
 
-**Alternative - Batch fetch with IN clause:**
-
-```typescript
-const orders = await ctx.integrations.db.query(
-  "SELECT * FROM orders",
-  OrderSchema,
-);
-const orderIds = orders.map((o) => o.id);
-
-// Single query for all items
-const items = await ctx.integrations.db.query(
-  "SELECT * FROM order_items WHERE order_id = ANY($1)",
-  ItemSchema,
-  [orderIds],
-);
-```
+When a join does not fit, fetch related rows in one batch with `WHERE id = ANY($1)`.
 
 ### Batch API Requests When Possible
 
-Some APIs support batch operations. Use them instead of making individual requests.
-
-**Inefficient - Individual requests:**
-
-```typescript
-// Makes 100 separate API calls!
-for (const userId of userIds) {
-  await ctx.integrations.notifier.apiRequest(
-    {
-      method: "POST",
-      path: "/chat.postMessage",
-      body: { channel: userId, text: "Hello!" },
-    },
-    { response: MessageSchema },
-  );
-}
-```
-
-**Efficient - Use batch endpoints when available:**
-
-```typescript
-// Check if the API supports batch operations
-// For Slack, consider using chat.postMessage with multiple channel webhooks
-// or processing in controlled parallel batches
-const BATCH_SIZE = 10;
-for (let i = 0; i < userIds.length; i += BATCH_SIZE) {
-  const batch = userIds.slice(i, i + BATCH_SIZE);
-  await Promise.all(
-    batch.map((userId) =>
-      ctx.integrations.notifier.apiRequest(
-        {
-          method: "POST",
-          path: "/chat.postMessage",
-          body: { channel: userId, text: "Hello!" },
-        },
-        { response: MessageSchema },
-      ),
-    ),
-  );
-}
-```
+Prefer a documented batch endpoint. When none exists, cap concurrency with small batches; do not launch one unbounded request per row.
 
 ### Use Precise Schemas
 
@@ -1330,156 +905,6 @@ const getUsers = useApi<typeof GetUsersApi>("GetUsers");
 const listProfiles = useApi<typeof ListProfiles>("ListProfiles");
 ```
 
-## Complete Example
-
-```typescript
-import { api, z, postgres, slack, openai } from "@superblocksteam/sdk-api";
-
-// Integration IDs from the integrations panel
-const PROD_POSTGRES = "a1b2c3d4-5678-90ab-cdef-ghijklmnopqr";
-const OPS_SLACK = "b2c3d4e5-6789-01ab-cdef-ghijklmnopqr";
-const PROD_OPENAI = "c3d4e5f6-7890-12ab-cdef-ghijklmnopqr";
-
-// Define reusable schemas
-const OrderItemSchema = z.object({
-  productId: z.string(),
-  quantity: z.number().int().positive(),
-});
-
-const CompletionRequestSchema = z.object({
-  model: z.string(),
-  messages: z.array(
-    z.object({
-      role: z.string(),
-      content: z.string(),
-    }),
-  ),
-});
-
-const CompletionResponseSchema = z.object({
-  choices: z.array(
-    z.object({
-      message: z.object({
-        content: z.string(),
-      }),
-    }),
-  ),
-});
-
-const CustomerSchema = z.object({
-  id: z.string(),
-  email: z.string().email(),
-});
-
-const SlackPostMessageResponseSchema = z.object({
-  ts: z.string().optional(),
-});
-
-export default api({
-  name: "CreateOrder",
-
-  // Declare all integrations upfront
-  integrations: {
-    db: postgres(PROD_POSTGRES),
-    notifier: slack(OPS_SLACK),
-    ai: openai(PROD_OPENAI),
-  },
-
-  input: z.object({
-    customerId: z.string().uuid(),
-    items: z.array(OrderItemSchema).min(1),
-    sendAiSummary: z.boolean().default(false),
-  }),
-
-  output: z.object({
-    orderId: z.string(),
-    total: z.number(),
-    itemCount: z.number(),
-    aiSummary: z.string().optional(),
-  }),
-
-  async run(ctx, { customerId, items, sendAiSummary }) {
-    ctx.log.info("Creating order", { customerId, itemCount: items.length });
-
-    // Get customer from database
-    const customers = await ctx.integrations.db.query(
-      "SELECT id, email FROM customers WHERE id = $1",
-      CustomerSchema,
-      [customerId],
-    );
-    const customer = customers[0];
-
-    if (!customer) {
-      throw new Error(`Customer not found: ${customerId}`);
-    }
-
-    // Calculate total
-    const total = items.reduce((sum, item) => {
-      // In real code, you'd look up prices
-      return sum + item.quantity * 10;
-    }, 0);
-
-    // Insert order
-    await ctx.integrations.db.execute(
-      "INSERT INTO orders (customer_id, total, item_count) VALUES ($1, $2, $3)",
-      [customerId, total, items.length],
-    );
-
-    const orderId = `ord_${Date.now()}`;
-
-    // Notify via Slack
-    const slackResult = await ctx.integrations.notifier.apiRequest(
-      {
-        method: "POST",
-        path: "/chat.postMessage",
-        body: {
-          channel: "#orders",
-          text: `New order ${orderId} from ${customer.email}: $${total.toFixed(2)}`,
-        },
-      },
-      { 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: "/chat/completions",
-          body: {
-            model: "gpt-4",
-            messages: [
-              {
-                role: "user",
-                content: `Summarize this order: ${items.length} items, total $${total}`,
-              },
-            ],
-          },
-        },
-        {
-          body: CompletionRequestSchema,
-          response: CompletionResponseSchema,
-        },
-      );
-
-      aiSummary = completion.choices[0]?.message.content;
-    }
-
-    return {
-      orderId,
-      total,
-      itemCount: items.length,
-      aiSummary,
-    };
-  },
-});
-```
-
 ## Development
 
 ```bash