npm - @superblocksteam/sdk-api - Versions diffs - 2.0.142-next.0 → 2.0.142-next.2 - Mend

@superblocksteam/sdk-api 2.0.142-next.0 → 2.0.142-next.2

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 (30) hide show

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

@@ -0,0 +1,359 @@
+/**
+ * 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 { z } from "zod";
+import { ActionResponseType } from "@superblocksteam/shared";
+import { RestApiValidationError } from "../../errors.js";
+import type { RestApiResponseType } 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",
+  pluginId: "restapiintegration",
+  configuration: {},
+};
+const XML_RESPONSE = `<?xml version="1.0"?><note><body>hi</body></note>`;
+function createClient(mockResult: unknown) {
+  const executeQuery = vi.fn().mockResolvedValue(mockResult);
+  const client = new RestApiIntegrationPluginClientImpl(
+    TEST_CONFIG,
+    executeQuery,
+  );
+  return { client, executeQuery };
+}
+describe("RestApiIntegrationPluginClientImpl", () => {
+  // ── Default JSON behavior (must not regress) ────────────────────
+  describe("default JSON behavior", () => {
+    it("sends responseType json when the option is omitted", async () => {
+      const { client, executeQuery } = createClient({ id: "1" });
+      await client.apiRequest(
+        { method: "GET", path: "/users" },
+        { response: z.object({ id: z.string() }) },
+      );
+      expect(executeQuery).toHaveBeenCalledWith(
+        expect.objectContaining({ responseType: "json" }),
+        undefined,
+        undefined,
+      );
+    });
+    it("validates the response against the provided schema", async () => {
+      const { client } = createClient({ id: "1", extra: "stripped" });
+      const result = await client.apiRequest(
+        { method: "GET", path: "/users" },
+        { response: z.object({ id: z.string() }) },
+      );
+      expect(result).toEqual({ id: "1" });
+    });
+    it("throws RestApiValidationError when the response does not match the schema", async () => {
+      const { client } = createClient(XML_RESPONSE);
+      await expect(
+        client.apiRequest(
+          { method: "GET", path: "/users" },
+          { response: z.object({ id: z.string() }) },
+        ),
+      ).rejects.toThrow(RestApiValidationError);
+    });
+  });
+  // ── responseType passthrough ────────────────────────────────────
+  describe("responseType passthrough", () => {
+    it("forwards responseType text to the orchestrator request", async () => {
+      const { client, executeQuery } = createClient(XML_RESPONSE);
+      await client.apiRequest({
+        method: "GET",
+        path: "/report.xml",
+        responseType: "text",
+      });
+      expect(executeQuery).toHaveBeenCalledWith(
+        expect.objectContaining({ responseType: "text" }),
+        undefined,
+        undefined,
+      );
+    });
+    it("returns a raw XML string with responseType text and no response schema", async () => {
+      const { client } = createClient(XML_RESPONSE);
+      const result = await client.apiRequest({
+        method: "GET",
+        path: "/report.xml",
+        responseType: "text",
+      });
+      expect(result).toBe(XML_RESPONSE);
+    });
+    it("still validates when a response schema is provided alongside responseType", async () => {
+      const { client, executeQuery } = createClient(XML_RESPONSE);
+      const result = await client.apiRequest(
+        { method: "GET", path: "/report.xml", responseType: "text" },
+        { response: z.string() },
+      );
+      expect(executeQuery).toHaveBeenCalledWith(
+        expect.objectContaining({ responseType: "text" }),
+        undefined,
+        undefined,
+      );
+      expect(result).toBe(XML_RESPONSE);
+    });
+    it("returns the raw response without validation when no schema is given", async () => {
+      const { client } = createClient({ ok: true, rows: [1, 2, 3] });
+      const result = await client.apiRequest({
+        method: "GET",
+        path: "/data",
+        responseType: "text",
+      });
+      expect(result).toEqual({ ok: true, rows: [1, 2, 3] });
+    });
+    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({
+        method: "GET",
+        path: "/empty",
+        responseType: "text",
+      });
+      expect(result).toBe("");
+    });
+    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(
+          textClient.apiRequest({
+            method: "GET",
+            path: "/broken",
+            responseType: "text",
+          }),
+        ).rejects.toThrow(RestApiValidationError);
+        // JSON mode always goes through the schema overload; the bad
+        // result is rejected before validation runs.
+        const { client: jsonClient } = createClient(badResult);
+        await expect(
+          jsonClient.apiRequest(
+            { method: "GET", path: "/broken" },
+            { response: z.object({}) },
+          ),
+        ).rejects.toThrow(RestApiValidationError);
+      }
+    });
+  });
+  // ── Request-body validation via the schema-less overload ────────
+  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(
+        client.apiRequest(
+          {
+            method: "POST",
+            path: "/orders",
+            body: dynamicBody,
+            responseType: "text",
+          },
+          { body: z.object({ amount: z.number() }) },
+        ),
+      ).rejects.toThrow(RestApiValidationError);
+      expect(executeQuery).not.toHaveBeenCalled();
+    });
+    it("sends a valid body and returns the raw response with a body-only schema", async () => {
+      const { client, executeQuery } = createClient({ ok: true });
+      const result = await client.apiRequest(
+        {
+          method: "POST",
+          path: "/orders",
+          body: { amount: 42 },
+          responseType: "text",
+        },
+        { body: z.object({ amount: z.number() }) },
+      );
+      expect(executeQuery).toHaveBeenCalledWith(
+        expect.objectContaining({
+          body: JSON.stringify({ amount: 42 }),
+          bodyType: "jsonBody",
+        }),
+        undefined,
+        undefined,
+      );
+      expect(result).toEqual({ ok: true });
+    });
+  });
+  // ── 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",
+        }),
+      ).rejects.toThrow(RestApiValidationError);
+      expect(executeQuery).not.toHaveBeenCalled();
+    });
+    it("rejects a body-only schema in explicit JSON mode without issuing the request", async () => {
+      const { client, executeQuery } = createClient({ ok: true });
+      await expect(
+        (client.apiRequest as UncheckedApiRequest)(
+          {
+            method: "POST",
+            path: "/orders",
+            body: { amount: 42 },
+            responseType: "json",
+          },
+          { body: z.object({ amount: z.number() }) },
+        ),
+      ).rejects.toThrow(RestApiValidationError);
+      expect(executeQuery).not.toHaveBeenCalled();
+    });
+    it("rejects an unexposed responseType value without issuing the request", async () => {
+      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();
+    });
+  });
+  // ── Compile-time overload contracts (verified by `pnpm typecheck`) ──
+  describe("overload resolution", () => {
+    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() }) },
+      );
+      expect(await typed).toEqual({ id: "1" });
+      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",
+        responseType: "text",
+      });
+      expect(await raw).toBe(XML_RESPONSE);
+      // @ts-expect-error schema-less apiRequest returns unknown, not a typed shape
+      const wrong: Promise<{ id: string }> = rawClient.apiRequest({
+        method: "GET",
+        path: "/report.xml",
+        responseType: "text",
+      });
+      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
+      const unvalidatedJson = rawClient.apiRequest({
+        method: "GET",
+        path: "/users",
+      });
+      await expect(unvalidatedJson).rejects.toThrow(RestApiValidationError);
+      // "auto" and "binary" are valid wire values but deliberately not
+      // exposed in the SDK union (see RestApiResponseType).
+      const autoCall = rawClient.apiRequest({
+        method: "GET",
+        path: "/report.xml",
+        // @ts-expect-error "auto" is not an exposed responseType
+        responseType: "auto",
+      });
+      await expect(autoCall).rejects.toThrow(RestApiValidationError);
+      const binaryCall = rawClient.apiRequest({
+        method: "GET",
+        path: "/report.xml",
+        // @ts-expect-error "binary" is not an exposed responseType
+        responseType: "binary",
+      });
+      await expect(binaryCall).rejects.toThrow(RestApiValidationError);
+    });
+  });
+});

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

@@ -1,5 +1,14 @@
 {
   "pluginId": "restapiintegration",
   "base": "README.md",
-  "overlays": []
+  "overlays": [
+    {
+      "file": "overlays/response-types.md",
+      "sdkVersionRange": ">=0.0.3"
+    },
+    {
+      "file": "overlays/response-types-unsupported.md",
+      "sdkVersionRange": "<0.0.3"
+    }
+  ]
 }

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

@@ -0,0 +1,5 @@
+## Non-JSON Responses
+This organization's agent does not support the `responseType` option on `apiRequest()` — its worker runs an sdk-api version that decodes every response as JSON and always requires a response schema. Endpoints returning XML, CSV, or other non-JSON payloads cannot be consumed from SDK APIs until the agent is upgraded.
+Do not generate code that passes a `responseType` value: it may typecheck against a newer local copy of the SDK but fails at runtime on this agent with a `RestApiValidationError` (for example, "Integration query returned ... — expected a JSON response object"). If the user needs to consume a non-JSON endpoint, tell them their Superblocks agent must be upgraded first.

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

@@ -0,0 +1,26 @@
+## Non-JSON Responses
+`apiRequest()` decodes responses as JSON by default. For endpoints that return non-JSON payloads (XML, CSV, HTML, plain text), pass `responseType: "text"` to receive the decoded body as a string.
+With `responseType: "text"` the response schema may be omitted — the raw string is returned typed `unknown`:
+```typescript
+const xml = await ctx.integrations.legacyApi.apiRequest({
+  method: "GET",
+  path: "/report.xml",
+  responseType: "text",
+});
+// xml is the raw XML string (typed unknown)
+```
+To get a typed string instead, validate with a schema matching 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
+```
+JSON responses (the default) always require a response schema. Omitting the schema is only allowed together with an explicit `responseType: "text"`, so unvalidated JSON is not representable.