@superblocksteam/sdk-api 0.0.4

package/src/integrations/kinesis/types.ts

@@ -0,0 +1,114 @@
+/**
+ * Kinesis client types.
+ *
+ * Kinesis uses a dedicated plugin (not REST API) with PUT and GET operations.
+ */
+
+import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
+
+/**
+ * Stream identifier type for Kinesis operations.
+ */
+export type KinesisStreamIdentifier = "STREAM_NAME" | "STREAM_ARN";
+
+/**
+ * Shard iterator type for Kinesis GET operations.
+ */
+export type KinesisShardIteratorType =
+  | "AT_SEQUENCE_NUMBER"
+  | "AFTER_SEQUENCE_NUMBER"
+  | "AT_TIMESTAMP"
+  | "TRIM_HORIZON"
+  | "LATEST";
+
+/**
+ * Parameters for a Kinesis PUT operation.
+ */
+export interface KinesisPutParams {
+  /** The data payload (JSON string or raw string) */
+  data: string;
+  /** The partition key for the record */
+  partitionKey: string;
+  /** How to identify the stream */
+  streamIdentifierType?: KinesisStreamIdentifier;
+  /** Stream name (when streamIdentifierType is STREAM_NAME) */
+  streamName?: string;
+  /** Stream ARN (when streamIdentifierType is STREAM_ARN) */
+  streamArn?: string;
+}
+
+/**
+ * Parameters for a Kinesis GET operation.
+ */
+export interface KinesisGetParams {
+  /** The shard ID to read from */
+  shardId: string;
+  /** How to position the shard iterator */
+  shardIteratorType: KinesisShardIteratorType;
+  /** Maximum number of records to return */
+  limit?: number;
+  /** Polling cooldown in milliseconds */
+  pollingCooldownMs?: number;
+  /** Starting sequence number (for AT/AFTER_SEQUENCE_NUMBER) */
+  startingSequenceNumber?: string;
+  /** Timestamp (for AT_TIMESTAMP) */
+  timestamp?: string;
+  /** How to identify the stream */
+  streamIdentifierType?: KinesisStreamIdentifier;
+  /** Stream name (when streamIdentifierType is STREAM_NAME) */
+  streamName?: string;
+  /** Stream ARN (when streamIdentifierType is STREAM_ARN) */
+  streamArn?: string;
+}
+
+/**
+ * Kinesis client for Amazon Kinesis Data Streams.
+ *
+ * Provides methods for putting records to and getting records from Kinesis streams.
+ *
+ * @example
+ * ```typescript
+ * // Declare in api(): integrations: { kinesis: kinesis(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.kinesis
+ *
+ * // Put a record
+ * await kinesis.putRecord({
+ *   data: JSON.stringify({ event: 'user_signup', userId: '123' }),
+ *   partitionKey: 'user-123',
+ *   streamName: 'user-events',
+ * });
+ *
+ * // Get records from a shard
+ * const records = await kinesis.getRecords({
+ *   shardId: 'shardId-000000000000',
+ *   shardIteratorType: 'LATEST',
+ *   streamName: 'user-events',
+ *   limit: 10,
+ * });
+ * ```
+ */
+export interface KinesisClient extends BaseIntegrationClient {
+  /**
+   * Put a record to a Kinesis stream.
+   *
+   * @param params - PUT operation parameters
+   * @returns The raw result from Kinesis (includes ShardId and SequenceNumber)
+   */
+  putRecord(
+    params: KinesisPutParams,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
+
+  /**
+   * Get records from a Kinesis stream shard.
+   *
+   * @param params - GET operation parameters
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The raw result from Kinesis (includes Records array)
+   */
+  getRecords(
+    params: KinesisGetParams,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
+}

package/src/integrations/lakebase/client.ts

@@ -0,0 +1,147 @@
+/**
+ * Lakebase client implementation.
+ *
+ * Uses the native Lakebase plugin type from @superblocksteam/types.
+ * Supports server-side parameterized SQL queries via the `parameters` field.
+ */
+
+import type { z } from "zod";
+import type { PartialMessage } from "@bufbuild/protobuf";
+import type { Plugin as LakebasePlugin } from "@superblocksteam/types/dist/src/plugins/lakebase/v1/plugin_pb";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { LakebaseClient } from "./types.js";
+import { QueryValidationError } from "../../errors.js";
+import { IntegrationError } from "../../runtime/errors.js";
+import { describeType } from "../utils.js";
+
+/**
+ * Lakebase request type derived from proto definition.
+ */
+type LakebaseRequest = PartialMessage<LakebasePlugin>;
+
+/**
+ * Internal implementation of LakebaseClient.
+ *
+ * Communicates with the orchestrator to execute SQL queries.
+ * Uses server-side parameterization via the `parameters` field.
+ */
+export class LakebaseClientImpl
+  implements LakebaseClient, IntegrationClientImpl
+{
+  readonly name: string;
+  readonly pluginId: string;
+  readonly config: IntegrationConfig;
+
+  private readonly executeQuery: QueryExecutor;
+
+  constructor(config: IntegrationConfig, executeQuery: QueryExecutor) {
+    this.name = config.name;
+    this.pluginId = config.pluginId;
+    this.config = config;
+    this.executeQuery = executeQuery;
+  }
+
+  /**
+   * Builds a Lakebase plugin request object.
+   *
+   * Parameters are passed via the `parameters` field as a JSON-stringified
+   * array. The server performs parameter binding, avoiding client-side
+   * SQL interpolation.
+   */
+  private buildRequest(sql: string, params?: unknown[]): LakebaseRequest {
+    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[],
+    metadata?: TraceMetadata,
+  ): Promise<T[]> {
+    const request = this.buildRequest(sql, params);
+
+    try {
+      const result = await this.executeQuery(
+        request as Record<string, unknown>,
+        undefined,
+        metadata,
+      );
+
+      if (!Array.isArray(result)) {
+        throw new IntegrationError(
+          this.config.name,
+          "query",
+          `Expected array result from Lakebase 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 execute(
+    sql: string,
+    params?: unknown[],
+    metadata?: TraceMetadata,
+  ): Promise<{ rowCount: number }> {
+    const request = this.buildRequest(sql, params);
+
+    try {
+      const result = await this.executeQuery(
+        request as Record<string, unknown>,
+        undefined,
+        metadata,
+      );
+
+      if (
+        typeof result === "object" &&
+        result !== null &&
+        "rowCount" in result
+      ) {
+        return { rowCount: Number(result.rowCount) || 0 };
+      }
+
+      if (Array.isArray(result)) {
+        return { rowCount: result.length };
+      }
+
+      return { rowCount: 0 };
+    } catch (error) {
+      throw new IntegrationError(this.config.name, "execute", error);
+    }
+  }
+}

package/src/integrations/lakebase/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Lakebase integration client.
+ *
+ * @module
+ */
+
+export type { LakebaseClient } from "./types.js";
+export { LakebaseClientImpl } from "./client.js";

package/src/integrations/lakebase/types.ts

@@ -0,0 +1,61 @@
+/**
+ * Lakebase client types.
+ *
+ * Lakebase is a SQL database integration that supports parameterized
+ * queries via the `body` and `parameters` proto fields.
+ */
+
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
+
+/**
+ * Lakebase client for SQL query and execute operations.
+ *
+ * @example
+ * ```typescript
+ * const lb = ctx.integrations.db;
+ *
+ * // Parameterized query
+ * const users = await lb.query(
+ *   'SELECT * FROM users WHERE status = ?',
+ *   UserSchema,
+ *   ['active'],
+ * );
+ *
+ * // Execute a mutation
+ * const result = await lb.execute(
+ *   'INSERT INTO users (name, email) VALUES (?, ?)',
+ *   ['Alice', 'alice@example.com'],
+ * );
+ * ```
+ */
+export interface LakebaseClient extends BaseIntegrationClient {
+  /**
+   * Execute a SQL query and return validated rows.
+   *
+   * @param sql - SQL query string with `?` placeholders for parameters
+   * @param schema - Zod schema for validating each result row
+   * @param params - Optional query parameters for server-side binding
+   * @returns Array of validated rows
+   */
+  query<T>(
+    sql: string,
+    schema: z.ZodSchema<T>,
+    params?: unknown[],
+    metadata?: TraceMetadata,
+  ): Promise<T[]>;
+
+  /**
+   * Execute a SQL statement (INSERT, UPDATE, DELETE).
+   *
+   * @param sql - SQL statement with `?` placeholders for parameters
+   * @param params - Optional query parameters for server-side binding
+   * @returns The affected row count
+   */
+  execute(
+    sql: string,
+    params?: unknown[],
+    metadata?: TraceMetadata,
+  ): Promise<{ rowCount: number }>;
+}