@superblocksteam/sdk-api 2.0.89-next.0

package/src/errors.ts

@@ -0,0 +1,130 @@
+/**
+ * Error classes for SDK runtime errors.
+ */
+
+import type { z } from 'zod';
+
+/**
+ * Error thrown when REST API response or request body validation fails.
+ *
+ * Contains the complete Zod error object and the actual data that failed validation,
+ * providing full context for debugging schema mismatches.
+ */
+export class RestApiValidationError extends Error {
+  constructor(
+    message: string,
+    public readonly details: {
+      /** The complete Zod error object with all validation information */
+      zodError: z.ZodError;
+      /** The actual data that failed validation (request body or response) */
+      data: unknown;
+    },
+  ) {
+    super(message);
+    this.name = 'RestApiValidationError';
+    // Ensure proper prototype chain for instanceof checks
+    Object.setPrototypeOf(this, RestApiValidationError.prototype);
+  }
+}
+
+/**
+ * Error thrown when query results fail schema validation.
+ *
+ * Contains detailed information about which row failed validation
+ * and the specific field-level errors from Zod.
+ */
+export class QueryValidationError extends Error {
+  constructor(
+    message: string,
+    public readonly details: {
+      /** Index of the row that failed validation (0-based) */
+      rowIndex: number;
+      /** Array of field-level validation errors from Zod */
+      errors: Array<{ path: (string | number)[]; message: string }>;
+      /** The raw row data that failed validation */
+      row: unknown;
+    },
+  ) {
+    super(message);
+    this.name = 'QueryValidationError';
+    // Ensure proper prototype chain for instanceof checks
+    Object.setPrototypeOf(this, QueryValidationError.prototype);
+  }
+}
+
+/**
+ * Error thrown when Python/JavaScript code execution fails.
+ *
+ * Contains context about the code, bindings, and any validation errors
+ * that occurred during execution.
+ */
+export class CodeExecutionError extends Error {
+  constructor(
+    message: string,
+    public readonly details?: {
+      /** The code that was executed */
+      code?: string;
+      /** Bindings that were passed to the code */
+      bindings?: Record<string, unknown>;
+      /** The actual result that failed validation */
+      result?: unknown;
+      /** Zod validation error if validation failed */
+      zodError?: z.ZodError;
+      /** Original error from the execution runtime */
+      originalError?: unknown;
+    },
+  ) {
+    super(message);
+    this.name = 'CodeExecutionError';
+    // Ensure proper prototype chain for instanceof checks
+    Object.setPrototypeOf(this, CodeExecutionError.prototype);
+  }
+}
+
+/**
+ * Error thrown when a streamed chunk fails validation.
+ *
+ * Contains information about the chunk index, the raw chunk data,
+ * and the Zod validation error details.
+ */
+export class StreamChunkValidationError extends Error {
+  constructor(
+    message: string,
+    public readonly details: {
+      /** Index of the chunk that failed validation (0-based) */
+      chunkIndex: number;
+      /** The raw chunk data that failed validation */
+      chunk: unknown;
+      /** The complete Zod error object with all validation information */
+      zodError: z.ZodError;
+    },
+  ) {
+    super(message);
+    this.name = 'StreamChunkValidationError';
+    // Ensure proper prototype chain for instanceof checks
+    Object.setPrototypeOf(this, StreamChunkValidationError.prototype);
+  }
+}
+
+/**
+ * Error thrown when a streaming API encounters an error mid-stream.
+ *
+ * This error indicates that the stream was interrupted before completion.
+ * Contains context about where in the stream the error occurred.
+ */
+export class StreamError extends Error {
+  constructor(
+    message: string,
+    public readonly details?: {
+      /** Number of chunks successfully received before the error */
+      chunksReceived?: number;
+      /** The original error that caused the stream to fail */
+      originalError?: unknown;
+    },
+  ) {
+    super(message);
+    this.name = 'StreamError';
+    // Ensure proper prototype chain for instanceof checks
+    Object.setPrototypeOf(this, StreamError.prototype);
+  }
+}

package/src/index.ts

@@ -0,0 +1,327 @@
+/**
+ * @superblocksteam/sdk-api - TypeScript SDK for Superblocks APIs.
+ *
+ * This SDK enables writing Superblocks APIs as simple TypeScript functions
+ * with type-safe input/output validation using Zod schemas and upfront
+ * integration declarations.
+ *
+ * @example
+ * ```typescript
+ * import { api, z, postgres, slack } from '@superblocksteam/sdk-api';
+ *
+ * export default api({
+ *   integrations: {
+ *     db: postgres('Production Postgres'),
+ *     notifier: slack('Ops Slack'),
+ *   },
+ *
+ *   input: z.object({
+ *     userId: z.string().uuid(),
+ *   }),
+ *
+ *   output: z.object({
+ *     user: z.object({
+ *       id: z.string(),
+ *       name: z.string(),
+ *       email: z.string().email(),
+ *     }),
+ *   }),
+ *
+ *   async run(ctx, { userId }) {
+ *     const [user] = await ctx.integrations.db.query(
+ *       'SELECT * FROM users WHERE id = $1',
+ *       z.object({ id: z.string(), name: z.string(), email: z.string() }),
+ *       [userId]
+ *     );
+ *
+ *     if (!user) {
+ *       throw new Error('User not found');
+ *     }
+ *
+ *     await ctx.integrations.notifier.postMessage({
+ *       channel: '#user-lookups',
+ *       text: `Fetched user ${user.name}`,
+ *     });
+ *
+ *     return { user };
+ *   },
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// Re-export Zod for convenience
+export { z } from "zod";
+
+// API definition and registry
+export {
+  api,
+  type CompiledApi,
+  // Streaming API support
+  streamingApi,
+  isStreamingApi,
+  type StreamingApiConfig,
+  type CompiledStreamingApi,
+} from "./api/index.js";
+
+// Type extraction utilities
+export type { ExtractApiInput, ExtractApiOutput } from "./api/definition.js";
+
+// Core types
+export type {
+  ApiConfig,
+  ApiContext,
+  ApiUser,
+  Logger,
+  BaseIntegrationClient,
+  IntegrationRef,
+  AnyIntegrationRef,
+  IntegrationsMap,
+} from "./types.js";
+
+// Integration declaration functions
+export {
+  postgres,
+  slack,
+  openai,
+  anthropic,
+  stripe,
+  github,
+  notion,
+  snowflake,
+  airtable,
+  asana,
+  bitbucket,
+  box,
+  circleci,
+  cohere,
+  confluence,
+  datadog,
+  dropbox,
+  elasticsearch,
+  fireworks,
+  front,
+  gemini,
+  googleAnalytics,
+  googleDrive,
+  groq,
+  hubspot,
+  intercom,
+  jira,
+  launchDarkly,
+  mistral,
+  pagerDuty,
+  perplexity,
+  segment,
+  sendGrid,
+  stabilityAI,
+  twilio,
+  zendesk,
+  zoom,
+  graphql,
+  mysql,
+  mariadb,
+  mssql,
+  cockroachdb,
+  oracledb,
+  redshift,
+  athena,
+  databricks,
+  bigquery,
+  mongodb,
+  dynamodb,
+  cosmosdb,
+  couchbase,
+  s3,
+  gcs,
+  googleSheets,
+  kafka,
+  kinesis,
+  salesforce,
+  redis,
+  superblocksOcr,
+  python,
+  // Types for advanced use
+  type IntegrationDeclaration,
+  type PostgresRef,
+  type SlackRef,
+  type OpenAIRef,
+  type AnthropicRef,
+  type StripeRef,
+  type GitHubRef,
+  type NotionRef,
+  type SnowflakeRef,
+  type AirtableRef,
+  type AsanaRef,
+  type BitbucketRef,
+  type BoxRef,
+  type CircleCIRef,
+  type CohereRef,
+  type ConfluenceRef,
+  type DatadogRef,
+  type DropboxRef,
+  type ElasticSearchRef,
+  type FireworksRef,
+  type FrontRef,
+  type GeminiRef,
+  type GoogleAnalyticsRef,
+  type GoogleDriveRef,
+  type GroqRef,
+  type HubSpotRef,
+  type IntercomRef,
+  type JiraRef,
+  type LaunchDarklyRef,
+  type MistralRef,
+  type PagerDutyRef,
+  type PerplexityRef,
+  type SegmentRef,
+  type SendGridRef,
+  type StabilityAIRef,
+  type TwilioRef,
+  type ZendeskRef,
+  type ZoomRef,
+  type GraphQLRef,
+  type MySQLRef,
+  type MariaDBRef,
+  type MSSQLRef,
+  type CockroachDBRef,
+  type OracleDBRef,
+  type RedshiftRef,
+  type AthenaRef,
+  type DatabricksRef,
+  type BigQueryRef,
+  type MongoDBRef,
+  type DynamoDBRef,
+  type CosmosDBRef,
+  type CouchbaseRef,
+  type S3Ref,
+  type GCSRef,
+  type GoogleSheetsRef,
+  type KafkaRef,
+  type KinesisRef,
+  type SalesforceRef,
+  type RedisRef,
+  type SuperblocksOCRRef,
+  type PythonRef,
+} from "./integrations/index.js";
+
+// Integration client types (for advanced use cases)
+export type { PostgresClient } from "./integrations/postgres/index.js";
+export type { SlackClient } from "./integrations/slack/index.js";
+export type { SnowflakeClient } from "./integrations/snowflake/index.js";
+export type { AirtableClient } from "./integrations/airtable/index.js";
+export type { AsanaClient } from "./integrations/asana/index.js";
+export type { BitbucketClient } from "./integrations/bitbucket/index.js";
+export type { BoxClient } from "./integrations/box/index.js";
+export type { CircleCIClient } from "./integrations/circleci/index.js";
+export type { CohereClient } from "./integrations/cohere/index.js";
+export type { ConfluenceClient } from "./integrations/confluence/index.js";
+export type { DatadogClient } from "./integrations/datadog/index.js";
+export type { DropboxClient } from "./integrations/dropbox/index.js";
+export type { ElasticSearchClient } from "./integrations/elasticsearch/index.js";
+export type { FireworksClient } from "./integrations/fireworks/index.js";
+export type { FrontClient } from "./integrations/front/index.js";
+export type { GeminiClient } from "./integrations/gemini/index.js";
+export type { GoogleAnalyticsClient } from "./integrations/googleanalytics/index.js";
+export type { GoogleDriveClient } from "./integrations/googledrive/index.js";
+export type { GroqClient } from "./integrations/groq/index.js";
+export type { HubSpotClient } from "./integrations/hubspot/index.js";
+export type { IntercomClient } from "./integrations/intercom/index.js";
+export type { JiraClient } from "./integrations/jira/index.js";
+export type { LaunchDarklyClient } from "./integrations/launchdarkly/index.js";
+export type { MistralClient } from "./integrations/mistral/index.js";
+export type { PagerDutyClient } from "./integrations/pagerduty/index.js";
+export type { PerplexityClient } from "./integrations/perplexity/index.js";
+export type { SegmentClient } from "./integrations/segment/index.js";
+export type { SendGridClient } from "./integrations/sendgrid/index.js";
+export type { StabilityAIClient } from "./integrations/stabilityai/index.js";
+export type { TwilioClient } from "./integrations/twilio/index.js";
+export type { ZendeskClient } from "./integrations/zendesk/index.js";
+export type { ZoomClient } from "./integrations/zoom/index.js";
+export type { GraphQLClient } from "./integrations/graphql/index.js";
+
+// Dedicated plugin client types and parameter types
+export type { DynamoDBClient, DynamoDBAttributeValue } from "./integrations/dynamodb/index.js";
+export type { CosmosDBClient } from "./integrations/cosmosdb/index.js";
+export type { CouchbaseClient, CouchbaseIdentifier } from "./integrations/couchbase/index.js";
+export type {
+  KinesisClient,
+  KinesisPutParams,
+  KinesisGetParams,
+  KinesisStreamIdentifier,
+  KinesisShardIteratorType,
+} from "./integrations/kinesis/index.js";
+export type { SalesforceClient, SalesforceCrudAction, SalesforceBulkAction } from "./integrations/salesforce/index.js";
+export type { RedisClient } from "./integrations/redis/index.js";
+export type { KafkaClient } from "./integrations/kafka/index.js";
+export type { S3Client } from "./integrations/s3/index.js";
+export type { GCSClient } from "./integrations/gcs/index.js";
+export type { GoogleSheetsClient } from "./integrations/gsheets/index.js";
+export type { SuperblocksOCRClient } from "./integrations/superblocks-ocr/index.js";
+export type { PythonClient } from "./integrations/python/index.js";
+
+// Runtime (for orchestrator use)
+export {
+  // Unified executor (recommended - handles both regular and streaming)
+  execute,
+  // Legacy executors (still available for specific use cases)
+  executeApi,
+  executeStreamingApi,
+  createStreamingApiGenerator,
+  // Context factories
+  createApiContext,
+  createStreamingApiContext,
+  // Error types
+  SdkError,
+  InputValidationError,
+  OutputValidationError,
+  IntegrationNotFoundError,
+  IntegrationError,
+  ExecutionError,
+  ErrorCode,
+} from "./runtime/index.js";
+
+export type {
+  // Unified types (recommended)
+  UnifiedExecuteApiRequest,
+  AnyCompiledApi,
+  // Legacy types (still available)
+  ExecuteApiRequest,
+  ExecuteApiResponse,
+  ExecuteApiSuccessResponse,
+  ExecuteApiErrorResponse,
+  ExecuteStreamingApiRequest,
+  StreamingApiCallbacks,
+  StreamingApiError,
+  ExecuteStreamingApiResult,
+  // Context types
+  CreateContextOptions,
+  CreateStreamingContextOptions,
+  ErrorCodeType,
+} from "./runtime/index.js";
+
+// Integration registry (for orchestrator use)
+export {
+  createClient,
+  isPluginSupported,
+  SUPPORTED_PLUGINS,
+} from "./integrations/index.js";
+
+export type {
+  IntegrationConfig,
+  IntegrationClientImpl,
+  SupportedPluginId,
+  QueryExecutor,
+  StreamingQueryExecutor,
+  CreateClientOptions,
+} from "./integrations/index.js";
+
+// SDK-level error types
+export {
+  RestApiValidationError,
+  QueryValidationError,
+  CodeExecutionError,
+  StreamChunkValidationError,
+  StreamError,
+} from "./errors.js";