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

package/src/integrations/groq/README.md

@@ -10,7 +10,9 @@ Interact with Groq's ultra-fast inference API for LLM chat completions with low
 
 ## Usage
 
-### Chat Completion
+### Step 1: List Available Models
+
+Model availability varies by account and changes over time. Before making requests, validate which models are available:
 
 ```typescript
 import { api, z, groq } from "@superblocksteam/sdk-api";
@@ -18,6 +20,30 @@ import { api, z, groq } from "@superblocksteam/sdk-api";
 // Integration ID from the integrations panel
 const PROD_GROQ = "a1b2c3d4-5678-90ab-cdef-groq00000001";
 
+const ModelsResponseSchema = z.object({
+  data: z.array(
+    z.object({
+      id: z.string(),
+      object: z.string(),
+    }),
+  ),
+});
+
+const models = await ctx.integrations.groq.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.literal("chat.completion"),
@@ -59,7 +85,7 @@ export default api({
     const result = await ctx.integrations.groq.apiRequest(
       {
         method: "POST",
-        path: "/openai/v1/chat/completions",
+        path: "/v1/chat/completions",
         body: {
           model: "llama-3.1-70b-versatile",
           messages: [
@@ -83,7 +109,7 @@ export default api({
 const llama70b = await ctx.integrations.groq.apiRequest(
   {
     method: "POST",
-    path: "/openai/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "llama-3.1-70b-versatile",
       messages: [{ role: "user", content: "Hello" }],
@@ -96,7 +122,7 @@ const llama70b = await ctx.integrations.groq.apiRequest(
 const llama8b = await ctx.integrations.groq.apiRequest(
   {
     method: "POST",
-    path: "/openai/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "llama-3.1-8b-instant",
       messages: [{ role: "user", content: "Hello" }],
@@ -109,7 +135,7 @@ const llama8b = await ctx.integrations.groq.apiRequest(
 const mixtral = await ctx.integrations.groq.apiRequest(
   {
     method: "POST",
-    path: "/openai/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "mixtral-8x7b-32768",
       messages: [{ role: "user", content: "Hello" }],
@@ -150,7 +176,7 @@ const ToolCallResponseSchema = z.object({
 const result = await ctx.integrations.groq.apiRequest(
   {
     method: "POST",
-    path: "/openai/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "llama-3.1-70b-versatile",
       messages: [{ role: "user", content: "What's the weather in Tokyo?" }],
@@ -200,7 +226,7 @@ const JSONResponseSchema = z.object({
 const result = await ctx.integrations.groq.apiRequest(
   {
     method: "POST",
-    path: "/openai/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "llama-3.1-70b-versatile",
       messages: [
@@ -234,55 +260,36 @@ await groq.createChatCompletion({ ... });
 
 // CORRECT - Use apiRequest
 await ctx.integrations.groq.apiRequest(
-  { method: "POST", path: "/openai/v1/chat/completions", body: { ... } },
+  { method: "POST", path: "/v1/chat/completions", body: { ... } },
   { response: ChatCompletionResponseSchema }
 );
 ```
 
 ### OpenAI-Compatible Path
 
-Groq uses OpenAI-compatible endpoints with `/openai/v1/` prefix:
+The integration's base URL already includes `https://api.groq.com/openai`, so paths should start with `/v1/`:
 
 ```typescript
-// WRONG - Missing /openai prefix
+// WRONG - Duplicates the /openai prefix (base URL already includes it)
 await ctx.integrations.groq.apiRequest(
-  { method: "POST", path: "/v1/chat/completions", body: { ... } },
+  { method: "POST", path: "/openai/v1/chat/completions", body: { ... } },
   { response: schema }
 );
 
-// CORRECT - Include /openai prefix
+// CORRECT - Start with /v1/ (the integration prepends /openai automatically)
 await ctx.integrations.groq.apiRequest(
-  { method: "POST", path: "/openai/v1/chat/completions", body: { ... } },
+  { method: "POST", path: "/v1/chat/completions", body: { ... } },
   { response: schema }
 );
 ```
 
-### Model Availability
-
-Groq has specific models available. Check current availability:
-
-| Model                   | Context Window | Best For           |
-| ----------------------- | -------------- | ------------------ |
-| llama-3.1-70b-versatile | 128K           | General use        |
-| llama-3.1-8b-instant    | 128K           | Fast, simple tasks |
-| mixtral-8x7b-32768      | 32K            | Code, reasoning    |
-| gemma2-9b-it            | 8K             | Lightweight tasks  |
-
-```typescript
-// Ensure model is available
-const body = {
-  model: "llama-3.1-70b-versatile", // Verify model exists
-  messages: [...],
-};
-```
-
 ### Rate Limits
 
 Groq has rate limits based on tokens per minute. Monitor usage:
 
 ```typescript
 const result = await ctx.integrations.groq.apiRequest(
-  { method: "POST", path: "/openai/v1/chat/completions", body: { ... } },
+  { method: "POST", path: "/v1/chat/completions", body: { ... } },
   { response: ChatCompletionResponseSchema }
 );
 
@@ -297,7 +304,7 @@ import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
   const result = await ctx.integrations.groq.apiRequest(
-    { method: "POST", path: "/openai/v1/chat/completions", body: { ... } },
+    { method: "POST", path: "/v1/chat/completions", body: { ... } },
     { response: ChatCompletionResponseSchema }
   );
 } catch (error) {

package/src/integrations/gsheets/README.md

@@ -24,7 +24,7 @@ Interact with Google Sheets with full type safety and runtime validation.
 ### Read Spreadsheet Data
 
 ```typescript
-import { api, z, gsheets } from "@superblocksteam/sdk-api";
+import { api, z, googleSheets } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_GSHEETS = "a1b2c3d4-5678-90ab-cdef-gsheets00001";
@@ -39,7 +39,7 @@ const RowSchema = z.array(
 
 export default api({
   integrations: {
-    sheets: gsheets(PROD_GSHEETS),
+    sheets: googleSheets(PROD_GSHEETS),
   },
   name: "GoogleSheetsExample",
   input: z.object({

package/src/integrations/index.ts

@@ -168,7 +168,6 @@ export {
   SUPPORTED_PLUGINS,
   type SupportedPluginId,
   type QueryExecutor,
-  type StreamingQueryExecutor,
   type TraceMetadata,
   type CreateClientOptions,
 } from "./registry.js";

package/src/integrations/launchdarkly/README.md

@@ -13,7 +13,7 @@ Manage feature flags, get flag evaluations, and interact with LaunchDarkly's fea
 ### Get Feature Flag
 
 ```typescript
-import { api, z, launchdarkly } from "@superblocksteam/sdk-api";
+import { api, z, launchDarkly } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_LAUNCHDARKLY = "a1b2c3d4-5678-90ab-cdef-launchda0001";
@@ -44,7 +44,7 @@ const FlagSchema = z.object({
 
 export default api({
   integrations: {
-    launchdarkly: launchdarkly(PROD_LAUNCHDARKLY),
+    launchdarkly: launchDarkly(PROD_LAUNCHDARKLY),
   },
   name: "LaunchDarklyExample",
   input: z.object({

package/src/integrations/mistral/README.md

@@ -10,7 +10,9 @@ Interact with Mistral AI's APIs for chat completions, embeddings, and code gener
 
 ## Usage
 
-### Chat Completion
+### Step 1: List Available Models
+
+Model availability varies by account and API plan. Before making requests, validate which models you can access:
 
 ```typescript
 import { api, z, mistral } from "@superblocksteam/sdk-api";
@@ -18,6 +20,30 @@ import { api, z, mistral } from "@superblocksteam/sdk-api";
 // Integration ID from the integrations panel
 const PROD_MISTRAL = "a1b2c3d4-5678-90ab-cdef-mistral00001";
 
+const ModelsResponseSchema = z.object({
+  data: z.array(
+    z.object({
+      id: z.string(),
+      object: z.string(),
+    }),
+  ),
+});
+
+const models = await ctx.integrations.mistral.apiRequest(
+  {
+    method: "GET",
+    path: "/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.mistral.apiRequest(
       {
         method: "POST",
-        path: "/v1/chat/completions",
+        path: "/chat/completions",
         body: {
           model: "mistral-large-latest",
           messages: [{ role: "user", content: prompt }],
@@ -76,7 +102,7 @@ export default api({
 const large = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "mistral-large-latest",
       messages: [{ role: "user", content: "Complex analysis..." }],
@@ -89,7 +115,7 @@ const large = await ctx.integrations.mistral.apiRequest(
 const medium = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "mistral-medium-latest",
       messages: [{ role: "user", content: "General task..." }],
@@ -102,7 +128,7 @@ const medium = await ctx.integrations.mistral.apiRequest(
 const small = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "mistral-small-latest",
       messages: [{ role: "user", content: "Simple task..." }],
@@ -115,7 +141,7 @@ const small = await ctx.integrations.mistral.apiRequest(
 const codestral = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "codestral-latest",
       messages: [{ role: "user", content: "Write a function to..." }],
@@ -148,7 +174,7 @@ const EmbeddingsResponseSchema = z.object({
 const result = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/embeddings",
+    path: "/embeddings",
     body: {
       model: "mistral-embed",
       input: ["Hello world", "Bonjour le monde"],
@@ -193,7 +219,7 @@ const FunctionCallResponseSchema = z.object({
 const result = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "mistral-large-latest",
       messages: [{ role: "user", content: "What's the weather in London?" }],
@@ -227,7 +253,7 @@ const result = await ctx.integrations.mistral.apiRequest(
 const result = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "mistral-large-latest",
       messages: [
@@ -260,7 +286,7 @@ await mistral.embed({ ... });
 
 // CORRECT - Use apiRequest
 await ctx.integrations.mistral.apiRequest(
-  { method: "POST", path: "/v1/chat/completions", body: { ... } },
+  { method: "POST", path: "/chat/completions", body: { ... } },
   { response: ChatCompletionResponseSchema }
 );
 ```
@@ -288,7 +314,7 @@ Mistral has a safe mode for content moderation:
 const result = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "mistral-large-latest",
       messages: [{ role: "user", content: "..." }],
@@ -307,7 +333,7 @@ Mistral supports system messages:
 const result = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "mistral-large-latest",
       messages: [
@@ -327,7 +353,7 @@ import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
   const result = await ctx.integrations.mistral.apiRequest(
-    { method: "POST", path: "/v1/chat/completions", body: { ... } },
+    { method: "POST", path: "/chat/completions", body: { ... } },
     { response: ChatCompletionResponseSchema }
   );
 } catch (error) {

package/src/integrations/openai_v2/README.md

@@ -4,14 +4,15 @@ Interact with OpenAI's APIs for chat completions, embeddings, image generation,
 
 ## Methods
 
-| Method                                         | Description                                        |
-| ---------------------------------------------- | -------------------------------------------------- |
-| `apiRequest(options, schema, metadata?)`       | Make any OpenAI API request with schema validation |
-| `streamApiRequest(options, schema, metadata?)` | Stream responses with real-time chunk validation   |
+| Method                                   | Description                                        |
+| ---------------------------------------- | -------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any OpenAI API request with schema validation |
 
 ## Usage
 
-### Chat Completion
+### Step 1: List Available Models
+
+Model availability depends on your OpenAI account and API tier. Before making requests, validate which models you can access:
 
 ```typescript
 import { api, z, openai } from "@superblocksteam/sdk-api";
@@ -19,6 +20,30 @@ import { api, z, openai } from "@superblocksteam/sdk-api";
 // Integration ID from the integrations panel
 const PROD_OPENAI = "a1b2c3d4-5678-90ab-cdef-333333333333";
 
+const ModelsResponseSchema = z.object({
+  data: z.array(
+    z.object({
+      id: z.string(),
+      object: z.string(),
+    }),
+  ),
+});
+
+const models = await ctx.integrations.ai.apiRequest(
+  {
+    method: "GET",
+    path: "/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.literal("chat.completion"),
@@ -56,7 +81,7 @@ export default api({
     const result = await ctx.integrations.ai.apiRequest(
       {
         method: "POST",
-        path: "/v1/chat/completions",
+        path: "/chat/completions",
         body: {
           model: "gpt-4",
           messages: [
@@ -105,7 +130,7 @@ const FunctionCallResponseSchema = z.object({
 const result = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "gpt-4",
       messages: [
@@ -161,7 +186,7 @@ const EmbeddingsResponseSchema = z.object({
 const embeddings = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
-    path: "/v1/embeddings",
+    path: "/embeddings",
     body: {
       model: "text-embedding-3-small",
       input: ["Hello world", "How are you?"],
@@ -192,7 +217,7 @@ const ImageResponseSchema = z.object({
 const images = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
-    path: "/v1/images/generations",
+    path: "/images/generations",
     body: {
       model: "dall-e-3",
       prompt: "A serene mountain landscape at sunset",
@@ -215,7 +240,7 @@ const imageUrl = images.data[0]?.url;
 const ttsResult = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
-    path: "/v1/audio/speech",
+    path: "/audio/speech",
     body: {
       model: "tts-1",
       input: "Hello, how are you today?",
@@ -226,91 +251,6 @@ const ttsResult = await ctx.integrations.ai.apiRequest(
 );
 ```
 
-### Streaming Chat Completions
-
-For real-time token streaming, use `streamApiRequest()` with `stream: true`:
-
-```typescript
-import { streamingApi, z, openai } from "@superblocksteam/sdk-api";
-
-// Integration ID from the integrations panel
-const PROD_OPENAI = "a1b2c3d4-5678-90ab-cdef-333333333333";
-
-// Schema for OpenAI's streaming SSE chunks
-const OpenAIStreamChunkSchema = z.object({
-  id: z.string(),
-  object: z.literal("chat.completion.chunk"),
-  created: z.number(),
-  model: z.string(),
-  choices: z.array(
-    z.object({
-      index: z.number(),
-      delta: z.object({
-        role: z.string().optional(),
-        content: z.string().optional(),
-      }),
-      finish_reason: z.string().nullable(),
-    }),
-  ),
-});
-
-export default streamingApi({
-  integrations: {
-    ai: openai(PROD_OPENAI),
-  },
-
-  input: z.object({ prompt: z.string() }),
-  chunk: z.object({ type: z.literal("text"), text: z.string() }),
-
-  async *run(ctx, { prompt }) {
-    const stream = ctx.integrations.ai.streamApiRequest(
-      {
-        method: "POST",
-        path: "/v1/chat/completions",
-        body: {
-          model: "gpt-4",
-          stream: true, // Enable streaming
-          messages: [
-            { role: "system", content: "You are a helpful assistant." },
-            { role: "user", content: prompt },
-          ],
-        },
-      },
-      { chunk: OpenAIStreamChunkSchema },
-    );
-
-    // Yield text chunks as they arrive
-    for await (const chunk of stream) {
-      const content = chunk.choices[0]?.delta?.content;
-      if (content) {
-        yield { type: "text" as const, text: content };
-      }
-    }
-  },
-});
-```
-
-#### Streaming Chunk Structure
-
-OpenAI's streaming chunks have this structure:
-
-```typescript
-{
-  id: "chatcmpl-...",
-  object: "chat.completion.chunk",
-  created: 1234567890,
-  model: "gpt-4",
-  choices: [{
-    index: 0,
-    delta: {
-      role: "assistant",  // Only in first chunk
-      content: "Hello"    // Incremental text
-    },
-    finish_reason: null   // "stop" in final chunk
-  }]
-}
-```
-
 ## 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.
@@ -319,7 +259,7 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 
 ### No Specialized Methods
 
-The OpenAI client only provides `apiRequest()`. There are no SDK-specific methods:
+The OpenAI client only provides `apiRequest()`. There are no other specialized methods:
 
 ```typescript
 // WRONG - These methods do not exist
@@ -328,7 +268,7 @@ await openai.createEmbedding({ ... });
 
 // CORRECT - Use apiRequest for all operations
 await ctx.integrations.ai.apiRequest(
-  { method: "POST", path: "/v1/chat/completions", body: { ... } },
+  { method: "POST", path: "/chat/completions", body: { ... } },
   { response: ResponseSchema }
 );
 ```
@@ -341,13 +281,13 @@ You must always provide a response schema:
 // WRONG - Missing response schema
 const result = await ctx.integrations.ai.apiRequest({
   method: "POST",
-  path: "/v1/chat/completions",
+  path: "/chat/completions",
   body: { ... },
 });
 
 // CORRECT - Include response schema
 const result = await ctx.integrations.ai.apiRequest(
-  { method: "POST", path: "/v1/chat/completions", body: { ... } },
+  { method: "POST", path: "/chat/completions", body: { ... } },
   { response: ChatCompletionResponseSchema }
 );
 ```
@@ -389,7 +329,7 @@ Some features require beta headers:
 const result = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
-    path: "/v1/assistants",
+    path: "/assistants",
     body: { ... },
     headers: {
       "OpenAI-Beta": "assistants=v2",
@@ -419,7 +359,7 @@ async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
 
 const result = await withRetry(() =>
   ctx.integrations.ai.apiRequest(
-    { method: "POST", path: "/v1/chat/completions", body: { ... } },
+    { method: "POST", path: "/chat/completions", body: { ... } },
     { response: ChatCompletionResponseSchema }
   )
 );
@@ -441,7 +381,7 @@ Be aware of model token limits:
 const result = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "gpt-4",
       messages: [...],
@@ -455,11 +395,11 @@ const result = await ctx.integrations.ai.apiRequest(
 ## Error Handling
 
 ```typescript
-import { RestApiValidationError, StreamChunkValidationError } from "@superblocksteam/sdk-api";
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
   const result = await ctx.integrations.ai.apiRequest(
-    { method: "POST", path: "/v1/chat/completions", body: { ... } },
+    { method: "POST", path: "/chat/completions", body: { ... } },
     { response: ChatCompletionResponseSchema }
   );
 } catch (error) {
@@ -468,18 +408,6 @@ try {
     console.error("Actual response:", error.details.data);
   }
 }
-
-// For streaming requests
-try {
-  for await (const chunk of stream) {
-    // Process chunk
-  }
-} catch (error) {
-  if (error instanceof StreamChunkValidationError) {
-    console.error("Chunk validation failed at index:", error.details.chunkIndex);
-    console.error("Raw chunk:", error.details.chunk);
-  }
-}
 ```
 
 ## API Reference

package/src/integrations/openai_v2/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";
 
 /**
  * OpenAI client for AI model interactions.
  *
- * Provides the generic apiRequest() method for any OpenAI API endpoint,
- * and streamApiRequest() for streaming responses.
+ * Provides the generic apiRequest() method for any OpenAI API endpoint.
  * Use this to interact with OpenAI's chat completions, embeddings, and other endpoints.
  *
  * @example
@@ -45,7 +41,7 @@ import type {
  * const completion = await ctx.integrations.ai.apiRequest(
  *   {
  *     method: 'POST',
- *     path: '/v1/chat/completions',
+ *     path: '/chat/completions',
  *     body: {
  *       model: 'gpt-4',
  *       messages: [{ role: 'user', content: 'Hello!' }],
@@ -57,30 +53,9 @@ import type {
  *   }
  * );
  *
- * // Or use streaming for real-time responses
- * const stream = openai.streamApiRequest(
- *   {
- *     method: 'POST',
- *     path: '/v1/chat/completions',
- *     body: {
- *       model: 'gpt-4',
- *       stream: true,
- *       messages: [{ role: 'user', content: 'Hello!' }],
- *     },
- *   },
- *   { chunk: StreamChunkSchema }
- * );
- *
- * for await (const chunk of stream) {
- *   // Handle streaming chunks
- * }
  * ```
  */
 export interface OpenAIClient
-  extends
-    BaseIntegrationClient,
-    SupportsApiRequest,
-    SupportsStreamingApiRequest {
+  extends BaseIntegrationClient, SupportsApiRequest {
   // apiRequest() method inherited from SupportsApiRequest
-  // streamApiRequest() method inherited from SupportsStreamingApiRequest
 }