@superblocksteam/sdk-api 0.0.6 → 0.0.7

package/src/api/streaming.ts

@@ -1,302 +0,0 @@
-/**
- * Streaming API definition function.
- *
- * This module provides the `streamingApi()` function used to define TypeScript-based APIs
- * that yield chunks over time, enabling real-time streaming from LLMs and other sources.
- */
-
-import type { z } from "zod";
-import type { ApiContext, AnyIntegrationRef } from "../types.js";
-import {
-  extractIntegrationDeclarations,
-  type IntegrationDeclaration,
-} from "../integrations/declarations.js";
-import { consumeEntryPoint } from "./definition.js";
-
-/**
- * Configuration for defining a streaming TypeScript-based API.
- *
- * @template TInput - Zod schema type for input validation
- * @template TChunk - Zod schema type for each streamed chunk
- * @template TIntegrations - Record of integration declarations
- *
- * @example
- * ```typescript
- * import { streamingApi, z, anthropic } from '@superblocksteam/sdk-api';
- *
- * export default streamingApi({
- *   integrations: {
- *     ai: anthropic('Production Anthropic'),
- *   },
- *
- *   input: z.object({
- *     prompt: z.string(),
- *   }),
- *
- *   chunk: z.object({
- *     type: z.literal('text-delta'),
- *     text: z.string(),
- *   }),
- *
- *   async *run(ctx, { prompt }) {
- *     const stream = ctx.integrations.ai.streamApiRequest(
- *       {
- *         method: 'POST',
- *         path: '/v1/messages',
- *         body: {
- *           model: 'claude-3-5-sonnet-20241022',
- *           max_tokens: 1024,
- *           stream: true,
- *           messages: [{ role: 'user', content: prompt }],
- *         },
- *       },
- *       { chunk: AnthropicStreamEventSchema }
- *     );
- *
- *     for await (const event of stream) {
- *       if (event.type === 'content_block_delta') {
- *         yield { type: 'text-delta' as const, text: event.delta.text };
- *       }
- *     }
- *   },
- * });
- * ```
- */
-export interface StreamingApiConfig<
-  TInput extends z.ZodType,
-  TChunk extends z.ZodType,
-  TIntegrations extends Record<string, AnyIntegrationRef> = Record<
-    string,
-    never
-  >,
-> {
-  /**
-   * Name for this API.
-   *
-   * Used for identification in execution logs and debugging.
-   */
-  name: string;
-
-  /**
-   * Plain-language summary of what this API does and which integrations it uses,
-   * written for a non-technical audience.
-   *
-   * This field is auto-generated by the AI agent when creating or editing an API.
-   */
-  description?: string;
-
-  /**
-   * Integration declarations for this API.
-   *
-   * Declare integrations upfront to enable type-safe access via `ctx.integrations`
-   * and to allow the runtime to authenticate integrations before execution.
-   *
-   * @example
-   * ```typescript
-   * integrations: {
-   *   ai: anthropic('Production Anthropic'),
-   *   db: postgres('Cache DB'),
-   * }
-   * ```
-   */
-  integrations?: TIntegrations;
-
-  /** Zod schema for input validation */
-  input: TInput;
-
-  /**
-   * Zod schema for validating each streamed chunk.
-   *
-   * Every chunk yielded by the run function is validated against this schema.
-   * Validation errors will terminate the stream.
-   */
-  chunk: TChunk;
-
-  /**
-   * The streaming API implementation function (async generator).
-   *
-   * @param ctx - Execution context with access to integrations
-   * @param input - Validated input parameters (can be destructured)
-   * @yields Chunks that are validated against the chunk schema
-   */
-  run: (
-    ctx: ApiContext<TIntegrations>,
-    input: z.infer<TInput>,
-  ) => AsyncIterable<z.infer<TChunk>>;
-}
-
-/**
- * A compiled streaming API definition ready for execution.
- *
- * @template TInput - The inferred input type
- * @template TChunk - The inferred chunk type
- */
-export interface CompiledStreamingApi<TInput = unknown, TChunk = unknown> {
-  /** Name of the API for identification in logs and debugging */
-  readonly name: string;
-
-  /** Plain-language summary of what this API does */
-  readonly description?: string;
-  /**
-   * Source file path relative to the app root (e.g. "server/apis/Chat/api.ts").
-   * Injected automatically by the Vite plugin — not authored by the user.
-   */
-  readonly entryPoint?: string;
-
-  /** Zod schema for validating inputs */
-  readonly inputSchema: z.ZodType<TInput>;
-
-  /**
-   * Zod schema for validating each streamed chunk.
-   *
-   * Every chunk yielded by the API is validated against this schema
-   * before being sent to the client.
-   */
-  readonly chunkSchema: z.ZodType<TChunk>;
-
-  /**
-   * The streaming API implementation function.
-   *
-   * @param ctx - Execution context
-   * @param input - Validated input parameters
-   * @returns AsyncIterable yielding validated chunks
-   */
-  readonly run: (
-    ctx: ApiContext<Record<string, AnyIntegrationRef>>,
-    input: TInput,
-  ) => AsyncIterable<TChunk>;
-
-  /**
-   * Declared integrations for upfront authentication.
-   *
-   * This array contains all integrations declared in the API config,
-   * allowing the runtime to authenticate them before API execution.
-   */
-  readonly integrations: ReadonlyArray<IntegrationDeclaration>;
-
-  /**
-   * Runtime flag indicating this is a streaming API.
-   *
-   * Always `true` for streaming APIs. Use `isStreamingApi()` type guard
-   * to distinguish streaming APIs from regular APIs at runtime.
-   */
-  readonly isStreaming: true;
-}
-
-/**
- * Define a streaming TypeScript-based API with chunk validation.
- *
- * This function creates a compiled streaming API definition that yields
- * chunks over time. Each chunk is validated against the provided schema.
- *
- * Use this for:
- * - Real-time LLM token streaming (OpenAI, Anthropic, etc.)
- * - Server-sent events
- * - Long-running operations with progress updates
- * - Any API that produces output incrementally
- *
- * @param config - The streaming API configuration
- * @returns A compiled streaming API definition
- *
- * @example
- * ```typescript
- * import { streamingApi, z, openai } from '@superblocksteam/sdk-api';
- *
- * export default streamingApi({
- *   integrations: {
- *     ai: openai('Production OpenAI'),
- *   },
- *
- *   input: z.object({
- *     prompt: z.string(),
- *   }),
- *
- *   chunk: z.object({
- *     content: z.string(),
- *   }),
- *
- *   async *run(ctx, { prompt }) {
- *     const stream = ctx.integrations.ai.streamApiRequest(
- *       {
- *         method: 'POST',
- *         path: '/v1/chat/completions',
- *         body: {
- *           model: 'gpt-4',
- *           stream: true,
- *           messages: [{ role: 'user', content: prompt }],
- *         },
- *       },
- *       { chunk: OpenAIChunkSchema }
- *     );
- *
- *     for await (const chunk of stream) {
- *       const content = chunk.choices[0]?.delta?.content;
- *       if (content) {
- *         yield { content };
- *       }
- *     }
- *   },
- * });
- * ```
- */
-export function streamingApi<
-  TInput extends z.ZodType,
-  TChunk extends z.ZodType,
-  TIntegrations extends Record<string, AnyIntegrationRef> = Record<
-    string,
-    never
-  >,
->(
-  config: StreamingApiConfig<TInput, TChunk, TIntegrations>,
-): CompiledStreamingApi<z.infer<TInput>, z.infer<TChunk>> {
-  // Extract integration declarations for upfront auth
-  const integrations = extractIntegrationDeclarations(config.integrations);
-
-  const compiled: CompiledStreamingApi<z.infer<TInput>, z.infer<TChunk>> = {
-    name: config.name,
-    description: config.description,
-    entryPoint: consumeEntryPoint(),
-    inputSchema: config.input,
-    chunkSchema: config.chunk,
-    run: config.run as (
-      ctx: ApiContext<Record<string, AnyIntegrationRef>>,
-      input: z.infer<TInput>,
-    ) => AsyncIterable<z.infer<TChunk>>,
-    integrations,
-    isStreaming: true,
-  };
-
-  return compiled;
-}
-
-/**
- * Type guard to check if an API is a streaming API.
- *
- * @param api - The API to check
- * @returns `true` if the API is a streaming API, `false` otherwise
- *
- * @example
- * ```typescript
- * import { isStreamingApi, executeApi, executeStreamingApi } from '@superblocksteam/sdk-api';
- *
- * if (isStreamingApi(api)) {
- *   await executeStreamingApi(api, request);
- * } else {
- *   await executeApi(api, request);
- * }
- * ```
- */
-export function isStreamingApi(
-  api: unknown,
-): api is CompiledStreamingApi<unknown, unknown> {
-  return (
-    typeof api === "object" &&
-    api !== null &&
-    "isStreaming" in api &&
-    (api as Record<string, unknown>).isStreaming === true &&
-    "inputSchema" in api &&
-    "chunkSchema" in api &&
-    "run" in api &&
-    typeof (api as Record<string, unknown>).run === "function"
-  );
-}

package/src/integrations/couchbase/README.md

@@ -1,138 +0,0 @@
-# Couchbase Client
-
-Interact with Couchbase databases with full type safety and runtime validation.
-
-## Methods
-
-| Method                                           | Description                                  |
-| ------------------------------------------------ | -------------------------------------------- |
-| `query(bucket, sql, schema, params?, metadata?)` | Execute a SQL++ query with schema validation |
-| `insert(key, value, identifier, metadata?)`      | Insert a document into a collection          |
-| `get(key, schema, identifier, metadata?)`        | Get a document by key with schema validation |
-| `remove(key, identifier, metadata?)`             | Remove a document by key                     |
-
-## Usage
-
-### SQL++ Query
-
-```typescript
-import { api, z, couchbase } from "@superblocksteam/sdk-api";
-
-// Integration ID from the integrations panel
-const PROD_COUCHBASE = "a1b2c3d4-5678-90ab-cdef-couchbase001";
-
-const UserSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  email: z.string(),
-});
-
-export default api({
-  name: "CouchbaseExample",
-  integrations: {
-    cb: couchbase(PROD_COUCHBASE),
-  },
-  input: z.object({
-    status: z.string(),
-  }),
-  output: z.object({
-    users: z.array(UserSchema),
-  }),
-  async run(ctx, { status }) {
-    const users = await ctx.integrations.cb.query(
-      "my-bucket",
-      `SELECT META().id, name, email FROM bucket WHERE status = "${status}"`,
-      UserSchema,
-    );
-
-    return { users };
-  },
-});
-```
-
-### Parameterized Query
-
-```typescript
-const users = await ctx.integrations.cb.query(
-  "my-bucket",
-  "SELECT META().id, name, email FROM bucket WHERE status = $1",
-  UserSchema,
-  [status],
-);
-```
-
-### Insert Document
-
-```typescript
-await ctx.integrations.cb.insert(
-  "user::123",
-  { name: "Alice", email: "alice@example.com", status: "active" },
-  { bucket: "my-bucket", scope: "_default", collection: "_default" },
-);
-```
-
-### Get Document
-
-```typescript
-const UserSchema = z.object({
-  name: z.string(),
-  email: z.string(),
-  status: z.string(),
-});
-
-const user = await ctx.integrations.cb.get("user::123", UserSchema, {
-  bucket: "my-bucket",
-  scope: "_default",
-  collection: "_default",
-});
-```
-
-### Remove Document
-
-```typescript
-await ctx.integrations.cb.remove("user::123", {
-  bucket: "my-bucket",
-  scope: "_default",
-  collection: "_default",
-});
-```
-
-## 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 {
-  QueryValidationError,
-  RestApiValidationError,
-} from "@superblocksteam/sdk-api";
-
-try {
-  const users = await ctx.integrations.cb.query(
-    "my-bucket",
-    "SELECT * FROM bucket",
-    UserSchema,
-  );
-} catch (error) {
-  if (error instanceof QueryValidationError) {
-    // Query result row failed schema validation
-    console.error(
-      "Row",
-      error.details.rowIndex,
-      "failed:",
-      error.details.errors,
-    );
-  }
-  if (error instanceof RestApiValidationError) {
-    // Document get result failed schema validation
-    console.error("Validation failed:", error.details.zodError);
-  }
-}
-```
-
-## API Reference
-
-- [SQL++ Query Language](https://docs.couchbase.com/server/current/n1ql/n1ql-language-reference/index.html)
-- [Couchbase Key-Value Operations](https://docs.couchbase.com/server/current/learn/data/data.html)

package/src/integrations/couchbase/client.ts

@@ -1,224 +0,0 @@
-/**
- * Couchbase client implementation.
- *
- * Builds proto JSON-style request objects for SQL++ queries, document insert,
- * get, and remove operations against Couchbase buckets.
- *
- * IMPORTANT: Request objects use plain objects with flat proto JSON keys
- * (e.g. `{runSql: {sqlBody}}`) rather than the protobuf-es `CouchbaseRequest`
- * type. The protobuf-es type uses oneof wrappers (`{case: "runSql", value: {...}}`)
- * which get lost during the JSON → Go proto → JSON roundtrip in the orchestrator,
- * resulting in "invalid operation: undefined". The Go orchestrator expects the
- * standard proto JSON format with flat field names, not the TS-specific wrapper.
- */
-
-import type { z } from "zod";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } 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";
-
-/**
- * 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[],
-    metadata?: TraceMetadata,
-  ): Promise<T[]> {
-    const hasParams = params && params.length > 0;
-    const request = {
-      bucketName: bucket,
-      runSql: {
-        sqlBody: sql,
-        parameters: hasParams ? JSON.stringify(params) : undefined,
-      },
-    };
-
-    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 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,
-    metadata?: TraceMetadata,
-  ): Promise<void> {
-    const request = {
-      bucketName: identifier.bucket,
-      insert: {
-        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>,
-        undefined,
-        metadata,
-      );
-    } 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,
-    metadata?: TraceMetadata,
-  ): Promise<T> {
-    const request = {
-      bucketName: identifier.bucket,
-      get: {
-        key,
-        identifier: {
-          scope: identifier.scope,
-          collection: identifier.collection,
-        },
-      },
-    };
-
-    try {
-      const result = await this.executeQuery(
-        request 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, "get", error);
-    }
-  }
-
-  async remove(
-    key: string,
-    identifier: CouchbaseIdentifier,
-    metadata?: TraceMetadata,
-  ): Promise<void> {
-    const request = {
-      bucketName: identifier.bucket,
-      remove: {
-        key,
-        identifier: {
-          scope: identifier.scope,
-          collection: identifier.collection,
-        },
-      },
-    };
-
-    try {
-      await this.executeQuery(
-        request as Record<string, unknown>,
-        undefined,
-        metadata,
-      );
-    } catch (error) {
-      if (error instanceof IntegrationError) {
-        throw error;
-      }
-
-      throw new IntegrationError(this.config.name, "remove", error);
-    }
-  }
-}

package/src/integrations/couchbase/index.ts

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