@superblocksteam/sdk-api 0.0.4

package/dist/integrations/athena/client.js

@@ -0,0 +1,95 @@
+/**
+ * Athena integration client implementation.
+ *
+ * Executes Athena queries through the Superblocks orchestrator with
+ * runtime validation using Zod schemas.
+ */
+import { QueryValidationError } from "../../errors.js";
+import { IntegrationError } from "../../runtime/errors.js";
+import { describeType } from "../utils.js";
+/**
+ * Internal implementation of the Athena client.
+ */
+export class AthenaClientImpl {
+    config;
+    executeQuery;
+    constructor(config, executeQuery) {
+        this.config = config;
+        this.executeQuery = executeQuery;
+    }
+    get name() {
+        return this.config.name;
+    }
+    get pluginId() {
+        return this.config.pluginId;
+    }
+    /**
+     * Builds an Athena request object from SQL and parameters.
+     *
+     * When params are provided, the SQL body is sent with placeholders intact
+     * and the parameter values are passed via the `parameters` field
+     * as a JSON-stringified array for server-side binding.
+     *
+     * @param sql - The SQL query with optional placeholders
+     * @param params - Optional array of parameter values for server-side binding
+     * @returns The plugin request object
+     */
+    buildRequest(sql, params) {
+        const hasParams = params && params.length > 0;
+        return {
+            runSql: {
+                sqlBody: sql,
+                parameters: hasParams ? JSON.stringify(params) : undefined,
+            },
+        };
+    }
+    async query(sql, schema, params, metadata) {
+        const request = this.buildRequest(sql, params);
+        try {
+            const result = await this.executeQuery(request, undefined, metadata);
+            if (!Array.isArray(result)) {
+                throw new IntegrationError(this.config.name, "query", `Expected array result from Athena query, got: ${describeType(result)}`);
+            }
+            const validated = [];
+            for (let i = 0; i < result.length; i++) {
+                const row = result[i];
+                const parseResult = schema.safeParse(row);
+                if (!parseResult.success) {
+                    throw new QueryValidationError(`Row ${i} validation failed: ${parseResult.error.message}`, {
+                        rowIndex: i,
+                        errors: parseResult.error.errors.map((err) => ({
+                            path: err.path,
+                            message: err.message,
+                        })),
+                        row,
+                    });
+                }
+                validated.push(parseResult.data);
+            }
+            return validated;
+        }
+        catch (error) {
+            if (error instanceof QueryValidationError ||
+                error instanceof IntegrationError) {
+                throw error;
+            }
+            throw new IntegrationError(this.config.name, "query", error);
+        }
+    }
+    async execute(sql, params, metadata) {
+        const request = this.buildRequest(sql, params);
+        try {
+            const result = await this.executeQuery(request, undefined, metadata);
+            if (typeof result === "object" &&
+                result !== null &&
+                "rowCount" in result) {
+                return { rowCount: Number(result.rowCount) || 0 };
+            }
+            return { rowCount: 0 };
+        }
+        catch (error) {
+            throw new IntegrationError(this.config.name, "execute", error);
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/integrations/athena/client.js.map

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

package/dist/integrations/athena/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Athena integration client.
+ *
+ * @module
+ */
+export type { AthenaClient } from "./types.js";
+export { AthenaClientImpl } from "./client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/integrations/athena/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/integrations/athena/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/integrations/athena/index.js

@@ -0,0 +1,7 @@
+/**
+ * Athena integration client.
+ *
+ * @module
+ */
+export { AthenaClientImpl } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/integrations/athena/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/integrations/athena/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

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

@@ -0,0 +1,55 @@
+/**
+ * Athena integration client types.
+ *
+ * Provides typed methods for executing Athena queries with runtime validation.
+ */
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
+/**
+ * Client for executing Athena queries with type-safe validation.
+ *
+ * @example
+ * ```typescript
+ * // Declare in api(): integrations: { athena: athena(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.athena
+ *
+ * // Query with validation
+ * const LogSchema = z.object({
+ *   timestamp: z.string(),
+ *   level: z.string(),
+ *   message: z.string(),
+ * });
+ *
+ * const logs = await athena.query(
+ *   'SELECT * FROM logs WHERE level = $1',
+ *   LogSchema,
+ *   ['ERROR']
+ * );
+ * ```
+ */
+export interface AthenaClient extends BaseIntegrationClient {
+    /**
+     * Execute a SQL query and validate results against a Zod schema.
+     *
+     * @param sql - SQL query string (use $1, $2, etc. for parameters)
+     * @param schema - Zod schema to validate the query results
+     * @param params - Optional query parameters
+     * @returns Promise resolving to validated query results
+     *
+     * @throws {QueryValidationError} If results don't match schema
+     * @throws {IntegrationError} If query execution fails
+     */
+    query<T>(sql: string, schema: z.ZodSchema<T>, params?: unknown[], metadata?: TraceMetadata): Promise<T[]>;
+    /**
+     * Execute a SQL statement (INSERT, UPDATE, DELETE) without output validation.
+     *
+     * @param sql - The SQL statement to execute
+     * @param params - Optional parameters for prepared statements
+     * @returns Promise resolving to execution result with row count
+     */
+    execute(sql: string, params?: unknown[], metadata?: TraceMetadata): Promise<{
+        rowCount: number;
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/integrations/athena/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,YAAa,SAAQ,qBAAqB;IACzD;;;;;;;;;;OAUG;IACH,KAAK,CAAC,CAAC,EACL,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EACtB,MAAM,CAAC,EAAE,OAAO,EAAE,EAClB,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAEhB;;;;;;OAMG;IACH,OAAO,CACL,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,OAAO,EAAE,EAClB,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClC"}

package/dist/integrations/athena/types.js

@@ -0,0 +1,7 @@
+/**
+ * Athena integration client types.
+ *
+ * Provides typed methods for executing Athena queries with runtime validation.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/integrations/athena/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/integrations/base/graphql-integration-client.d.ts

@@ -0,0 +1,57 @@
+/**
+ * GraphQL integration client base class.
+ *
+ * Provides the foundation for GraphQL integration clients with query() and mutation() methods.
+ * Handles proto message construction and response validation.
+ */
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import { z } from "zod";
+/**
+ * Base class for GraphQL integration clients.
+ *
+ * This class handles:
+ * - Building graphql.v1.Plugin proto messages
+ * - Executing queries and mutations through the orchestrator
+ * - Required Zod schema validation on full GraphQL response
+ * - Variables serialization for parameterized queries
+ */
+export declare abstract class GraphQLIntegrationClient implements IntegrationClientImpl {
+    readonly name: string;
+    readonly pluginId: string;
+    readonly config: IntegrationConfig;
+    private executeQuery;
+    constructor(config: IntegrationConfig, executeQuery: QueryExecutor);
+    /**
+     * Execute a GraphQL query.
+     *
+     * @param query - GraphQL query string
+     * @param schema - Zod schema for full response validation (REQUIRED)
+     * @param variables - Optional variables for the query
+     * @param metadata - Optional trace metadata for observability
+     * @returns Validated query result
+     */
+    query<TResponse>(query: string, schema: {
+        response: z.ZodSchema<TResponse>;
+    }, variables?: Record<string, unknown>, metadata?: TraceMetadata): Promise<TResponse>;
+    /**
+     * Execute a GraphQL mutation.
+     *
+     * @param mutation - GraphQL mutation string
+     * @param schema - Zod schema for full response validation (REQUIRED)
+     * @param variables - Optional variables for the mutation
+     * @param metadata - Optional trace metadata for observability
+     * @returns Validated mutation result
+     */
+    mutation<TResponse>(mutation: string, schema: {
+        response: z.ZodSchema<TResponse>;
+    }, variables?: Record<string, unknown>, metadata?: TraceMetadata): Promise<TResponse>;
+    /**
+     * Execute a GraphQL operation (query or mutation).
+     *
+     * Builds the graphql.v1.Plugin proto message, executes through orchestrator,
+     * and validates the full response against the required schema.
+     */
+    private executeGraphQL;
+}
+//# sourceMappingURL=graphql-integration-client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graphql-integration-client.d.ts","sourceRoot":"","sources":["../../../src/integrations/base/graphql-integration-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;GAQG;AACH,8BAAsB,wBAAyB,YAAW,qBAAqB;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,OAAO,CAAC,YAAY,CAAgB;gBAExB,MAAM,EAAE,iBAAiB,EAAE,YAAY,EAAE,aAAa;IAOlE;;;;;;;;OAQG;IACG,KAAK,CAAC,SAAS,EACnB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE;QAAE,QAAQ,EAAE,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAA;KAAE,EAC5C,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,SAAS,CAAC;IAIrB;;;;;;;;OAQG;IACG,QAAQ,CAAC,SAAS,EACtB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE;QAAE,QAAQ,EAAE,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAA;KAAE,EAC5C,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,SAAS,CAAC;IAIrB;;;;;OAKG;YACW,cAAc;CAsC7B"}

package/dist/integrations/base/graphql-integration-client.js

@@ -0,0 +1,89 @@
+/**
+ * GraphQL integration client base class.
+ *
+ * Provides the foundation for GraphQL integration clients with query() and mutation() methods.
+ * Handles proto message construction and response validation.
+ */
+import { RestApiValidationError } from "../../errors.js";
+/**
+ * Base class for GraphQL integration clients.
+ *
+ * This class handles:
+ * - Building graphql.v1.Plugin proto messages
+ * - Executing queries and mutations through the orchestrator
+ * - Required Zod schema validation on full GraphQL response
+ * - Variables serialization for parameterized queries
+ */
+export class GraphQLIntegrationClient {
+    name;
+    pluginId;
+    config;
+    executeQuery;
+    constructor(config, executeQuery) {
+        this.name = config.name;
+        this.pluginId = config.pluginId;
+        this.config = config;
+        this.executeQuery = executeQuery;
+    }
+    /**
+     * Execute a GraphQL query.
+     *
+     * @param query - GraphQL query string
+     * @param schema - Zod schema for full response validation (REQUIRED)
+     * @param variables - Optional variables for the query
+     * @param metadata - Optional trace metadata for observability
+     * @returns Validated query result
+     */
+    async query(query, schema, variables, metadata) {
+        return this.executeGraphQL(query, schema, variables, metadata);
+    }
+    /**
+     * Execute a GraphQL mutation.
+     *
+     * @param mutation - GraphQL mutation string
+     * @param schema - Zod schema for full response validation (REQUIRED)
+     * @param variables - Optional variables for the mutation
+     * @param metadata - Optional trace metadata for observability
+     * @returns Validated mutation result
+     */
+    async mutation(mutation, schema, variables, metadata) {
+        return this.executeGraphQL(mutation, schema, variables, metadata);
+    }
+    /**
+     * Execute a GraphQL operation (query or mutation).
+     *
+     * Builds the graphql.v1.Plugin proto message, executes through orchestrator,
+     * and validates the full response against the required schema.
+     */
+    async executeGraphQL(queryString, schema, variables, metadata) {
+        // Build graphql.v1.Plugin proto message
+        const request = {
+            body: queryString,
+            custom: variables
+                ? {
+                    variables: {
+                        key: "variables",
+                        value: JSON.stringify(variables),
+                    },
+                }
+                : undefined,
+            verboseHttpOutput: false,
+            failOnGraphqlErrors: true,
+        };
+        // Execute query through orchestrator
+        const response = await this.executeQuery(request, undefined, metadata);
+        // Return full GraphQL response without unwrapping
+        // Users should access result.data themselves
+        // GraphQL responses have shape: { data: {...}, errors?: [...] }
+        // Schema is REQUIRED - always validate
+        const result = schema.response.safeParse(response);
+        if (!result.success) {
+            throw new RestApiValidationError("GraphQL response validation failed", {
+                zodError: result.error,
+                data: response,
+            });
+        }
+        return result.data;
+    }
+}
+//# sourceMappingURL=graphql-integration-client.js.map

package/dist/integrations/base/graphql-integration-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphql-integration-client.js","sourceRoot":"","sources":["../../../src/integrations/base/graphql-integration-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAEzD;;;;;;;;GAQG;AACH,MAAM,OAAgB,wBAAwB;IACnC,IAAI,CAAS;IACb,QAAQ,CAAS;IACjB,MAAM,CAAoB;IAC3B,YAAY,CAAgB;IAEpC,YAAY,MAAyB,EAAE,YAA2B;QAChE,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACxB,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,KAAK,CACT,KAAa,EACb,MAA4C,EAC5C,SAAmC,EACnC,QAAwB;QAExB,OAAO,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IACjE,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,QAAQ,CACZ,QAAgB,EAChB,MAA4C,EAC5C,SAAmC,EACnC,QAAwB;QAExB,OAAO,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IACpE,CAAC;IAED;;;;;OAKG;IACK,KAAK,CAAC,cAAc,CAC1B,WAAmB,EACnB,MAA4C,EAC5C,SAAmC,EACnC,QAAwB;QAExB,wCAAwC;QACxC,MAAM,OAAO,GAAG;YACd,IAAI,EAAE,WAAW;YACjB,MAAM,EAAE,SAAS;gBACf,CAAC,CAAC;oBACE,SAAS,EAAE;wBACT,GAAG,EAAE,WAAW;wBAChB,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC;qBACjC;iBACF;gBACH,CAAC,CAAC,SAAS;YACb,iBAAiB,EAAE,KAAK;YACxB,mBAAmB,EAAE,IAAI;SAC1B,CAAC;QAEF,qCAAqC;QACrC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QAEvE,kDAAkD;QAClD,6CAA6C;QAC7C,gEAAgE;QAEhE,uCAAuC;QACvC,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACnD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,IAAI,sBAAsB,CAAC,oCAAoC,EAAE;gBACrE,QAAQ,EAAE,MAAM,CAAC,KAAK;gBACtB,IAAI,EAAE,QAAQ;aACf,CAAC,CAAC;QACL,CAAC;QACD,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;CACF"}

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

@@ -0,0 +1,8 @@
+/**
+ * Base clients for integrations.
+ */
+export { RestApiIntegrationClient } from "./rest-api-integration-client.js";
+export type { RestApiRequest } from "./rest-api-integration-client.js";
+export { GraphQLIntegrationClient } from "./graphql-integration-client.js";
+export type { ApiRequestOptions, ApiRequestSchema, SupportsApiRequest, StreamApiRequestSchema, SupportsStreamingApiRequest, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/integrations/base/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,YAAY,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,YAAY,CAAC"}

package/dist/integrations/base/index.js

@@ -0,0 +1,6 @@
+/**
+ * Base clients for integrations.
+ */
+export { RestApiIntegrationClient } from "./rest-api-integration-client.js";
+export { GraphQLIntegrationClient } from "./graphql-integration-client.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/integrations/base/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAE5E,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC"}

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

@@ -0,0 +1,78 @@
+/**
+ * Base client for REST API Integration (OpenAPI) based integrations.
+ *
+ * Provides common apiRequest() method for all OpenAPI-based plugins.
+ */
+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 type { ApiRequestOptions, ApiRequestSchema, SupportsApiRequest, StreamApiRequestSchema, SupportsStreamingApiRequest } from "./types.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.
+ */
+export declare abstract class RestApiIntegrationClient implements IntegrationClientImpl, SupportsApiRequest, SupportsStreamingApiRequest {
+    readonly name: string;
+    readonly pluginId: string;
+    readonly config: IntegrationConfig;
+    protected readonly executeQuery: QueryExecutor;
+    protected readonly executeStreamingQuery?: StreamingQueryExecutor;
+    constructor(config: IntegrationConfig, executeQuery: QueryExecutor, executeStreamingQuery?: StreamingQueryExecutor);
+    /**
+     * Helper to create a Property object for params.
+     */
+    protected createParam(key: string, value: unknown): PartialMessage<Property>;
+    apiRequest<TBody, TResponse>(options: ApiRequestOptions<TBody>, schema: ApiRequestSchema<TBody, TResponse> & {
+        response: z.ZodSchema<TResponse>;
+    }, metadata?: TraceMetadata): Promise<TResponse>;
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    streamApiRequest<TBody, TChunk>(options: ApiRequestOptions<TBody>, schema: StreamApiRequestSchema<TBody, TChunk>, metadata?: TraceMetadata): AsyncIterable<TChunk>;
+}
+//# sourceMappingURL=rest-api-integration-client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rest-api-integration-client.d.ts","sourceRoot":"","sources":["../../../src/integrations/base/rest-api-integration-client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,IAAI,wBAAwB,EAAE,MAAM,yEAAyE,CAAC;AAClI,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qDAAqD,CAAC;AACpF,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,KAAK,EACV,aAAa,EACb,sBAAsB,EACtB,aAAa,EACd,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,2BAA2B,EAC5B,MAAM,YAAY,CAAC;AAKpB,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,MAAM,MAAM,cAAc,GAAG,cAAc,CAAC,wBAAwB,CAAC,CAAC;AAEtE;;;;;;GAMG;AACH,8BAAsB,wBACpB,YACE,qBAAqB,EACrB,kBAAkB,EAClB,2BAA2B;IAE7B,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;IAC/C,SAAS,CAAC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,sBAAsB,CAAC;gBAGhE,MAAM,EAAE,iBAAiB,EACzB,YAAY,EAAE,aAAa,EAC3B,qBAAqB,CAAC,EAAE,sBAAsB;IAShD;;OAEG;IACH,SAAS,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,cAAc,CAAC,QAAQ,CAAC;IAOtE,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;IAuErB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACI,gBAAgB,CAAC,KAAK,EAAE,MAAM,EACnC,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,EACjC,MAAM,EAAE,sBAAsB,CAAC,KAAK,EAAE,MAAM,CAAC,EAC7C,QAAQ,CAAC,EAAE,aAAa,GACvB,aAAa,CAAC,MAAM,CAAC;CAoFzB"}

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

@@ -0,0 +1,194 @@
+/**
+ * Base client for REST API Integration (OpenAPI) based integrations.
+ *
+ * Provides common apiRequest() method for all OpenAPI-based plugins.
+ */
+import { RestApiValidationError, StreamChunkValidationError, } from "../../errors.js";
+/**
+ * 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.
+ */
+export class RestApiIntegrationClient {
+    name;
+    pluginId;
+    config;
+    executeQuery;
+    executeStreamingQuery;
+    constructor(config, executeQuery, executeStreamingQuery) {
+        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.
+     */
+    createParam(key, value) {
+        return {
+            key,
+            value: typeof value === "string" ? value : JSON.stringify(value),
+        };
+    }
+    async apiRequest(options, schema, metadata) {
+        // 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 = [];
+        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 = [];
+        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 = {
+            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";
+        }
+        // Execute the request
+        const result = await this.executeQuery(request, undefined, metadata);
+        // 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,
+            });
+        }
+        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(options, schema, metadata) {
+        // 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 = [];
+        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 = [];
+        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 = {
+            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, 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++;
+        }
+    }
+}
+//# sourceMappingURL=rest-api-integration-client.js.map