@superblocksteam/sdk-api 0.0.4

package/src/integrations/registry.ts

@@ -0,0 +1,551 @@
+/**
+ * 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 { SnowflakeCortexClientImpl } from "./snowflakecortex/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 { SnowflakePostgresClientImpl } from "./snowflakepostgres/index.js";
+import { SmtpClientImpl } from "./smtp/index.js";
+// REST API plugins
+import { RestApiIntegrationPluginClientImpl } from "./restapiintegration/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",
+  snowflakecortex: "snowflakecortex",
+  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",
+  snowflakepostgres: "snowflakepostgres",
+  // Email
+  smtp: "smtp",
+  // REST API plugins
+  restapiintegration: "restapiintegration",
+  // Code execution
+  python: "python",
+} as const;
+
+export type SupportedPluginId =
+  (typeof SUPPORTED_PLUGINS)[keyof typeof SUPPORTED_PLUGINS];
+
+/**
+ * Optional metadata attached to an integration call for diagnostics.
+ *
+ * When `includeDiagnostics` is enabled, the `label` and `description`
+ * are captured alongside the standard timing/input/output data and
+ * surfaced in the Trace View UI.
+ *
+ * **Security:** Do not include secrets, passwords, access tokens, or other
+ * sensitive/PII data in trace metadata, as it may be stored in logs or trace
+ * payloads and visible to others with access to diagnostics.
+ */
+export interface TraceMetadata {
+  /** Short human-readable label for this call (e.g., "Fetch active users"). */
+  label?: string;
+  /** Longer description of what this call does and why. */
+  description?: string;
+}
+
+/**
+ * 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)
+ * @param metadata - Optional trace metadata (label, description) for diagnostics
+ * @returns Promise resolving to the operation result
+ */
+export type QueryExecutor = (
+  request: Record<string, unknown>,
+  bindings?: Record<string, unknown>,
+  metadata?: TraceMetadata,
+) => 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
+ * @param metadata - Optional trace metadata (label, description) for diagnostics
+ * @returns AsyncIterable yielding raw chunks from the stream
+ */
+export type StreamingQueryExecutor = (
+  request: Record<string, unknown>,
+  metadata?: TraceMetadata,
+) => 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.snowflakecortex:
+      return new SnowflakeCortexClientImpl(
+        config,
+        executeQuery,
+        executeStreamingQuery,
+      );
+
+    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.snowflakepostgres:
+      return new SnowflakePostgresClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.smtp:
+      return new SmtpClientImpl(config, executeQuery);
+
+    case SUPPORTED_PLUGINS.restapiintegration:
+      return new RestApiIntegrationPluginClientImpl(
+        config,
+        executeQuery,
+        executeStreamingQuery,
+      );
+
+    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,
+  );
+}

package/src/integrations/restapiintegration/client.ts

@@ -0,0 +1,21 @@
+/**
+ * REST API Integration client implementation.
+ *
+ * Uses the proto-generated REST API Integration Plugin type from @superblocksteam/types.
+ * This is the generic REST API Integration plugin that users configure with a base URL
+ * and authentication in the integrations page.
+ */
+
+import { RestApiIntegrationClient } from "../base/index.js";
+import type { RestApiIntegrationPluginClient } from "./types.js";
+
+/**
+ * Internal implementation of RestApiIntegrationPluginClient.
+ *
+ * Extends RestApiIntegrationClient to inherit the generic apiRequest() method.
+ * At runtime, the orchestrator handles base URL resolution, authentication,
+ * and API request execution.
+ */
+export class RestApiIntegrationPluginClientImpl
+  extends RestApiIntegrationClient
+  implements RestApiIntegrationPluginClient {}

package/src/integrations/restapiintegration/index.ts

@@ -0,0 +1,6 @@
+/**
+ * REST API Integration module.
+ */
+
+export type { RestApiIntegrationPluginClient } from "./types.js";
+export { RestApiIntegrationPluginClientImpl } from "./client.js";

package/src/integrations/restapiintegration/types.ts

@@ -0,0 +1,40 @@
+/**
+ * REST API Integration client types.
+ */
+
+import type { BaseIntegrationClient } from "../../types.js";
+import type {
+  SupportsApiRequest,
+  SupportsStreamingApiRequest,
+} from "../base/index.js";
+
+/**
+ * REST API Integration client for making HTTP requests to configured endpoints.
+ *
+ * This is the generic REST API Integration plugin. Use apiRequest() to make
+ * HTTP calls to any endpoint configured on the integration (base URL, auth, etc.).
+ *
+ * @example
+ * ```typescript
+ * // Declare in api(): integrations: { myApi: restApiIntegration(INTEGRATION_ID) }
+ * // In run(), access via: ctx.integrations.myApi
+ *
+ * const ResponseSchema = z.object({
+ *   data: z.array(z.object({ id: z.string(), name: z.string() })),
+ * });
+ *
+ * const result = await ctx.integrations.myApi.apiRequest(
+ *   {
+ *     method: 'GET',
+ *     path: '/users',
+ *     params: { limit: 10 },
+ *   },
+ *   { response: ResponseSchema },
+ * );
+ * ```
+ */
+export interface RestApiIntegrationPluginClient
+  extends
+    BaseIntegrationClient,
+    SupportsApiRequest,
+    SupportsStreamingApiRequest {}