@superblocksteam/sdk-api 2.0.89-next.0

package/src/integrations/redshift/client.ts

@@ -0,0 +1,133 @@
+/**
+ * Redshift integration client implementation.
+ *
+ * Executes Redshift queries through the Superblocks orchestrator with
+ * runtime validation using Zod schemas.
+ */
+
+import type { z } from 'zod';
+import type { PartialMessage } from '@bufbuild/protobuf';
+import type { Plugin as RedshiftPlugin } from '@superblocksteam/types/dist/src/plugins/redshift/v1/plugin_pb';
+import type { IntegrationConfig, IntegrationClientImpl } from '../types.js';
+import type { QueryExecutor } from '../registry.js';
+import { QueryValidationError } from '../../errors.js';
+import { IntegrationError } from '../../runtime/errors.js';
+import { describeType } from '../utils.js';
+import type { RedshiftClient } from './types.js';
+
+/**
+ * Internal implementation of the Redshift client.
+ */
+export class RedshiftClientImpl implements RedshiftClient, IntegrationClientImpl {
+  readonly config: IntegrationConfig;
+  private readonly executeQuery: QueryExecutor;
+
+  constructor(config: IntegrationConfig, executeQuery: QueryExecutor) {
+    this.config = config;
+    this.executeQuery = executeQuery;
+  }
+
+  get name(): string {
+    return this.config.name;
+  }
+
+  get pluginId(): string {
+    return this.config.pluginId;
+  }
+
+  /**
+   * Builds a Redshift request object from SQL and parameters.
+   *
+   * When params are provided, the SQL body is sent with placeholders intact
+   * (e.g. $1, $2) 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 $1, $2 placeholders
+   * @param params - Optional array of parameter values for server-side binding
+   * @returns The plugin request object
+   */
+  private buildRequest(
+    sql: string,
+    params?: unknown[],
+  ): PartialMessage<RedshiftPlugin> {
+    const hasParams = params && params.length > 0;
+
+    return {
+      body: sql,
+      parameters: hasParams ? JSON.stringify(params) : undefined,
+    };
+  }
+
+  async query<T>(
+    sql: string,
+    schema: z.ZodSchema<T>,
+    params?: unknown[],
+  ): Promise<T[]> {
+    const request = this.buildRequest(sql, params);
+
+    try {
+      const result = await this.executeQuery(request);
+
+      if (!Array.isArray(result)) {
+        throw new IntegrationError(
+          this.config.name,
+          'query',
+          `Expected array result from Redshift query, got: ${describeType(result)}`,
+        );
+      }
+
+      const validated: T[] = [];
+      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: string, params?: unknown[]): Promise<{ rowCount: number }> {
+    const request = this.buildRequest(sql, params);
+
+    try {
+      const result = await this.executeQuery(request);
+
+      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);
+    }
+  }
+}

package/src/integrations/redshift/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Redshift integration client.
+ *
+ * @module
+ */
+
+export type { RedshiftClient } from './types.js';
+export { RedshiftClientImpl } from './client.js';

package/src/integrations/redshift/types.ts

@@ -0,0 +1,53 @@
+/**
+ * Redshift integration client types.
+ *
+ * Provides typed methods for executing Redshift queries with runtime validation.
+ */
+
+import type { z } from 'zod';
+import type { BaseIntegrationClient } from '../../types.js';
+
+/**
+ * Client for executing Redshift queries with type-safe validation.
+ *
+ * @example
+ * ```typescript
+ * const redshift = ctx.redshift('Production Redshift');
+ *
+ * // Query with validation
+ * const UserSchema = z.object({
+ *   id: z.number(),
+ *   name: z.string(),
+ *   email: z.string().email(),
+ * });
+ *
+ * const users = await redshift.query(
+ *   'SELECT * FROM users WHERE status = $1',
+ *   UserSchema,
+ *   ['active']
+ * );
+ * ```
+ */
+export interface RedshiftClient 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[]): 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[]): Promise<{ rowCount: number }>;
+}

package/src/integrations/registry.ts

@@ -0,0 +1,437 @@
+/**
+ * Integration client registry and factory.
+ *
+ * Maps plugin IDs to their corresponding client implementations
+ * and provides factory functions for creating clients.
+ */
+
+import type { IntegrationConfig, IntegrationClientImpl } from './types.js';
+import { PostgresClientImpl } from './postgres/index.js';
+import { SlackClientImpl } from './slack/index.js';
+import { OpenAIClientImpl } from './openai_v2/index.js';
+import { AnthropicClientImpl } from './anthropic/index.js';
+import { StripeClientImpl } from './stripe/index.js';
+import { GitHubClientImpl } from './github/index.js';
+import { NotionClientImpl } from './notion/index.js';
+import { SnowflakeClientImpl } from './snowflake/index.js';
+import { AirtableClientImpl } from './airtable/index.js';
+import { AsanaClientImpl } from './asana/index.js';
+import { BitbucketClientImpl } from './bitbucket/index.js';
+import { BoxClientImpl } from './box/index.js';
+import { CircleCIClientImpl } from './circleci/index.js';
+import { CohereClientImpl } from './cohere/index.js';
+import { ConfluenceClientImpl } from './confluence/index.js';
+import { DatadogClientImpl } from './datadog/index.js';
+import { DropboxClientImpl } from './dropbox/index.js';
+import { ElasticSearchClientImpl } from './elasticsearch/index.js';
+import { FireworksClientImpl } from './fireworks/index.js';
+import { FrontClientImpl } from './front/index.js';
+import { GeminiClientImpl } from './gemini/index.js';
+import { GoogleAnalyticsClientImpl } from './googleanalytics/index.js';
+import { GoogleDriveClientImpl } from './googledrive/index.js';
+import { GroqClientImpl } from './groq/index.js';
+import { HubSpotClientImpl } from './hubspot/index.js';
+import { IntercomClientImpl } from './intercom/index.js';
+import { JiraClientImpl } from './jira/index.js';
+import { LaunchDarklyClientImpl } from './launchdarkly/index.js';
+import { MistralClientImpl } from './mistral/index.js';
+import { PagerDutyClientImpl } from './pagerduty/index.js';
+import { PerplexityClientImpl } from './perplexity/index.js';
+import { SegmentClientImpl } from './segment/index.js';
+import { SendGridClientImpl } from './sendgrid/index.js';
+import { StabilityAIClientImpl } from './stabilityai/index.js';
+import { TwilioClientImpl } from './twilio/index.js';
+import { ZendeskClientImpl } from './zendesk/index.js';
+import { ZoomClientImpl } from './zoom/index.js';
+import { GraphQLClientImpl } from './graphql/index.js';
+// SQL Database clients
+import { MySQLClientImpl } from './mysql/index.js';
+import { MariaDBClientImpl } from './mariadb/index.js';
+import { MSSQLClientImpl } from './mssql/index.js';
+import { CockroachDBClientImpl } from './cockroachdb/index.js';
+import { OracleDBClientImpl } from './oracledb/index.js';
+import { RedshiftClientImpl } from './redshift/index.js';
+import { AthenaClientImpl } from './athena/index.js';
+import { DatabricksClientImpl } from './databricks/index.js';
+import { BigQueryClientImpl } from './bigquery/index.js';
+// REST API clients
+import { MongoDBClientImpl } from './mongodb/index.js';
+import { DynamoDBClientImpl } from './dynamodb/index.js';
+import { CosmosDBClientImpl } from './cosmosdb/index.js';
+import { CouchbaseClientImpl } from './couchbase/index.js';
+import { S3ClientImpl } from './s3/index.js';
+import { GCSClientImpl } from './gcs/index.js';
+import { GoogleSheetsClientImpl } from './gsheets/index.js';
+import { KafkaClientImpl } from './kafka/index.js';
+import { KinesisClientImpl } from './kinesis/index.js';
+import { SalesforceClientImpl } from './salesforce/index.js';
+import { RedisClientImpl } from './redis/index.js';
+import { SuperblocksOCRClientImpl } from './superblocks-ocr/index.js';
+import { LakebaseClientImpl } from './lakebase/index.js';
+import { SmtpClientImpl } from './smtp/index.js';
+// Code execution clients
+import { PythonClientImpl } from './python/index.js';
+
+/**
+ * Supported plugin IDs mapped to their client constructors.
+ */
+export const SUPPORTED_PLUGINS = {
+  postgres: 'postgres',
+  slack: 'slack',
+  openai_v2: 'openai_v2',
+  anthropic: 'anthropic',
+  stripe: 'stripe',
+  github: 'github',
+  notion: 'notion',
+  snowflake: 'snowflake',
+  airtable: 'airtable',
+  asana: 'asana',
+  bitbucket: 'bitbucket',
+  box: 'box',
+  circleci: 'circleci',
+  cohere: 'cohere',
+  confluence: 'confluence',
+  datadog: 'datadog',
+  dropbox: 'dropbox',
+  elasticsearch: 'elasticsearch',
+  fireworks: 'fireworks',
+  front: 'front',
+  gemini: 'gemini',
+  googleanalytics: 'googleanalytics',
+  googledrive: 'googledrive',
+  graphqlintegration: 'graphqlintegration',
+  groq: 'groq',
+  hubspot: 'hubspot',
+  intercom: 'intercom',
+  jira: 'jira',
+  launchdarkly: 'launchdarkly',
+  mistral: 'mistral',
+  pagerduty: 'pagerduty',
+  perplexity: 'perplexity',
+  segment: 'segment',
+  sendgrid: 'sendgrid',
+  stabilityai: 'stabilityai',
+  twilio: 'twilio',
+  zendesk: 'zendesk',
+  zoom: 'zoom',
+  // SQL databases
+  mysql: 'mysql',
+  mariadb: 'mariadb',
+  mssql: 'mssql',
+  cockroachdb: 'cockroachdb',
+  oracledb: 'oracledb',
+  redshift: 'redshift',
+  athena: 'athena',
+  databricks: 'databricks',
+  bigquery: 'bigquery',
+  // REST API integrations
+  mongodb: 'mongodb',
+  dynamodb: 'dynamodb',
+  cosmosdb: 'cosmosdb',
+  couchbase: 'couchbase',
+  s3: 's3',
+  gcs: 'gcs',
+  gsheets: 'gsheets',
+  kafka: 'kafka',
+  kinesis: 'kinesis',
+  salesforce: 'salesforce',
+  redis: 'redis',
+  'superblocks-ocr': 'superblocks-ocr',
+  // Kafka-compatible streaming
+  confluent: 'confluent',
+  redpanda: 'redpanda',
+  // SQL databases (continued)
+  lakebase: 'lakebase',
+  // Email
+  smtp: 'smtp',
+  // Code execution
+  python: 'python',
+} as const;
+
+export type SupportedPluginId = (typeof SUPPORTED_PLUGINS)[keyof typeof SUPPORTED_PLUGINS];
+
+/**
+ * Type for the query executor function provided by the orchestrator.
+ *
+ * Accepts a plugin request object that matches the protobuf Plugin definition
+ * for the specific integration type (e.g., postgresql.v1.Plugin, restapi.v1.Plugin).
+ *
+ * For language plugins (Python, JavaScript), the bindings parameter should be passed
+ * to the API execution request as `input` or `inputs` field for binding resolution.
+ *
+ * @param request - Plugin-specific request object matching the proto schema
+ * @param bindings - Optional bindings data for binding resolution (e.g., Python/JavaScript bindings)
+ * @returns Promise resolving to the operation result
+ */
+export type QueryExecutor = (
+  request: Record<string, unknown>,
+  bindings?: Record<string, unknown>
+) => Promise<unknown>;
+
+/**
+ * Type for the streaming query executor function provided by the orchestrator.
+ *
+ * Similar to QueryExecutor but returns an AsyncIterable for streaming responses.
+ * Used for streaming operations like LLM token streaming.
+ *
+ * @param request - Plugin-specific request object matching the proto schema
+ * @returns AsyncIterable yielding raw chunks from the stream
+ */
+export type StreamingQueryExecutor = (
+  request: Record<string, unknown>,
+) => AsyncIterable<unknown>;
+
+/**
+ * Options for creating an integration client.
+ */
+export interface CreateClientOptions {
+  /** Integration configuration from the orchestrator */
+  config: IntegrationConfig;
+
+  /** Function to execute queries/operations against the integration */
+  executeQuery: QueryExecutor;
+
+  /**
+   * Optional function to execute streaming queries/operations.
+   * If provided, enables streaming support for compatible clients.
+   */
+  executeStreamingQuery?: StreamingQueryExecutor;
+}
+
+/**
+ * Creates an integration client based on the plugin ID.
+ *
+ * This factory function is called by the runtime to create typed
+ * integration clients that the user's API code can interact with.
+ *
+ * @param options - Client creation options
+ * @returns The appropriate typed client implementation
+ * @throws Error if the plugin ID is not supported
+ *
+ * @example
+ * ```typescript
+ * const client = createClient({
+ *   config: {
+ *     id: 'int_123',
+ *     name: 'Production Postgres',
+ *     pluginId: 'postgres',
+ *     configuration: {},
+ *   },
+ *   executeQuery: orchestratorExecutor,
+ * });
+ * ```
+ */
+export function createClient(options: CreateClientOptions): IntegrationClientImpl {
+  const { config, executeQuery, executeStreamingQuery } = options;
+
+  switch (config.pluginId) {
+    case SUPPORTED_PLUGINS.postgres:
+      return new PostgresClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.slack:
+      return new SlackClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.openai_v2:
+      return new OpenAIClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.anthropic:
+      return new AnthropicClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.stripe:
+      return new StripeClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.github:
+      return new GitHubClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.notion:
+      return new NotionClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.snowflake:
+      return new SnowflakeClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.airtable:
+      return new AirtableClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.asana:
+      return new AsanaClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.bitbucket:
+      return new BitbucketClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.box:
+      return new BoxClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.circleci:
+      return new CircleCIClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.cohere:
+      return new CohereClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.confluence:
+      return new ConfluenceClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.datadog:
+      return new DatadogClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.dropbox:
+      return new DropboxClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.elasticsearch:
+      return new ElasticSearchClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.fireworks:
+      return new FireworksClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.front:
+      return new FrontClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.gemini:
+      return new GeminiClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.googleanalytics:
+      return new GoogleAnalyticsClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.googledrive:
+      return new GoogleDriveClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.graphqlintegration:
+      return new GraphQLClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.groq:
+      return new GroqClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.hubspot:
+      return new HubSpotClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.intercom:
+      return new IntercomClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.jira:
+      return new JiraClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.launchdarkly:
+      return new LaunchDarklyClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.mistral:
+      return new MistralClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.pagerduty:
+      return new PagerDutyClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.perplexity:
+      return new PerplexityClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.segment:
+      return new SegmentClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.sendgrid:
+      return new SendGridClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.stabilityai:
+      return new StabilityAIClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.twilio:
+      return new TwilioClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.zendesk:
+      return new ZendeskClientImpl(config, executeQuery, executeStreamingQuery);
+
+    case SUPPORTED_PLUGINS.zoom:
+      return new ZoomClientImpl(config, executeQuery, executeStreamingQuery);
+
+    // SQL databases
+    case SUPPORTED_PLUGINS.mysql:
+      return new MySQLClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.mariadb:
+      return new MariaDBClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.mssql:
+      return new MSSQLClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.cockroachdb:
+      return new CockroachDBClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.oracledb:
+      return new OracleDBClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.redshift:
+      return new RedshiftClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.athena:
+      return new AthenaClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.databricks:
+      return new DatabricksClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.bigquery:
+      return new BigQueryClientImpl(config, executeQuery);
+
+    // REST API integrations
+    case SUPPORTED_PLUGINS.mongodb:
+      return new MongoDBClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.dynamodb:
+      return new DynamoDBClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.cosmosdb:
+      return new CosmosDBClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.couchbase:
+      return new CouchbaseClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.s3:
+      return new S3ClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.gcs:
+      return new GCSClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.gsheets:
+      return new GoogleSheetsClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.kafka:
+      return new KafkaClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.kinesis:
+      return new KinesisClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.salesforce:
+      return new SalesforceClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.redis:
+      return new RedisClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS['superblocks-ocr']:
+      return new SuperblocksOCRClientImpl(config, executeQuery);
+
+    // Confluent and Redpanda use the same Kafka plugin proto
+    case SUPPORTED_PLUGINS.confluent:
+    case SUPPORTED_PLUGINS.redpanda:
+      return new KafkaClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.lakebase:
+      return new LakebaseClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.smtp:
+      return new SmtpClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.python:
+      return new PythonClientImpl(config, executeQuery);
+
+    default:
+      throw new Error(
+        `Unsupported plugin: ${config.pluginId}. ` +
+          `Supported plugins: ${Object.values(SUPPORTED_PLUGINS).join(', ')}`,
+      );
+  }
+}
+
+/**
+ * Checks if a plugin ID is supported by the SDK.
+ *
+ * @param pluginId - The plugin ID to check
+ * @returns True if the plugin is supported
+ */
+export function isPluginSupported(pluginId: string): pluginId is SupportedPluginId {
+  return Object.values(SUPPORTED_PLUGINS).includes(pluginId as SupportedPluginId);
+}