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

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
 }

package/src/integrations/oracledb/README.md

@@ -39,7 +39,7 @@ export default api({
   }),
   async run(ctx, { status }) {
     const users = await ctx.integrations.oracledb.query(
-      "SELECT ID, NAME, EMAIL, CREATED_AT FROM USERS WHERE STATUS = $1",
+      "SELECT ID, NAME, EMAIL, CREATED_AT FROM USERS WHERE STATUS = :1",
       UserSchema,
       [status],
     );
@@ -54,13 +54,13 @@ export default api({
 ```typescript
 // INSERT
 await ctx.integrations.oracledb.execute(
-  "INSERT INTO USERS (NAME, EMAIL) VALUES ($1, $2)",
+  "INSERT INTO USERS (NAME, EMAIL) VALUES (:1, :2)",
   ["John Doe", "john@example.com"],
 );
 
 // UPDATE
 const updateResult = await ctx.integrations.oracledb.execute(
-  "UPDATE USERS SET LAST_LOGIN = SYSDATE WHERE ID = $1",
+  "UPDATE USERS SET LAST_LOGIN = SYSDATE WHERE ID = :1",
   [userId],
 );
 console.log(`Updated ${updateResult.rowCount} rows`);

package/src/integrations/oracledb/types.ts

@@ -25,7 +25,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const users = await oracledb.query(
- *   'SELECT * FROM users WHERE status = $1',
+ *   'SELECT * FROM users WHERE status = :1',
  *   UserSchema,
  *   ['active']
  * );
@@ -35,7 +35,7 @@ export interface OracleDBClient 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 :1, :2, etc. for parameters)
    * @param schema - Zod schema to validate the query results
    * @param params - Optional query parameters
    * @returns Promise resolving to validated query results

package/src/integrations/pagerduty/README.md

@@ -13,7 +13,7 @@ Create incidents, manage services, and interact with PagerDuty's incident manage
 ### Create an Incident
 
 ```typescript
-import { api, z, pagerduty } from "@superblocksteam/sdk-api";
+import { api, z, pagerDuty } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_PAGERDUTY = "a1b2c3d4-5678-90ab-cdef-pagerdu00001";
@@ -52,7 +52,7 @@ const CreateIncidentResponseSchema = z.object({
 
 export default api({
   integrations: {
-    pagerduty: pagerduty(PROD_PAGERDUTY),
+    pagerduty: pagerDuty(PROD_PAGERDUTY),
   },
   name: "PagerDutyExample",
   input: z.object({

package/src/integrations/perplexity/README.md

@@ -231,10 +231,11 @@ if (sources.length === 0) {
 
 ### Model Naming Convention
 
-Perplexity models follow a specific naming pattern:
+Perplexity models follow a specific naming pattern. Note that available models change over time — check the [Perplexity model cards](https://docs.perplexity.ai/docs/model-cards) for current options:
 
 ```typescript
 // Pattern: llama-3.1-sonar-{size}-{context}-{type}
+// These are examples — verify current model names in the Perplexity docs
 const models = [
   "llama-3.1-sonar-small-128k-online", // Small, online search
   "llama-3.1-sonar-small-128k-chat", // Small, no search

package/src/integrations/registry.test.ts

@@ -13,9 +13,8 @@ describe("integration registry", () => {
     expect(isPluginSupported(SUPPORTED_PLUGINS.snowflakecortex)).toBe(true);
   });
 
-  it("creates a SnowflakeCortex client with streaming support", () => {
+  it("creates a SnowflakeCortex client", () => {
     const executeQuery = vi.fn();
-    const executeStreamingQuery = vi.fn();
 
     const client = createClient({
       config: {
@@ -25,7 +24,6 @@ describe("integration registry", () => {
         configuration: {},
       },
       executeQuery,
-      executeStreamingQuery,
     });
 
     expect(client).toBeInstanceOf(SnowflakeCortexClientImpl);