@superblocksteam/sdk-api 0.0.5 → 0.0.7

package/src/integrations/base/rest-api-integration-client.ts

@@ -1,75 +1,33 @@
 /**
- * Base client for REST API Integration (OpenAPI) based integrations.
+ * Generic REST API Integration client with Zod response validation.
  *
- * Provides common apiRequest() method for all OpenAPI-based plugins.
+ * Extends RestApiClientBase with an apiRequest() that validates the
+ * full response against a caller-supplied Zod schema and throws
+ * RestApiValidationError on mismatch.
  */
 
-import type { PartialMessage } from "@bufbuild/protobuf";
-import type { Plugin as RestApiIntegrationPlugin } from "@superblocksteam/types/dist/src/plugins/restapiintegration/v1/plugin_pb";
-import type { Property } from "@superblocksteam/types/dist/src/common/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type {
-  QueryExecutor,
-  StreamingQueryExecutor,
-  TraceMetadata,
-} from "../registry.js";
+import type { z } from "zod";
+
+import { RestApiValidationError } from "../../errors.js";
+import type { TraceMetadata } from "../registry.js";
+import { RestApiClientBase } from "./rest-api-client-base.js";
 import type {
   ApiRequestOptions,
   ApiRequestSchema,
   SupportsApiRequest,
-  StreamApiRequestSchema,
-  SupportsStreamingApiRequest,
 } from "./types.js";
-import {
-  RestApiValidationError,
-  StreamChunkValidationError,
-} from "../../errors.js";
-import type { z } from "zod";
-
-export type RestApiRequest = PartialMessage<RestApiIntegrationPlugin>;
 
 /**
  * Base implementation for REST API Integration clients.
  *
- * All OpenAPI-based integration clients extend this class to inherit
- * the generic apiRequest() method with runtime schema validation.
- * Also supports streaming API requests when a streaming executor is provided.
+ * All OpenAPI-based integration clients (except those with
+ * integration-specific response handling) extend this class to
+ * inherit the generic apiRequest() method with runtime Zod validation.
  */
 export abstract class RestApiIntegrationClient
-  implements
-    IntegrationClientImpl,
-    SupportsApiRequest,
-    SupportsStreamingApiRequest
+  extends RestApiClientBase
+  implements SupportsApiRequest
 {
-  readonly name: string;
-  readonly pluginId: string;
-  readonly config: IntegrationConfig;
-
-  protected readonly executeQuery: QueryExecutor;
-  protected readonly executeStreamingQuery?: StreamingQueryExecutor;
-
-  constructor(
-    config: IntegrationConfig,
-    executeQuery: QueryExecutor,
-    executeStreamingQuery?: StreamingQueryExecutor,
-  ) {
-    this.name = config.name;
-    this.pluginId = config.pluginId;
-    this.config = config;
-    this.executeQuery = executeQuery;
-    this.executeStreamingQuery = executeStreamingQuery;
-  }
-
-  /**
-   * Helper to create a Property object for params.
-   */
-  protected createParam(key: string, value: unknown): PartialMessage<Property> {
-    return {
-      key,
-      value: typeof value === "string" ? value : JSON.stringify(value),
-    };
-  }
-
   async apiRequest<TBody, TResponse>(
     options: ApiRequestOptions<TBody>,
     schema: ApiRequestSchema<TBody, TResponse> & {
@@ -77,59 +35,7 @@ export abstract class RestApiIntegrationClient
     },
     metadata?: TraceMetadata,
   ): Promise<TResponse> {
-    // Validate request body against schema if both are present.
-    // Body schema is optional — if not provided, the body is sent unvalidated.
-    if (options.body !== undefined && schema?.body) {
-      const bodyParseResult = schema.body.safeParse(options.body);
-      if (!bodyParseResult.success) {
-        throw new RestApiValidationError(
-          `Request body validation failed: ${bodyParseResult.error.message}`,
-          {
-            zodError: bodyParseResult.error,
-            data: options.body,
-          },
-        );
-      }
-    }
-
-    // Convert headers to Property array
-    const headers: PartialMessage<Property>[] = [];
-    if (options.headers) {
-      for (const [key, value] of Object.entries(options.headers)) {
-        headers.push(this.createParam(key, value));
-      }
-    }
-
-    // Convert query params to Property array
-    const params: PartialMessage<Property>[] = [];
-    if (options.params) {
-      for (const [key, value] of Object.entries(options.params)) {
-        params.push(this.createParam(key, value));
-      }
-    }
-
-    // Build the request using raw HTTP mode
-    const request: RestApiRequest = {
-      openApiAction: "genericHttpRequest",
-      httpMethod: options.method.toUpperCase(),
-      urlPath: options.path,
-      headers,
-      params,
-      responseType: "json",
-    };
-
-    // Add body if provided
-    if (options.body !== undefined) {
-      request.body = JSON.stringify(options.body);
-      request.bodyType = "jsonBody";
-    }
-
-    // Execute the request
-    const result = await this.executeQuery(
-      request as Record<string, unknown>,
-      undefined,
-      metadata,
-    );
+    const result = await this.executeApiRequest(options, schema.body, metadata);
 
     // Response schema is REQUIRED - always validate
     const responseParseResult = schema.response.safeParse(result);
@@ -146,134 +52,4 @@ export abstract class RestApiIntegrationClient
 
     return responseParseResult.data;
   }
-
-  /**
-   * 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
-   * @param metadata - Optional trace metadata for observability (label, description)
-   * @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 },
-   *   { label: 'openai.chatCompletions', description: 'Stream chat completion' }
-   * );
-   *
-   * for await (const chunk of stream) {
-   *   console.log(chunk.choices[0]?.delta?.content);
-   * }
-   * ```
-   */
-  async *streamApiRequest<TBody, TChunk>(
-    options: ApiRequestOptions<TBody>,
-    schema: StreamApiRequestSchema<TBody, TChunk>,
-    metadata?: TraceMetadata,
-  ): AsyncIterable<TChunk> {
-    // Validate that streaming is supported
-    if (!this.executeStreamingQuery) {
-      throw new Error(
-        `Streaming is not supported for integration "${this.name}". ` +
-          "The orchestrator must provide a streaming query executor.",
-      );
-    }
-
-    // Validate request body against schema if both are present.
-    // Body schema is optional — if not provided, the body is sent unvalidated.
-    if (options.body !== undefined && schema?.body) {
-      const bodyParseResult = schema.body.safeParse(options.body);
-      if (!bodyParseResult.success) {
-        throw new RestApiValidationError(
-          `Request body validation failed: ${bodyParseResult.error.message}`,
-          {
-            zodError: bodyParseResult.error,
-            data: options.body,
-          },
-        );
-      }
-    }
-
-    // Convert headers to Property array
-    const headers: PartialMessage<Property>[] = [];
-    if (options.headers) {
-      for (const [key, value] of Object.entries(options.headers)) {
-        headers.push(this.createParam(key, value));
-      }
-    }
-
-    // Convert query params to Property array
-    const params: PartialMessage<Property>[] = [];
-    if (options.params) {
-      for (const [key, value] of Object.entries(options.params)) {
-        params.push(this.createParam(key, value));
-      }
-    }
-
-    // Build the request using raw HTTP mode with streaming response
-    // Note: responseType must be "raw" for streaming - the orchestrator's
-    // Stream block expects SSE responses and only works with "raw" type.
-    const request: RestApiRequest = {
-      openApiAction: "genericHttpRequest",
-      httpMethod: options.method.toUpperCase(),
-      urlPath: options.path,
-      headers,
-      params,
-      responseType: "raw",
-    };
-
-    // Add body if provided
-    if (options.body !== undefined) {
-      request.body = JSON.stringify(options.body);
-      request.bodyType = "jsonBody";
-    }
-
-    // Execute the streaming request
-    const stream = this.executeStreamingQuery(
-      request as Record<string, unknown>,
-      metadata,
-    );
-
-    // Validate and yield each chunk
-    let chunkIndex = 0;
-    for await (const rawChunk of stream) {
-      const parseResult = schema.chunk.safeParse(rawChunk);
-
-      if (!parseResult.success) {
-        throw new StreamChunkValidationError(
-          `Chunk validation failed at index ${chunkIndex}: ${parseResult.error.message}`,
-          {
-            chunkIndex,
-            chunk: rawChunk,
-            zodError: parseResult.error,
-          },
-        );
-      }
-
-      yield parseResult.data;
-      chunkIndex++;
-    }
-  }
 }

package/src/integrations/base/types.ts

@@ -3,8 +3,12 @@
  */
 
 import type { z } from "zod";
+
 import type { TraceMetadata } from "../registry.js";
 
+// Re-export for backwards compatibility
+export type { TraceMetadata };
+
 /**
  * Options for making a generic REST API request.
  */
@@ -100,77 +104,3 @@ export interface SupportsApiRequest {
     metadata?: TraceMetadata,
   ): 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)
-   * @param metadata - Optional trace metadata for observability (label, description)
-   * @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 },
-   *   { label: 'openai.chatCompletions', description: 'Stream chat completion' }
-   * );
-   *
-   * for await (const chunk of stream) {
-   *   console.log(chunk.choices[0]?.delta?.content);
-   * }
-   * ```
-   */
-  streamApiRequest<TBody, TChunk>(
-    options: ApiRequestOptions<TBody>,
-    schema: StreamApiRequestSchema<TBody, TChunk>,
-    metadata?: TraceMetadata,
-  ): AsyncIterable<TChunk>;
-}

package/src/integrations/bigquery/README.md

@@ -40,7 +40,7 @@ export default api({
     const events = await ctx.integrations.bigquery.query(
       `SELECT event_id, event_name, user_id, timestamp
        FROM \`project.dataset.events\`
-       WHERE event_name = $1
+       WHERE event_name = ?
        LIMIT 100`,
       EventSchema,
       [event_name],
@@ -51,12 +51,16 @@ export default api({
 });
 ```
 
+The SDK currently binds BigQuery parameters from the positional `params` array.
+Even though native BigQuery also supports named parameters like `@event_name`,
+use `?` placeholders in SDK queries and pass values in array order.
+
 ### Executing INSERT, UPDATE, DELETE Statements
 
 ```typescript
 // INSERT
 await ctx.integrations.bigquery.execute(
-  "INSERT INTO `project.dataset.metrics` (name, value, timestamp) VALUES ($1, $2, CURRENT_TIMESTAMP())",
+  "INSERT INTO `project.dataset.metrics` (name, value, timestamp) VALUES (?, ?, CURRENT_TIMESTAMP())",
   ["cpu_usage", "75.5"],
 );
 ```
@@ -116,6 +120,27 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 
 ## Common Pitfalls
 
+### SDK Parameters Are Positional
+
+The SDK accepts an array of parameter values and binds them server-side in
+order. When you need parameters, use `?` placeholders in the SQL text:
+
+```typescript
+// WRONG - Native BigQuery named parameter syntax is not the SDK contract
+await ctx.integrations.bigquery.query(
+  "SELECT * FROM `project.dataset.events` WHERE event_name = @event_name",
+  EventSchema,
+  ["signup"],
+);
+
+// CORRECT - Use positional params with ? placeholders
+await ctx.integrations.bigquery.query(
+  "SELECT * FROM `project.dataset.events` WHERE event_name = ?",
+  EventSchema,
+  ["signup"],
+);
+```
+
 ### Backtick Table References
 
 BigQuery uses backticks for fully-qualified table names:
@@ -165,7 +190,7 @@ BigQuery charges by data scanned. Use partitions and column selection:
 const query = `
   SELECT event_id, event_name
   FROM \`project.dataset.events\`
-  WHERE _PARTITIONDATE = $1
+  WHERE _PARTITIONDATE = ?
 `;
 ```
 

package/src/integrations/bigquery/client.ts

@@ -5,13 +5,15 @@
  * runtime validation using Zod schemas.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 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, TraceMetadata } from "../registry.js";
+
 import { QueryValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import { describeType } from "../utils.js";
 import type { BigQueryClient } from "./types.js";
 

package/src/integrations/bigquery/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "bigquery",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/bigquery/types.ts

@@ -5,6 +5,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 
@@ -24,7 +25,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const events = await bigquery.query(
- *   'SELECT * FROM events WHERE date = $1',
+ *   'SELECT * FROM events WHERE date = ?',
  *   EventSchema,
  *   ['2024-01-01']
  * );
@@ -34,9 +35,9 @@ 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 sql - SQL query string (use ? placeholders for parameters)
    * @param schema - Zod schema to validate the query results
-   * @param params - Optional query parameters
+   * @param params - Optional query parameters, bound positionally from the provided array
    * @returns Promise resolving to validated query results
    *
    * @throws {QueryValidationError} If results don't match schema

package/src/integrations/bitbucket/README.md

@@ -54,7 +54,7 @@ export default api({
     const result = await ctx.integrations.bitbucket.apiRequest(
       {
         method: "GET",
-        path: `/2.0/repositories/${workspace}`,
+        path: `/repositories/${workspace}`,
         params: {
           pagelen: 50,
         },
@@ -78,7 +78,7 @@ export default api({
 const repo = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "GET",
-    path: `/2.0/repositories/${workspace}/${repoSlug}`,
+    path: `/repositories/${workspace}/${repoSlug}`,
   },
   { response: RepositorySchema },
 );
@@ -111,7 +111,7 @@ const PullRequestSchema = z.object({
 const pr = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "POST",
-    path: `/2.0/repositories/${workspace}/${repoSlug}/pullrequests`,
+    path: `/repositories/${workspace}/${repoSlug}/pullrequests`,
     body: {
       title: "Add new feature",
       description: "This PR adds...",
@@ -143,7 +143,7 @@ const ListPRsResponseSchema = z.object({
 const result = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "GET",
-    path: `/2.0/repositories/${workspace}/${repoSlug}/pullrequests`,
+    path: `/repositories/${workspace}/${repoSlug}/pullrequests`,
     params: {
       state: "OPEN", // OPEN, MERGED, DECLINED, SUPERSEDED
       pagelen: 25,
@@ -172,7 +172,7 @@ const MergeResponseSchema = z.object({
 const result = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "POST",
-    path: `/2.0/repositories/${workspace}/${repoSlug}/pullrequests/${prId}/merge`,
+    path: `/repositories/${workspace}/${repoSlug}/pullrequests/${prId}/merge`,
     body: {
       type: "pullrequest",
       message: "Merge pull request #123",
@@ -209,7 +209,7 @@ const ListCommitsResponseSchema = z.object({
 const result = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "GET",
-    path: `/2.0/repositories/${workspace}/${repoSlug}/commits`,
+    path: `/repositories/${workspace}/${repoSlug}/commits`,
     params: {
       branch: "main",
       pagelen: 10,
@@ -232,7 +232,7 @@ const BranchSchema = z.object({
 const branch = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "POST",
-    path: `/2.0/repositories/${workspace}/${repoSlug}/refs/branches`,
+    path: `/repositories/${workspace}/${repoSlug}/refs/branches`,
     body: {
       name: "feature/new-feature",
       target: {
@@ -251,7 +251,7 @@ const branch = await ctx.integrations.bitbucket.apiRequest(
 const content = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "GET",
-    path: `/2.0/repositories/${workspace}/${repoSlug}/src/main/README.md`,
+    path: `/repositories/${workspace}/${repoSlug}/src/main/README.md`,
   },
   { response: z.string() },
 );
@@ -274,7 +274,7 @@ const CommentSchema = z.object({
 const comment = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "POST",
-    path: `/2.0/repositories/${workspace}/${repoSlug}/pullrequests/${prId}/comments`,
+    path: `/repositories/${workspace}/${repoSlug}/pullrequests/${prId}/comments`,
     body: {
       content: {
         raw: "LGTM! :+1:",
@@ -300,20 +300,20 @@ await bitbucket.listRepos();
 
 // CORRECT - Use apiRequest
 await ctx.integrations.bitbucket.apiRequest(
-  { method: "POST", path: `/2.0/repositories/${workspace}/${repo}/pullrequests`, body: { ... } },
+  { method: "POST", path: `/repositories/${workspace}/${repo}/pullrequests`, body: { ... } },
   { response: PullRequestSchema }
 );
 ```
 
 ### API Version in Path
 
-Always include `/2.0/` prefix:
+The base URL already includes `/2.0`, so do not repeat it in paths:
 
 ```typescript
-// WRONG - Missing version
+// CORRECT - No version prefix (base URL already has /2.0)
 const path = `/repositories/${workspace}/${repo}`;
 
-// CORRECT - Include version
+// WRONG - Duplicates version from base URL
 const path = `/2.0/repositories/${workspace}/${repo}`;
 ```
 
@@ -323,10 +323,10 @@ Use workspace slug for API calls:
 
 ```typescript
 // Workspace slug (preferred)
-const path = `/2.0/repositories/myworkspace/myrepo`;
+const path = `/repositories/myworkspace/myrepo`;
 
 // Can also be username for personal repos
-const path = `/2.0/repositories/myusername/myrepo`;
+const path = `/repositories/myusername/myrepo`;
 ```
 
 ### Pagination
@@ -340,7 +340,7 @@ async function getAllPRs(
   repo: string,
 ) {
   const allPRs: PullRequest[] = [];
-  let url = `/2.0/repositories/${workspace}/${repo}/pullrequests`;
+  let url = `/repositories/${workspace}/${repo}/pullrequests`;
 
   while (url) {
     const result = await ctx.integrations.bitbucket.apiRequest(
@@ -385,7 +385,7 @@ Branch names with slashes need encoding:
 ```typescript
 // Branch name: feature/my-feature
 const branchName = encodeURIComponent("feature/my-feature");
-const path = `/2.0/repositories/${workspace}/${repo}/src/${branchName}/file.txt`;
+const path = `/repositories/${workspace}/${repo}/src/${branchName}/file.txt`;
 ```
 
 ### Raw File Content
@@ -397,7 +397,7 @@ File content endpoints return raw text, not JSON:
 const content = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "GET",
-    path: `/2.0/repositories/${workspace}/${repo}/src/main/file.txt`,
+    path: `/repositories/${workspace}/${repo}/src/main/file.txt`,
   },
   { response: z.string() }, // Not a JSON schema
 );
@@ -410,7 +410,7 @@ import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
   const result = await ctx.integrations.bitbucket.apiRequest(
-    { method: "GET", path: `/2.0/repositories/${workspace}/${repo}` },
+    { method: "GET", path: `/repositories/${workspace}/${repo}` },
     { response: RepositorySchema },
   );
 } catch (error) {

package/src/integrations/bitbucket/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "bitbucket",
+  "base": "README.md",
+  "overlays": []
+}