@superblocksteam/sdk-api 0.0.4

package/src/integrations/openai_v2/README.md

@@ -0,0 +1,490 @@
+# OpenAI Client
+
+Interact with OpenAI's APIs for chat completions, embeddings, image generation, and more.
+
+## 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   |
+
+## Usage
+
+### Chat Completion
+
+```typescript
+import { api, z, openai } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_OPENAI = "a1b2c3d4-5678-90ab-cdef-333333333333";
+
+const ChatCompletionResponseSchema = z.object({
+  id: z.string(),
+  object: z.literal("chat.completion"),
+  created: z.number(),
+  model: z.string(),
+  choices: z.array(
+    z.object({
+      index: z.number(),
+      message: z.object({
+        role: z.string(),
+        content: z.string().nullable(),
+      }),
+      finish_reason: z.string().nullable(),
+    }),
+  ),
+  usage: z.object({
+    prompt_tokens: z.number(),
+    completion_tokens: z.number(),
+    total_tokens: z.number(),
+  }),
+});
+
+export default api({
+  name: "UopenaiUv2Example",
+  integrations: {
+    ai: openai(PROD_OPENAI),
+  },
+  input: z.object({
+    prompt: z.string(),
+  }),
+  output: z.object({
+    response: z.string(),
+  }),
+  async run(ctx, { prompt }) {
+    const result = await ctx.integrations.ai.apiRequest(
+      {
+        method: "POST",
+        path: "/v1/chat/completions",
+        body: {
+          model: "gpt-4",
+          messages: [
+            { role: "system", content: "You are a helpful assistant." },
+            { role: "user", content: prompt },
+          ],
+          temperature: 0.7,
+        },
+      },
+      { response: ChatCompletionResponseSchema },
+    );
+
+    return { response: result.choices[0]?.message.content ?? "" };
+  },
+});
+```
+
+### Chat Completion with Function Calling
+
+```typescript
+const FunctionCallResponseSchema = z.object({
+  id: z.string(),
+  choices: z.array(
+    z.object({
+      message: z.object({
+        role: z.string(),
+        content: z.string().nullable(),
+        tool_calls: z
+          .array(
+            z.object({
+              id: z.string(),
+              type: z.literal("function"),
+              function: z.object({
+                name: z.string(),
+                arguments: z.string(), // JSON string
+              }),
+            }),
+          )
+          .optional(),
+      }),
+      finish_reason: z.string().nullable(),
+    }),
+  ),
+});
+
+const result = await ctx.integrations.ai.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/chat/completions",
+    body: {
+      model: "gpt-4",
+      messages: [
+        { role: "user", content: "What's the weather in San Francisco?" },
+      ],
+      tools: [
+        {
+          type: "function",
+          function: {
+            name: "get_weather",
+            description: "Get the current weather for a location",
+            parameters: {
+              type: "object",
+              properties: {
+                location: { type: "string", description: "City name" },
+              },
+              required: ["location"],
+            },
+          },
+        },
+      ],
+    },
+  },
+  { response: FunctionCallResponseSchema },
+);
+
+const toolCall = result.choices[0]?.message.tool_calls?.[0];
+if (toolCall) {
+  const args = JSON.parse(toolCall.function.arguments);
+  console.log(`Function: ${toolCall.function.name}, Args:`, args);
+}
+```
+
+### Generate Embeddings
+
+```typescript
+const EmbeddingsResponseSchema = z.object({
+  object: z.literal("list"),
+  data: z.array(
+    z.object({
+      object: z.literal("embedding"),
+      index: z.number(),
+      embedding: z.array(z.number()),
+    }),
+  ),
+  model: z.string(),
+  usage: z.object({
+    prompt_tokens: z.number(),
+    total_tokens: z.number(),
+  }),
+});
+
+const embeddings = await ctx.integrations.ai.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/embeddings",
+    body: {
+      model: "text-embedding-3-small",
+      input: ["Hello world", "How are you?"],
+    },
+  },
+  { response: EmbeddingsResponseSchema },
+);
+
+embeddings.data.forEach((item) => {
+  console.log(`Index ${item.index}: ${item.embedding.length} dimensions`);
+});
+```
+
+### Image Generation (DALL-E)
+
+```typescript
+const ImageResponseSchema = z.object({
+  created: z.number(),
+  data: z.array(
+    z.object({
+      url: z.string().optional(),
+      b64_json: z.string().optional(),
+      revised_prompt: z.string().optional(),
+    }),
+  ),
+});
+
+const images = await ctx.integrations.ai.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/images/generations",
+    body: {
+      model: "dall-e-3",
+      prompt: "A serene mountain landscape at sunset",
+      n: 1,
+      size: "1024x1024",
+      quality: "standard",
+    },
+  },
+  { response: ImageResponseSchema },
+);
+
+const imageUrl = images.data[0]?.url;
+```
+
+### Text-to-Speech
+
+```typescript
+// Note: Audio endpoints return binary data
+// This example shows the request structure
+const ttsResult = await ctx.integrations.ai.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/audio/speech",
+    body: {
+      model: "tts-1",
+      input: "Hello, how are you today?",
+      voice: "alloy",
+    },
+  },
+  { response: z.unknown() }, // Binary response
+);
+```
+
+### 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.
+
+## Common Pitfalls
+
+### No Specialized Methods
+
+The OpenAI client only provides `apiRequest()`. There are no SDK-specific methods:
+
+```typescript
+// WRONG - These methods do not exist
+await openai.createChatCompletion({ ... });
+await openai.createEmbedding({ ... });
+
+// CORRECT - Use apiRequest for all operations
+await ctx.integrations.ai.apiRequest(
+  { method: "POST", path: "/v1/chat/completions", body: { ... } },
+  { response: ResponseSchema }
+);
+```
+
+### Response Schema is Required
+
+You must always provide a response schema:
+
+```typescript
+// WRONG - Missing response schema
+const result = await ctx.integrations.ai.apiRequest({
+  method: "POST",
+  path: "/v1/chat/completions",
+  body: { ... },
+});
+
+// CORRECT - Include response schema
+const result = await ctx.integrations.ai.apiRequest(
+  { method: "POST", path: "/v1/chat/completions", body: { ... } },
+  { response: ChatCompletionResponseSchema }
+);
+```
+
+### Content Can Be Null
+
+Chat completion content can be `null` when using function calling:
+
+```typescript
+// WRONG - Assumes content is always a string
+const schema = z.object({
+  choices: z.array(
+    z.object({
+      message: z.object({
+        content: z.string(), // Will fail if null
+      }),
+    }),
+  ),
+});
+
+// CORRECT - Allow null content
+const schema = z.object({
+  choices: z.array(
+    z.object({
+      message: z.object({
+        content: z.string().nullable(),
+      }),
+    }),
+  ),
+});
+```
+
+### API Version Headers for Beta Features
+
+Some features require beta headers:
+
+```typescript
+// Using Assistants API (beta)
+const result = await ctx.integrations.ai.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/assistants",
+    body: { ... },
+    headers: {
+      "OpenAI-Beta": "assistants=v2",
+    },
+  },
+  { response: AssistantResponseSchema }
+);
+```
+
+### Handling Rate Limits
+
+OpenAI has rate limits. Consider implementing retry logic:
+
+```typescript
+async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (i === maxRetries - 1) throw error;
+      // Wait with exponential backoff
+      await new Promise((r) => setTimeout(r, Math.pow(2, i) * 1000));
+    }
+  }
+  throw new Error("Max retries exceeded");
+}
+
+const result = await withRetry(() =>
+  ctx.integrations.ai.apiRequest(
+    { method: "POST", path: "/v1/chat/completions", body: { ... } },
+    { response: ChatCompletionResponseSchema }
+  )
+);
+```
+
+### Token Limits
+
+Be aware of model token limits:
+
+| Model         | Max Tokens |
+| ------------- | ---------- |
+| gpt-4         | 8,192      |
+| gpt-4-32k     | 32,768     |
+| gpt-4-turbo   | 128,000    |
+| gpt-3.5-turbo | 16,385     |
+
+```typescript
+// Set max_tokens to control response length
+const result = await ctx.integrations.ai.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/chat/completions",
+    body: {
+      model: "gpt-4",
+      messages: [...],
+      max_tokens: 1000, // Limit response tokens
+    },
+  },
+  { response: ChatCompletionResponseSchema }
+);
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError, StreamChunkValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await ctx.integrations.ai.apiRequest(
+    { method: "POST", path: "/v1/chat/completions", body: { ... } },
+    { response: ChatCompletionResponseSchema }
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Response validation failed:", error.details.zodError);
+    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
+
+- [OpenAI API Reference](https://platform.openai.com/docs/api-reference)
+- [Chat Completions](https://platform.openai.com/docs/api-reference/chat)
+- [Embeddings](https://platform.openai.com/docs/api-reference/embeddings)
+- [Images](https://platform.openai.com/docs/api-reference/images)

package/src/integrations/openai_v2/client.ts

@@ -0,0 +1,24 @@
+/**
+ * OpenAI client implementation.
+ *
+ * Uses the proto-generated REST API Integration Plugin type from @superblocksteam/types.
+ * OpenAI integrations use the REST API Integration plugin under the hood.
+ */
+
+import { RestApiIntegrationClient } from "../base/index.js";
+import type { OpenAIClient } from "./types.js";
+
+/**
+ * Internal implementation of OpenAIClient.
+ *
+ * Extends RestApiIntegrationClient to inherit the generic apiRequest() method.
+ * This implementation communicates with the orchestrator to execute
+ * OpenAI API calls. At runtime, the orchestrator handles authentication
+ * and API request execution.
+ */
+export class OpenAIClientImpl
+  extends RestApiIntegrationClient
+  implements OpenAIClient {
+  // Inherits: name, pluginId, config, executeQuery, createParam(), apiRequest()
+  // Can add OpenAI-specific methods here in the future if needed
+}

package/src/integrations/openai_v2/index.ts

@@ -0,0 +1,2 @@
+export { OpenAIClientImpl } from "./client.js";
+export type { OpenAIClient } from "./types.js";

package/src/integrations/openai_v2/types.ts

@@ -0,0 +1,86 @@
+/**
+ * OpenAI client types.
+ */
+
+import type { BaseIntegrationClient } from "../../types.js";
+import type {
+  SupportsApiRequest,
+  SupportsStreamingApiRequest,
+} 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.
+ * Use this to interact with OpenAI's chat completions, embeddings, and other endpoints.
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * // Declare in api(): integrations: { ai: openai(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.ai
+ *
+ * // Define request and response schemas
+ * const ChatCompletionRequestSchema = z.object({
+ *   model: z.string(),
+ *   messages: z.array(z.object({
+ *     role: z.string(),
+ *     content: z.string(),
+ *   })),
+ * });
+ *
+ * const CompletionSchema = z.object({
+ *   id: z.string(),
+ *   choices: z.array(z.object({
+ *     message: z.object({
+ *       role: z.string(),
+ *       content: z.string(),
+ *     }),
+ *   })),
+ * });
+ *
+ * // Make a chat completion request
+ * const completion = await ctx.integrations.ai.apiRequest(
+ *   {
+ *     method: 'POST',
+ *     path: '/v1/chat/completions',
+ *     body: {
+ *       model: 'gpt-4',
+ *       messages: [{ role: 'user', content: 'Hello!' }],
+ *     },
+ *   },
+ *   {
+ *     body: ChatCompletionRequestSchema,
+ *     response: CompletionSchema,
+ *   }
+ * );
+ *
+ * // 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 {
+  // apiRequest() method inherited from SupportsApiRequest
+  // streamApiRequest() method inherited from SupportsStreamingApiRequest
+}