@superblocksteam/sdk-api 2.0.93 → 2.0.94-next.1

package/src/integrations/openai_v2/README.md

@@ -4,17 +4,17 @@ Interact with OpenAI's APIs for chat completions, embeddings, image generation,
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
-| `apiRequest(options, schema)` | Make any OpenAI API request with schema validation |
-| `streamApiRequest(options, schema)` | Stream responses with real-time chunk validation |
+| Method                              | Description                                        |
+| ----------------------------------- | -------------------------------------------------- |
+| `apiRequest(options, schema)`       | Make any OpenAI API request with schema validation |
+| `streamApiRequest(options, schema)` | Stream responses with real-time chunk validation   |
 
 ## Usage
 
 ### Chat Completion
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, openai } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_OPENAI = "a1b2c3d4-5678-90ab-cdef-333333333333";
@@ -32,7 +32,7 @@ const ChatCompletionResponseSchema = z.object({
         content: z.string().nullable(),
       }),
       finish_reason: z.string().nullable(),
-    })
+    }),
   ),
   usage: z.object({
     prompt_tokens: z.number(),
@@ -43,6 +43,9 @@ const ChatCompletionResponseSchema = z.object({
 
 export default api({
   name: "UopenaiUv2Example",
+  integrations: {
+    ai: openai(PROD_OPENAI),
+  },
   input: z.object({
     prompt: z.string(),
   }),
@@ -50,9 +53,7 @@ export default api({
     response: z.string(),
   }),
   async run(ctx, { prompt }) {
-    const openai = ctx.openai(PROD_OPENAI);
-
-    const result = await openai.apiRequest(
+    const result = await ctx.integrations.ai.apiRequest(
       {
         method: "POST",
         path: "/v1/chat/completions",
@@ -65,7 +66,7 @@ export default api({
           temperature: 0.7,
         },
       },
-      { response: ChatCompletionResponseSchema }
+      { response: ChatCompletionResponseSchema },
     );
 
     return { response: result.choices[0]?.message.content ?? "" };
@@ -92,16 +93,16 @@ const FunctionCallResponseSchema = z.object({
                 name: z.string(),
                 arguments: z.string(), // JSON string
               }),
-            })
+            }),
           )
           .optional(),
       }),
       finish_reason: z.string().nullable(),
-    })
+    }),
   ),
 });
 
-const result = await openai.apiRequest(
+const result = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
     path: "/v1/chat/completions",
@@ -128,7 +129,7 @@ const result = await openai.apiRequest(
       ],
     },
   },
-  { response: FunctionCallResponseSchema }
+  { response: FunctionCallResponseSchema },
 );
 
 const toolCall = result.choices[0]?.message.tool_calls?.[0];
@@ -148,7 +149,7 @@ const EmbeddingsResponseSchema = z.object({
       object: z.literal("embedding"),
       index: z.number(),
       embedding: z.array(z.number()),
-    })
+    }),
   ),
   model: z.string(),
   usage: z.object({
@@ -157,7 +158,7 @@ const EmbeddingsResponseSchema = z.object({
   }),
 });
 
-const embeddings = await openai.apiRequest(
+const embeddings = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
     path: "/v1/embeddings",
@@ -166,7 +167,7 @@ const embeddings = await openai.apiRequest(
       input: ["Hello world", "How are you?"],
     },
   },
-  { response: EmbeddingsResponseSchema }
+  { response: EmbeddingsResponseSchema },
 );
 
 embeddings.data.forEach((item) => {
@@ -184,11 +185,11 @@ const ImageResponseSchema = z.object({
       url: z.string().optional(),
       b64_json: z.string().optional(),
       revised_prompt: z.string().optional(),
-    })
+    }),
   ),
 });
 
-const images = await openai.apiRequest(
+const images = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
     path: "/v1/images/generations",
@@ -200,7 +201,7 @@ const images = await openai.apiRequest(
       quality: "standard",
     },
   },
-  { response: ImageResponseSchema }
+  { response: ImageResponseSchema },
 );
 
 const imageUrl = images.data[0]?.url;
@@ -211,7 +212,7 @@ const imageUrl = images.data[0]?.url;
 ```typescript
 // Note: Audio endpoints return binary data
 // This example shows the request structure
-const ttsResult = await openai.apiRequest(
+const ttsResult = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
     path: "/v1/audio/speech",
@@ -221,7 +222,7 @@ const ttsResult = await openai.apiRequest(
       voice: "alloy",
     },
   },
-  { response: z.unknown() } // Binary response
+  { response: z.unknown() }, // Binary response
 );
 ```
 
@@ -249,7 +250,7 @@ const OpenAIStreamChunkSchema = z.object({
         content: z.string().optional(),
       }),
       finish_reason: z.string().nullable(),
-    })
+    }),
   ),
 });
 
@@ -275,7 +276,7 @@ export default streamingApi({
           ],
         },
       },
-      { chunk: OpenAIStreamChunkSchema }
+      { chunk: OpenAIStreamChunkSchema },
     );
 
     // Yield text chunks as they arrive
@@ -322,7 +323,7 @@ await openai.createChatCompletion({ ... });
 await openai.createEmbedding({ ... });
 
 // CORRECT - Use apiRequest for all operations
-await openai.apiRequest(
+await ctx.integrations.ai.apiRequest(
   { method: "POST", path: "/v1/chat/completions", body: { ... } },
   { response: ResponseSchema }
 );
@@ -334,14 +335,14 @@ You must always provide a response schema:
 
 ```typescript
 // WRONG - Missing response schema
-const result = await openai.apiRequest({
+const result = await ctx.integrations.ai.apiRequest({
   method: "POST",
   path: "/v1/chat/completions",
   body: { ... },
 });
 
 // CORRECT - Include response schema
-const result = await openai.apiRequest(
+const result = await ctx.integrations.ai.apiRequest(
   { method: "POST", path: "/v1/chat/completions", body: { ... } },
   { response: ChatCompletionResponseSchema }
 );
@@ -359,7 +360,7 @@ const schema = z.object({
       message: z.object({
         content: z.string(), // Will fail if null
       }),
-    })
+    }),
   ),
 });
 
@@ -370,7 +371,7 @@ const schema = z.object({
       message: z.object({
         content: z.string().nullable(),
       }),
-    })
+    }),
   ),
 });
 ```
@@ -381,7 +382,7 @@ Some features require beta headers:
 
 ```typescript
 // Using Assistants API (beta)
-const result = await openai.apiRequest(
+const result = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
     path: "/v1/assistants",
@@ -413,7 +414,7 @@ async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
 }
 
 const result = await withRetry(() =>
-  openai.apiRequest(
+  ctx.integrations.ai.apiRequest(
     { method: "POST", path: "/v1/chat/completions", body: { ... } },
     { response: ChatCompletionResponseSchema }
   )
@@ -424,16 +425,16 @@ const result = await withRetry(() =>
 
 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 |
+| 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 openai.apiRequest(
+const result = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
     path: "/v1/chat/completions",
@@ -453,7 +454,7 @@ const result = await openai.apiRequest(
 import { RestApiValidationError, StreamChunkValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await openai.apiRequest(
+  const result = await ctx.integrations.ai.apiRequest(
     { method: "POST", path: "/v1/chat/completions", body: { ... } },
     { response: ChatCompletionResponseSchema }
   );

package/src/integrations/openai_v2/client.ts

@@ -5,8 +5,8 @@
  * OpenAI integrations use the REST API Integration plugin under the hood.
  */
 
-import { RestApiIntegrationClient } from '../base/index.js';
-import type { OpenAIClient } from './types.js';
+import { RestApiIntegrationClient } from "../base/index.js";
+import type { OpenAIClient } from "./types.js";
 
 /**
  * Internal implementation of OpenAIClient.
@@ -16,7 +16,9 @@ import type { OpenAIClient } from './types.js';
  * OpenAI API calls. At runtime, the orchestrator handles authentication
  * and API request execution.
  */
-export class OpenAIClientImpl extends RestApiIntegrationClient implements OpenAIClient {
+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

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

package/src/integrations/openai_v2/types.ts

@@ -2,8 +2,11 @@
  * OpenAI client types.
  */
 
-import type { BaseIntegrationClient } from '../../types.js';
-import type { SupportsApiRequest, SupportsStreamingApiRequest } from '../base/index.js';
+import type { BaseIntegrationClient } from "../../types.js";
+import type {
+  SupportsApiRequest,
+  SupportsStreamingApiRequest,
+} from "../base/index.js";
 
 /**
  * OpenAI client for AI model interactions.
@@ -16,7 +19,8 @@ import type { SupportsApiRequest, SupportsStreamingApiRequest } from '../base/in
  * ```typescript
  * import { z } from 'zod';
  *
- * const openai = ctx.integration('Production OpenAI');
+ * // Declare in api(): integrations: { ai: openai(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.ai
  *
  * // Define request and response schemas
  * const ChatCompletionRequestSchema = z.object({
@@ -38,7 +42,7 @@ import type { SupportsApiRequest, SupportsStreamingApiRequest } from '../base/in
  * });
  *
  * // Make a chat completion request
- * const completion = await openai.apiRequest(
+ * const completion = await ctx.integrations.ai.apiRequest(
  *   {
  *     method: 'POST',
  *     path: '/v1/chat/completions',
@@ -73,7 +77,10 @@ import type { SupportsApiRequest, SupportsStreamingApiRequest } from '../base/in
  * ```
  */
 export interface OpenAIClient
-  extends BaseIntegrationClient, SupportsApiRequest, SupportsStreamingApiRequest {
+  extends
+    BaseIntegrationClient,
+    SupportsApiRequest,
+    SupportsStreamingApiRequest {
   // apiRequest() method inherited from SupportsApiRequest
   // streamApiRequest() method inherited from SupportsStreamingApiRequest
 }

package/src/integrations/oracledb/README.md

@@ -4,17 +4,17 @@ Execute SQL queries and statements against Oracle databases with full type safet
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
-| `query<T>(sql, schema, params?)` | Execute a SELECT query and return validated, typed results |
-| `execute(sql, params?)` | Execute a statement (INSERT, UPDATE, DELETE) and return affected row count |
+| Method                           | Description                                                                |
+| -------------------------------- | -------------------------------------------------------------------------- |
+| `query<T>(sql, schema, params?)` | Execute a SELECT query and return validated, typed results                 |
+| `execute(sql, params?)`          | Execute a statement (INSERT, UPDATE, DELETE) and return affected row count |
 
 ## Usage
 
 ### Basic Query with Schema Validation
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, oracledb } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_ORACLE = "a1b2c3d4-5678-90ab-cdef-oracle000001";
@@ -27,6 +27,9 @@ const UserSchema = z.object({
 });
 
 export default api({
+  integrations: {
+    oracledb: oracledb(PROD_ORACLE),
+  },
   name: "OracleDBExample",
   input: z.object({
     status: z.string(),
@@ -35,12 +38,10 @@ export default api({
     users: z.array(UserSchema),
   }),
   async run(ctx, { status }) {
-    const oracledb = ctx.oracledb(PROD_ORACLE);
-
-    const users = await oracledb.query(
+    const users = await ctx.integrations.oracledb.query(
       "SELECT ID, NAME, EMAIL, CREATED_AT FROM USERS WHERE STATUS = $1",
       UserSchema,
-      [status]
+      [status],
     );
 
     return { users };
@@ -51,24 +52,22 @@ export default api({
 ### Executing INSERT, UPDATE, DELETE Statements
 
 ```typescript
-const oracledb = ctx.oracledb(PROD_ORACLE);
-
 // INSERT
-await oracledb.execute(
+await ctx.integrations.oracledb.execute(
   "INSERT INTO USERS (NAME, EMAIL) VALUES ($1, $2)",
-  ["John Doe", "john@example.com"]
+  ["John Doe", "john@example.com"],
 );
 
 // UPDATE
-const updateResult = await oracledb.execute(
+const updateResult = await ctx.integrations.oracledb.execute(
   "UPDATE USERS SET LAST_LOGIN = SYSDATE WHERE ID = $1",
-  [userId]
+  [userId],
 );
 console.log(`Updated ${updateResult.rowCount} rows`);
 
 // DELETE
-const deleteResult = await oracledb.execute(
-  "DELETE FROM SESSIONS WHERE EXPIRES_AT < SYSDATE"
+const deleteResult = await ctx.integrations.oracledb.execute(
+  "DELETE FROM SESSIONS WHERE EXPIRES_AT < SYSDATE",
 );
 console.log(`Deleted ${deleteResult.rowCount} expired sessions`);
 ```
@@ -82,7 +81,7 @@ const AnalyticsSchema = z.object({
   ORDER_COUNT: z.coerce.number(),
 });
 
-const analytics = await oracledb.query(
+const analytics = await ctx.integrations.oracledb.query(
   `SELECT
     TRUNC(ORDER_DATE) as REPORT_DATE,
     SUM(TOTAL) as TOTAL_SALES,
@@ -91,7 +90,7 @@ const analytics = await oracledb.query(
   WHERE ORDER_DATE >= SYSDATE - 30
   GROUP BY TRUNC(ORDER_DATE)
   ORDER BY REPORT_DATE DESC`,
-  AnalyticsSchema
+  AnalyticsSchema,
 );
 ```
 
@@ -126,7 +125,10 @@ const schema = z.object({
 
 ```typescript
 // CORRECT - Schema is required
-const users = await oracledb.query("SELECT * FROM USERS", UserSchema);
+const users = await ctx.integrations.oracledb.query(
+  "SELECT * FROM USERS",
+  UserSchema,
+);
 ```
 
 ### NULL Handling
@@ -144,7 +146,10 @@ const schema = z.object({
 import { QueryValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const users = await oracledb.query("SELECT * FROM USERS", UserSchema);
+  const users = await ctx.integrations.oracledb.query(
+    "SELECT * FROM USERS",
+    UserSchema,
+  );
 } catch (error) {
   if (error instanceof QueryValidationError) {
     console.error("Row index:", error.details.rowIndex);

package/src/integrations/oracledb/client.ts

@@ -5,20 +5,22 @@
  * runtime validation using Zod schemas.
  */
 
-import type { z } from 'zod';
-import type { PartialMessage } from '@bufbuild/protobuf';
-import type { Plugin as OracleDBPlugin } from '@superblocksteam/types/dist/src/plugins/oracledb/v1/plugin_pb';
-import type { IntegrationConfig, IntegrationClientImpl } from '../types.js';
-import type { QueryExecutor } from '../registry.js';
-import { QueryValidationError } from '../../errors.js';
-import { IntegrationError } from '../../runtime/errors.js';
-import { describeType } from '../utils.js';
-import type { OracleDBClient } from './types.js';
+import type { z } from "zod";
+import type { PartialMessage } from "@bufbuild/protobuf";
+import type { Plugin as OracleDBPlugin } from "@superblocksteam/types/dist/src/plugins/oracledb/v1/plugin_pb";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
+import type { QueryExecutor } from "../registry.js";
+import { QueryValidationError } from "../../errors.js";
+import { IntegrationError } from "../../runtime/errors.js";
+import { describeType } from "../utils.js";
+import type { OracleDBClient } from "./types.js";
 
 /**
  * Internal implementation of the OracleDB client.
  */
-export class OracleDBClientImpl implements OracleDBClient, IntegrationClientImpl {
+export class OracleDBClientImpl
+  implements OracleDBClient, IntegrationClientImpl
+{
   readonly config: IntegrationConfig;
   private readonly executeQuery: QueryExecutor;
 
@@ -73,7 +75,7 @@ export class OracleDBClientImpl implements OracleDBClient, IntegrationClientImpl
       if (!Array.isArray(result)) {
         throw new IntegrationError(
           this.config.name,
-          'query',
+          "query",
           `Expected array result from OracleDB query, got: ${describeType(result)}`,
         );
       }
@@ -109,27 +111,30 @@ export class OracleDBClientImpl implements OracleDBClient, IntegrationClientImpl
         throw error;
       }
 
-      throw new IntegrationError(this.config.name, 'query', error);
+      throw new IntegrationError(this.config.name, "query", error);
     }
   }
 
-  async execute(sql: string, params?: unknown[]): Promise<{ rowCount: number }> {
+  async execute(
+    sql: string,
+    params?: unknown[],
+  ): Promise<{ rowCount: number }> {
     const request = this.buildRequest(sql, params);
 
     try {
       const result = await this.executeQuery(request);
 
       if (
-        typeof result === 'object' &&
+        typeof result === "object" &&
         result !== null &&
-        'rowCount' in result
+        "rowCount" in result
       ) {
         return { rowCount: Number(result.rowCount) || 0 };
       }
 
       return { rowCount: 0 };
     } catch (error) {
-      throw new IntegrationError(this.config.name, 'execute', error);
+      throw new IntegrationError(this.config.name, "execute", error);
     }
   }
 }

package/src/integrations/oracledb/index.ts

@@ -4,5 +4,5 @@
  * @module
  */
 
-export type { OracleDBClient } from './types.js';
-export { OracleDBClientImpl } from './client.js';
+export type { OracleDBClient } from "./types.js";
+export { OracleDBClientImpl } from "./client.js";

package/src/integrations/oracledb/types.ts

@@ -4,15 +4,16 @@
  * Provides typed methods for executing OracleDB queries with runtime validation.
  */
 
-import type { z } from 'zod';
-import type { BaseIntegrationClient } from '../../types.js';
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
 
 /**
  * Client for executing OracleDB queries with type-safe validation.
  *
  * @example
  * ```typescript
- * const oracledb = ctx.oracledb('Production Oracle');
+ * // Declare in api(): integrations: { oracledb: oracledb(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.oracledb
  *
  * // Query with validation
  * const UserSchema = z.object({
@@ -40,7 +41,11 @@ export interface OracleDBClient extends BaseIntegrationClient {
    * @throws {QueryValidationError} If results don't match schema
    * @throws {IntegrationError} If query execution fails
    */
-  query<T>(sql: string, schema: z.ZodSchema<T>, params?: unknown[]): Promise<T[]>;
+  query<T>(
+    sql: string,
+    schema: z.ZodSchema<T>,
+    params?: unknown[],
+  ): Promise<T[]>;
 
   /**
    * Execute a SQL statement (INSERT, UPDATE, DELETE) without output validation.