@superblocksteam/sdk-api 0.0.6 → 0.0.8

package/src/integrations/base/index.ts

@@ -2,13 +2,13 @@
  * Base clients for integrations.
  */
 
+export { RestApiClientBase } from "./rest-api-client-base.js";
 export { RestApiIntegrationClient } from "./rest-api-integration-client.js";
-export type { RestApiRequest } from "./rest-api-integration-client.js";
+export type { RestApiRequest } from "./rest-api-client-base.js";
 export { GraphQLIntegrationClient } from "./graphql-integration-client.js";
 export type {
   ApiRequestOptions,
   ApiRequestSchema,
+  RestApiResponseType,
   SupportsApiRequest,
-  StreamApiRequestSchema,
-  SupportsStreamingApiRequest,
 } from "./types.js";

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

@@ -0,0 +1,158 @@
+/**
+ * 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";
+import type { Plugin as RestApiIntegrationPlugin } from "@superblocksteam/types/dist/src/plugins/restapiintegration/v1/plugin_pb";
+
+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>;
+
+/**
+ * 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;
+  readonly config: IntegrationConfig;
+
+  protected readonly executeQuery: QueryExecutor;
+
+  constructor(config: IntegrationConfig, executeQuery: QueryExecutor) {
+    this.name = config.name;
+    this.pluginId = config.pluginId;
+    this.config = config;
+    this.executeQuery = executeQuery;
+  }
+
+  /**
+   * Create a Property object for query params / headers.
+   */
+  protected createParam(key: string, value: unknown): PartialMessage<Property> {
+    return {
+      key,
+      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
+   */
+  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) {
+        throw new RestApiValidationError(
+          `Request body validation failed: ${bodyParseResult.error.message}`,
+          {
+            zodError: bodyParseResult.error,
+            data: options.body,
+          },
+        );
+      }
+    }
+
+    const headers: PartialMessage<Property>[] = [];
+    if (options.headers) {
+      for (const [key, value] of Object.entries(options.headers)) {
+        headers.push(this.createParam(key, value));
+      }
+    }
+
+    const params: PartialMessage<Property>[] = [];
+    if (options.params) {
+      for (const [key, value] of Object.entries(options.params)) {
+        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(", ")}`,
+        {
+          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,
+    };
+
+    if (options.body !== undefined) {
+      request.body = JSON.stringify(options.body);
+      request.bodyType = "jsonBody";
+    }
+
+    const result = await this.executeQuery(
+      request as Record<string, unknown>,
+      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) {
+      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;
+  }
+}

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

@@ -1,137 +1,92 @@
 /**
- * Base client for REST API Integration (OpenAPI) based integrations.
+ * Generic REST API Integration client with Zod response validation.
  *
- * Provides common apiRequest() method for all OpenAPI-based plugins.
+ * 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 type { PartialMessage } from "@bufbuild/protobuf";
-import type { Plugin as RestApiIntegrationPlugin } from "@superblocksteam/types/dist/src/plugins/restapiintegration/v1/plugin_pb";
-import type { Property } from "@superblocksteam/types/dist/src/common/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type {
-  QueryExecutor,
-  StreamingQueryExecutor,
-  TraceMetadata,
-} from "../registry.js";
+import { z } from "zod";
+
+import { RestApiValidationError } from "../../errors.js";
+import type { TraceMetadata } from "../registry.js";
+import { RestApiClientBase } from "./rest-api-client-base.js";
 import type {
   ApiRequestOptions,
   ApiRequestSchema,
+  RestApiResponseType,
   SupportsApiRequest,
-  StreamApiRequestSchema,
-  SupportsStreamingApiRequest,
 } from "./types.js";
-import {
-  RestApiValidationError,
-  StreamChunkValidationError,
-} from "../../errors.js";
-import type { z } from "zod";
-
-export type RestApiRequest = PartialMessage<RestApiIntegrationPlugin>;
 
 /**
  * Base implementation for REST API Integration clients.
  *
- * All OpenAPI-based integration clients extend this class to inherit
- * the generic apiRequest() method with runtime schema validation.
- * Also supports streaming API requests when a streaming executor is provided.
+ * 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
-  implements
-    IntegrationClientImpl,
-    SupportsApiRequest,
-    SupportsStreamingApiRequest
+  extends RestApiClientBase
+  implements SupportsApiRequest
 {
-  readonly name: string;
-  readonly pluginId: string;
-  readonly config: IntegrationConfig;
-
-  protected readonly executeQuery: QueryExecutor;
-  protected readonly executeStreamingQuery?: StreamingQueryExecutor;
-
-  constructor(
-    config: IntegrationConfig,
-    executeQuery: QueryExecutor,
-    executeStreamingQuery?: StreamingQueryExecutor,
-  ) {
-    this.name = config.name;
-    this.pluginId = config.pluginId;
-    this.config = config;
-    this.executeQuery = executeQuery;
-    this.executeStreamingQuery = executeStreamingQuery;
-  }
-
-  /**
-   * Helper to create a Property object for params.
-   */
-  protected createParam(key: string, value: unknown): PartialMessage<Property> {
-    return {
-      key,
-      value: typeof value === "string" ? value : JSON.stringify(value),
-    };
-  }
-
   async apiRequest<TBody, TResponse>(
     options: ApiRequestOptions<TBody>,
     schema: ApiRequestSchema<TBody, TResponse> & {
       response: z.ZodSchema<TResponse>;
     },
     metadata?: TraceMetadata,
-  ): Promise<TResponse> {
-    // Validate request body against schema if both are present.
-    // Body schema is optional — if not provided, the body is sent unvalidated.
-    if (options.body !== undefined && schema?.body) {
-      const bodyParseResult = schema.body.safeParse(options.body);
-      if (!bodyParseResult.success) {
-        throw new RestApiValidationError(
-          `Request body validation failed: ${bodyParseResult.error.message}`,
-          {
-            zodError: bodyParseResult.error,
-            data: options.body,
-          },
-        );
-      }
-    }
-
-    // Convert headers to Property array
-    const headers: PartialMessage<Property>[] = [];
-    if (options.headers) {
-      for (const [key, value] of Object.entries(options.headers)) {
-        headers.push(this.createParam(key, value));
-      }
-    }
-
-    // Convert query params to Property array
-    const params: PartialMessage<Property>[] = [];
-    if (options.params) {
-      for (const [key, value] of Object.entries(options.params)) {
-        params.push(this.createParam(key, value));
-      }
-    }
-
-    // Build the request using raw HTTP mode
-    const request: RestApiRequest = {
-      openApiAction: "genericHttpRequest",
-      httpMethod: options.method.toUpperCase(),
-      urlPath: options.path,
-      headers,
-      params,
-      responseType: "json",
-    };
-
-    // Add body if provided
-    if (options.body !== undefined) {
-      request.body = JSON.stringify(options.body);
-      request.bodyType = "jsonBody";
+  ): 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,
+        },
+      );
     }
 
-    // Execute the request
-    const result = await this.executeQuery(
-      request as Record<string, unknown>,
-      undefined,
+    const result = await this.executeApiRequest(
+      options,
+      schema?.body,
       metadata,
     );
 
-    // Response schema is REQUIRED - always validate
+    // 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) {
@@ -146,134 +101,4 @@ export abstract class RestApiIntegrationClient
 
     return responseParseResult.data;
   }
-
-  /**
-   * Execute a streaming API request with type-safe chunk validation.
-   *
-   * Returns an AsyncIterable that yields validated chunks as they arrive.
-   * Each chunk is validated against the provided schema before being yielded.
-   *
-   * @param options - Request configuration including method, path, params, and body
-   * @param schema - Zod schemas for request body and chunk validation
-   * @param metadata - Optional trace metadata for observability (label, description)
-   * @returns AsyncIterable yielding validated chunks
-   *
-   * @example
-   * ```typescript
-   * const ChunkSchema = z.object({
-   *   id: z.string(),
-   *   choices: z.array(z.object({
-   *     delta: z.object({
-   *       content: z.string().optional(),
-   *     }),
-   *   })),
-   * });
-   *
-   * const stream = client.streamApiRequest(
-   *   {
-   *     method: 'POST',
-   *     path: '/v1/chat/completions',
-   *     body: {
-   *       model: 'gpt-4',
-   *       stream: true,
-   *       messages: [{ role: 'user', content: 'Hello!' }],
-   *     },
-   *   },
-   *   { chunk: ChunkSchema },
-   *   { label: 'openai.chatCompletions', description: 'Stream chat completion' }
-   * );
-   *
-   * for await (const chunk of stream) {
-   *   console.log(chunk.choices[0]?.delta?.content);
-   * }
-   * ```
-   */
-  async *streamApiRequest<TBody, TChunk>(
-    options: ApiRequestOptions<TBody>,
-    schema: StreamApiRequestSchema<TBody, TChunk>,
-    metadata?: TraceMetadata,
-  ): AsyncIterable<TChunk> {
-    // Validate that streaming is supported
-    if (!this.executeStreamingQuery) {
-      throw new Error(
-        `Streaming is not supported for integration "${this.name}". ` +
-          "The orchestrator must provide a streaming query executor.",
-      );
-    }
-
-    // Validate request body against schema if both are present.
-    // Body schema is optional — if not provided, the body is sent unvalidated.
-    if (options.body !== undefined && schema?.body) {
-      const bodyParseResult = schema.body.safeParse(options.body);
-      if (!bodyParseResult.success) {
-        throw new RestApiValidationError(
-          `Request body validation failed: ${bodyParseResult.error.message}`,
-          {
-            zodError: bodyParseResult.error,
-            data: options.body,
-          },
-        );
-      }
-    }
-
-    // Convert headers to Property array
-    const headers: PartialMessage<Property>[] = [];
-    if (options.headers) {
-      for (const [key, value] of Object.entries(options.headers)) {
-        headers.push(this.createParam(key, value));
-      }
-    }
-
-    // Convert query params to Property array
-    const params: PartialMessage<Property>[] = [];
-    if (options.params) {
-      for (const [key, value] of Object.entries(options.params)) {
-        params.push(this.createParam(key, value));
-      }
-    }
-
-    // Build the request using raw HTTP mode with streaming response
-    // Note: responseType must be "raw" for streaming - the orchestrator's
-    // Stream block expects SSE responses and only works with "raw" type.
-    const request: RestApiRequest = {
-      openApiAction: "genericHttpRequest",
-      httpMethod: options.method.toUpperCase(),
-      urlPath: options.path,
-      headers,
-      params,
-      responseType: "raw",
-    };
-
-    // Add body if provided
-    if (options.body !== undefined) {
-      request.body = JSON.stringify(options.body);
-      request.bodyType = "jsonBody";
-    }
-
-    // Execute the streaming request
-    const stream = this.executeStreamingQuery(
-      request as Record<string, unknown>,
-      metadata,
-    );
-
-    // Validate and yield each chunk
-    let chunkIndex = 0;
-    for await (const rawChunk of stream) {
-      const parseResult = schema.chunk.safeParse(rawChunk);
-
-      if (!parseResult.success) {
-        throw new StreamChunkValidationError(
-          `Chunk validation failed at index ${chunkIndex}: ${parseResult.error.message}`,
-          {
-            chunkIndex,
-            chunk: rawChunk,
-            zodError: parseResult.error,
-          },
-        );
-      }
-
-      yield parseResult.data;
-      chunkIndex++;
-    }
-  }
 }