@superblocksteam/sdk-api 0.0.7 → 0.0.9

package/src/integrations/base/decode-worker-binary-response.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from "vitest";
+
+import { RestApiValidationError } from "../../errors.js";
+import { decodeWorkerBinaryResponse } from "./decode-worker-binary-response.js";
+
+describe("decodeWorkerBinaryResponse", () => {
+  it("copies a Uint8Array into a plain Uint8Array with the same bytes", () => {
+    const source = new Uint8Array([1, 2, 255]);
+
+    const result = decodeWorkerBinaryResponse(source);
+
+    expect(result).toBeInstanceOf(Uint8Array);
+    expect(result.constructor).toBe(Uint8Array);
+    expect(Array.from(result)).toEqual([1, 2, 255]);
+    source[0] = 9;
+    expect(result[0]).toBe(1);
+  });
+
+  it("converts worker Buffer JSON into a plain Uint8Array", () => {
+    const result = decodeWorkerBinaryResponse({
+      type: "Buffer",
+      data: [37, 80, 68, 70],
+    });
+
+    expect(result.constructor).toBe(Uint8Array);
+    expect(Array.from(result)).toEqual([37, 80, 68, 70]);
+  });
+
+  it("converts empty Buffer JSON into a zero-length Uint8Array", () => {
+    const result = decodeWorkerBinaryResponse({ type: "Buffer", data: [] });
+
+    expect(result).toBeInstanceOf(Uint8Array);
+    expect(result.byteLength).toBe(0);
+  });
+
+  it("rejects a missing discriminant", () => {
+    expect(() => decodeWorkerBinaryResponse({ data: [1] })).toThrow(
+      RestApiValidationError,
+    );
+  });
+
+  it("rejects a non-Buffer discriminant", () => {
+    expect(() =>
+      decodeWorkerBinaryResponse({ type: "Array", data: [1] }),
+    ).toThrow(RestApiValidationError);
+  });
+
+  it("rejects a non-array data field", () => {
+    expect(() =>
+      decodeWorkerBinaryResponse({ type: "Buffer", data: "00ff" }),
+    ).toThrow(RestApiValidationError);
+  });
+
+  it("rejects a byte outside 0 through 255", () => {
+    expect(() =>
+      decodeWorkerBinaryResponse({ type: "Buffer", data: [256] }),
+    ).toThrow(RestApiValidationError);
+  });
+
+  it("rejects a negative byte", () => {
+    expect(() =>
+      decodeWorkerBinaryResponse({ type: "Buffer", data: [-1] }),
+    ).toThrow(RestApiValidationError);
+  });
+
+  it("reports the index of a non-integer byte", () => {
+    try {
+      decodeWorkerBinaryResponse({ type: "Buffer", data: [1, 1.5] });
+    } catch (error) {
+      expect(error).toBeInstanceOf(RestApiValidationError);
+      if (!(error instanceof RestApiValidationError)) {
+        throw error;
+      }
+      expect(error.details.zodError.issues).toEqual([
+        expect.objectContaining({ path: ["data", 1] }),
+      ]);
+      return;
+    }
+    throw new Error("Expected binary response validation to fail");
+  });
+
+  it("redacts malformed binary data from validation errors", () => {
+    const data = Array.from({ length: 4096 }, () => 0);
+    data[4095] = 256;
+
+    try {
+      decodeWorkerBinaryResponse({ type: "Buffer", data });
+    } 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 malformed binary response to fail");
+  });
+
+  it("rejects a string payload", () => {
+    expect(() => decodeWorkerBinaryResponse("not-binary")).toThrow(
+      RestApiValidationError,
+    );
+  });
+});

package/src/integrations/base/decode-worker-binary-response.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+
+import {
+  REDACTED_BINARY_RESPONSE_DATA,
+  RestApiValidationError,
+} from "../../errors.js";
+
+export { REDACTED_BINARY_RESPONSE_DATA };
+
+const workerBinaryResponseSchema = z.union([
+  z.instanceof(Uint8Array).transform((value) => new Uint8Array(value)),
+  z
+    .object({
+      data: z.unknown(),
+      type: z.literal("Buffer"),
+    })
+    .transform((value, context) => {
+      if (!Array.isArray(value.data)) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "data must be an array of bytes",
+          path: ["data"],
+        });
+        return z.NEVER;
+      }
+
+      const bytes = new Uint8Array(value.data.length);
+      for (let index = 0; index < value.data.length; index += 1) {
+        const item = value.data[index];
+        if (
+          typeof item !== "number" ||
+          !Number.isInteger(item) ||
+          item < 0 ||
+          item > 255
+        ) {
+          context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "byte must be an integer from 0 through 255",
+            path: ["data", index],
+          });
+          return z.NEVER;
+        }
+        bytes[index] = item;
+      }
+
+      return bytes;
+    }),
+]);
+
+export function decodeWorkerBinaryResponse(value: unknown): Uint8Array {
+  const result = workerBinaryResponseSchema.safeParse(value);
+  if (!result.success) {
+    throw new RestApiValidationError(
+      `Binary response is malformed: ${result.error.message}`,
+      {
+        data: REDACTED_BINARY_RESPONSE_DATA,
+        zodError: result.error,
+      },
+    );
+  }
+  return result.data;
+}

package/src/integrations/base/index.ts

@@ -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

@@ -1,13 +1,3 @@
-/**
- * Abstract base for REST API Integration clients.
- *
- * Owns the shared infrastructure that every REST-API-backed integration
- * needs: config storage, parameter helpers, body validation, request
- * construction, and query execution. Subclasses add their own
- * `apiRequest` with whatever response-handling strategy they need
- * (e.g. direct Zod validation, discriminated-union wrapping).
- */
-
 import type { PartialMessage } from "@bufbuild/protobuf";
 import { z } from "zod";
 
@@ -17,17 +7,12 @@ 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 { decodeWorkerBinaryResponse } from "./decode-worker-binary-response.js";
+import { REST_API_RESPONSE_TYPES } from "./types.js";
 import type { ApiRequestOptions } from "./types.js";
 
 export type RestApiRequest = PartialMessage<RestApiIntegrationPlugin>;
 
-/**
- * Shared base for all REST API Integration clients.
- *
- * Provides config fields, parameter helpers, body validation, request
- * building, and query execution. Does NOT define `apiRequest` — each
- * concrete subclass supplies its own return-type contract.
- */
 export abstract class RestApiClientBase implements IntegrationClientImpl {
   readonly name: string;
   readonly pluginId: string;
@@ -52,23 +37,11 @@ export abstract class RestApiClientBase implements IntegrationClientImpl {
     };
   }
 
-  /**
-   * Validate the request body, build the proto request, and execute it.
-   *
-   * 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 bodySchema - Optional Zod schema for body validation
-   * @param metadata - Optional trace metadata for observability
-   * @returns Raw response from the orchestrator
-   */
   protected async executeApiRequest<TBody>(
     options: ApiRequestOptions<TBody>,
     bodySchema?: z.ZodSchema<TBody>,
     metadata?: TraceMetadata,
   ): Promise<unknown> {
-    // Validate request body if both body and schema are present.
     if (options.body !== undefined && bodySchema) {
       const bodyParseResult = bodySchema.safeParse(options.body);
       if (!bodyParseResult.success) {
@@ -96,13 +69,27 @@ export abstract class RestApiClientBase implements IntegrationClientImpl {
       }
     }
 
+    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) {
@@ -110,25 +97,34 @@ export abstract class RestApiClientBase implements IntegrationClientImpl {
       request.bodyType = "jsonBody";
     }
 
-    const result = await this.executeQuery(
-      request as Record<string, unknown>,
-      undefined,
-      metadata,
-    );
+    const result = await this.executeQuery({ ...request }, undefined, metadata);
 
     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`,
-          {
-            zodError: nonNullResult.error,
-            data: result,
-          },
-        );
-      }
+      throw new RestApiValidationError(
+        `Integration query returned ${String(result)} for responseType "${responseType}" - expected a response value`,
+        {
+          zodError: new z.ZodError([
+            {
+              code: z.ZodIssueCode.custom,
+              message: "response value is required",
+              path: [],
+            },
+          ]),
+          data: result,
+        },
+      );
     }
 
-    return result;
+    switch (responseType) {
+      case "binary":
+        return decodeWorkerBinaryResponse(result);
+      case "json":
+      case "text":
+        return result;
+      default: {
+        const _exhaustive: never = responseType;
+        return _exhaustive;
+      }
+    }
   }
 }

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

@@ -1,12 +1,4 @@
-/**
- * Generic REST API Integration client with Zod response validation.
- *
- * Extends RestApiClientBase with an apiRequest() that validates the
- * full response against a caller-supplied Zod schema and throws
- * RestApiValidationError on mismatch.
- */
-
-import type { z } from "zod";
+import { z } from "zod";
 
 import { RestApiValidationError } from "../../errors.js";
 import type { TraceMetadata } from "../registry.js";
@@ -14,38 +6,76 @@ import { RestApiClientBase } from "./rest-api-client-base.js";
 import type {
   ApiRequestOptions,
   ApiRequestSchema,
+  RestApiResponseType,
   SupportsApiRequest,
 } from "./types.js";
 
-/**
- * Base implementation for REST API Integration clients.
- *
- * All OpenAPI-based integration clients (except those with
- * integration-specific response handling) extend this class to
- * inherit the generic apiRequest() method with runtime Zod validation.
- */
 export abstract class RestApiIntegrationClient
   extends RestApiClientBase
   implements SupportsApiRequest
 {
   async apiRequest<TBody, TResponse>(
-    options: ApiRequestOptions<TBody>,
+    options: ApiRequestOptions<TBody> & {
+      responseType?: Exclude<RestApiResponseType, "binary">;
+    },
     schema: ApiRequestSchema<TBody, TResponse> & {
       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: "binary";
+    },
+    schema?: ApiRequestSchema<TBody, Uint8Array>,
+    metadata?: TraceMetadata,
+  ): Promise<Uint8Array>;
+  async apiRequest<TBody>(
+    options: ApiRequestOptions<TBody> & {
+      responseType: "text";
+    },
+    schema?: ApiRequestSchema<TBody, unknown>,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
+  async apiRequest<TBody, TResponse>(
+    options: ApiRequestOptions<TBody>,
+    schema?: ApiRequestSchema<TBody, TResponse>,
+    metadata?: TraceMetadata,
+  ): Promise<TResponse | Uint8Array | unknown> {
+    if ((options.responseType ?? "json") === "json" && !schema?.response) {
+      throw new RestApiValidationError(
+        'apiRequest() with responseType "json" requires a response schema. Provide one, or set responseType to "text" or "binary"',
+        {
+          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,
+    );
+
+    if (!schema?.response) {
+      return result;
+    }
 
-    // Response schema is REQUIRED - always validate
     const responseParseResult = schema.response.safeParse(result);
 
     if (!responseParseResult.success) {
       throw new RestApiValidationError(
         `Response validation failed: ${responseParseResult.error.message}`,
         {
-          zodError: responseParseResult.error,
           data: result,
+          zodError: responseParseResult.error,
         },
       );
     }

package/src/integrations/base/types.ts

@@ -1,17 +1,13 @@
-/**
- * Shared types for REST API Integration (OpenAPI) based clients.
- */
-
 import type { z } from "zod";
 
 import type { TraceMetadata } from "../registry.js";
 
-// Re-export for backwards compatibility
 export type { TraceMetadata };
 
-/**
- * Options for making a generic REST API request.
- */
+export const REST_API_RESPONSE_TYPES = ["binary", "json", "text"] as const;
+
+export type RestApiResponseType = (typeof REST_API_RESPONSE_TYPES)[number];
+
 export interface ApiRequestOptions<TBody = unknown> {
   /**
    * HTTP method for the request.
@@ -38,15 +34,23 @@ 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. Use `"binary"` for PDFs and other byte payloads. When
+   * requesting a text or binary response, omit the response schema (or
+   * use one matching the decoded value, e.g. `z.string()` or
+   * `z.instanceof(Uint8Array)`).
+   */
+  responseType?: RestApiResponseType;
 }
 
-/**
- * Schema configuration for API request validation.
- */
 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 +64,17 @@ 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 decoded response: `Uint8Array` for `responseType: "binary"`,
+ * or `unknown` for `responseType: "text"`. JSON still requires a schema.
+ * 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
    *
@@ -97,10 +104,73 @@ export interface SupportsApiRequest {
    * ```
    */
   apiRequest<TBody, TResponse>(
-    options: ApiRequestOptions<TBody>,
+    options: ApiRequestOptions<TBody> & {
+      responseType?: Exclude<RestApiResponseType, "binary">;
+    },
     schema: ApiRequestSchema<TBody, TResponse> & {
       response: z.ZodSchema<TResponse>;
     },
     metadata?: TraceMetadata,
   ): Promise<TResponse>;
+
+  /**
+   * Execute a generic API request that returns binary data.
+   *
+   * @param options - Request configuration; `responseType` must be "binary"
+   * @param schema - Optional Zod schemas for request body and decoded response validation
+   * @param metadata - Optional trace metadata for observability (label, description)
+   * @returns The decoded body as a `Uint8Array`
+   *
+   * @example
+   * ```typescript
+   * const pdf = await ctx.integrations.legacyApi.apiRequest({
+   *   method: 'GET',
+   *   path: '/file.pdf',
+   *   responseType: 'binary',
+   * });
+   * // pdf is a Uint8Array
+   * ```
+   */
+  apiRequest<TBody>(
+    options: ApiRequestOptions<TBody> & {
+      responseType: "binary";
+    },
+    schema?: ApiRequestSchema<TBody, Uint8Array>,
+    metadata?: TraceMetadata,
+  ): Promise<Uint8Array>;
+
+  /**
+   * Execute a generic API request without response validation.
+   *
+   * This overload requires an explicit `responseType: "text"` - JSON
+   * responses must always be consumed through the schema overload above,
+   * so "unvalidated JSON" is unrepresentable. The decoded text
+   * 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: "text";
+    },
+    schema?: ApiRequestSchema<TBody, unknown>,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
 }