@superblocksteam/sdk-api 2.0.89-next.0

package/src/integrations/couchbase/client.ts

@@ -0,0 +1,212 @@
+/**
+ * Couchbase client implementation.
+ *
+ * Uses the native Couchbase plugin type from @superblocksteam/types.
+ * Builds proto-style request objects for SQL++ queries, document insert,
+ * get, and remove operations against Couchbase buckets.
+ */
+
+import type { z } from 'zod';
+import type { PartialMessage } from '@bufbuild/protobuf';
+import type { Plugin as CouchbasePlugin } from '@superblocksteam/types/dist/src/plugins/couchbase/v1/plugin_pb';
+import type { IntegrationConfig, IntegrationClientImpl } from '../types.js';
+import type { QueryExecutor } from '../registry.js';
+import { QueryValidationError, RestApiValidationError } from '../../errors.js';
+import { IntegrationError } from '../../runtime/errors.js';
+import { describeType } from '../utils.js';
+import type { CouchbaseClient, CouchbaseIdentifier } from './types.js';
+
+/**
+ * Couchbase request type derived from proto definition.
+ */
+type CouchbaseRequest = PartialMessage<CouchbasePlugin>;
+
+/**
+ * Internal implementation of CouchbaseClient.
+ *
+ * Communicates with the orchestrator using the native Couchbase plugin
+ * proto format, supporting SQL++ queries and key-value document operations.
+ * All operations require a bucket name.
+ */
+export class CouchbaseClientImpl implements CouchbaseClient, 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;
+  }
+
+  async query<T>(
+    bucket: string,
+    sql: string,
+    schema: z.ZodSchema<T>,
+    params?: unknown[],
+  ): Promise<T[]> {
+    const hasParams = params && params.length > 0;
+    const request: CouchbaseRequest = {
+      bucketName: bucket,
+      couchbaseAction: {
+        case: 'runSql',
+        value: {
+          sqlBody: sql,
+          parameters: hasParams ? JSON.stringify(params) : undefined,
+        },
+      },
+    };
+
+    try {
+      const result = await this.executeQuery(request as Record<string, unknown>);
+
+      if (!Array.isArray(result)) {
+        throw new IntegrationError(
+          this.config.name,
+          'query',
+          `Expected array result from Couchbase 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} failed validation: ${parseResult.error.message}`,
+            {
+              rowIndex: i,
+              errors: parseResult.error.errors,
+              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 insert(
+    key: string,
+    value: unknown,
+    identifier: CouchbaseIdentifier,
+  ): Promise<void> {
+    const request: CouchbaseRequest = {
+      bucketName: identifier.bucket,
+      couchbaseAction: {
+        case: 'insert',
+        value: {
+          key,
+          value: typeof value === 'string' ? value : JSON.stringify(value),
+          identifier: {
+            scope: identifier.scope,
+            collection: identifier.collection,
+          },
+        },
+      },
+    };
+
+    try {
+      await this.executeQuery(request as Record<string, unknown>);
+    } catch (error) {
+      if (error instanceof IntegrationError) {
+        throw error;
+      }
+
+      throw new IntegrationError(this.config.name, 'insert', error);
+    }
+  }
+
+  async get<T>(
+    key: string,
+    schema: z.ZodSchema<T>,
+    identifier: CouchbaseIdentifier,
+  ): Promise<T> {
+    const request: CouchbaseRequest = {
+      bucketName: identifier.bucket,
+      couchbaseAction: {
+        case: 'get',
+        value: {
+          key,
+          identifier: {
+            scope: identifier.scope,
+            collection: identifier.collection,
+          },
+        },
+      },
+    };
+
+    try {
+      const result = await this.executeQuery(request as Record<string, unknown>);
+
+      const parseResult = schema.safeParse(result);
+
+      if (!parseResult.success) {
+        throw new RestApiValidationError(
+          `Result validation failed: ${parseResult.error.message}`,
+          {
+            zodError: parseResult.error,
+            data: result,
+          },
+        );
+      }
+
+      return parseResult.data;
+    } catch (error) {
+      if (
+        error instanceof RestApiValidationError ||
+        error instanceof IntegrationError
+      ) {
+        throw error;
+      }
+
+      throw new IntegrationError(this.config.name, 'get', error);
+    }
+  }
+
+  async remove(key: string, identifier: CouchbaseIdentifier): Promise<void> {
+    const request: CouchbaseRequest = {
+      bucketName: identifier.bucket,
+      couchbaseAction: {
+        case: 'remove',
+        value: {
+          key,
+          identifier: {
+            scope: identifier.scope,
+            collection: identifier.collection,
+          },
+        },
+      },
+    };
+
+    try {
+      await this.executeQuery(request as Record<string, unknown>);
+    } catch (error) {
+      if (error instanceof IntegrationError) {
+        throw error;
+      }
+
+      throw new IntegrationError(this.config.name, 'remove', error);
+    }
+  }
+}

package/src/integrations/couchbase/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Couchbase integration client.
+ *
+ * @module
+ */
+
+export type { CouchbaseClient, CouchbaseIdentifier } from './types.js';
+export { CouchbaseClientImpl } from './client.js';

package/src/integrations/couchbase/types.ts

@@ -0,0 +1,108 @@
+/**
+ * Couchbase client types.
+ */
+
+import type { z } from 'zod';
+import type { BaseIntegrationClient } from '../../types.js';
+
+/**
+ * Parameters for identifying a Couchbase document location.
+ *
+ * All Couchbase operations require a bucket name. Key-value operations
+ * (insert, get, remove) additionally require a scope and collection.
+ */
+export interface CouchbaseIdentifier {
+  /** The bucket name (required for all operations) */
+  bucket: string;
+  /** The scope name */
+  scope: string;
+  /** The collection name */
+  collection: string;
+}
+
+/**
+ * Couchbase client for document and query operations.
+ *
+ * Provides methods for SQL++ queries, document insertion, retrieval,
+ * and removal in Couchbase buckets.
+ *
+ * @example
+ * ```typescript
+ * const cb = ctx.couchbase('Production Couchbase');
+ *
+ * // Run a SQL++ query
+ * const users = await cb.query(
+ *   'my-bucket',
+ *   'SELECT * FROM bucket WHERE status = "active"',
+ *   UserSchema,
+ * );
+ *
+ * // Insert a document
+ * await cb.insert('user::123', { name: 'Alice' }, {
+ *   bucket: 'my-bucket',
+ *   scope: '_default',
+ *   collection: '_default',
+ * });
+ *
+ * // Get a document
+ * const doc = await cb.get('user::123', DocSchema, {
+ *   bucket: 'my-bucket',
+ *   scope: '_default',
+ *   collection: '_default',
+ * });
+ *
+ * // Remove a document
+ * await cb.remove('user::123', {
+ *   bucket: 'my-bucket',
+ *   scope: '_default',
+ *   collection: '_default',
+ * });
+ * ```
+ */
+export interface CouchbaseClient extends BaseIntegrationClient {
+  /**
+   * Execute a SQL++ query against Couchbase.
+   *
+   * @param bucket - The bucket name to query against
+   * @param sql - The SQL++ query string (with optional $1, $2 placeholders when parameterized)
+   * @param schema - Zod schema for validating result rows
+   * @param params - Optional array of parameter values for server-side binding
+   * @returns Array of validated result rows
+   */
+  query<T>(bucket: string, sql: string, schema: z.ZodSchema<T>, params?: unknown[]): Promise<T[]>;
+
+  /**
+   * Insert a document into a collection.
+   *
+   * @param key - The document key
+   * @param value - The document value (will be JSON-serialized)
+   * @param identifier - The bucket, scope, and collection to insert into
+   */
+  insert(
+    key: string,
+    value: unknown,
+    identifier: CouchbaseIdentifier,
+  ): Promise<void>;
+
+  /**
+   * Get a document by key from a collection.
+   *
+   * @param key - The document key
+   * @param schema - Zod schema for validating the result
+   * @param identifier - The bucket, scope, and collection to get from
+   * @returns The validated document
+   */
+  get<T>(
+    key: string,
+    schema: z.ZodSchema<T>,
+    identifier: CouchbaseIdentifier,
+  ): Promise<T>;
+
+  /**
+   * Remove a document by key from a collection.
+   *
+   * @param key - The document key
+   * @param identifier - The bucket, scope, and collection to remove from
+   */
+  remove(key: string, identifier: CouchbaseIdentifier): Promise<void>;
+}

package/src/integrations/databricks/README.md

@@ -0,0 +1,151 @@
+# Databricks Client
+
+Execute SQL queries against Databricks SQL warehouses 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_DATABRICKS = "a1b2c3d4-5678-90ab-cdef-databric0001";
+
+const DataSchema = z.object({
+  id: z.number(),
+  value: z.string(),
+  timestamp: z.string(),
+});
+
+export default api({
+  name: "DatabricksExample",
+  input: z.object({
+    date: z.string(),
+  }),
+  output: z.object({
+    data: z.array(DataSchema),
+  }),
+  async run(ctx, { date }) {
+    const databricks = ctx.databricks(PROD_DATABRICKS);
+
+    const data = await databricks.query(
+      "SELECT id, value, timestamp FROM data WHERE date = $1",
+      DataSchema,
+      [date]
+    );
+
+    return { data };
+  },
+});
+```
+
+### Executing INSERT, UPDATE, DELETE Statements
+
+```typescript
+const databricks = ctx.databricks(PROD_DATABRICKS);
+
+// INSERT
+await databricks.execute(
+  "INSERT INTO metrics (name, value) VALUES ($1, $2)",
+  ["cpu_usage", "75.5"]
+);
+
+// UPDATE
+const updateResult = await databricks.execute(
+  "UPDATE metrics SET value = $1 WHERE name = $2",
+  ["80.0", "cpu_usage"]
+);
+console.log(`Updated ${updateResult.rowCount} rows`);
+
+// DELETE
+const deleteResult = await databricks.execute(
+  "DELETE FROM metrics WHERE timestamp < $1",
+  ["2024-01-01"]
+);
+console.log(`Deleted ${deleteResult.rowCount} rows`);
+```
+
+### Analytics Query with Delta Lake
+
+```typescript
+const AnalyticsSchema = z.object({
+  date: z.string(),
+  total_revenue: z.string(),
+  order_count: z.coerce.number(),
+});
+
+const analytics = await databricks.query(
+  `SELECT
+    date,
+    SUM(revenue) as total_revenue,
+    COUNT(*) as order_count
+  FROM orders
+  WHERE date >= DATE_SUB(CURRENT_DATE(), 30)
+  GROUP BY date
+  ORDER BY date DESC`,
+  AnalyticsSchema
+);
+```
+
+## Common Pitfalls
+
+### BIGINT/LONG Values Returned as Strings
+
+```typescript
+const schema = z.object({
+  count: z.coerce.number(),
+});
+```
+
+### DECIMAL Values Returned as Strings
+
+```typescript
+const schema = z.object({
+  amount: z.string().transform((val) => parseFloat(val)),
+});
+```
+
+### Schema Parameter is Required
+
+```typescript
+// CORRECT - Schema is required
+const data = await databricks.query("SELECT * FROM data", DataSchema);
+```
+
+### NULL Handling
+
+```typescript
+const schema = z.object({
+  name: z.string(),
+  description: z.string().nullable(),
+});
+```
+
+## Error Handling
+
+```typescript
+import { QueryValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const data = await databricks.query("SELECT * FROM data", DataSchema);
+} catch (error) {
+  if (error instanceof QueryValidationError) {
+    console.error("Row index:", error.details.rowIndex);
+    console.error("Validation errors:", error.details.errors);
+  }
+}
+```
+
+## API Reference
+
+- [Databricks SQL Documentation](https://docs.databricks.com/sql/index.html)
+- [Databricks SQL Reference](https://docs.databricks.com/sql/language-manual/index.html)
+- [Databricks Data Types](https://docs.databricks.com/sql/language-manual/sql-ref-datatypes.html)

package/src/integrations/databricks/client.ts

@@ -0,0 +1,137 @@
+/**
+ * Databricks integration client implementation.
+ *
+ * Executes Databricks 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 DatabricksPlugin } from '@superblocksteam/types/dist/src/plugins/databricks/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 { DatabricksClient } from './types.js';
+
+/**
+ * Internal implementation of the Databricks client.
+ */
+export class DatabricksClientImpl
+  implements DatabricksClient, 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 Databricks 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<DatabricksPlugin> {
+    const hasParams = params && params.length > 0;
+
+    return {
+      runSql: {
+        sqlBody: 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 Databricks 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/databricks/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Databricks integration client.
+ *
+ * @module
+ */
+
+export type { DatabricksClient } from './types.js';
+export { DatabricksClientImpl } from './client.js';

package/src/integrations/databricks/types.ts

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