@superblocksteam/sdk-api 2.0.89-next.0

package/src/integrations/base/types.ts

@@ -0,0 +1,172 @@
+/**
+ * Shared types for REST API Integration (OpenAPI) based clients.
+ */
+
+import type { z } from 'zod';
+
+/**
+ * Options for making a generic REST API request.
+ */
+export interface ApiRequestOptions<TBody = unknown> {
+  /**
+   * HTTP method for the request.
+   */
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+
+  /**
+   * API endpoint path (e.g., "/users", "/repos/owner/repo")
+   */
+  path: string;
+
+  /**
+   * Optional request body (for POST, PUT, PATCH requests).
+   * Type is inferred from bodySchema parameter.
+   */
+  body?: TBody;
+
+  /**
+   * Optional query parameters
+   */
+  params?: Record<string, unknown>;
+
+  /**
+   * Optional HTTP headers
+   */
+  headers?: Record<string, string>;
+}
+
+/**
+ * Schema configuration for API request validation.
+ */
+export interface ApiRequestSchema<TBody = unknown, TResponse = unknown> {
+  /**
+   * Optional Zod schema for request body validation.
+   * Required if body is provided in options.
+   */
+  body?: z.ZodSchema<TBody>;
+
+  /**
+   * Optional Zod schema for response validation.
+   * If not provided, response is returned without validation.
+   */
+  response?: z.ZodSchema<TResponse>;
+}
+
+/**
+ * Interface for integration clients that support generic API requests.
+ *
+ * All API requests require response schema validation for type safety.
+ */
+export interface SupportsApiRequest {
+  /**
+   * Execute a generic API request with type-safe validation.
+   *
+   * @param options - Request configuration including method, path, params, and body
+   * @param schema - Zod schemas for request body and response validation (response schema REQUIRED)
+   * @returns Validated response data
+   *
+   * @example
+   * ```typescript
+   * const client = ctx.slack('Ops Slack');
+   *
+   * const ResponseSchema = z.object({
+   *   ts: z.string(),
+   *   channel: z.string(),
+   * });
+   *
+   * const result = await client.apiRequest(
+   *   {
+   *     method: 'POST',
+   *     path: '/chat.postMessage',
+   *     body: {
+   *       channel: '#alerts',
+   *       text: 'Hello!',
+   *     },
+   *   },
+   *   {
+   *     body: z.object({
+   *       channel: z.string(),
+   *       text: z.string(),
+   *     }),
+   *     response: ResponseSchema,
+   *   }
+   * );
+   * // result is typed as { ts: string; channel: string }
+   * ```
+   */
+  apiRequest<TBody, TResponse>(
+    options: ApiRequestOptions<TBody>,
+    schema: ApiRequestSchema<TBody, TResponse> & { response: z.ZodSchema<TResponse> }
+  ): Promise<TResponse>;
+}
+
+/**
+ * Schema configuration for streaming API request validation.
+ */
+export interface StreamApiRequestSchema<TBody = unknown, TChunk = unknown> {
+  /**
+   * Optional Zod schema for request body validation.
+   * Required if body is provided in options.
+   */
+  body?: z.ZodSchema<TBody>;
+
+  /**
+   * Zod schema for validating each streamed chunk.
+   *
+   * Every chunk received from the stream is validated against this schema.
+   * Validation errors will terminate the stream.
+   */
+  chunk: z.ZodSchema<TChunk>;
+}
+
+/**
+ * Interface for integration clients that support streaming API requests.
+ *
+ * Streaming API requests return an AsyncIterable of validated chunks,
+ * enabling real-time data streaming from LLMs and other sources.
+ */
+export interface SupportsStreamingApiRequest {
+  /**
+   * 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 (chunk schema REQUIRED)
+   * @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 }
+   * );
+   *
+   * for await (const chunk of stream) {
+   *   console.log(chunk.choices[0]?.delta?.content);
+   * }
+   * ```
+   */
+  streamApiRequest<TBody, TChunk>(
+    options: ApiRequestOptions<TBody>,
+    schema: StreamApiRequestSchema<TBody, TChunk>,
+  ): AsyncIterable<TChunk>;
+}

package/src/integrations/bigquery/README.md

@@ -0,0 +1,185 @@
+# BigQuery Client
+
+Execute SQL queries against Google BigQuery with full type safety and runtime validation.
+
+## Methods
+
+| Method | Description |
+| ------ | ----------- |
+| `query<T>(sql, schema, params?)` | Execute a SELECT query and return validated, typed results |
+| `execute(sql, params?)` | Execute a statement and return affected row count |
+
+## Usage
+
+### Basic Query with Schema Validation
+
+```typescript
+import { api, z } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_BIGQUERY = "a1b2c3d4-5678-90ab-cdef-bigquery0001";
+
+const EventSchema = z.object({
+  event_id: z.string(),
+  event_name: z.string(),
+  user_id: z.string(),
+  timestamp: z.string(),
+});
+
+export default api({
+  input: z.object({
+    event_name: z.string(),
+  }),
+  output: z.object({
+    events: z.array(EventSchema),
+  }),
+  async run(ctx, { event_name }) {
+    const bigquery = ctx.bigquery(PROD_BIGQUERY);
+
+    const events = await bigquery.query(
+      `SELECT event_id, event_name, user_id, timestamp
+       FROM \`project.dataset.events\`
+       WHERE event_name = $1
+       LIMIT 100`,
+      EventSchema,
+      [event_name]
+    );
+
+    return { events };
+  },
+});
+```
+
+### Executing INSERT, UPDATE, DELETE Statements
+
+```typescript
+const bigquery = ctx.bigquery(PROD_BIGQUERY);
+
+// INSERT
+await bigquery.execute(
+  "INSERT INTO `project.dataset.metrics` (name, value, timestamp) VALUES ($1, $2, CURRENT_TIMESTAMP())",
+  ["cpu_usage", "75.5"]
+);
+```
+
+### Analytics Query
+
+```typescript
+const AnalyticsSchema = z.object({
+  date: z.string(),
+  total_events: z.coerce.number(),
+  unique_users: z.coerce.number(),
+});
+
+const analytics = await bigquery.query(
+  `SELECT
+    DATE(timestamp) as date,
+    COUNT(*) as total_events,
+    COUNT(DISTINCT user_id) as unique_users
+  FROM \`project.dataset.events\`
+  WHERE timestamp >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
+  GROUP BY date
+  ORDER BY date DESC`,
+  AnalyticsSchema
+);
+```
+
+### Working with STRUCT and ARRAY
+
+```typescript
+const UserActivitySchema = z.object({
+  user_id: z.string(),
+  events: z.array(
+    z.object({
+      event_name: z.string(),
+      count: z.coerce.number(),
+    })
+  ),
+});
+
+const activity = await bigquery.query(
+  `SELECT
+    user_id,
+    ARRAY_AGG(STRUCT(event_name, count)) as events
+  FROM (
+    SELECT user_id, event_name, COUNT(*) as count
+    FROM \`project.dataset.events\`
+    GROUP BY user_id, event_name
+  )
+  GROUP BY user_id`,
+  UserActivitySchema
+);
+```
+
+## Common Pitfalls
+
+### Backtick Table References
+
+BigQuery uses backticks for fully-qualified table names:
+
+```typescript
+// CORRECT
+const query = "SELECT * FROM `project.dataset.table`";
+
+// WRONG
+const query = "SELECT * FROM project.dataset.table";
+```
+
+### INT64/NUMERIC Values Returned as Strings
+
+```typescript
+const schema = z.object({
+  count: z.coerce.number(),
+  amount: z.string().transform((val) => parseFloat(val)),
+});
+```
+
+### Schema Parameter is Required
+
+```typescript
+// CORRECT - Schema is required
+const events = await bigquery.query("SELECT * FROM `project.dataset.events`", EventSchema);
+```
+
+### NULL Handling
+
+```typescript
+const schema = z.object({
+  name: z.string(),
+  description: z.string().nullable(),
+});
+```
+
+### Query Costs
+
+BigQuery charges by data scanned. Use partitions and column selection:
+
+```typescript
+// GOOD - Select specific columns and use partition filter
+const query = `
+  SELECT event_id, event_name
+  FROM \`project.dataset.events\`
+  WHERE _PARTITIONDATE = $1
+`;
+```
+
+## Error Handling
+
+```typescript
+import { QueryValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const events = await bigquery.query("SELECT * FROM `project.dataset.events`", EventSchema);
+} catch (error) {
+  if (error instanceof QueryValidationError) {
+    console.error("Row index:", error.details.rowIndex);
+    console.error("Validation errors:", error.details.errors);
+  }
+}
+```
+
+## API Reference
+
+- [BigQuery Documentation](https://cloud.google.com/bigquery/docs)
+- [BigQuery SQL Reference](https://cloud.google.com/bigquery/docs/reference/standard-sql/query-syntax)
+- [BigQuery Data Types](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types)

package/src/integrations/bigquery/client.ts

@@ -0,0 +1,133 @@
+/**
+ * BigQuery integration client implementation.
+ *
+ * Executes BigQuery 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 BigQueryPlugin } from '@superblocksteam/types/dist/src/plugins/bigquery/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 { BigQueryClient } from './types.js';
+
+/**
+ * Internal implementation of the BigQuery client.
+ */
+export class BigQueryClientImpl implements BigQueryClient, 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 BigQuery 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
+   */
+  private buildRequest(
+    sql: string,
+    params?: unknown[],
+  ): PartialMessage<BigQueryPlugin> {
+    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 BigQuery 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/bigquery/index.ts

@@ -0,0 +1,8 @@
+/**
+ * BigQuery integration client.
+ *
+ * @module
+ */
+
+export type { BigQueryClient } from './types.js';
+export { BigQueryClientImpl } from './client.js';

package/src/integrations/bigquery/types.ts

@@ -0,0 +1,53 @@
+/**
+ * BigQuery integration client types.
+ *
+ * Provides typed methods for executing BigQuery queries with runtime validation.
+ */
+
+import type { z } from 'zod';
+import type { BaseIntegrationClient } from '../../types.js';
+
+/**
+ * Client for executing BigQuery queries with type-safe validation.
+ *
+ * @example
+ * ```typescript
+ * const bigquery = ctx.bigquery('Production BigQuery');
+ *
+ * // Query with validation
+ * const EventSchema = z.object({
+ *   event_id: z.string(),
+ *   event_name: z.string(),
+ *   timestamp: z.string(),
+ * });
+ *
+ * const events = await bigquery.query(
+ *   'SELECT * FROM events WHERE date = $1',
+ *   EventSchema,
+ *   ['2024-01-01']
+ * );
+ * ```
+ */
+export interface BigQueryClient 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 }>;
+}