@superblocksteam/sdk-api 2.0.156-next.3 → 2.0.156

package/dist/errors.d.ts

@@ -2,10 +2,6 @@
  * Error classes for SDK runtime errors.
  */
 import type { z } from "zod";
-export declare const REDACTED_BINARY_RESPONSE_DATA: Readonly<{
-    dataType: "binary";
-    redacted: true;
-}>;
 /**
  * Error thrown when REST API response or request body validation fails.
  *
@@ -14,12 +10,16 @@ export declare const REDACTED_BINARY_RESPONSE_DATA: Readonly<{
  */
 export declare class RestApiValidationError extends Error {
     readonly details: {
-        data: unknown;
+        /** The complete Zod error object with all validation information */
         zodError: z.ZodError;
+        /** The actual data that failed validation (request body or response) */
+        data: unknown;
     };
     constructor(message: string, details: {
-        data: unknown;
+        /** The complete Zod error object with all validation information */
         zodError: z.ZodError;
+        /** The actual data that failed validation (request body or response) */
+        data: unknown;
     });
 }
 /**

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,eAAO,MAAM,6BAA6B;;;EAGxC,CAAC;AAmBH;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,OAAO,EAAE;QAChB,IAAI,EAAE,OAAO,CAAC;QACd,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC;KACtB,CAAC;gBAGA,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,IAAI,EAAE,OAAO,CAAC;QACd,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC;KACtB;CAUJ;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;aAG3B,OAAO,EAAE;QACvB,wDAAwD;QACxD,QAAQ,EAAE,MAAM,CAAC;QACjB,sDAAsD;QACtD,MAAM,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC9D,8CAA8C;QAC9C,GAAG,EAAE,OAAO,CAAC;KACd;gBARD,OAAO,EAAE,MAAM,EACC,OAAO,EAAE;QACvB,wDAAwD;QACxD,QAAQ,EAAE,MAAM,CAAC;QACjB,sDAAsD;QACtD,MAAM,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC9D,8CAA8C;QAC9C,GAAG,EAAE,OAAO,CAAC;KACd;CAOJ;AAED;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;aAGzB,OAAO,CAAC,EAAE;QACxB,iCAAiC;QACjC,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,4CAA4C;QAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,+CAA+C;QAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,gDAAgD;QAChD,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC;QACtB,gDAAgD;QAChD,aAAa,CAAC,EAAE,OAAO,CAAC;KACzB;gBAZD,OAAO,EAAE,MAAM,EACC,OAAO,CAAC,EAAE;QACxB,iCAAiC;QACjC,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,4CAA4C;QAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,+CAA+C;QAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,gDAAgD;QAChD,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC;QACtB,gDAAgD;QAChD,aAAa,CAAC,EAAE,OAAO,CAAC;KACzB,YAAA;CAOJ"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;aAG7B,OAAO,EAAE;QACvB,oEAAoE;QACpE,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC;QACrB,wEAAwE;QACxE,IAAI,EAAE,OAAO,CAAC;KACf;gBAND,OAAO,EAAE,MAAM,EACC,OAAO,EAAE;QACvB,oEAAoE;QACpE,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC;QACrB,wEAAwE;QACxE,IAAI,EAAE,OAAO,CAAC;KACf;CAOJ;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;aAG3B,OAAO,EAAE;QACvB,wDAAwD;QACxD,QAAQ,EAAE,MAAM,CAAC;QACjB,sDAAsD;QACtD,MAAM,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC9D,8CAA8C;QAC9C,GAAG,EAAE,OAAO,CAAC;KACd;gBARD,OAAO,EAAE,MAAM,EACC,OAAO,EAAE;QACvB,wDAAwD;QACxD,QAAQ,EAAE,MAAM,CAAC;QACjB,sDAAsD;QACtD,MAAM,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC9D,8CAA8C;QAC9C,GAAG,EAAE,OAAO,CAAC;KACd;CAOJ;AAED;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;aAGzB,OAAO,CAAC,EAAE;QACxB,iCAAiC;QACjC,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,4CAA4C;QAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,+CAA+C;QAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,gDAAgD;QAChD,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC;QACtB,gDAAgD;QAChD,aAAa,CAAC,EAAE,OAAO,CAAC;KACzB;gBAZD,OAAO,EAAE,MAAM,EACC,OAAO,CAAC,EAAE;QACxB,iCAAiC;QACjC,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,4CAA4C;QAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,+CAA+C;QAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,gDAAgD;QAChD,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC;QACtB,gDAAgD;QAChD,aAAa,CAAC,EAAE,OAAO,CAAC;KACzB,YAAA;CAOJ"}

package/dist/errors.js

@@ -1,25 +1,6 @@
 /**
  * Error classes for SDK runtime errors.
  */
-export const REDACTED_BINARY_RESPONSE_DATA = Object.freeze({
-    dataType: "binary",
-    redacted: true,
-});
-function isWorkerBufferJson(data) {
-    if (typeof data !== "object" || data === null) {
-        return false;
-    }
-    if (!("data" in data) || !("type" in data)) {
-        return false;
-    }
-    return data.type === "Buffer" && Array.isArray(data.data);
-}
-function redactBinaryValidationData(data) {
-    if (data instanceof Uint8Array || isWorkerBufferJson(data)) {
-        return REDACTED_BINARY_RESPONSE_DATA;
-    }
-    return data;
-}
 /**
  * Error thrown when REST API response or request body validation fails.
  *
@@ -30,11 +11,9 @@ export class RestApiValidationError extends Error {
     details;
     constructor(message, details) {
         super(message);
+        this.details = details;
         this.name = "RestApiValidationError";
-        this.details = {
-            data: redactBinaryValidationData(details.data),
-            zodError: details.zodError,
-        };
+        // Ensure proper prototype chain for instanceof checks
         Object.setPrototypeOf(this, RestApiValidationError.prototype);
     }
 }

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,CAAC,MAAM,6BAA6B,GAAG,MAAM,CAAC,MAAM,CAAC;IACzD,QAAQ,EAAE,QAAQ;IAClB,QAAQ,EAAE,IAAI;CACf,CAAC,CAAC;AAEH,SAAS,kBAAkB,CAAC,IAAa;IACvC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC,EAAE,CAAC;QAC3C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,0BAA0B,CAAC,IAAa;IAC/C,IAAI,IAAI,YAAY,UAAU,IAAI,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3D,OAAO,6BAA6B,CAAC;IACvC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IACtC,OAAO,CAGd;IAEF,YACE,OAAe,EACf,OAGC;QAED,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,OAAO,GAAG;YACb,IAAI,EAAE,0BAA0B,CAAC,OAAO,CAAC,IAAI,CAAC;YAC9C,QAAQ,EAAE,OAAO,CAAC,QAAQ;SAC3B,CAAC;QACF,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAChE,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAG3B;IAFlB,YACE,OAAe,EACC,OAOf;QAED,KAAK,CAAC,OAAO,CAAC,CAAC;QATC,YAAO,GAAP,OAAO,CAOtB;QAGD,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,sDAAsD;QACtD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAC9D,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAGzB;IAFlB,YACE,OAAe,EACC,OAWf;QAED,KAAK,CAAC,OAAO,CAAC,CAAC;QAbC,YAAO,GAAP,OAAO,CAWtB;QAGD,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,sDAAsD;QACtD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAC;IAC5D,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;;;GAKG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAG7B;IAFlB,YACE,OAAe,EACC,OAKf;QAED,KAAK,CAAC,OAAO,CAAC,CAAC;QAPC,YAAO,GAAP,OAAO,CAKtB;QAGD,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,sDAAsD;QACtD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAChE,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAG3B;IAFlB,YACE,OAAe,EACC,OAOf;QAED,KAAK,CAAC,OAAO,CAAC,CAAC;QATC,YAAO,GAAP,OAAO,CAOtB;QAGD,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,sDAAsD;QACtD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAC9D,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAGzB;IAFlB,YACE,OAAe,EACC,OAWf;QAED,KAAK,CAAC,OAAO,CAAC,CAAC;QAbC,YAAO,GAAP,OAAO,CAWtB;QAGD,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,sDAAsD;QACtD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAC;IAC5D,CAAC;CACF"}

package/dist/integrations/base/rest-api-client-base.d.ts

@@ -1,3 +1,12 @@
+/**
+ * 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";
 import type { Property } from "@superblocksteam/types/dist/src/common/v1/plugin_pb";
@@ -6,6 +15,13 @@ import type { QueryExecutor, TraceMetadata } from "../registry.js";
 import type { IntegrationConfig, IntegrationClientImpl } 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 declare abstract class RestApiClientBase implements IntegrationClientImpl {
     readonly name: string;
     readonly pluginId: string;
@@ -16,6 +32,17 @@ export declare abstract class RestApiClientBase implements IntegrationClientImpl
      * Create a Property object for query params / headers.
      */
     protected createParam(key: string, value: unknown): PartialMessage<Property>;
+    /**
+     * 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 - 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
+     */
     protected executeApiRequest<TBody>(options: ApiRequestOptions<TBody>, bodySchema?: z.ZodSchema<TBody>, metadata?: TraceMetadata): Promise<unknown>;
 }
 //# sourceMappingURL=rest-api-client-base.d.ts.map

package/dist/integrations/base/rest-api-client-base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rest-api-client-base.d.ts","sourceRoot":"","sources":["../../../src/integrations/base/rest-api-client-base.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qDAAqD,CAAC;AACpF,OAAO,KAAK,EAAE,MAAM,IAAI,wBAAwB,EAAE,MAAM,yEAAyE,CAAC;AAGlI,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAG5E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,MAAM,cAAc,GAAG,cAAc,CAAC,wBAAwB,CAAC,CAAC;AAEtE,8BAAsB,iBAAkB,YAAW,qBAAqB;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IAEnC,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC;gBAEnC,MAAM,EAAE,iBAAiB,EAAE,YAAY,EAAE,aAAa;IAOlE;;OAEG;IACH,SAAS,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,cAAc,CAAC,QAAQ,CAAC;cAO5D,iBAAiB,CAAC,KAAK,EACrC,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,EACjC,UAAU,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,EAC/B,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,OAAO,CAAC;CAsFpB"}
+{"version":3,"file":"rest-api-client-base.d.ts","sourceRoot":"","sources":["../../../src/integrations/base/rest-api-client-base.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qDAAqD,CAAC;AACpF,OAAO,KAAK,EAAE,MAAM,IAAI,wBAAwB,EAAE,MAAM,yEAAyE,CAAC;AAGlI,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE5E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,MAAM,cAAc,GAAG,cAAc,CAAC,wBAAwB,CAAC,CAAC;AAEtE;;;;;;GAMG;AACH,8BAAsB,iBAAkB,YAAW,qBAAqB;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IAEnC,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC;gBAEnC,MAAM,EAAE,iBAAiB,EAAE,YAAY,EAAE,aAAa;IAOlE;;OAEG;IACH,SAAS,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,cAAc,CAAC,QAAQ,CAAC;IAO5E;;;;;;;;;;OAUG;cACa,iBAAiB,CAAC,KAAK,EACrC,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,EACjC,UAAU,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,EAC/B,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,OAAO,CAAC;CAuFpB"}

package/dist/integrations/base/rest-api-client-base.js

@@ -1,7 +1,22 @@
+/**
+ * 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 { z } from "zod";
 import { RestApiValidationError } from "../../errors.js";
-import { decodeWorkerBinaryResponse } from "./decode-worker-binary-response.js";
 import { REST_API_RESPONSE_TYPES } from "./types.js";
+/**
+ * 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 class RestApiClientBase {
     name;
     pluginId;
@@ -22,7 +37,19 @@ export class RestApiClientBase {
             value: typeof value === "string" ? value : JSON.stringify(value),
         };
     }
+    /**
+     * 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 - 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
+     */
     async executeApiRequest(options, bodySchema, metadata) {
+        // Validate request body if both body and schema are present.
         if (options.body !== undefined && bodySchema) {
             const bodyParseResult = bodySchema.safeParse(options.body);
             if (!bodyParseResult.success) {
@@ -44,11 +71,15 @@ export class RestApiClientBase {
                 params.push(this.createParam(key, value));
             }
         }
+        // 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(", ")}`, {
+            throw new RestApiValidationError(`Unsupported responseType ${JSON.stringify(options.responseType)} — expected one of: ${REST_API_RESPONSE_TYPES.join(", ")}`, {
                 zodError: responseTypeResult.error,
                 data: options.responseType,
             });
@@ -66,30 +97,22 @@ export class RestApiClientBase {
             request.body = JSON.stringify(options.body);
             request.bodyType = "jsonBody";
         }
-        const result = await this.executeQuery({ ...request }, undefined, metadata);
+        const result = await this.executeQuery(request, undefined, 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) {
-            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,
-            });
-        }
-        switch (responseType) {
-            case "binary":
-                return decodeWorkerBinaryResponse(result);
-            case "json":
-            case "text":
-                return result;
-            default: {
-                const _exhaustive = responseType;
-                return _exhaustive;
+            const nonNullResult = z.object({}).safeParse(result);
+            if (!nonNullResult.success) {
+                throw new RestApiValidationError(`Integration query returned ${String(result)} for responseType "${responseType}" — expected a response value`, {
+                    zodError: nonNullResult.error,
+                    data: result,
+                });
             }
         }
+        return result;
     }
 }
 //# sourceMappingURL=rest-api-client-base.js.map

package/dist/integrations/base/rest-api-client-base.js.map

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

package/dist/integrations/base/rest-api-integration-client.d.ts

@@ -1,18 +1,30 @@
+/**
+ * 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. 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 { z } from "zod";
 import type { TraceMetadata } from "../registry.js";
 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 declare abstract class RestApiIntegrationClient extends RestApiClientBase implements SupportsApiRequest {
-    apiRequest<TBody, TResponse>(options: ApiRequestOptions<TBody> & {
-        responseType?: Exclude<RestApiResponseType, "binary">;
-    }, schema: ApiRequestSchema<TBody, TResponse> & {
+    apiRequest<TBody, TResponse>(options: ApiRequestOptions<TBody>, schema: ApiRequestSchema<TBody, TResponse> & {
         response: z.ZodSchema<TResponse>;
     }, metadata?: TraceMetadata): Promise<TResponse>;
     apiRequest<TBody>(options: ApiRequestOptions<TBody> & {
-        responseType: "binary";
-    }, schema?: ApiRequestSchema<TBody, Uint8Array>, metadata?: TraceMetadata): Promise<Uint8Array>;
-    apiRequest<TBody>(options: ApiRequestOptions<TBody> & {
-        responseType: "text";
+        responseType: Exclude<RestApiResponseType, "json">;
     }, schema?: ApiRequestSchema<TBody, unknown>, metadata?: TraceMetadata): Promise<unknown>;
 }
 //# sourceMappingURL=rest-api-integration-client.d.ts.map

package/dist/integrations/base/rest-api-integration-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rest-api-integration-client.d.ts","sourceRoot":"","sources":["../../../src/integrations/base/rest-api-integration-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB,8BAAsB,wBACpB,SAAQ,iBACR,YAAW,kBAAkB;IAEvB,UAAU,CAAC,KAAK,EAAE,SAAS,EAC/B,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAAG;QAClC,YAAY,CAAC,EAAE,OAAO,CAAC,mBAAmB,EAAE,QAAQ,CAAC,CAAC;KACvD,EACD,MAAM,EAAE,gBAAgB,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG;QAC3C,QAAQ,EAAE,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;KAClC,EACD,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,SAAS,CAAC;IACf,UAAU,CAAC,KAAK,EACpB,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAAG;QAClC,YAAY,EAAE,QAAQ,CAAC;KACxB,EACD,MAAM,CAAC,EAAE,gBAAgB,CAAC,KAAK,EAAE,UAAU,CAAC,EAC5C,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,UAAU,CAAC;IAChB,UAAU,CAAC,KAAK,EACpB,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAAG;QAClC,YAAY,EAAE,MAAM,CAAC;KACtB,EACD,MAAM,CAAC,EAAE,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,EACzC,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,OAAO,CAAC;CA8CpB"}
+{"version":3,"file":"rest-api-integration-client.d.ts","sourceRoot":"","sources":["../../../src/integrations/base/rest-api-integration-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,8BAAsB,wBACpB,SAAQ,iBACR,YAAW,kBAAkB;IAEvB,UAAU,CAAC,KAAK,EAAE,SAAS,EAC/B,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,EACjC,MAAM,EAAE,gBAAgB,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG;QAC3C,QAAQ,EAAE,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;KAClC,EACD,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,SAAS,CAAC;IACf,UAAU,CAAC,KAAK,EACpB,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAAG;QAClC,YAAY,EAAE,OAAO,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC;KACpD,EACD,MAAM,CAAC,EAAE,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,EACzC,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,OAAO,CAAC;CAwDpB"}

package/dist/integrations/base/rest-api-integration-client.js

@@ -1,10 +1,30 @@
+/**
+ * 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. 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 { z } from "zod";
 import { RestApiValidationError } from "../../errors.js";
 import { RestApiClientBase } from "./rest-api-client-base.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 class RestApiIntegrationClient extends RestApiClientBase {
     async apiRequest(options, schema, metadata) {
+        // 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 to "text" or "binary"', {
+            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,
@@ -16,14 +36,21 @@ export class RestApiIntegrationClient extends RestApiClientBase {
             });
         }
         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;
         }
         const responseParseResult = schema.response.safeParse(result);
         if (!responseParseResult.success) {
             throw new RestApiValidationError(`Response validation failed: ${responseParseResult.error.message}`, {
-                data: result,
                 zodError: responseParseResult.error,
+                data: result,
             });
         }
         return responseParseResult.data;

package/dist/integrations/base/rest-api-integration-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"rest-api-integration-client.js","sourceRoot":"","sources":["../../../src/integrations/base/rest-api-integration-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAQ9D,MAAM,OAAgB,wBACpB,SAAQ,iBAAiB;IA0BzB,KAAK,CAAC,UAAU,CACd,OAAiC,EACjC,MAA2C,EAC3C,QAAwB;QAExB,IAAI,CAAC,OAAO,CAAC,YAAY,IAAI,MAAM,CAAC,KAAK,MAAM,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC;YACrE,MAAM,IAAI,sBAAsB,CAC9B,0HAA0H,EAC1H;gBACE,QAAQ,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC;oBACvB;wBACE,IAAI,EAAE,CAAC,CAAC,YAAY,CAAC,MAAM;wBAC3B,OAAO,EAAE,gDAAgD;wBACzD,IAAI,EAAE,CAAC,UAAU,CAAC;qBACnB;iBACF,CAAC;gBACF,IAAI,EAAE,SAAS;aAChB,CACF,CAAC;QACJ,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,iBAAiB,CACzC,OAAO,EACP,MAAM,EAAE,IAAI,EACZ,QAAQ,CACT,CAAC;QAEF,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC;YACtB,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,MAAM,mBAAmB,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAE9D,IAAI,CAAC,mBAAmB,CAAC,OAAO,EAAE,CAAC;YACjC,MAAM,IAAI,sBAAsB,CAC9B,+BAA+B,mBAAmB,CAAC,KAAK,CAAC,OAAO,EAAE,EAClE;gBACE,IAAI,EAAE,MAAM;gBACZ,QAAQ,EAAE,mBAAmB,CAAC,KAAK;aACpC,CACF,CAAC;QACJ,CAAC;QAED,OAAO,mBAAmB,CAAC,IAAI,CAAC;IAClC,CAAC;CACF"}
+{"version":3,"file":"rest-api-integration-client.js","sourceRoot":"","sources":["../../../src/integrations/base/rest-api-integration-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAQ9D;;;;;;GAMG;AACH,MAAM,OAAgB,wBACpB,SAAQ,iBAAiB;IAiBzB,KAAK,CAAC,UAAU,CACd,OAAiC,EACjC,MAA2C,EAC3C,QAAwB;QAExB,qEAAqE;QACrE,sEAAsE;QACtE,oEAAoE;QACpE,IAAI,CAAC,OAAO,CAAC,YAAY,IAAI,MAAM,CAAC,KAAK,MAAM,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC;YACrE,MAAM,IAAI,sBAAsB,CAC9B,uJAAuJ,EACvJ;gBACE,QAAQ,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC;oBACvB;wBACE,IAAI,EAAE,CAAC,CAAC,YAAY,CAAC,MAAM;wBAC3B,OAAO,EAAE,gDAAgD;wBACzD,IAAI,EAAE,CAAC,UAAU,CAAC;qBACnB;iBACF,CAAC;gBACF,IAAI,EAAE,SAAS;aAChB,CACF,CAAC;QACJ,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,iBAAiB,CACzC,OAAO,EACP,MAAM,EAAE,IAAI,EACZ,QAAQ,CACT,CAAC;QAEF,oEAAoE;QACpE,mEAAmE;QACnE,mEAAmE;QACnE,gEAAgE;QAChE,oEAAoE;QACpE,oEAAoE;QACpE,yBAAyB;QACzB,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC;YACtB,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,MAAM,mBAAmB,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAE9D,IAAI,CAAC,mBAAmB,CAAC,OAAO,EAAE,CAAC;YACjC,MAAM,IAAI,sBAAsB,CAC9B,+BAA+B,mBAAmB,CAAC,KAAK,CAAC,OAAO,EAAE,EAClE;gBACE,QAAQ,EAAE,mBAAmB,CAAC,KAAK;gBACnC,IAAI,EAAE,MAAM;aACb,CACF,CAAC;QACJ,CAAC;QAED,OAAO,mBAAmB,CAAC,IAAI,CAAC;IAClC,CAAC;CACF"}

package/dist/integrations/base/types.d.ts

@@ -1,8 +1,36 @@
+/**
+ * Shared types for REST API Integration (OpenAPI) based clients.
+ */
 import type { z } from "zod";
 import type { TraceMetadata } from "../registry.js";
 export type { TraceMetadata };
-export declare const REST_API_RESPONSE_TYPES: readonly ["binary", "json", "text"];
+/**
+ * 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 declare const REST_API_RESPONSE_TYPES: readonly ["json", "text"];
 export type RestApiResponseType = (typeof REST_API_RESPONSE_TYPES)[number];
+/**
+ * Options for making a generic REST API request.
+ */
 export interface ApiRequestOptions<TBody = unknown> {
     /**
      * HTTP method for the request.
@@ -29,13 +57,14 @@ export interface ApiRequestOptions<TBody = unknown> {
      * 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)`).
+     * XML. When requesting a text response, omit the response schema (or
+     * use one matching the decoded string, e.g. `z.string()`).
      */
     responseType?: RestApiResponseType;
 }
+/**
+ * Schema configuration for API request validation.
+ */
 export interface ApiRequestSchema<TBody = unknown, TResponse = unknown> {
     /**
      * Optional Zod schema for request body validation.
@@ -52,9 +81,10 @@ export interface ApiRequestSchema<TBody = unknown, TResponse = unknown> {
  * Interface for integration clients that support generic API requests.
  *
  * 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.
+ * 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 {
     /**
@@ -90,41 +120,18 @@ export interface SupportsApiRequest {
      * // result is typed as { ts: string; channel: string }
      * ```
      */
-    apiRequest<TBody, TResponse>(options: ApiRequestOptions<TBody> & {
-        responseType?: Exclude<RestApiResponseType, "binary">;
-    }, schema: ApiRequestSchema<TBody, TResponse> & {
+    apiRequest<TBody, TResponse>(options: ApiRequestOptions<TBody>, 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
+     * 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 text
+     * 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
+     * Note: request-body validation is opt-in — it runs only when
      * `schema.body` is provided. Omitting `schema` sends `options.body`
      * without validation.
      *
@@ -144,7 +151,7 @@ export interface SupportsApiRequest {
      * ```
      */
     apiRequest<TBody>(options: ApiRequestOptions<TBody> & {
-        responseType: "text";
+        responseType: Exclude<RestApiResponseType, "json">;
     }, schema?: ApiRequestSchema<TBody, unknown>, metadata?: TraceMetadata): Promise<unknown>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/integrations/base/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/integrations/base/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B,eAAO,MAAM,uBAAuB,qCAAsC,CAAC;AAE3E,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3E,MAAM,WAAW,iBAAiB,CAAC,KAAK,GAAG,OAAO;IAChD;;OAEG;IACH,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;IAEzE;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,IAAI,CAAC,EAAE,KAAK,CAAC;IAEb;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEjC;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB,CAAC,KAAK,GAAG,OAAO,EAAE,SAAS,GAAG,OAAO;IACpE;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,UAAU,CAAC,KAAK,EAAE,SAAS,EACzB,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAAG;QAClC,YAAY,CAAC,EAAE,OAAO,CAAC,mBAAmB,EAAE,QAAQ,CAAC,CAAC;KACvD,EACD,MAAM,EAAE,gBAAgB,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG;QAC3C,QAAQ,EAAE,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;KAClC,EACD,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,SAAS,CAAC,CAAC;IAEtB;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,KAAK,EACd,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAAG;QAClC,YAAY,EAAE,QAAQ,CAAC;KACxB,EACD,MAAM,CAAC,EAAE,gBAAgB,CAAC,KAAK,EAAE,UAAU,CAAC,EAC5C,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,UAAU,CAAC,CAAC;IAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,UAAU,CAAC,KAAK,EACd,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAAG;QAClC,YAAY,EAAE,MAAM,CAAC;KACtB,EACD,MAAM,CAAC,EAAE,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,EACzC,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/integrations/base/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,uBAAuB,2BAA4B,CAAC;AAEjE,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3E;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,KAAK,GAAG,OAAO;IAChD;;OAEG;IACH,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;IAEzE;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,IAAI,CAAC,EAAE,KAAK,CAAC;IAEb;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEjC;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,KAAK,GAAG,OAAO,EAAE,SAAS,GAAG,OAAO;IACpE;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,UAAU,CAAC,KAAK,EAAE,SAAS,EACzB,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,EACjC,MAAM,EAAE,gBAAgB,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG;QAC3C,QAAQ,EAAE,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;KAClC,EACD,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,SAAS,CAAC,CAAC;IAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,UAAU,CAAC,KAAK,EACd,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAAG;QAClC,YAAY,EAAE,OAAO,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC;KACpD,EACD,MAAM,CAAC,EAAE,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,EACzC,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB"}

package/dist/integrations/base/types.js

@@ -1,2 +1,27 @@
-export const REST_API_RESPONSE_TYPES = ["binary", "json", "text"];
+/**
+ * Shared types for REST API Integration (OpenAPI) based clients.
+ */
+/**
+ * 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"];
 //# sourceMappingURL=types.js.map

package/dist/integrations/base/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/integrations/base/types.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAU,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/integrations/base/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAU,CAAC"}

package/dist/integrations/documentation-resolver.test.js

@@ -728,20 +728,15 @@ describe("resolveIntegrationDocumentation", () => {
         });
     });
     describe("restapiintegration responseType gating (real docs)", () => {
-        it("documents text responseType for agents whose sdk-api supports text only", async () => {
+        // 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('responseType: "binary"');
-            expect(docs).not.toContain("does not support the `responseType`");
-        });
-        it("documents binary responseType only for agents whose sdk-api supports it", async () => {
-            const docs = await resolveIntegrationDocumentation("restapiintegration", {
-                sdkVersion: "0.0.4",
-            });
-            expect(docs).toContain('responseType: "text"');
-            expect(docs).toContain('responseType: "binary"');
             expect(docs).not.toContain("does not support the `responseType`");
         });
         it("notes non-support instead of documenting responseType on older agents", async () => {
@@ -750,7 +745,6 @@ describe("resolveIntegrationDocumentation", () => {
             });
             expect(docs).toContain("does not support the `responseType`");
             expect(docs).not.toContain('responseType: "text"');
-            expect(docs).not.toContain('responseType: "binary"');
         });
         it("stays silent about responseType when the agent reports no sdk-api version", async () => {
             const docs = await resolveIntegrationDocumentation("restapiintegration");