@superblocksteam/sdk-api 0.0.5 → 0.0.7

package/src/integrations/couchbase/types.ts

@@ -1,125 +0,0 @@
-/**
- * Couchbase client types.
- */
-
-import type { z } from "zod";
-import type { BaseIntegrationClient } from "../../types.js";
-import type { TraceMetadata } from "../registry.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
- * // Declare in api(): integrations: { cb: couchbase(INTEGRATION_ID) }
- * // In run(), access via ctx.integrations.cb
- *
- * // Run a SQL++ query
- * const users = await ctx.integrations.cb.query(
- *   'my-bucket',
- *   'SELECT * FROM bucket WHERE status = "active"',
- *   UserSchema,
- * );
- *
- * // Insert a document
- * await ctx.integrations.cb.insert('user::123', { name: 'Alice' }, {
- *   bucket: 'my-bucket',
- *   scope: '_default',
- *   collection: '_default',
- * });
- *
- * // Get a document
- * const doc = await ctx.integrations.cb.get('user::123', DocSchema, {
- *   bucket: 'my-bucket',
- *   scope: '_default',
- *   collection: '_default',
- * });
- *
- * // Remove a document
- * await ctx.integrations.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[],
-    metadata?: TraceMetadata,
-  ): 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
-   * @param metadata - Optional trace metadata for diagnostics
-   */
-  insert(
-    key: string,
-    value: unknown,
-    identifier: CouchbaseIdentifier,
-    metadata?: TraceMetadata,
-  ): 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
-   * @param metadata - Optional trace metadata for diagnostics
-   * @returns The validated document
-   */
-  get<T>(
-    key: string,
-    schema: z.ZodSchema<T>,
-    identifier: CouchbaseIdentifier,
-    metadata?: TraceMetadata,
-  ): 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
-   * @param metadata - Optional trace metadata for diagnostics
-   */
-  remove(
-    key: string,
-    identifier: CouchbaseIdentifier,
-    metadata?: TraceMetadata,
-  ): Promise<void>;
-}

package/src/integrations/kafka/README.md

@@ -1,144 +0,0 @@
-# Kafka Client
-
-Interact with Apache Kafka with full type safety and runtime validation.
-
-## Methods
-
-| Method                               | Description                         |
-| ------------------------------------ | ----------------------------------- |
-| `consume(schema, params, metadata?)` | Consume messages from a Kafka topic |
-| `produce(schema, params, metadata?)` | Produce messages to Kafka topics    |
-
-## Usage
-
-### Consume Messages
-
-```typescript
-import { api, z, kafka } from "@superblocksteam/sdk-api";
-
-// Integration ID from the integrations panel
-const PROD_KAFKA = "a1b2c3d4-5678-90ab-cdef-kafka0000001";
-
-const MessageSchema = z.array(
-  z.object({
-    topic: z.string(),
-    partition: z.number(),
-    offset: z.number(),
-    value: z.unknown(),
-  }),
-);
-
-export default api({
-  integrations: {
-    kafka: kafka(PROD_KAFKA),
-  },
-  name: "KafkaExample",
-  input: z.object({
-    topic: z.string(),
-  }),
-  output: z.object({
-    messages: MessageSchema,
-  }),
-  async run(ctx, { topic }) {
-    const messages = await kafka.consume(MessageSchema, {
-      topic: topic,
-      from: "LATEST",
-      groupId: "my-consumer-group",
-    });
-
-    return { messages };
-  },
-});
-```
-
-### Consume from Beginning
-
-```typescript
-const messages = await kafka.consume(MessageSchema, {
-  topic: "my-topic",
-  from: "BEGINNING",
-  groupId: "my-consumer-group",
-});
-```
-
-### Produce Messages
-
-```typescript
-const ProduceResultSchema = z.any();
-
-const result = await ctx.integrations.kafka.produce(ProduceResultSchema, {
-  messages: JSON.stringify([
-    { topic: "my-topic", value: { event: "purchase", amount: 99.99 } },
-    { topic: "my-topic", value: { event: "signup", userId: "123" } },
-  ]),
-});
-```
-
-### Produce with Options
-
-```typescript
-const result = await ctx.integrations.kafka.produce(ProduceResultSchema, {
-  messages: JSON.stringify([
-    { topic: "my-topic", key: "user-123", value: { data: "payload" } },
-  ]),
-  acks: "ALL",
-  compression: "GZIP",
-  autoCreateTopic: true,
-  transaction: true,
-});
-```
-
-## Consume Parameters
-
-| Parameter         | Type                                | Description                          |
-| ----------------- | ----------------------------------- | ------------------------------------ |
-| `topic`           | `string`                            | Topic to consume from                |
-| `from`            | `'BEGINNING' \| 'LATEST' \| 'SEEK'` | Where to start consuming from        |
-| `groupId`         | `string`                            | Consumer group ID                    |
-| `clientId`        | `string`                            | Client ID                            |
-| `readUncommitted` | `boolean`                           | Whether to read uncommitted messages |
-| `seek`            | `object`                            | Seek position for SEEK mode          |
-
-## Produce Parameters
-
-| Parameter         | Type                                    | Description                   |
-| ----------------- | --------------------------------------- | ----------------------------- |
-| `messages`        | `string`                                | JSON string array of messages |
-| `acks`            | `'NONE' \| 'LEADER' \| 'ALL'`           | Acknowledgment level          |
-| `compression`     | `'GZIP' \| 'SNAPPY' \| 'LZ4' \| 'ZSTD'` | Compression type              |
-| `autoCreateTopic` | `boolean`                               | Auto-create topic if missing  |
-| `transaction`     | `boolean`                               | Use transactions              |
-| `idempotent`      | `boolean`                               | Enable idempotent delivery    |
-| `clientId`        | `string`                                | Client ID                     |
-| `timeout`         | `number`                                | Timeout in milliseconds       |
-
-## Trace Metadata
-
-All methods accept an optional `metadata` parameter as the last argument for diagnostics labeling. See the [root SDK README](../../../README.md#trace-metadata) for details.
-
-## Error Handling
-
-```typescript
-import {
-  RestApiValidationError,
-  IntegrationError,
-} from "@superblocksteam/sdk-api";
-
-try {
-  const messages = await kafka.consume(MessageSchema, {
-    topic: "my-topic",
-    from: "LATEST",
-  });
-} catch (error) {
-  if (error instanceof RestApiValidationError) {
-    console.error("Validation failed:", error.details.zodError);
-  } else if (error instanceof IntegrationError) {
-    console.error("Kafka error:", error.message);
-  }
-}
-```
-
-## API Reference
-
-- [Apache Kafka Documentation](https://kafka.apache.org/documentation/)
-- [Confluent Documentation](https://docs.confluent.io/)

package/src/integrations/kafka/client.ts

@@ -1,215 +0,0 @@
-/**
- * Kafka client implementation.
- *
- * Constructs request objects matching the expected backend format.
- */
-
-import type { z } from "zod";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
-import { RestApiValidationError } from "../../errors.js";
-import { IntegrationError } from "../../runtime/errors.js";
-import type {
-  KafkaClient,
-  KafkaConsumeParams,
-  KafkaProduceParams,
-} from "./types.js";
-
-/**
- * Consume request structure.
- */
-interface KafkaConsumeRequest {
-  operation: "OPERATION_CONSUME";
-  consume: {
-    topic: string;
-    from: string;
-    groupId?: string;
-    clientId?: string;
-    readUncommitted?: boolean;
-    seek?: {
-      topic?: string;
-      offset?: string;
-      partition?: number;
-    };
-  };
-}
-
-/**
- * Produce request structure.
- */
-interface KafkaProduceRequest {
-  operation: "OPERATION_PRODUCE";
-  produce: {
-    messages: string;
-    acks?: string;
-    clientId?: string;
-    timeout?: number;
-    compression?: string;
-    transactionId?: string;
-    autoCreateTopic?: boolean;
-    idempotent?: boolean;
-    transaction?: boolean;
-  };
-}
-
-/**
- * Kafka plugin request - discriminated union on operation.
- */
-type KafkaRequest = KafkaConsumeRequest | KafkaProduceRequest;
-
-/**
- * Operation string values expected by the Kafka plugin.
- */
-const OPERATION = {
-  CONSUME: "OPERATION_CONSUME",
-  PRODUCE: "OPERATION_PRODUCE",
-} as const;
-
-/**
- * Consume from string values.
- */
-const CONSUME_FROM = {
-  BEGINNING: "FROM_BEGINNING",
-  LATEST: "FROM_LATEST",
-  SEEK: "FROM_SEEK",
-} as const;
-
-/**
- * Acks string values.
- */
-const ACKS = {
-  NONE: "ACKS_NONE",
-  LEADER: "ACKS_LEADER",
-  ALL: "ACKS_ALL",
-} as const;
-
-/**
- * Compression string values.
- */
-const COMPRESSION = {
-  GZIP: "COMPRESSION_GZIP",
-  SNAPPY: "COMPRESSION_SNAPPY",
-  LZ4: "COMPRESSION_LZ4",
-  ZSTD: "COMPRESSION_ZSTD",
-} as const;
-
-/**
- * Internal implementation of KafkaClient.
- */
-export class KafkaClientImpl implements KafkaClient, 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;
-  }
-
-  private buildConsumeRequest(params: KafkaConsumeParams): KafkaConsumeRequest {
-    const request: KafkaConsumeRequest = {
-      operation: OPERATION.CONSUME,
-      consume: {
-        topic: params.topic,
-        from: params.from ? CONSUME_FROM[params.from] : CONSUME_FROM.LATEST,
-        groupId: params.groupId,
-        clientId: params.clientId,
-        readUncommitted: params.readUncommitted ?? false,
-      },
-    };
-
-    if (params.seek && request.consume) {
-      request.consume.seek = {
-        topic: params.seek.topic,
-        offset: String(params.seek.offset),
-        partition: params.seek.partition,
-      };
-    }
-
-    return request;
-  }
-
-  private buildProduceRequest(params: KafkaProduceParams): KafkaProduceRequest {
-    const request: KafkaProduceRequest = {
-      operation: OPERATION.PRODUCE,
-      produce: {
-        messages: params.messages,
-        acks: params.acks ? ACKS[params.acks] : ACKS.ALL,
-        clientId: params.clientId,
-        timeout: params.timeout,
-        compression: params.compression
-          ? COMPRESSION[params.compression]
-          : undefined,
-        transactionId: params.transactionId,
-        autoCreateTopic: params.autoCreateTopic ?? false,
-        idempotent: params.idempotent ?? false,
-        transaction: params.transaction ?? false,
-      },
-    };
-
-    return request;
-  }
-
-  private async executeAndValidate<T>(
-    request: KafkaRequest,
-    schema: z.ZodSchema<T>,
-    operation: string,
-    metadata?: TraceMetadata,
-  ): Promise<T> {
-    try {
-      const result = await this.executeQuery(
-        request as unknown as Record<string, unknown>,
-        undefined,
-        metadata,
-      );
-
-      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, operation, error);
-    }
-  }
-
-  async consume<T>(
-    schema: z.ZodSchema<T>,
-    params: KafkaConsumeParams,
-    metadata?: TraceMetadata,
-  ): Promise<T> {
-    const request = this.buildConsumeRequest(params);
-    return this.executeAndValidate(request, schema, "consume", metadata);
-  }
-
-  async produce<T>(
-    schema: z.ZodSchema<T>,
-    params: KafkaProduceParams,
-    metadata?: TraceMetadata,
-  ): Promise<T> {
-    const request = this.buildProduceRequest(params);
-    return this.executeAndValidate(request, schema, "produce", metadata);
-  }
-}

package/src/integrations/kafka/index.ts

@@ -1,14 +0,0 @@
-/**
- * Kafka integration client.
- *
- * @module
- */
-
-export type {
-  KafkaClient,
-  KafkaOperation,
-  KafkaSeek,
-  KafkaConsumeParams,
-  KafkaProduceParams,
-} from "./types.js";
-export { KafkaClientImpl } from "./client.js";

package/src/integrations/kafka/types.ts

@@ -1,127 +0,0 @@
-/**
- * Kafka client types.
- */
-
-import type { z } from "zod";
-import type { BaseIntegrationClient } from "../../types.js";
-import type { TraceMetadata } from "../registry.js";
-
-/**
- * Kafka operation types.
- */
-export type KafkaOperation = "CONSUME" | "PRODUCE";
-
-/**
- * Seek position for consuming from a specific offset.
- */
-export interface KafkaSeek {
-  /** Topic name */
-  topic: string;
-  /** Offset to start from */
-  offset: number;
-  /** Partition to consume from */
-  partition: number;
-}
-
-/**
- * Parameters for Kafka consume operation.
- */
-export interface KafkaConsumeParams {
-  /** Topic to consume from */
-  topic: string;
-  /** Where to start consuming from */
-  from?: "BEGINNING" | "LATEST" | "SEEK";
-  /** Consumer group ID */
-  groupId?: string;
-  /** Client ID */
-  clientId?: string;
-  /** Seek position for SEEK mode */
-  seek?: KafkaSeek;
-  /** Whether to read uncommitted messages */
-  readUncommitted?: boolean;
-}
-
-/**
- * Parameters for Kafka produce operation.
- */
-export interface KafkaProduceParams {
-  /** Messages to produce (JSON string) */
-  messages: string;
-  /** Acknowledgment level */
-  acks?: "NONE" | "LEADER" | "ALL";
-  /** Client ID */
-  clientId?: string;
-  /** Timeout in milliseconds */
-  timeout?: number;
-  /** Compression type */
-  compression?: "GZIP" | "SNAPPY" | "LZ4" | "ZSTD";
-  /** Transaction ID for transactional produce */
-  transactionId?: string;
-  /** Whether to auto-create topic */
-  autoCreateTopic?: boolean;
-  /** Whether to enable idempotent delivery */
-  idempotent?: boolean;
-  /** Whether to use transactions */
-  transaction?: boolean;
-}
-
-/**
- * Kafka client for message streaming operations.
- *
- * Provides consume() and produce() methods for Kafka operations.
- *
- * @example
- * ```typescript
- * // Declare in api(): integrations: { kafka: kafka(INTEGRATION_ID) }
- * // In run(), access via ctx.integrations.kafka
- *
- * // Consume messages
- * const MessageSchema = z.array(z.object({
- *   topic: z.string(),
- *   partition: z.number(),
- *   offset: z.number(),
- *   value: z.unknown(),
- * }));
- *
- * const messages = await kafka.consume(MessageSchema, {
- *   topic: 'my-topic',
- *   from: 'LATEST',
- *   groupId: 'my-consumer-group',
- * });
- *
- * // Produce messages
- * const result = await kafka.produce(z.any(), {
- *   messages: JSON.stringify([
- *     { topic: 'my-topic', value: { key: 'value' } }
- *   ]),
- * });
- * ```
- */
-export interface KafkaClient extends BaseIntegrationClient {
-  /**
-   * Consume messages from Kafka.
-   *
-   * @param schema - Zod schema for validating the result
-   * @param params - Consume parameters
-   * @returns The validated result
-   */
-  consume<T>(
-    schema: z.ZodSchema<T>,
-    params: KafkaConsumeParams,
-    metadata?: TraceMetadata,
-  ): Promise<T>;
-
-  /**
-   * Produce messages to Kafka.
-   *
-   * @param schema - Zod schema for validating the result
-   * @param params - Produce parameters
-   * @param metadata - Optional trace metadata for diagnostics
-   * @returns The validated result
-   */
-  produce<T>(
-    schema: z.ZodSchema<T>,
-    params: KafkaProduceParams,
-    metadata?: TraceMetadata,
-  ): Promise<T>;
-}