@superblocksteam/sdk-api 0.0.12 → 0.0.13

package/src/integrations/restapiintegration/overlays/request-body-types.md

@@ -0,0 +1,115 @@
+## Request Body Types
+
+`apiRequest()` serializes request bodies as JSON by default. For endpoints that expect another encoding, pass `bodyType`:
+
+- `"json"` for JSON payloads. This is the default.
+- `"raw"` for caller-encoded string bodies such as XML, CSV, or plain text.
+- `"formUrlencoded"` for `application/x-www-form-urlencoded` payloads.
+- `"multipartForm"` for multipart fields and file parts.
+- `"binary"` for byte payloads. Pass bytes such as a `Uint8Array`, `ArrayBuffer`, `DataView`, or `Buffer`.
+
+### Form URL-Encoded Requests
+
+Use `bodyType: "formUrlencoded"` for OAuth token exchanges and other APIs that expect HTML form encoding. Arrays repeat the key, so `tags: ["a", "b"]` encodes as `tags=a&tags=b`. APIs that expect bracket keys need the brackets in the key, and nested fields must be flattened with bracket notation:
+
+```typescript
+const token = await ctx.integrations.authApi.apiRequest(
+  {
+    method: "POST",
+    path: "/oauth/token",
+    bodyType: "formUrlencoded",
+    body: {
+      grant_type: "client_credentials",
+      client_id: input.clientId,
+      scope: "read:orders write:orders",
+    },
+  },
+  { response: TokenResponseSchema },
+);
+
+const order = await ctx.integrations.ordersApi.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/orders",
+    bodyType: "formUrlencoded",
+    body: {
+      amount: 2000,
+      currency: "usd",
+      "metadata[order_id]": "6735",
+    },
+  },
+  { response: OrderResponseSchema },
+);
+```
+
+The SDK adds `Content-Type: application/x-www-form-urlencoded` unless you already provided a `Content-Type` header.
+Fields whose value is `undefined` are omitted. Empty arrays are omitted. The body must encode at least one field.
+
+### Binary Uploads
+
+Use `bodyType: "binary"` for APIs that accept the request body as bytes, such as SharePoint-style upload endpoints. For an uploaded file, pass the `Uint8Array` returned by `await file.readContentsAsync("raw")` directly as the body:
+
+```typescript
+const file = input.upload.files[0];
+
+await ctx.integrations.sharepoint.apiRequest(
+  {
+    method: "PUT",
+    path: `/sites/${siteId}/drive/root:/reports/${file.name}:/content`,
+    bodyType: "binary",
+    body: await file.readContentsAsync("raw"),
+    headers: { "Content-Type": file.type || "application/octet-stream" },
+  },
+  { response: UploadResponseSchema },
+);
+```
+
+For bytes that do not come from an uploaded file, pass a byte container supported by the SDK, such as `Uint8Array`, `ArrayBuffer`, `DataView`, or `Buffer`. Do not convert file bytes to a string. `readContentsAsync("binary")` returns base64 text, not bytes. Never send that text as a file body. Use `readContentsAsync("raw")` instead. If only base64 text is available, decode it with `Buffer.from(text, "base64")` and send the result with `bodyType: "binary"`.
+
+The SDK sends the exact byte window of a byte view, so `bytes.subarray(start, end)` uploads a slice. It adds `Content-Type: application/octet-stream` unless you already provided a `Content-Type` header such as `application/pdf`.
+
+Binary request bodies must be non-empty; a zero-length body throws a validation error.
+
+### Multipart Uploads
+
+Use `bodyType: "multipartForm"` for endpoints that expect fields plus file parts. File parts must be wrapped as `{ value, filename }`; a bare binary value without that wrapper is rejected with a message naming the required `{ value, filename }` shape. A file part `value` is a string or bytes such as the `Uint8Array` returned by `await file.readContentsAsync("raw")`. `readContentsAsync("binary")` returns base64 text, not bytes; never pass that text as a file part value, it will be UTF-8 encoded a second time and silently corrupt the upload. Use `readContentsAsync("raw")` for file part bytes.
+
+```typescript
+const invoice = input.upload.files[0];
+
+const upload = await ctx.integrations.filesApi.apiRequest(
+  {
+    method: "POST",
+    path: "/files",
+    bodyType: "multipartForm",
+    body: {
+      folder: "invoices",
+      invoice: {
+        value: await invoice.readContentsAsync("raw"),
+        filename: invoice.name,
+      },
+    },
+  },
+  { response: UploadResponseSchema },
+);
+```
+
+Do not set `Content-Type` for multipart requests. The worker generates the multipart boundary during execution.
+Do not set per-part `contentType`. Arrays repeat the key, so `files: [partA, partB]` sends two `files` parts. Fields whose value is `undefined` are omitted. Empty file parts are allowed.
+
+### Raw String Bodies
+
+Use `bodyType: "raw"` for pre-encoded text bodies. The SDK does not add a `Content-Type` header in raw mode, so provide the header expected by the API. Prefer `"json"`, `"formUrlencoded"`, `"multipartForm"`, or `"binary"` when the target API fits one of those shapes; reach for `"raw"` only when the API needs a pre-encoded format none of the typed body types cover, such as SOAP/XML or a signed payload:
+
+```typescript
+await ctx.integrations.legacyApi.apiRequest(
+  {
+    method: "POST",
+    path: "/soap",
+    bodyType: "raw",
+    body: `<Envelope><Body>${payload}</Body></Envelope>`,
+    headers: { "Content-Type": "text/xml" },
+  },
+  { response: SoapResponseSchema },
+);
+```

package/src/integrations/s3/client.ts

@@ -9,7 +9,10 @@ import type { z } from "zod";
 
 import type { Plugin as S3Plugin } from "@superblocksteam/types/dist/src/plugins/s3/v1/plugin_pb";
 
-import { RestApiValidationError } from "../../errors.js";
+import {
+  RestApiValidationError,
+  restApiValidationErrorFromZodError,
+} from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
 import type { QueryExecutor, TraceMetadata } from "../registry.js";
 import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
@@ -71,12 +74,10 @@ export class S3ClientImpl implements S3Client, IntegrationClientImpl {
     const parseResult = schema.safeParse(result);
 
     if (!parseResult.success) {
-      throw new RestApiValidationError(
-        `Result validation failed: ${parseResult.error.message}`,
-        {
-          zodError: parseResult.error,
-          data: result,
-        },
+      throw restApiValidationErrorFromZodError(
+        "Result validation failed",
+        parseResult.error,
+        result,
       );
     }
 

package/src/integrations/salesforce/client.ts

@@ -7,7 +7,11 @@
 
 import type { z } from "zod";
 
-import { QueryValidationError, RestApiValidationError } from "../../errors.js";
+import {
+  QueryValidationError,
+  RestApiValidationError,
+  restApiValidationErrorFromZodError,
+} from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
 import type { QueryExecutor, TraceMetadata } from "../registry.js";
 import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
@@ -205,12 +209,10 @@ export class SalesforceClientImpl
 
     const parseResult = schema.safeParse(result);
     if (!parseResult.success) {
-      throw new RestApiValidationError(
-        `Result validation failed: ${parseResult.error.message}`,
-        {
-          zodError: parseResult.error,
-          data: result,
-        },
+      throw restApiValidationErrorFromZodError(
+        "Result validation failed",
+        parseResult.error,
+        result,
       );
     }
 

package/src/integrations/slack/client.test.ts

@@ -307,6 +307,36 @@ describe("SlackClientImpl", () => {
       expect(request.params).toEqual([{ key: "unfurl_links", value: "false" }]);
     });
 
+    it("sends formUrlencoded bodies through the shared request builder", async () => {
+      const { client, executeQuery } = createClient({
+        ok: true,
+        channel: "C123",
+        ts: "1234567890.123456",
+      });
+
+      await client.apiRequest(
+        {
+          method: "POST",
+          path: "/chat.postMessage",
+          body: { channel: "#alerts", text: "hello" },
+          bodyType: "formUrlencoded",
+        },
+        { response: PostMessageSchema },
+      );
+
+      expect(executeQuery).toHaveBeenCalledWith(
+        expect.objectContaining({
+          body: expect.any(String),
+          bodyType: "rawBody",
+          headers: [
+            { key: "Content-Type", value: "application/x-www-form-urlencoded" },
+          ],
+        }),
+        undefined,
+        undefined,
+      );
+    });
+
     it("passes trace metadata to executeQuery", async () => {
       const { client, executeQuery } = createClient({
         ok: true,

package/src/integrations/slack/client.ts

@@ -8,7 +8,7 @@
 
 import type { z } from "zod";
 
-import { RestApiValidationError } from "../../errors.js";
+import { restApiValidationErrorFromZodError } from "../../errors.js";
 import { RestApiClientBase } from "../base/rest-api-client-base.js";
 import type { ApiRequestOptions } from "../base/types.js";
 import type { TraceMetadata } from "../registry.js";
@@ -51,24 +51,20 @@ export class SlackClientImpl extends RestApiClientBase implements SlackClient {
       "ok" in result &&
       (result as Record<string, unknown>).ok === false
     ) {
-      throw new RestApiValidationError(
-        `Slack returned ok: false but the response did not match the expected error shape: ${errorResult.error.message}`,
-        {
-          zodError: errorResult.error,
-          data: result,
-        },
+      throw restApiValidationErrorFromZodError(
+        "Slack returned ok: false but the response did not match the expected error shape",
+        errorResult.error,
+        result,
       );
     }
 
     // Success responses must carry the Slack envelope discriminant.
     const successEnvelopeResult = SlackSuccessEnvelopeSchema.safeParse(result);
     if (!successEnvelopeResult.success) {
-      throw new RestApiValidationError(
-        `Slack success response is missing the expected ok: true envelope: ${successEnvelopeResult.error.message}`,
-        {
-          zodError: successEnvelopeResult.error,
-          data: result,
-        },
+      throw restApiValidationErrorFromZodError(
+        "Slack success response is missing the expected ok: true envelope",
+        successEnvelopeResult.error,
+        result,
       );
     }
 
@@ -81,12 +77,10 @@ export class SlackClientImpl extends RestApiClientBase implements SlackClient {
 
     const payloadResult = schema.response.safeParse(payloadCandidate);
     if (!payloadResult.success) {
-      throw new RestApiValidationError(
-        `Response validation failed: ${payloadResult.error.message}`,
-        {
-          zodError: payloadResult.error,
-          data: result,
-        },
+      throw restApiValidationErrorFromZodError(
+        "Response validation failed",
+        payloadResult.error,
+        result,
       );
     }
 

package/src/integrations/stabilityai/README.md

@@ -79,84 +79,6 @@ export default api({
 });
 ```
 
-### Image-to-Image (Transform Existing Image)
-
-```typescript
-const result = await ctx.integrations.stability.apiRequest(
-  {
-    method: "POST",
-    path: "/v1/generation/stable-diffusion-xl-1024-v1-0/image-to-image",
-    headers: {
-      "Content-Type": "multipart/form-data",
-    },
-    body: {
-      init_image: sourceImageBase64,
-      text_prompts: [{ text: "A vibrant oil painting style", weight: 1 }],
-      image_strength: 0.35, // How much to modify (0-1)
-      cfg_scale: 7,
-      samples: 1,
-      steps: 30,
-    },
-  },
-  { response: GenerationResponseSchema },
-);
-```
-
-### Upscale an Image
-
-```typescript
-const UpscaleResponseSchema = z.object({
-  artifacts: z.array(
-    z.object({
-      base64: z.string(),
-      finishReason: z.string(),
-      seed: z.number(),
-    }),
-  ),
-});
-
-const result = await ctx.integrations.stability.apiRequest(
-  {
-    method: "POST",
-    path: "/v1/generation/esrgan-v1-x2plus/image-to-image/upscale",
-    headers: {
-      "Content-Type": "multipart/form-data",
-    },
-    body: {
-      image: sourceImageBase64,
-      width: 2048, // Target width (optional)
-    },
-  },
-  { response: UpscaleResponseSchema },
-);
-
-const upscaledImage = result.artifacts[0].base64;
-```
-
-### Inpainting (Edit Parts of an Image)
-
-```typescript
-const result = await ctx.integrations.stability.apiRequest(
-  {
-    method: "POST",
-    path: "/v1/generation/stable-diffusion-xl-1024-v1-0/image-to-image/masking",
-    headers: {
-      "Content-Type": "multipart/form-data",
-    },
-    body: {
-      init_image: sourceImageBase64,
-      mask_image: maskImageBase64, // White areas will be regenerated
-      mask_source: "MASK_IMAGE_WHITE",
-      text_prompts: [{ text: "A golden retriever sitting", weight: 1 }],
-      cfg_scale: 7,
-      samples: 1,
-      steps: 30,
-    },
-  },
-  { response: GenerationResponseSchema },
-);
-```
-
 ### Generate with Specific Style
 
 ```typescript
@@ -263,12 +185,6 @@ The engine/model ID is part of the URL path:
 // Text-to-image with SDXL 1.0
 const path = "/v1/generation/stable-diffusion-xl-1024-v1-0/text-to-image";
 
-// Image-to-image
-const path = "/v1/generation/stable-diffusion-xl-1024-v1-0/image-to-image";
-
-// Upscaling
-const path = "/v1/generation/esrgan-v1-x2plus/image-to-image/upscale";
-
 // Available engines:
 // - stable-diffusion-xl-1024-v1-0 (SDXL 1.0)
 // - stable-diffusion-v1-6
@@ -402,9 +318,6 @@ const imageBase64 = result.artifacts[0].base64;
 
 // To save or display, you may need to add data URL prefix
 const dataUrl = `data:image/png;base64,${imageBase64}`;
-
-// For input images (image-to-image), provide raw base64 without prefix
-const inputImage = rawBase64WithoutPrefix;
 ```
 
 ### Seed for Reproducibility

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

@@ -1,5 +1,14 @@
 {
   "pluginId": "stabilityai",
   "base": "README.md",
-  "overlays": []
+  "overlays": [
+    {
+      "file": "overlays/image-uploads.md",
+      "sdkVersionRange": ">=0.0.7"
+    },
+    {
+      "file": "overlays/image-uploads-unsupported.md",
+      "sdkVersionRange": "<0.0.7"
+    }
+  ]
 }

package/src/integrations/stabilityai/overlays/image-uploads-unsupported.md

@@ -0,0 +1,3 @@
+## Image-to-Image, Upscale, and Inpainting
+
+The `/image-to-image`, `/image-to-image/upscale`, and `/image-to-image/masking` endpoints require `multipart/form-data`. This agent's sdk-api cannot upload images to them through `apiRequest()` because it serializes every body as JSON. Do not generate image-to-image, upscale, or inpainting code until the agent is upgraded. Text-to-image, account balance, and engine listing work as documented above.

package/src/integrations/stabilityai/overlays/image-uploads.md

@@ -0,0 +1,120 @@
+## Image-to-Image, Upscale, and Inpainting
+
+The `/image-to-image`, `/image-to-image/upscale`, and `/image-to-image/masking` endpoints expect `multipart/form-data`, so pass `bodyType: "multipartForm"`. Image parts are `{ value, filename }` with raw bytes. Multipart fields are flat, so `text_prompts` uses bracketed keys such as `"text_prompts[0][text]"`. Do not set `Content-Type`. The worker generates the multipart boundary.
+
+For an uploaded file, pass `await file.readContentsAsync("raw")` as the part value. For an image returned by a previous generation, decode its `base64` artifact with `Buffer.from(artifact.base64, "base64")`.
+
+The engine/model ID is part of the URL path:
+
+```typescript
+// Image-to-image
+const path = "/v1/generation/stable-diffusion-xl-1024-v1-0/image-to-image";
+
+// Upscaling
+const path = "/v1/generation/esrgan-v1-x2plus/image-to-image/upscale";
+```
+
+### Image-to-Image (Transform Existing Image)
+
+```typescript
+const source = input.upload.files[0];
+
+const result = await ctx.integrations.stability.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/generation/stable-diffusion-xl-1024-v1-0/image-to-image",
+    bodyType: "multipartForm",
+    body: {
+      init_image: {
+        value: await source.readContentsAsync("raw"),
+        filename: source.name,
+      },
+      "text_prompts[0][text]": "A vibrant oil painting style",
+      "text_prompts[0][weight]": 1,
+      image_strength: 0.35, // How much to modify (0-1)
+      cfg_scale: 7,
+      samples: 1,
+      steps: 30,
+    },
+  },
+  { response: GenerationResponseSchema },
+);
+```
+
+### Upscale an Image
+
+```typescript
+const UpscaleResponseSchema = z.object({
+  artifacts: z.array(
+    z.object({
+      base64: z.string(),
+      finishReason: z.string(),
+      seed: z.number(),
+    }),
+  ),
+});
+
+// Response of an earlier text-to-image apiRequest call.
+const generated = await ctx.integrations.stability.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/generation/stable-diffusion-xl-1024-v1-0/text-to-image",
+    body: {
+      text_prompts: [{ text: "A vibrant oil painting style", weight: 1 }],
+      cfg_scale: 7,
+      samples: 1,
+      steps: 30,
+    },
+  },
+  { response: GenerationResponseSchema },
+);
+
+const result = await ctx.integrations.stability.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/generation/esrgan-v1-x2plus/image-to-image/upscale",
+    bodyType: "multipartForm",
+    body: {
+      image: {
+        value: Buffer.from(generated.artifacts[0].base64, "base64"),
+        filename: "generated.png",
+      },
+      width: 2048, // Target width (optional)
+    },
+  },
+  { response: UpscaleResponseSchema },
+);
+
+const upscaledImage = result.artifacts[0].base64;
+```
+
+### Inpainting (Edit Parts of an Image)
+
+```typescript
+const [source, mask] = input.upload.files;
+
+const result = await ctx.integrations.stability.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/generation/stable-diffusion-xl-1024-v1-0/image-to-image/masking",
+    bodyType: "multipartForm",
+    body: {
+      init_image: {
+        value: await source.readContentsAsync("raw"),
+        filename: source.name,
+      },
+      mask_image: {
+        value: await mask.readContentsAsync("raw"),
+        filename: mask.name,
+      },
+      mask_source: "MASK_IMAGE_WHITE", // White areas will be regenerated
+      "text_prompts[0][text]": "A golden retriever sitting",
+      "text_prompts[0][weight]": 1,
+      cfg_scale: 7,
+      samples: 1,
+      steps: 30,
+    },
+  },
+  { response: GenerationResponseSchema },
+);
+```