npm - @superblocksteam/sdk-api - Versions diffs - 2.0.157 → 2.0.158 - Mend

@superblocksteam/sdk-api 2.0.157 → 2.0.158

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (57) hide show

package/src/integrations/openai_v2/README.md CHANGED Viewed

@@ -257,6 +257,13 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 ## Common Pitfalls
+### Streaming Is Not Supported
+`apiRequest()` does not support streaming or Server-Sent Events. Do not set
+`stream: true` — streaming responses fail schema validation. Every call
+returns the complete response; if a UI needs real-time token streaming,
+handle it at the frontend layer, not through the SDK.
 ### No Specialized Methods
 The OpenAI client only provides `apiRequest()`. There are no other specialized methods:

package/src/integrations/perplexity/README.md CHANGED Viewed

@@ -189,6 +189,13 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 ## Common Pitfalls
+### Streaming Is Not Supported
+`apiRequest()` does not support streaming or Server-Sent Events. Do not set
+`stream: true` — streaming responses fail schema validation. Every call
+returns the complete response; if a UI needs real-time token streaming,
+handle it at the frontend layer, not through the SDK.
 ### No Specialized Methods
 ```typescript

package/src/integrations/restapiintegration/client.test.ts CHANGED Viewed

@@ -1,37 +1,13 @@
-/**
- * Tests for RestApiIntegrationPluginClientImpl (generic REST API Integration).
- *
- * Covers the responseType passthrough:
- * - default requests keep responseType "json"; callers that pass a
- *   response schema still get validated results
- * - the responseType option is forwarded to the orchestrator request
- * - non-JSON responses (e.g. XML with responseType "text") are returned
- *   raw when no response schema is provided
- */
-import { describe, it, expect, vi } from "vitest";
+import { describe, expect, expectTypeOf, it, vi } from "vitest";
 import { z } from "zod";
-import { ActionResponseType } from "@superblocksteam/shared";
+import type { ActionResponseType } from "@superblocksteam/shared";
 import { RestApiValidationError } from "../../errors.js";
-import type { RestApiResponseType } from "../base/types.js";
+import { REST_API_RESPONSE_TYPES } from "../base/types.js";
 import type { IntegrationConfig } from "../types.js";
 import { RestApiIntegrationPluginClientImpl } from "./client.js";
-// ── Wire-contract assertions (verified by `pnpm typecheck`) ────────
-//
-// The responseType strings are sent to the orchestrator as-is; the
-// accepted values are defined by ActionResponseType. This assertion
-// fails compilation if the SDK union drifts outside the wire values.
-//
-// The SDK union is a deliberate subset of the wire values: "auto" and
-// "binary" are implemented by the orchestrator but not exposed (see the
-// RestApiResponseType doc for why), and "raw" is streaming-only.
-const _sdkValuesAreValidWireValues: Exclude<`${ActionResponseType}`, "raw">[] =
-  [] as RestApiResponseType[];
-void _sdkValuesAreValidWireValues;
 const TEST_CONFIG: IntegrationConfig = {
   id: "restapi-test-id",
   name: "Test REST API",
@@ -40,6 +16,11 @@ const TEST_CONFIG: IntegrationConfig = {
 };
 const XML_RESPONSE = `<?xml version="1.0"?><note><body>hi</body></note>`;
+const PDF_BYTES = [0x25, 0x50, 0x44, 0x46];
+function workerBufferPayload(data: unknown): unknown {
+  return { type: "Buffer", data };
+}
 function createClient(mockResult: unknown) {
   const executeQuery = vi.fn().mockResolvedValue(mockResult);
@@ -50,9 +31,14 @@ function createClient(mockResult: unknown) {
   return { client, executeQuery };
 }
-describe("RestApiIntegrationPluginClientImpl", () => {
-  // ── Default JSON behavior (must not regress) ────────────────────
+function callApiRequest(
+  client: RestApiIntegrationPluginClientImpl,
+  ...args: unknown[]
+): Promise<unknown> {
+  return Reflect.apply(client.apiRequest, client, args);
+}
+describe("RestApiIntegrationPluginClientImpl", () => {
   describe("default JSON behavior", () => {
     it("sends responseType json when the option is omitted", async () => {
       const { client, executeQuery } = createClient({ id: "1" });
@@ -81,19 +67,26 @@ describe("RestApiIntegrationPluginClientImpl", () => {
     });
     it("throws RestApiValidationError when the response does not match the schema", async () => {
-      const { client } = createClient(XML_RESPONSE);
+      const payload = XML_RESPONSE;
+      const { client } = createClient(payload);
-      await expect(
-        client.apiRequest(
+      try {
+        await client.apiRequest(
           { method: "GET", path: "/users" },
           { response: z.object({ id: z.string() }) },
-        ),
-      ).rejects.toThrow(RestApiValidationError);
+        );
+      } catch (error) {
+        expect(error).toBeInstanceOf(RestApiValidationError);
+        if (!(error instanceof RestApiValidationError)) {
+          throw error;
+        }
+        expect(error.details.data).toBe(payload);
+        return;
+      }
+      throw new Error("Expected JSON response validation to fail");
     });
   });
-  // ── responseType passthrough ────────────────────────────────────
   describe("responseType passthrough", () => {
     it("forwards responseType text to the orchestrator request", async () => {
       const { client, executeQuery } = createClient(XML_RESPONSE);
@@ -152,8 +145,6 @@ describe("RestApiIntegrationPluginClientImpl", () => {
     });
     it("returns an empty string unchanged for responseType text", async () => {
-      // An empty text body legitimately decodes to "" — the null/undefined
-      // guard must not reject it.
       const { client } = createClient("");
       const result = await client.apiRequest({
@@ -166,10 +157,6 @@ describe("RestApiIntegrationPluginClientImpl", () => {
     });
     it("rejects null and undefined results for every response type", async () => {
-      // Neither value is a legitimate decode result for the exposed
-      // response types: JSON parses to a value the schema sees, and an
-      // empty text body decodes to "". Either means a broken execution
-      // contract, so both throw.
       for (const badResult of [null, undefined]) {
         const { client: textClient } = createClient(badResult);
         await expect(
@@ -180,8 +167,15 @@ describe("RestApiIntegrationPluginClientImpl", () => {
           }),
         ).rejects.toThrow(RestApiValidationError);
-        // JSON mode always goes through the schema overload; the bad
-        // result is rejected before validation runs.
+        const { client: binaryClient } = createClient(badResult);
+        await expect(
+          binaryClient.apiRequest({
+            method: "GET",
+            path: "/broken",
+            responseType: "binary",
+          }),
+        ).rejects.toThrow(RestApiValidationError);
         const { client: jsonClient } = createClient(badResult);
         await expect(
           jsonClient.apiRequest(
@@ -193,14 +187,109 @@ describe("RestApiIntegrationPluginClientImpl", () => {
     });
   });
-  // ── Request-body validation via the schema-less overload ────────
+  describe("responseType binary", () => {
+    it("forwards responseType binary and returns decoded bytes", async () => {
+      const { client, executeQuery } = createClient(
+        workerBufferPayload(PDF_BYTES),
+      );
+      const result = await client.apiRequest({
+        method: "GET",
+        path: "/file.pdf",
+        responseType: "binary",
+      });
+      expect(executeQuery).toHaveBeenCalledWith(
+        expect.objectContaining({ responseType: "binary" }),
+        undefined,
+        undefined,
+      );
+      expect(result).toBeInstanceOf(Uint8Array);
+      expect(result.constructor).toBe(Uint8Array);
+      expect(Array.from(result)).toEqual(PDF_BYTES);
+    });
+    it("rejects malformed binary data before applying a response schema", async () => {
+      const malformed = workerBufferPayload([256]);
+      const { client, executeQuery } = createClient(malformed);
+      const workerShapeSchema = z.object({
+        type: z.literal("Buffer"),
+        data: z.array(z.number()),
+      });
+      await expect(
+        callApiRequest(
+          client,
+          { method: "GET", path: "/file.pdf", responseType: "binary" },
+          { response: workerShapeSchema },
+        ),
+      ).rejects.toThrow(RestApiValidationError);
+      expect(executeQuery).toHaveBeenCalled();
+    });
+    it("accepts response schemas that transform bytes to bytes", async () => {
+      const { client } = createClient(workerBufferPayload(PDF_BYTES));
+      const result = await client.apiRequest(
+        { method: "GET", path: "/file.pdf", responseType: "binary" },
+        {
+          response: z
+            .instanceof(Uint8Array)
+            .refine((bytes) => bytes[0] === 0x25)
+            .transform((bytes) => bytes.slice(1)),
+        },
+      );
+      expect(Array.from(result)).toEqual(PDF_BYTES.slice(1));
+    });
+    it("throws RestApiValidationError when the schema rejects normalized bytes", async () => {
+      const { client } = createClient(workerBufferPayload(PDF_BYTES));
+      await expect(
+        client.apiRequest(
+          { method: "GET", path: "/file.pdf", responseType: "binary" },
+          {
+            response: z
+              .instanceof(Uint8Array)
+              .refine((bytes) => bytes.byteLength > 64),
+          },
+        ),
+      ).rejects.toThrow(RestApiValidationError);
+    });
+    it("redacts binary data from response validation errors", async () => {
+      const bytes = Array.from({ length: 4096 }, () => 0);
+      const { client } = createClient(workerBufferPayload(bytes));
+      try {
+        await client.apiRequest(
+          { method: "GET", path: "/file.pdf", responseType: "binary" },
+          {
+            response: z
+              .instanceof(Uint8Array)
+              .refine((value) => value.byteLength < 1024),
+          },
+        );
+      } catch (error) {
+        expect(error).toBeInstanceOf(RestApiValidationError);
+        if (!(error instanceof RestApiValidationError)) {
+          throw error;
+        }
+        expect(error.details.data).toEqual({
+          dataType: "binary",
+          redacted: true,
+        });
+        return;
+      }
+      throw new Error("Expected binary response validation to fail");
+    });
+  });
   describe("request body validation", () => {
     it("throws RestApiValidationError for an invalid body with a body-only schema", async () => {
       const { client, executeQuery } = createClient({ ok: true });
-      // Runtime-invalid bodies reach this path via dynamic data (user
-      // input, parsed JSON) that the compiler cannot check.
       const dynamicBody: unknown = JSON.parse('{"amount":"not-a-number"}');
       await expect(
@@ -242,23 +331,12 @@ describe("RestApiIntegrationPluginClientImpl", () => {
     });
   });
-  // ── Runtime contract enforcement ─────────────────────────────────
-  //
-  // The overloads make these calls unrepresentable in TypeScript, but
-  // user API code executes as esbuild-bundled JS with no type
-  // enforcement — the same contract must hold at runtime.
   describe("runtime contract enforcement", () => {
-    type UncheckedApiRequest = (...args: unknown[]) => Promise<unknown>;
     it("rejects a schema-less call in default JSON mode without issuing the request", async () => {
       const { client, executeQuery } = createClient({ ok: true });
       await expect(
-        (client.apiRequest as UncheckedApiRequest)({
-          method: "GET",
-          path: "/users",
-        }),
+        callApiRequest(client, { method: "GET", path: "/users" }),
       ).rejects.toThrow(RestApiValidationError);
       expect(executeQuery).not.toHaveBeenCalled();
     });
@@ -267,7 +345,8 @@ describe("RestApiIntegrationPluginClientImpl", () => {
       const { client, executeQuery } = createClient({ ok: true });
       await expect(
-        (client.apiRequest as UncheckedApiRequest)(
+        callApiRequest(
+          client,
           {
             method: "POST",
             path: "/orders",
@@ -280,27 +359,32 @@ describe("RestApiIntegrationPluginClientImpl", () => {
       expect(executeQuery).not.toHaveBeenCalled();
     });
-    it("rejects an unexposed responseType value without issuing the request", async () => {
-      const { client, executeQuery } = createClient({ ok: true });
+    it("rejects auto, which can yield unvalidated JSON, and raw, which is streaming-only", async () => {
+      for (const responseType of ["auto", "raw"]) {
+        const { client, executeQuery } = createClient({ ok: true });
-      await expect(
-        (client.apiRequest as UncheckedApiRequest)({
-          method: "GET",
-          path: "/report",
-          responseType: "auto",
-        }),
-      ).rejects.toThrow(RestApiValidationError);
-      expect(executeQuery).not.toHaveBeenCalled();
+        await expect(
+          callApiRequest(client, {
+            method: "GET",
+            path: "/report",
+            responseType,
+          }),
+        ).rejects.toThrow(RestApiValidationError);
+        expect(executeQuery).not.toHaveBeenCalled();
+      }
     });
   });
-  // ── Compile-time overload contracts (verified by `pnpm typecheck`) ──
   describe("overload resolution", () => {
+    it("keeps public response types within the worker contract", () => {
+      expectTypeOf<(typeof REST_API_RESPONSE_TYPES)[number]>().toMatchTypeOf<
+        Exclude<`${ActionResponseType}`, "raw">
+      >();
+    });
     it("keeps typed results for schema callers and unknown for schema-less calls", async () => {
       const { client } = createClient({ id: "1" });
-      // With a response schema: resolves to the typed overload.
       const typed: Promise<{ id: string }> = client.apiRequest(
         { method: "GET", path: "/users" },
         { response: z.object({ id: z.string() }) },
@@ -309,7 +393,6 @@ describe("RestApiIntegrationPluginClientImpl", () => {
       const { client: rawClient } = createClient(XML_RESPONSE);
-      // Without a schema: resolves to the raw overload returning unknown.
       const raw: Promise<unknown> = rawClient.apiRequest({
         method: "GET",
         path: "/report.xml",
@@ -325,20 +408,58 @@ describe("RestApiIntegrationPluginClientImpl", () => {
       });
       await wrong;
-      // The remaining cases are rejected twice over: at compile time by
-      // the overloads (@ts-expect-error) and at runtime by the contract
-      // guards, since bundled user code carries no types.
-      // @ts-expect-error unvalidated JSON is unrepresentable — schema-less
-      // calls must opt into a non-JSON responseType
+      // @ts-expect-error unvalidated JSON is unrepresentable; schema-less calls must opt into a non-JSON responseType
       const unvalidatedJson = rawClient.apiRequest({
         method: "GET",
         path: "/users",
       });
       await expect(unvalidatedJson).rejects.toThrow(RestApiValidationError);
+    });
+    it("types schema-less binary responses as Uint8Array", async () => {
+      const { client: binaryClient } = createClient(
+        workerBufferPayload(PDF_BYTES),
+      );
+      const binary: Promise<Uint8Array> = binaryClient.apiRequest({
+        method: "GET",
+        path: "/file.pdf",
+        responseType: "binary",
+      });
+      expectTypeOf(binary).toEqualTypeOf<Promise<Uint8Array>>();
+      expect(Array.from(await binary)).toEqual(PDF_BYTES);
+      // @ts-expect-error schema-less binary apiRequest returns Uint8Array
+      const wrongBinary: Promise<string> = binaryClient.apiRequest({
+        method: "GET",
+        path: "/file.pdf",
+        responseType: "binary",
+      });
+      await wrongBinary;
+    });
+    it("rejects binary response schemas that transform bytes to another type", () => {
+      const { client: binaryClient } = createClient(
+        workerBufferPayload(PDF_BYTES),
+      );
-      // "auto" and "binary" are valid wire values but deliberately not
-      // exposed in the SDK union (see RestApiResponseType).
+      // @ts-expect-error binary response schemas must output Uint8Array
+      binaryClient.apiRequest(
+        {
+          method: "GET",
+          path: "/file.pdf",
+          responseType: "binary",
+        },
+        {
+          response: z
+            .instanceof(Uint8Array)
+            .transform((bytes) => bytes.byteLength),
+        },
+      );
+    });
+    it("rejects response types outside the public SDK contract", async () => {
+      const { client: rawClient } = createClient(XML_RESPONSE);
       const autoCall = rawClient.apiRequest({
         method: "GET",
         path: "/report.xml",
@@ -347,13 +468,13 @@ describe("RestApiIntegrationPluginClientImpl", () => {
       });
       await expect(autoCall).rejects.toThrow(RestApiValidationError);
-      const binaryCall = rawClient.apiRequest({
+      const rawCall = rawClient.apiRequest({
         method: "GET",
         path: "/report.xml",
-        // @ts-expect-error "binary" is not an exposed responseType
-        responseType: "binary",
+        // @ts-expect-error "raw" is not an exposed responseType
+        responseType: "raw",
       });
-      await expect(binaryCall).rejects.toThrow(RestApiValidationError);
+      await expect(rawCall).rejects.toThrow(RestApiValidationError);
     });
   });
 });

package/src/integrations/restapiintegration/docs.manifest.json CHANGED Viewed

@@ -4,7 +4,11 @@
   "overlays": [
     {
       "file": "overlays/response-types.md",
-      "sdkVersionRange": ">=0.0.3"
+      "sdkVersionRange": ">=0.0.3 <0.0.4"
+    },
+    {
+      "file": "overlays/response-types-binary.md",
+      "sdkVersionRange": ">=0.0.4"
     },
     {
       "file": "overlays/response-types-unsupported.md",

package/src/integrations/restapiintegration/overlays/response-types-binary.md ADDED Viewed

@@ -0,0 +1,51 @@
+## Non-JSON Responses
+`apiRequest()` decodes responses as JSON by default. For endpoints that return non-JSON payloads, pass `responseType`:
+- `"binary"` for PDFs and other byte payloads. The result is a `Uint8Array`
+- `"text"` for XML, CSV, HTML, and other decoded strings
+With `responseType: "text"` or `responseType: "binary"` the response schema may be omitted. Text returns the raw string typed `unknown`. Binary returns a `Uint8Array`:
+```typescript
+const xml = await ctx.integrations.legacyApi.apiRequest({
+  method: "GET",
+  path: "/report.xml",
+  responseType: "text",
+});
+// xml is the raw XML string (typed unknown)
+const pdf = await ctx.integrations.legacyApi.apiRequest({
+  method: "GET",
+  path: "/file.pdf",
+  responseType: "binary",
+});
+// pdf is a Uint8Array
+```
+To validate after decoding, pass a schema that matches the decoded value:
+```typescript
+const xml = await ctx.integrations.legacyApi.apiRequest(
+  { method: "GET", path: "/report.xml", responseType: "text" },
+  { response: z.string() },
+);
+// xml is typed string
+const pdf = await ctx.integrations.legacyApi.apiRequest(
+  { method: "GET", path: "/file.pdf", responseType: "binary" },
+  { response: z.instanceof(Uint8Array) },
+);
+// pdf is typed Uint8Array
+```
+Convert binary data to a JSON-safe representation before returning it from an SDK API:
+```typescript
+return {
+  contentBase64: Buffer.from(pdf).toString("base64"),
+  filename: "file.pdf",
+};
+```
+JSON responses (the default) always require a response schema. Omitting the schema is only allowed together with an explicit `responseType: "text"` or `responseType: "binary"`, so unvalidated JSON is not representable.

package/src/integrations/s3/README.md CHANGED Viewed

@@ -25,6 +25,7 @@ import { api, z, s3 } from "@superblocksteam/sdk-api";
 const PROD_S3 = "a1b2c3d4-5678-90ab-cdef-s300000001";
 export default api({
+  name: "ListBucketObjects",
   integrations: {
     storage: s3(PROD_S3),
   },

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

@@ -12,6 +12,7 @@ import { describe, it, expect, vi } from "vitest";
 import { z } from "zod";
 import { RestApiValidationError } from "../../errors.js";
+import { REDACTED_BINARY_RESPONSE_DATA } from "../base/decode-worker-binary-response.js";
 import type { IntegrationConfig } from "../types.js";
 import { SlackClientImpl } from "./client.js";
 import type { SlackErrorResponse } from "./types.js";
@@ -508,7 +509,41 @@ describe("SlackClientImpl", () => {
     });
   });
-  // ── Type narrowing (compile-time verification) ─────────────────
+  describe("responseType binary", () => {
+    const pdfBytes = [0x25, 0x50, 0x44, 0x46];
+    const workerPayload = { type: "Buffer", data: pdfBytes };
+    it("decodes worker Buffer JSON and redacts it from validation errors", async () => {
+      const { client, executeQuery } = createClient(workerPayload);
+      try {
+        await client.apiRequest(
+          {
+            method: "GET",
+            path: "/files.download",
+            responseType: "binary",
+          },
+          { response: ChannelsSchema },
+        );
+      } catch (error) {
+        expect(error).toBeInstanceOf(RestApiValidationError);
+        if (!(error instanceof RestApiValidationError)) {
+          throw error;
+        }
+        expect(executeQuery).toHaveBeenCalledWith(
+          expect.objectContaining({ responseType: "binary" }),
+          undefined,
+          undefined,
+        );
+        expect(error.details.data).toEqual(REDACTED_BINARY_RESPONSE_DATA);
+        expect(error.details.data).not.toEqual(workerPayload);
+        return;
+      }
+      throw new Error(
+        "Expected Slack binary apiRequest to fail envelope validation",
+      );
+    });
+  });
   describe("type narrowing", () => {
     it("narrows to error response fields when ok is false", async () => {

package/src/integrations/snowflakecortex/README.md CHANGED Viewed

@@ -108,6 +108,14 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 ## Common Pitfalls
+### Streaming Is Not Supported
+`apiRequest()` does not support streaming or Server-Sent Events. Always set
+`stream: false` in Cortex request bodies (as the examples do) — a streaming
+response fails schema validation. Every call returns the complete response;
+if a UI needs real-time token streaming, handle it at the frontend layer,
+not through the SDK.
 ### No Specialized Methods
 The Snowflake Cortex client only provides `apiRequest()`. There are no other specialized methods:

package/src/integrations/stabilityai/README.md CHANGED Viewed

@@ -234,6 +234,13 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 ## Common Pitfalls
+### Streaming Is Not Supported
+`apiRequest()` does not support streaming or Server-Sent Events. Do not set
+`stream: true` — streaming responses fail schema validation. Every call
+returns the complete response; if a UI needs real-time token streaming,
+handle it at the frontend layer, not through the SDK.
 ### No Specialized Methods
 ```typescript