@superblocksteam/sdk-api 2.0.103 → 2.0.104-next.0

package/src/integrations/anthropic/types.ts

@@ -3,16 +3,12 @@
  */
 
 import type { BaseIntegrationClient } from "../../types.js";
-import type {
-  SupportsApiRequest,
-  SupportsStreamingApiRequest,
-} from "../base/index.js";
+import type { SupportsApiRequest } from "../base/index.js";
 
 /**
  * Anthropic client for Claude AI model interactions.
  *
- * Provides the generic apiRequest() method for any Anthropic API endpoint,
- * and streamApiRequest() for streaming responses.
+ * Provides the generic apiRequest() method for any Anthropic API endpoint.
  * Use this to interact with Anthropic's messages API and other endpoints.
  *
  * @example
@@ -58,31 +54,9 @@ import type {
  *   }
  * );
  *
- * // Or use streaming for real-time responses
- * const stream = anthropic.streamApiRequest(
- *   {
- *     method: 'POST',
- *     path: '/v1/messages',
- *     body: {
- *       model: 'claude-3-5-sonnet-20241022',
- *       max_tokens: 1024,
- *       stream: true,
- *       messages: [{ role: 'user', content: 'Hello!' }],
- *     },
- *   },
- *   { chunk: StreamEventSchema }
- * );
- *
- * for await (const event of stream) {
- *   // Handle streaming events
- * }
  * ```
  */
 export interface AnthropicClient
-  extends
-    BaseIntegrationClient,
-    SupportsApiRequest,
-    SupportsStreamingApiRequest {
+  extends BaseIntegrationClient, SupportsApiRequest {
   // apiRequest() method inherited from SupportsApiRequest
-  // streamApiRequest() method inherited from SupportsStreamingApiRequest
 }

package/src/integrations/base/index.ts

@@ -9,6 +9,4 @@ export type {
   ApiRequestOptions,
   ApiRequestSchema,
   SupportsApiRequest,
-  StreamApiRequestSchema,
-  SupportsStreamingApiRequest,
 } from "./types.js";

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

@@ -10,22 +10,13 @@ import type { z } from "zod";
 import type { Property } from "@superblocksteam/types/dist/src/common/v1/plugin_pb";
 import type { Plugin as RestApiIntegrationPlugin } from "@superblocksteam/types/dist/src/plugins/restapiintegration/v1/plugin_pb";
 
-import {
-  RestApiValidationError,
-  StreamChunkValidationError,
-} from "../../errors.js";
-import type {
-  QueryExecutor,
-  StreamingQueryExecutor,
-  TraceMetadata,
-} from "../registry.js";
+import { RestApiValidationError } from "../../errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
 import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import type {
   ApiRequestOptions,
   ApiRequestSchema,
   SupportsApiRequest,
-  StreamApiRequestSchema,
-  SupportsStreamingApiRequest,
 } from "./types.js";
 
 export type RestApiRequest = PartialMessage<RestApiIntegrationPlugin>;
@@ -35,31 +26,21 @@ export type RestApiRequest = PartialMessage<RestApiIntegrationPlugin>;
  *
  * 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.
  */
 export abstract class RestApiIntegrationClient
-  implements
-    IntegrationClientImpl,
-    SupportsApiRequest,
-    SupportsStreamingApiRequest
+  implements IntegrationClientImpl, 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,
-  ) {
+  constructor(config: IntegrationConfig, executeQuery: QueryExecutor) {
     this.name = config.name;
     this.pluginId = config.pluginId;
     this.config = config;
     this.executeQuery = executeQuery;
-    this.executeStreamingQuery = executeStreamingQuery;
   }
 
   /**
@@ -148,134 +129,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

@@ -6,6 +6,9 @@ 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.
  */
@@ -101,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/cohere/README.md

@@ -52,7 +52,7 @@ export default api({
     const result = await ctx.integrations.cohere.apiRequest(
       {
         method: "POST",
-        path: "/v1/chat",
+        path: "/chat",
         body: {
           model: "command-r-plus",
           message: message,
@@ -81,7 +81,7 @@ const EmbedResponseSchema = z.object({
 const result = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
-    path: "/v1/embed",
+    path: "/embed",
     body: {
       model: "embed-english-v3.0",
       texts: ["Hello world", "How are you?"],
@@ -115,7 +115,7 @@ const ClassifyResponseSchema = z.object({
 const result = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
-    path: "/v1/classify",
+    path: "/classify",
     body: {
       model: "embed-english-v3.0",
       inputs: ["This product is amazing!", "Terrible experience, never again"],
@@ -159,7 +159,7 @@ const documents = [
 const result = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
-    path: "/v1/rerank",
+    path: "/rerank",
     body: {
       model: "rerank-english-v3.0",
       query: "What is the capital of the United States?",
@@ -193,7 +193,7 @@ const GenerateResponseSchema = z.object({
 const result = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
-    path: "/v1/generate",
+    path: "/generate",
     body: {
       model: "command",
       prompt: "Write a creative story about",
@@ -220,7 +220,7 @@ await cohere.embed({ ... });
 
 // CORRECT - Use apiRequest
 await ctx.integrations.cohere.apiRequest(
-  { method: "POST", path: "/v1/chat", body: { ... } },
+  { method: "POST", path: "/chat", body: { ... } },
   { response: ChatResponseSchema }
 );
 ```
@@ -234,7 +234,7 @@ When creating embeddings, specify the correct `input_type`:
 const docEmbeddings = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
-    path: "/v1/embed",
+    path: "/embed",
     body: {
       texts: documents,
       input_type: "search_document", // For documents
@@ -247,7 +247,7 @@ const docEmbeddings = await ctx.integrations.cohere.apiRequest(
 const queryEmbedding = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
-    path: "/v1/embed",
+    path: "/embed",
     body: {
       texts: [query],
       input_type: "search_query", // For queries
@@ -266,7 +266,7 @@ The classify endpoint requires labeled examples:
 const result = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
-    path: "/v1/classify",
+    path: "/classify",
     body: {
       inputs: ["Great product!"],
       // Missing examples!
@@ -279,7 +279,7 @@ const result = await ctx.integrations.cohere.apiRequest(
 const result = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
-    path: "/v1/classify",
+    path: "/classify",
     body: {
       inputs: ["Great product!"],
       examples: [
@@ -299,7 +299,7 @@ import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
   const result = await ctx.integrations.cohere.apiRequest(
-    { method: "POST", path: "/v1/chat", body: { ... } },
+    { method: "POST", path: "/chat", body: { ... } },
     { response: ChatResponseSchema }
   );
 } catch (error) {

package/src/integrations/fireworks/README.md

@@ -10,7 +10,9 @@ Interact with Fireworks AI's fast inference platform for LLM chat completions an
 
 ## Usage
 
-### Chat Completion
+### Step 1: List Available Models
+
+Model availability varies by account. Before making requests, validate which models are deployed on your account:
 
 ```typescript
 import { api, z, fireworks } from "@superblocksteam/sdk-api";
@@ -18,6 +20,30 @@ import { api, z, fireworks } from "@superblocksteam/sdk-api";
 // Integration ID from the integrations panel
 const PROD_FIREWORKS = "a1b2c3d4-5678-90ab-cdef-fireworks001";
 
+const ModelsResponseSchema = z.object({
+  data: z.array(
+    z.object({
+      id: z.string(),
+      object: z.string(),
+    }),
+  ),
+});
+
+const models = await ctx.integrations.fireworks.apiRequest(
+  {
+    method: "GET",
+    path: "/v1/models",
+  },
+  { response: ModelsResponseSchema },
+);
+
+// Use a model ID from the response in subsequent requests
+const availableModelId = models.data[0]?.id;
+```
+
+### Chat Completion
+
+```typescript
 const ChatCompletionResponseSchema = z.object({
   id: z.string(),
   object: z.string(),
@@ -55,7 +81,7 @@ export default api({
     const result = await ctx.integrations.fireworks.apiRequest(
       {
         method: "POST",
-        path: "/inference/v1/chat/completions",
+        path: "/v1/chat/completions",
         body: {
           model: "accounts/fireworks/models/llama-v3p1-70b-instruct",
           messages: [{ role: "user", content: prompt }],
@@ -76,7 +102,7 @@ export default api({
 const llama70b = await ctx.integrations.fireworks.apiRequest(
   {
     method: "POST",
-    path: "/inference/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "accounts/fireworks/models/llama-v3p1-70b-instruct",
       messages: [{ role: "user", content: "Complex task..." }],
@@ -89,7 +115,7 @@ const llama70b = await ctx.integrations.fireworks.apiRequest(
 const llama8b = await ctx.integrations.fireworks.apiRequest(
   {
     method: "POST",
-    path: "/inference/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "accounts/fireworks/models/llama-v3p1-8b-instruct",
       messages: [{ role: "user", content: "Simple task..." }],
@@ -102,7 +128,7 @@ const llama8b = await ctx.integrations.fireworks.apiRequest(
 const mixtral = await ctx.integrations.fireworks.apiRequest(
   {
     method: "POST",
-    path: "/inference/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "accounts/fireworks/models/mixtral-8x7b-instruct",
       messages: [{ role: "user", content: "..." }],
@@ -115,7 +141,7 @@ const mixtral = await ctx.integrations.fireworks.apiRequest(
 const qwen = await ctx.integrations.fireworks.apiRequest(
   {
     method: "POST",
-    path: "/inference/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "accounts/fireworks/models/qwen2p5-coder-32b-instruct",
       messages: [{ role: "user", content: "Write code..." }],
@@ -147,7 +173,7 @@ const EmbeddingsResponseSchema = z.object({
 const result = await ctx.integrations.fireworks.apiRequest(
   {
     method: "POST",
-    path: "/inference/v1/embeddings",
+    path: "/v1/embeddings",
     body: {
       model: "accounts/fireworks/models/nomic-embed-text-v1.5",
       input: ["Hello world", "How are you?"],
@@ -188,7 +214,7 @@ const FunctionCallResponseSchema = z.object({
 const result = await ctx.integrations.fireworks.apiRequest(
   {
     method: "POST",
-    path: "/inference/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "accounts/fireworks/models/firefunction-v2",
       messages: [{ role: "user", content: "What's the weather in Paris?" }],
@@ -220,7 +246,7 @@ const result = await ctx.integrations.fireworks.apiRequest(
 const result = await ctx.integrations.fireworks.apiRequest(
   {
     method: "POST",
-    path: "/inference/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "accounts/fireworks/models/llama-v3p1-70b-instruct",
       messages: [{ role: "user", content: "List 3 colors in JSON format" }],
@@ -239,7 +265,7 @@ const data = JSON.parse(result.choices[0]?.message.content ?? "{}");
 const result = await ctx.integrations.fireworks.apiRequest(
   {
     method: "POST",
-    path: "/inference/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "accounts/fireworks/models/llama-v3p1-70b-instruct",
       messages: [{ role: "user", content: "Generate user data" }],
@@ -276,7 +302,7 @@ await fireworks.complete({ ... });
 
 // CORRECT - Use apiRequest
 await ctx.integrations.fireworks.apiRequest(
-  { method: "POST", path: "/inference/v1/chat/completions", body: { ... } },
+  { method: "POST", path: "/v1/chat/completions", body: { ... } },
   { response: ChatCompletionResponseSchema }
 );
 ```
@@ -301,18 +327,18 @@ const body = {
 
 ### API Path
 
-Fireworks uses `/inference/v1/` prefix:
+The integration's base URL already includes `https://api.fireworks.ai/inference`, so paths should start with `/v1/`:
 
 ```typescript
-// WRONG - Missing inference prefix
+// WRONG - Duplicates the /inference prefix (base URL already includes it)
 await ctx.integrations.fireworks.apiRequest(
-  { method: "POST", path: "/v1/chat/completions", body: { ... } },
+  { method: "POST", path: "/inference/v1/chat/completions", body: { ... } },
   { response: schema }
 );
 
-// CORRECT - Include inference prefix
+// CORRECT - Start with /v1/ (the integration prepends /inference automatically)
 await ctx.integrations.fireworks.apiRequest(
-  { method: "POST", path: "/inference/v1/chat/completions", body: { ... } },
+  { method: "POST", path: "/v1/chat/completions", body: { ... } },
   { response: schema }
 );
 ```
@@ -347,7 +373,7 @@ import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
   const result = await ctx.integrations.fireworks.apiRequest(
-    { method: "POST", path: "/inference/v1/chat/completions", body: { ... } },
+    { method: "POST", path: "/v1/chat/completions", body: { ... } },
     { response: ChatCompletionResponseSchema }
   );
 } catch (error) {

package/src/integrations/googleanalytics/README.md

@@ -13,7 +13,7 @@ Run reports, get real-time data, and interact with Google Analytics 4 properties
 ### Run a Report
 
 ```typescript
-import { api, z, googleanalytics } from "@superblocksteam/sdk-api";
+import { api, z, googleAnalytics } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_GA4 = "a1b2c3d4-5678-90ab-cdef-ga4000000001";
@@ -46,7 +46,7 @@ const ReportResponseSchema = z.object({
 
 export default api({
   integrations: {
-    ga: googleanalytics(PROD_GA4),
+    ga: googleAnalytics(PROD_GA4),
   },
   name: "GoogleAnalyticsExample",
   input: z.object({

package/src/integrations/googledrive/README.md

@@ -13,7 +13,7 @@ Upload, download, and manage files in Google Drive.
 ### List Files
 
 ```typescript
-import { api, z, googledrive } from "@superblocksteam/sdk-api";
+import { api, z, googleDrive } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_DRIVE = "a1b2c3d4-5678-90ab-cdef-gdrive000001";
@@ -45,7 +45,7 @@ const ListFilesResponseSchema = z.object({
 
 export default api({
   integrations: {
-    drive: googledrive(PROD_DRIVE),
+    drive: googleDrive(PROD_DRIVE),
   },
   name: "GoogleDriveExample",
   input: z.object({