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/dist/integrations/restapiintegration/client.test.js ADDED Viewed

@@ -0,0 +1,236 @@
+/**
+ * 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 { RestApiValidationError } from "../../errors.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 = [];
+void _sdkValuesAreValidWireValues;
+const TEST_CONFIG = {
+    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) {
+    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 = 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", () => {
+        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({
+                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({
+                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({
+                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 = 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 = 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 = 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);
+        });
+    });
+});
+//# sourceMappingURL=client.test.js.map

package/dist/integrations/restapiintegration/client.test.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"client.test.js","sourceRoot":"","sources":["../../../src/integrations/restapiintegration/client.test.ts"],"names":[],"mappings":"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"}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@superblocksteam/sdk-api",
-  "version": "2.0.142-next.0",
+  "version": "2.0.142-next.2",
   "description": "Superblocks SDK for TypeScript-based API definitions",
   "license": "Superblocks Community Software License",
   "files": [
@@ -30,7 +30,8 @@
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.59.2",
     "uuid": "^11.1.1",
-    "vitest": "^2.0.0"
+    "vitest": "^2.0.0",
+    "@superblocksteam/shared": "0.9601.0"
   },
   "engines": {
     "node": ">=20",

package/src/integrations/base/index.ts CHANGED Viewed

@@ -9,5 +9,6 @@ export { GraphQLIntegrationClient } from "./graphql-integration-client.js";
 export type {
   ApiRequestOptions,
   ApiRequestSchema,
+  RestApiResponseType,
   SupportsApiRequest,
 } from "./types.js";

package/src/integrations/base/rest-api-client-base.ts CHANGED Viewed

@@ -17,6 +17,7 @@ import type { Plugin as RestApiIntegrationPlugin } from "@superblocksteam/types/
 import { RestApiValidationError } from "../../errors.js";
 import type { QueryExecutor, TraceMetadata } from "../registry.js";
 import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
+import { REST_API_RESPONSE_TYPES } from "./types.js";
 import type { ApiRequestOptions } from "./types.js";
 export type RestApiRequest = PartialMessage<RestApiIntegrationPlugin>;
@@ -58,7 +59,7 @@ export abstract class RestApiClientBase implements IntegrationClientImpl {
    * Returns the raw (unvalidated) response from the orchestrator.
    * Subclasses call this, then apply their own response handling.
    *
-   * @param options - HTTP method, path, body, params, headers
+   * @param options - Request configuration (see {@link ApiRequestOptions})
    * @param bodySchema - Optional Zod schema for body validation
    * @param metadata - Optional trace metadata for observability
    * @returns Raw response from the orchestrator
@@ -96,13 +97,31 @@ export abstract class RestApiClientBase implements IntegrationClientImpl {
       }
     }
+    // The RestApiResponseType union is erased in the bundled JS user APIs
+    // run as, so values outside it (including wire values the orchestrator
+    // implements but the SDK deliberately does not expose, like "auto")
+    // must also be rejected at runtime, before the request is issued.
+    const responseTypeResult = z
+      .enum(REST_API_RESPONSE_TYPES)
+      .safeParse(options.responseType ?? "json");
+    if (!responseTypeResult.success) {
+      throw new RestApiValidationError(
+        `Unsupported responseType ${JSON.stringify(options.responseType)} — expected one of: ${REST_API_RESPONSE_TYPES.join(", ")}`,
+        {
+          zodError: responseTypeResult.error,
+          data: options.responseType,
+        },
+      );
+    }
+    const responseType = responseTypeResult.data;
     const request: RestApiRequest = {
       openApiAction: "genericHttpRequest",
       httpMethod: options.method.toUpperCase(),
       urlPath: options.path,
       headers,
       params,
-      responseType: "json",
+      responseType,
     };
     if (options.body !== undefined) {
@@ -116,11 +135,16 @@ export abstract class RestApiClientBase implements IntegrationClientImpl {
       metadata,
     );
+    // Neither `null` nor `undefined` 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 value only arises from a
+    // broken execution contract, so both throw. (If "auto" is ever exposed,
+    // `null` becomes legitimate — it parses a literal `null` JSON body.)
     if (result === null || result === undefined) {
       const nonNullResult = z.object({}).safeParse(result);
       if (!nonNullResult.success) {
         throw new RestApiValidationError(
-          `Integration query returned ${String(result)} — expected a JSON response object`,
+          `Integration query returned ${String(result)} for responseType "${responseType}" — expected a response value`,
           {
             zodError: nonNullResult.error,
             data: result,

package/src/integrations/base/rest-api-integration-client.ts CHANGED Viewed

@@ -3,10 +3,13 @@
  *
  * Extends RestApiClientBase with an apiRequest() that validates the
  * full response against a caller-supplied Zod schema and throws
- * RestApiValidationError on mismatch.
+ * RestApiValidationError on mismatch. When no response schema is
+ * provided, the raw result is returned without validation — useful for
+ * non-JSON responses (e.g. XML), which can alternatively be validated
+ * with a schema matching the decoded value (e.g. z.string()).
  */
-import type { z } from "zod";
+import { z } from "zod";
 import { RestApiValidationError } from "../../errors.js";
 import type { TraceMetadata } from "../registry.js";
@@ -14,6 +17,7 @@ import { RestApiClientBase } from "./rest-api-client-base.js";
 import type {
   ApiRequestOptions,
   ApiRequestSchema,
+  RestApiResponseType,
   SupportsApiRequest,
 } from "./types.js";
@@ -34,10 +38,55 @@ export abstract class RestApiIntegrationClient
       response: z.ZodSchema<TResponse>;
     },
     metadata?: TraceMetadata,
-  ): Promise<TResponse> {
-    const result = await this.executeApiRequest(options, schema.body, metadata);
+  ): Promise<TResponse>;
+  async apiRequest<TBody>(
+    options: ApiRequestOptions<TBody> & {
+      responseType: Exclude<RestApiResponseType, "json">;
+    },
+    schema?: ApiRequestSchema<TBody, unknown>,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
+  async apiRequest<TBody, TResponse>(
+    options: ApiRequestOptions<TBody>,
+    schema?: ApiRequestSchema<TBody, TResponse>,
+    metadata?: TraceMetadata,
+  ): Promise<TResponse | unknown> {
+    // The overloads make schema-less JSON unrepresentable in TypeScript,
+    // but user API code executes as bundled JS with no type enforcement —
+    // enforce the same contract at runtime, before issuing the request.
+    if ((options.responseType ?? "json") === "json" && !schema?.response) {
+      throw new RestApiValidationError(
+        'apiRequest() with responseType "json" requires a response schema — provide one, or set responseType: "text" to receive a non-JSON payload unvalidated',
+        {
+          zodError: new z.ZodError([
+            {
+              code: z.ZodIssueCode.custom,
+              message: "response schema is required for JSON responses",
+              path: ["response"],
+            },
+          ]),
+          data: undefined,
+        },
+      );
+    }
+    const result = await this.executeApiRequest(
+      options,
+      schema?.body,
+      metadata,
+    );
+    // Without a response schema the raw result is returned as-is (typed
+    // unknown). Non-JSON responses (e.g. responseType "text" returning
+    // XML) can either omit the schema or pass one matching the decoded
+    // value, such as z.string(). Request-body validation is opt-in:
+    // executeApiRequest only validates options.body when schema.body is
+    // provided (unchanged from the previous contract, where schema.body
+    // was already optional).
+    if (!schema?.response) {
+      return result;
+    }
-    // Response schema is REQUIRED - always validate
     const responseParseResult = schema.response.safeParse(result);
     if (!responseParseResult.success) {

package/src/integrations/base/types.ts CHANGED Viewed

@@ -9,6 +9,32 @@ import type { TraceMetadata } from "../registry.js";
 // Re-export for backwards compatibility
 export type { TraceMetadata };
+/**
+ * How the orchestrator should decode the HTTP response body.
+ *
+ * - `"json"` (default): parse the response as JSON; fails on non-JSON bodies
+ * - `"text"`: return the decoded response body as a string (XML, CSV, HTML, ...)
+ *
+ * The orchestrator also implements `"auto"`, `"binary"`, and `"raw"` wire
+ * values; they are deliberately not exposed here (widening this union later
+ * is backward-compatible, narrowing it is not):
+ *
+ * - `"auto"` returns parsed JSON whenever the body happens to parse, which
+ *   would let JSON responses bypass schema validation via the schema-less
+ *   overload
+ * - `"binary"` would freeze the worker's internal Buffer JSON encoding
+ *   (`{ type: "Buffer", data: number[] }`, ~4x payload inflation) into the
+ *   public SDK contract
+ * - `"raw"` is rejected by the orchestrator for non-streaming requests
+ *
+ * The runtime tuple backs the request-time guard in `executeApiRequest`:
+ * the type-level union is erased in the bundled JS user APIs run as, so
+ * values outside it must also be rejected at runtime.
+ */
+export const REST_API_RESPONSE_TYPES = ["json", "text"] as const;
+export type RestApiResponseType = (typeof REST_API_RESPONSE_TYPES)[number];
 /**
  * Options for making a generic REST API request.
  */
@@ -38,6 +64,15 @@ export interface ApiRequestOptions<TBody = unknown> {
    * Optional HTTP headers
    */
   headers?: Record<string, string>;
+  /**
+   * How the response body should be decoded. Defaults to `"json"`.
+   *
+   * Use `"text"` for endpoints that return non-JSON payloads such as
+   * XML. When requesting a text response, omit the response schema (or
+   * use one matching the decoded string, e.g. `z.string()`).
+   */
+  responseType?: RestApiResponseType;
 }
 /**
@@ -46,7 +81,7 @@ export interface ApiRequestOptions<TBody = unknown> {
 export interface ApiRequestSchema<TBody = unknown, TResponse = unknown> {
   /**
    * Optional Zod schema for request body validation.
-   * Required if body is provided in options.
+   * When omitted, `options.body` is sent without validation.
    */
   body?: z.ZodSchema<TBody>;
@@ -60,14 +95,18 @@ export interface ApiRequestSchema<TBody = unknown, TResponse = unknown> {
 /**
  * Interface for integration clients that support generic API requests.
  *
- * All API requests require response schema validation for type safety.
+ * Providing a response schema gives type-safe, validated results. Omitting
+ * it returns the raw response as `unknown`. For non-JSON payloads (e.g.
+ * `responseType: "text"` for XML), either omit the schema or supply one
+ * matching the decoded value (e.g. `z.string()` for text) — object schemas
+ * only make sense for JSON-shaped results.
  */
 export interface SupportsApiRequest {
   /**
    * Execute a generic API request with type-safe validation.
    *
    * @param options - Request configuration including method, path, params, and body
-   * @param schema - Zod schemas for request body and response validation (response schema REQUIRED)
+   * @param schema - Zod schemas for request body and response validation
    * @param metadata - Optional trace metadata for observability (label, description)
    * @returns Validated response data
    *
@@ -103,4 +142,39 @@ export interface SupportsApiRequest {
     },
     metadata?: TraceMetadata,
   ): Promise<TResponse>;
+  /**
+   * Execute a generic API request without response validation.
+   *
+   * This overload requires an explicit non-JSON `responseType` — JSON
+   * responses must always be consumed through the schema overload above,
+   * so "unvalidated JSON" is unrepresentable. The decoded non-JSON
+   * response is returned as-is, typed `unknown`.
+   *
+   * Note: request-body validation is opt-in — it runs only when
+   * `schema.body` is provided. Omitting `schema` sends `options.body`
+   * without validation.
+   *
+   * @param options - Request configuration; `responseType` must be "text"
+   * @param schema - Optional Zod schema for request body validation
+   * @param metadata - Optional trace metadata for observability (label, description)
+   * @returns The raw response from the integration
+   *
+   * @example
+   * ```typescript
+   * const xml = await ctx.integrations.legacyApi.apiRequest({
+   *   method: 'GET',
+   *   path: '/report.xml',
+   *   responseType: 'text',
+   * });
+   * // xml is the raw XML string
+   * ```
+   */
+  apiRequest<TBody>(
+    options: ApiRequestOptions<TBody> & {
+      responseType: Exclude<RestApiResponseType, "json">;
+    },
+    schema?: ApiRequestSchema<TBody, unknown>,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
 }

package/src/integrations/documentation-resolver.test.ts CHANGED Viewed

@@ -838,6 +838,37 @@ describe("resolveIntegrationDocumentation", () => {
     });
   });
+  describe("restapiintegration responseType gating (real docs)", () => {
+    // These resolve the actual shipped docs, not a fixture: the overlay
+    // gating is the discoverability guard for the responseType feature
+    // (agents whose worker sdk-api predates it must never be told the
+    // option exists), so the real manifest content is the contract.
+    it("documents responseType for agents whose sdk-api supports it", async () => {
+      const docs = await resolveIntegrationDocumentation("restapiintegration", {
+        sdkVersion: "0.0.3",
+      });
+      expect(docs).toContain('responseType: "text"');
+      expect(docs).not.toContain("does not support the `responseType`");
+    });
+    it("notes non-support instead of documenting responseType on older agents", async () => {
+      const docs = await resolveIntegrationDocumentation("restapiintegration", {
+        sdkVersion: "0.0.2",
+      });
+      expect(docs).toContain("does not support the `responseType`");
+      expect(docs).not.toContain('responseType: "text"');
+    });
+    it("stays silent about responseType when the agent reports no sdk-api version", async () => {
+      const docs = await resolveIntegrationDocumentation("restapiintegration");
+      expect(docs).not.toContain("responseType");
+    });
+  });
   it("blocks overlay paths outside the plugin directory", async () => {
     const integrationsDirectory = createPluginDocsFixture("dropbox", {
       "README.md": "base",