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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superblocksteam/sdk-api",
-  "version": "2.0.106-next.0",
+  "version": "2.0.106-next.1",
   "description": "Superblocks SDK for TypeScript-based API definitions",
   "license": "Superblocks Community Software License",
   "files": [

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/)