@superblocksteam/sdk-api 0.0.6 → 0.0.7

package/src/integrations/mongodb/README.md

@@ -79,16 +79,21 @@ const UserSchema = z
     name: z.string(),
     email: z.string(),
   })
-  .nullable();
+  .nullable()
+  .optional();
 
 const user = await ctx.integrations.mongodb.run(
   "users",
   "findOne",
   UserSchema,
   {
-    query: { _id: userId },
+    query: { _id: { $oid: userId } },
   },
 );
+
+// findOne returns undefined (not null) when no document matches,
+// so use .nullable().optional() and coalesce if needed:
+const result = user ?? null;
 ```
 
 ### Insert Document
@@ -116,8 +121,8 @@ const result = await ctx.integrations.mongodb.run(
 
 ```typescript
 const UpdateResultSchema = z.object({
-  matchedCount: z.number(),
-  modifiedCount: z.number(),
+  matchedCount: z.coerce.number(),
+  modifiedCount: z.coerce.number(),
 });
 
 const result = await ctx.integrations.mongodb.run(
@@ -125,7 +130,7 @@ const result = await ctx.integrations.mongodb.run(
   "updateOne",
   UpdateResultSchema,
   {
-    filter: { _id: userId },
+    filter: { _id: { $oid: userId } },
     update: {
       $set: { status: "active", updatedAt: new Date().toISOString() },
     },
@@ -137,7 +142,7 @@ const result = await ctx.integrations.mongodb.run(
 
 ```typescript
 const DeleteResultSchema = z.object({
-  deletedCount: z.number(),
+  deletedCount: z.coerce.number(),
 });
 
 const result = await ctx.integrations.mongodb.run(
@@ -145,7 +150,7 @@ const result = await ctx.integrations.mongodb.run(
   "deleteOne",
   DeleteResultSchema,
   {
-    filter: { _id: userId },
+    filter: { _id: { $oid: userId } },
   },
 );
 ```
@@ -156,8 +161,8 @@ const result = await ctx.integrations.mongodb.run(
 const AggregateResultSchema = z.array(
   z.object({
     _id: z.string(),
-    count: z.number(),
-    totalAmount: z.number(),
+    count: z.coerce.number(),
+    totalAmount: z.coerce.number(),
   }),
 );
 
@@ -183,9 +188,14 @@ const result = await ctx.integrations.mongodb.run(
 ### Count Documents
 
 ```typescript
-const count = await ctx.integrations.mongodb.run("users", "count", z.number(), {
-  query: { status: "active" },
-});
+const count = await ctx.integrations.mongodb.run(
+  "users",
+  "count",
+  z.coerce.number(),
+  {
+    query: { status: "active" },
+  },
+);
 ```
 
 ### Find with Projection and Sort
@@ -245,6 +255,49 @@ try {
 }
 ```
 
+## Gotchas
+
+### Numeric fields are returned as strings
+
+MongoDB numeric values (e.g. `int32`, `int64`, `double`) are returned as strings by the integration. Using `z.number()` in your schema will fail with `"Expected number, received string"`. Use `z.coerce.number()` instead to automatically convert string values to numbers:
+
+```typescript
+// ❌ Will fail — MongoDB returns numbers as strings
+const Schema = z.object({ rating: z.number() });
+
+// ✅ Correct — coerces string values to numbers
+const Schema = z.object({ rating: z.coerce.number() });
+```
+
+### ObjectId fields require `$oid` syntax
+
+When querying by `_id` or any ObjectId field, passing a plain string does not match. You must wrap the value using MongoDB Extended JSON `$oid` syntax:
+
+```typescript
+// ❌ Will not match — returns null/undefined
+const bad = { query: { _id: userId } };
+
+// ✅ Correct — uses Extended JSON $oid wrapper
+const good = { query: { _id: { $oid: userId } } };
+```
+
+This applies to `findOne`, `updateOne`, `deleteOne`, and any operation filtering by ObjectId fields.
+
+### `findOne` returns `undefined` when no document matches
+
+When no document is found, `findOne` returns `undefined` rather than `null`. If your schema uses only `.nullable()`, Zod will reject `undefined` with `"Expected object, received undefined"`. Use `.nullable().optional()` to handle both cases:
+
+```typescript
+// ❌ Will fail when no document matches
+const Schema = z.object({ name: z.string() }).nullable();
+
+// ✅ Correct — handles both null and undefined
+const Schema = z.object({ name: z.string() }).nullable().optional();
+
+// Coalesce to null if needed
+const result = (await ctx.integrations.mongodb.run(...)) ?? null;
+```
+
 ## API Reference
 
 - [MongoDB Manual](https://www.mongodb.com/docs/manual/)

package/src/integrations/mongodb/client.ts

@@ -4,13 +4,15 @@
  * Uses the native MongoDB plugin type from @superblocksteam/types.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as MongoDBPlugin } from "@superblocksteam/types/dist/src/plugins/mongodb/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { RestApiValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import type { MongoDBClient, MongoDBAction, MongoDBParams } from "./types.js";
 
 /**

package/src/integrations/mongodb/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "mongodb",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/mongodb/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 

package/src/integrations/mssql/README.md

@@ -39,7 +39,7 @@ export default api({
   }),
   async run(ctx, { status }) {
     const users = await ctx.integrations.mssql.query(
-      "SELECT id, name, email, created_at FROM users WHERE status = $1",
+      "SELECT id, name, email, created_at FROM users WHERE status = @PARAM_1",
       UserSchema,
       [status],
     );
@@ -54,13 +54,13 @@ export default api({
 ```typescript
 // INSERT
 await ctx.integrations.mssql.execute(
-  "INSERT INTO users (name, email) VALUES ($1, $2)",
+  "INSERT INTO users (name, email) VALUES (@PARAM_1, @PARAM_2)",
   ["John Doe", "john@example.com"],
 );
 
 // UPDATE
 const updateResult = await ctx.integrations.mssql.execute(
-  "UPDATE users SET last_login = GETDATE() WHERE id = $1",
+  "UPDATE users SET last_login = GETDATE() WHERE id = @PARAM_1",
   [userId],
 );
 console.log(`Updated ${updateResult.rowCount} rows`);

package/src/integrations/mssql/client.ts

@@ -5,13 +5,15 @@
  * runtime validation using Zod schemas.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as MSSQLPlugin } from "@superblocksteam/types/dist/src/plugins/mssql/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { QueryValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import { describeType } from "../utils.js";
 import type { MSSQLClient } from "./types.js";
 

package/src/integrations/mssql/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "mssql",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/mssql/types.ts

@@ -5,6 +5,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 
@@ -24,7 +25,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const users = await mssql.query(
- *   'SELECT * FROM users WHERE status = $1',
+ *   'SELECT * FROM users WHERE status = @PARAM_1',
  *   UserSchema,
  *   ['active']
  * );
@@ -34,7 +35,7 @@ export interface MSSQLClient extends BaseIntegrationClient {
   /**
    * Execute a SQL query and validate results against a Zod schema.
    *
-   * @param sql - SQL query string (use $1, $2, etc. for parameters)
+   * @param sql - SQL query string (use @PARAM_1, @PARAM_2, etc. for parameters)
    * @param schema - Zod schema to validate the query results
    * @param params - Optional query parameters
    * @returns Promise resolving to validated query results

package/src/integrations/mysql/README.md

@@ -39,7 +39,7 @@ export default api({
   }),
   async run(ctx, { status }) {
     const users = await ctx.integrations.mysql.query(
-      "SELECT id, name, email, created_at FROM users WHERE status = $1",
+      "SELECT id, name, email, created_at FROM users WHERE status = ?",
       UserSchema,
       [status],
     );
@@ -54,13 +54,13 @@ export default api({
 ```typescript
 // INSERT
 await ctx.integrations.mysql.execute(
-  "INSERT INTO users (name, email) VALUES ($1, $2)",
+  "INSERT INTO users (name, email) VALUES (?, ?)",
   ["John Doe", "john@example.com"],
 );
 
 // UPDATE
 const updateResult = await ctx.integrations.mysql.execute(
-  "UPDATE users SET last_login = NOW() WHERE id = $1",
+  "UPDATE users SET last_login = NOW() WHERE id = ?",
   [userId],
 );
 console.log(`Updated ${updateResult.rowCount} rows`);
@@ -90,7 +90,7 @@ const orders = await ctx.integrations.mysql.query(
     c.email as customer_email
   FROM orders o
   JOIN customers c ON o.customer_id = c.id
-  WHERE o.status = $1`,
+  WHERE o.status = ?`,
   OrderWithCustomerSchema,
   ["pending"],
 );

package/src/integrations/mysql/client.ts

@@ -5,13 +5,15 @@
  * runtime validation using Zod schemas.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as MySQLPlugin } from "@superblocksteam/types/dist/src/plugins/mysql/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { QueryValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import { describeType } from "../utils.js";
 import type { MySQLClient } from "./types.js";
 

package/src/integrations/mysql/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "mysql",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/mysql/types.ts

@@ -5,6 +5,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 
@@ -24,7 +25,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const users = await mysql.query(
- *   'SELECT * FROM users WHERE status = $1',
+ *   'SELECT * FROM users WHERE status = ?',
  *   UserSchema,
  *   ['active']
  * );
@@ -34,7 +35,7 @@ export interface MySQLClient extends BaseIntegrationClient {
   /**
    * Execute a SQL query and validate results against a Zod schema.
    *
-   * @param sql - SQL query string (use $1, $2, etc. for parameters)
+   * @param sql - SQL query string (use ? placeholders for parameters)
    * @param schema - Zod schema to validate the query results
    * @param params - Optional query parameters
    * @returns Promise resolving to validated query results
@@ -51,7 +52,7 @@ export interface MySQLClient extends BaseIntegrationClient {
    * });
    *
    * const users = await mysql.query(
-   *   'SELECT * FROM users WHERE status = $1',
+   *   'SELECT * FROM users WHERE status = ?',
    *   UserSchema,
    *   ['active']
    * );
@@ -74,7 +75,7 @@ export interface MySQLClient extends BaseIntegrationClient {
    * @example
    * ```typescript
    * const result = await mysql.execute(
-   *   'UPDATE users SET last_login = NOW() WHERE id = $1',
+   *   'UPDATE users SET last_login = NOW() WHERE id = ?',
    *   [userId]
    * );
    * console.log(`Updated ${result.rowCount} rows`);

package/src/integrations/notion/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "notion",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/openai_v2/README.md

@@ -4,14 +4,15 @@ Interact with OpenAI's APIs for chat completions, embeddings, image generation,
 
 ## Methods
 
-| Method                                         | Description                                        |
-| ---------------------------------------------- | -------------------------------------------------- |
-| `apiRequest(options, schema, metadata?)`       | Make any OpenAI API request with schema validation |
-| `streamApiRequest(options, schema, metadata?)` | Stream responses with real-time chunk validation   |
+| Method                                   | Description                                        |
+| ---------------------------------------- | -------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any OpenAI API request with schema validation |
 
 ## Usage
 
-### Chat Completion
+### Step 1: List Available Models
+
+Model availability depends on your OpenAI account and API tier. Before making requests, validate which models you can access:
 
 ```typescript
 import { api, z, openai } from "@superblocksteam/sdk-api";
@@ -19,6 +20,30 @@ import { api, z, openai } from "@superblocksteam/sdk-api";
 // Integration ID from the integrations panel
 const PROD_OPENAI = "a1b2c3d4-5678-90ab-cdef-333333333333";
 
+const ModelsResponseSchema = z.object({
+  data: z.array(
+    z.object({
+      id: z.string(),
+      object: z.string(),
+    }),
+  ),
+});
+
+const models = await ctx.integrations.ai.apiRequest(
+  {
+    method: "GET",
+    path: "/models",
+  },
+  { response: ModelsResponseSchema },
+);
+
+// Use a model ID from the response in subsequent requests
+const availableModelId = models.data[0]?.id;
+```
+
+### Chat Completion
+
+```typescript
 const ChatCompletionResponseSchema = z.object({
   id: z.string(),
   object: z.literal("chat.completion"),
@@ -56,7 +81,7 @@ export default api({
     const result = await ctx.integrations.ai.apiRequest(
       {
         method: "POST",
-        path: "/v1/chat/completions",
+        path: "/chat/completions",
         body: {
           model: "gpt-4",
           messages: [
@@ -105,7 +130,7 @@ const FunctionCallResponseSchema = z.object({
 const result = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "gpt-4",
       messages: [
@@ -161,7 +186,7 @@ const EmbeddingsResponseSchema = z.object({
 const embeddings = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
-    path: "/v1/embeddings",
+    path: "/embeddings",
     body: {
       model: "text-embedding-3-small",
       input: ["Hello world", "How are you?"],
@@ -192,7 +217,7 @@ const ImageResponseSchema = z.object({
 const images = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
-    path: "/v1/images/generations",
+    path: "/images/generations",
     body: {
       model: "dall-e-3",
       prompt: "A serene mountain landscape at sunset",
@@ -215,7 +240,7 @@ const imageUrl = images.data[0]?.url;
 const ttsResult = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
-    path: "/v1/audio/speech",
+    path: "/audio/speech",
     body: {
       model: "tts-1",
       input: "Hello, how are you today?",
@@ -226,91 +251,6 @@ const ttsResult = await ctx.integrations.ai.apiRequest(
 );
 ```
 
-### Streaming Chat Completions
-
-For real-time token streaming, use `streamApiRequest()` with `stream: true`:
-
-```typescript
-import { streamingApi, z, openai } from "@superblocksteam/sdk-api";
-
-// Integration ID from the integrations panel
-const PROD_OPENAI = "a1b2c3d4-5678-90ab-cdef-333333333333";
-
-// Schema for OpenAI's streaming SSE chunks
-const OpenAIStreamChunkSchema = z.object({
-  id: z.string(),
-  object: z.literal("chat.completion.chunk"),
-  created: z.number(),
-  model: z.string(),
-  choices: z.array(
-    z.object({
-      index: z.number(),
-      delta: z.object({
-        role: z.string().optional(),
-        content: z.string().optional(),
-      }),
-      finish_reason: z.string().nullable(),
-    }),
-  ),
-});
-
-export default streamingApi({
-  integrations: {
-    ai: openai(PROD_OPENAI),
-  },
-
-  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/chat/completions",
-        body: {
-          model: "gpt-4",
-          stream: true, // Enable streaming
-          messages: [
-            { role: "system", content: "You are a helpful assistant." },
-            { role: "user", content: prompt },
-          ],
-        },
-      },
-      { chunk: OpenAIStreamChunkSchema },
-    );
-
-    // Yield text chunks as they arrive
-    for await (const chunk of stream) {
-      const content = chunk.choices[0]?.delta?.content;
-      if (content) {
-        yield { type: "text" as const, text: content };
-      }
-    }
-  },
-});
-```
-
-#### Streaming Chunk Structure
-
-OpenAI's streaming chunks have this structure:
-
-```typescript
-{
-  id: "chatcmpl-...",
-  object: "chat.completion.chunk",
-  created: 1234567890,
-  model: "gpt-4",
-  choices: [{
-    index: 0,
-    delta: {
-      role: "assistant",  // Only in first chunk
-      content: "Hello"    // Incremental text
-    },
-    finish_reason: null   // "stop" in final chunk
-  }]
-}
-```
-
 ## Trace Metadata
 
 All methods accept an optional `metadata` parameter as the last argument for diagnostics labeling. See the [root SDK README](../../../README.md#trace-metadata) for details.
@@ -319,7 +259,7 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 
 ### No Specialized Methods
 
-The OpenAI client only provides `apiRequest()`. There are no SDK-specific methods:
+The OpenAI client only provides `apiRequest()`. There are no other specialized methods:
 
 ```typescript
 // WRONG - These methods do not exist
@@ -328,7 +268,7 @@ await openai.createEmbedding({ ... });
 
 // CORRECT - Use apiRequest for all operations
 await ctx.integrations.ai.apiRequest(
-  { method: "POST", path: "/v1/chat/completions", body: { ... } },
+  { method: "POST", path: "/chat/completions", body: { ... } },
   { response: ResponseSchema }
 );
 ```
@@ -341,13 +281,13 @@ You must always provide a response schema:
 // WRONG - Missing response schema
 const result = await ctx.integrations.ai.apiRequest({
   method: "POST",
-  path: "/v1/chat/completions",
+  path: "/chat/completions",
   body: { ... },
 });
 
 // CORRECT - Include response schema
 const result = await ctx.integrations.ai.apiRequest(
-  { method: "POST", path: "/v1/chat/completions", body: { ... } },
+  { method: "POST", path: "/chat/completions", body: { ... } },
   { response: ChatCompletionResponseSchema }
 );
 ```
@@ -389,7 +329,7 @@ Some features require beta headers:
 const result = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
-    path: "/v1/assistants",
+    path: "/assistants",
     body: { ... },
     headers: {
       "OpenAI-Beta": "assistants=v2",
@@ -419,7 +359,7 @@ async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
 
 const result = await withRetry(() =>
   ctx.integrations.ai.apiRequest(
-    { method: "POST", path: "/v1/chat/completions", body: { ... } },
+    { method: "POST", path: "/chat/completions", body: { ... } },
     { response: ChatCompletionResponseSchema }
   )
 );
@@ -441,7 +381,7 @@ Be aware of model token limits:
 const result = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "gpt-4",
       messages: [...],
@@ -455,11 +395,11 @@ const result = await ctx.integrations.ai.apiRequest(
 ## Error Handling
 
 ```typescript
-import { RestApiValidationError, StreamChunkValidationError } from "@superblocksteam/sdk-api";
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
   const result = await ctx.integrations.ai.apiRequest(
-    { method: "POST", path: "/v1/chat/completions", body: { ... } },
+    { method: "POST", path: "/chat/completions", body: { ... } },
     { response: ChatCompletionResponseSchema }
   );
 } catch (error) {
@@ -468,18 +408,6 @@ try {
     console.error("Actual response:", error.details.data);
   }
 }
-
-// For streaming requests
-try {
-  for await (const chunk of stream) {
-    // Process chunk
-  }
-} catch (error) {
-  if (error instanceof StreamChunkValidationError) {
-    console.error("Chunk validation failed at index:", error.details.chunkIndex);
-    console.error("Raw chunk:", error.details.chunk);
-  }
-}
 ```
 
 ## API Reference

package/src/integrations/openai_v2/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "openai_v2",
+  "base": "README.md",
+  "overlays": []
+}