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

package/src/integrations/graphql/types.ts

@@ -2,8 +2,8 @@
  * GraphQL client types.
  */
 
-import type { BaseIntegrationClient } from '../../types.js';
-import type { z } from 'zod';
+import type { BaseIntegrationClient } from "../../types.js";
+import type { z } from "zod";
 
 /**
  * GraphQL client for executing queries and mutations.
@@ -13,7 +13,8 @@ import type { z } from 'zod';
  *
  * @example
  * ```typescript
- * const graphql = ctx.graphql('Production GraphQL');
+ * // Declare in api(): integrations: { graphql: graphql(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.graphql
  *
  * // Execute a query
  * // Schema validates the full GraphQL response (including data wrapper)
@@ -87,7 +88,7 @@ export interface GraphQLClient extends BaseIntegrationClient {
   query<TResponse>(
     query: string,
     schema: { response: z.ZodSchema<TResponse> },
-    variables?: Record<string, unknown>
+    variables?: Record<string, unknown>,
   ): Promise<TResponse>;
 
   /**
@@ -116,6 +117,6 @@ export interface GraphQLClient extends BaseIntegrationClient {
   mutation<TResponse>(
     mutation: string,
     schema: { response: z.ZodSchema<TResponse> },
-    variables?: Record<string, unknown>
+    variables?: Record<string, unknown>,
   ): Promise<TResponse>;
 }

package/src/integrations/groq/README.md

@@ -4,8 +4,8 @@ Interact with Groq's ultra-fast inference API for LLM chat completions with low
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                      |
+| ----------------------------- | ------------------------------------------------ |
 | `apiRequest(options, schema)` | Make any Groq API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Interact with Groq's ultra-fast inference API for LLM chat completions with low
 ### Chat Completion
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, groq } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_GROQ = "a1b2c3d4-5678-90ab-cdef-groq00000001";
@@ -31,7 +31,7 @@ const ChatCompletionResponseSchema = z.object({
         content: z.string(),
       }),
       finish_reason: z.string(),
-    })
+    }),
   ),
   usage: z.object({
     prompt_tokens: z.number(),
@@ -45,6 +45,9 @@ const ChatCompletionResponseSchema = z.object({
 });
 
 export default api({
+  integrations: {
+    groq: groq(PROD_GROQ),
+  },
   name: "GroqExample",
   input: z.object({
     prompt: z.string(),
@@ -53,9 +56,7 @@ export default api({
     response: z.string(),
   }),
   async run(ctx, { prompt }) {
-    const groq = ctx.groq(PROD_GROQ);
-
-    const result = await groq.apiRequest(
+    const result = await ctx.integrations.groq.apiRequest(
       {
         method: "POST",
         path: "/openai/v1/chat/completions",
@@ -67,7 +68,7 @@ export default api({
           ],
         },
       },
-      { response: ChatCompletionResponseSchema }
+      { response: ChatCompletionResponseSchema },
     );
 
     return { response: result.choices[0]?.message.content ?? "" };
@@ -79,7 +80,7 @@ export default api({
 
 ```typescript
 // Llama 3.1 70B - Best balance of speed and quality
-const llama70b = await groq.apiRequest(
+const llama70b = await ctx.integrations.groq.apiRequest(
   {
     method: "POST",
     path: "/openai/v1/chat/completions",
@@ -88,11 +89,11 @@ const llama70b = await groq.apiRequest(
       messages: [{ role: "user", content: "Hello" }],
     },
   },
-  { response: ChatCompletionResponseSchema }
+  { response: ChatCompletionResponseSchema },
 );
 
 // Llama 3.1 8B - Fastest, good for simple tasks
-const llama8b = await groq.apiRequest(
+const llama8b = await ctx.integrations.groq.apiRequest(
   {
     method: "POST",
     path: "/openai/v1/chat/completions",
@@ -101,11 +102,11 @@ const llama8b = await groq.apiRequest(
       messages: [{ role: "user", content: "Hello" }],
     },
   },
-  { response: ChatCompletionResponseSchema }
+  { response: ChatCompletionResponseSchema },
 );
 
 // Mixtral 8x7B - Good for code and reasoning
-const mixtral = await groq.apiRequest(
+const mixtral = await ctx.integrations.groq.apiRequest(
   {
     method: "POST",
     path: "/openai/v1/chat/completions",
@@ -114,7 +115,7 @@ const mixtral = await groq.apiRequest(
       messages: [{ role: "user", content: "Hello" }],
     },
   },
-  { response: ChatCompletionResponseSchema }
+  { response: ChatCompletionResponseSchema },
 );
 ```
 
@@ -137,24 +138,22 @@ const ToolCallResponseSchema = z.object({
                 name: z.string(),
                 arguments: z.string(),
               }),
-            })
+            }),
           )
           .optional(),
       }),
       finish_reason: z.string(),
-    })
+    }),
   ),
 });
 
-const result = await groq.apiRequest(
+const result = await ctx.integrations.groq.apiRequest(
   {
     method: "POST",
     path: "/openai/v1/chat/completions",
     body: {
       model: "llama-3.1-70b-versatile",
-      messages: [
-        { role: "user", content: "What's the weather in Tokyo?" },
-      ],
+      messages: [{ role: "user", content: "What's the weather in Tokyo?" }],
       tools: [
         {
           type: "function",
@@ -174,7 +173,7 @@ const result = await groq.apiRequest(
       tool_choice: "auto",
     },
   },
-  { response: ToolCallResponseSchema }
+  { response: ToolCallResponseSchema },
 );
 
 const toolCall = result.choices[0]?.message.tool_calls?.[0];
@@ -194,11 +193,11 @@ const JSONResponseSchema = z.object({
       message: z.object({
         content: z.string(), // Will be valid JSON
       }),
-    })
+    }),
   ),
 });
 
-const result = await groq.apiRequest(
+const result = await ctx.integrations.groq.apiRequest(
   {
     method: "POST",
     path: "/openai/v1/chat/completions",
@@ -214,7 +213,7 @@ const result = await groq.apiRequest(
       response_format: { type: "json_object" },
     },
   },
-  { response: JSONResponseSchema }
+  { response: JSONResponseSchema },
 );
 
 const data = JSON.parse(result.choices[0]?.message.content ?? "{}");
@@ -230,7 +229,7 @@ await groq.chat({ ... });
 await groq.createChatCompletion({ ... });
 
 // CORRECT - Use apiRequest
-await groq.apiRequest(
+await ctx.integrations.groq.apiRequest(
   { method: "POST", path: "/openai/v1/chat/completions", body: { ... } },
   { response: ChatCompletionResponseSchema }
 );
@@ -242,13 +241,13 @@ Groq uses OpenAI-compatible endpoints with `/openai/v1/` prefix:
 
 ```typescript
 // WRONG - Missing /openai prefix
-await groq.apiRequest(
+await ctx.integrations.groq.apiRequest(
   { method: "POST", path: "/v1/chat/completions", body: { ... } },
   { response: schema }
 );
 
 // CORRECT - Include /openai prefix
-await groq.apiRequest(
+await ctx.integrations.groq.apiRequest(
   { method: "POST", path: "/openai/v1/chat/completions", body: { ... } },
   { response: schema }
 );
@@ -258,12 +257,12 @@ await groq.apiRequest(
 
 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 |
+| 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
@@ -278,7 +277,7 @@ const body = {
 Groq has rate limits based on tokens per minute. Monitor usage:
 
 ```typescript
-const result = await groq.apiRequest(
+const result = await ctx.integrations.groq.apiRequest(
   { method: "POST", path: "/openai/v1/chat/completions", body: { ... } },
   { response: ChatCompletionResponseSchema }
 );
@@ -293,7 +292,7 @@ console.log("Completion time:", result.usage.completion_time, "seconds");
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await groq.apiRequest(
+  const result = await ctx.integrations.groq.apiRequest(
     { method: "POST", path: "/openai/v1/chat/completions", body: { ... } },
     { response: ChatCompletionResponseSchema }
   );

package/src/integrations/groq/client.ts

@@ -5,8 +5,8 @@
  * Groq integrations use the REST API Integration plugin under the hood.
  */
 
-import { RestApiIntegrationClient } from '../base/index.js';
-import type { GroqClient } from './types.js';
+import { RestApiIntegrationClient } from "../base/index.js";
+import type { GroqClient } from "./types.js";
 
 /**
  * Internal implementation of GroqClient.
@@ -16,6 +16,8 @@ import type { GroqClient } from './types.js';
  * Groq API calls. At runtime, the orchestrator handles authentication
  * and API request execution.
  */
-export class GroqClientImpl extends RestApiIntegrationClient implements GroqClient {
+export class GroqClientImpl
+  extends RestApiIntegrationClient
+  implements GroqClient {
   // Inherits: name, pluginId, config, executeQuery, apiRequest()
 }

package/src/integrations/groq/index.ts

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

package/src/integrations/groq/types.ts

@@ -2,8 +2,8 @@
  * Groq client types.
  */
 
-import type { BaseIntegrationClient } from '../../types.js';
-import type { SupportsApiRequest } from '../base/index.js';
+import type { BaseIntegrationClient } from "../../types.js";
+import type { SupportsApiRequest } from "../base/index.js";
 
 /**
  * Groq client for API interactions.
@@ -13,7 +13,8 @@ import type { SupportsApiRequest } from '../base/index.js';
  *
  * @example
  * ```typescript
- * const groq = ctx.groq('My Groq');
+ * // Declare in api(): integrations: { groq: groq(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.groq
  *
  * // Make API requests
  * const ResponseSchema = z.object({

package/src/integrations/gsheets/README.md

@@ -4,38 +4,43 @@ Interact with Google Sheets with full type safety and runtime validation.
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                       |
+| ----------------------------- | --------------------------------- |
 | `run(action, schema, params)` | Execute a Google Sheets operation |
 
 ## Actions
 
-| Action | Description |
-| ------ | ----------- |
-| `READ_SPREADSHEET` | Read all data from a sheet |
-| `READ_SPREADSHEET_RANGE` | Read data from a range |
-| `APPEND_SPREADSHEET` | Append rows to a sheet |
+| Action                    | Description                        |
+| ------------------------- | ---------------------------------- |
+| `READ_SPREADSHEET`        | Read all data from a sheet         |
+| `READ_SPREADSHEET_RANGE`  | Read data from a range             |
+| `APPEND_SPREADSHEET`      | Append rows to a sheet             |
 | `CREATE_SPREADSHEET_ROWS` | Create rows at a specific position |
-| `CLEAR_SPREADSHEET` | Clear all data from a sheet |
-| `CREATE_WORKSHEET` | Add a new sheet to a spreadsheet |
+| `CLEAR_SPREADSHEET`       | Clear all data from a sheet        |
+| `CREATE_WORKSHEET`        | Add a new sheet to a spreadsheet   |
 
 ## Usage
 
 ### Read Spreadsheet Data
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, gsheets } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_GSHEETS = "a1b2c3d4-5678-90ab-cdef-gsheets00001";
 
-const RowSchema = z.array(z.object({
-  name: z.string(),
-  email: z.string(),
-  status: z.string(),
-}));
+const RowSchema = z.array(
+  z.object({
+    name: z.string(),
+    email: z.string(),
+    status: z.string(),
+  }),
+);
 
 export default api({
+  integrations: {
+    sheets: gsheets(PROD_GSHEETS),
+  },
   name: "GoogleSheetsExample",
   input: z.object({
     spreadsheetId: z.string(),
@@ -44,14 +49,16 @@ export default api({
     rows: RowSchema,
   }),
   async run(ctx, { spreadsheetId }) {
-    const sheets = ctx.gsheets(PROD_GSHEETS);
-
-    const rows = await sheets.run("READ_SPREADSHEET_RANGE", RowSchema, {
-      spreadsheetId: spreadsheetId,
-      sheetTitle: "Sheet1",
-      range: "A1:C100",
-      extractFirstRowHeader: true,
-    });
+    const rows = await ctx.integrations.sheets.run(
+      "READ_SPREADSHEET_RANGE",
+      RowSchema,
+      {
+        spreadsheetId: spreadsheetId,
+        sheetTitle: "Sheet1",
+        range: "A1:C100",
+        extractFirstRowHeader: true,
+      },
+    );
 
     return { rows };
   },
@@ -61,7 +68,7 @@ export default api({
 ### Append Rows
 
 ```typescript
-await sheets.run("APPEND_SPREADSHEET", z.any(), {
+await ctx.integrations.sheets.run("APPEND_SPREADSHEET", z.any(), {
   spreadsheetId: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
   sheetTitle: "Sheet1",
   data: JSON.stringify([
@@ -74,7 +81,7 @@ await sheets.run("APPEND_SPREADSHEET", z.any(), {
 ### Create Rows at Position
 
 ```typescript
-await sheets.run("CREATE_SPREADSHEET_ROWS", z.any(), {
+await ctx.integrations.sheets.run("CREATE_SPREADSHEET_ROWS", z.any(), {
   spreadsheetId: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
   sheetTitle: "Sheet1",
   rowNumber: "5",
@@ -87,7 +94,7 @@ await sheets.run("CREATE_SPREADSHEET_ROWS", z.any(), {
 ### Clear Sheet
 
 ```typescript
-await sheets.run("CLEAR_SPREADSHEET", z.any(), {
+await ctx.integrations.sheets.run("CLEAR_SPREADSHEET", z.any(), {
   spreadsheetId: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
   sheetTitle: "Sheet1",
   preserveHeaderRow: true,
@@ -97,7 +104,7 @@ await sheets.run("CLEAR_SPREADSHEET", z.any(), {
 ### Create New Worksheet
 
 ```typescript
-await sheets.run("CREATE_WORKSHEET", z.any(), {
+await ctx.integrations.sheets.run("CREATE_WORKSHEET", z.any(), {
   spreadsheetId: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
   addSheet: {
     sheetTitle: "New Sheet",
@@ -109,18 +116,18 @@ await sheets.run("CREATE_WORKSHEET", z.any(), {
 
 ## Parameters
 
-| Parameter | Type | Description |
-| --------- | ---- | ----------- |
-| `spreadsheetId` | `string` | The spreadsheet ID (required) |
-| `sheetTitle` | `string` | Sheet name/title |
-| `range` | `string` | Range in A1 notation (e.g., "A1:D10") |
-| `data` | `string` | JSON string of data to write |
-| `extractFirstRowHeader` | `boolean` | Treat first row as headers |
-| `headerRowNumber` | `string` | Header row number |
-| `preserveHeaderRow` | `boolean` | Preserve headers when clearing |
-| `includeHeaderRow` | `boolean` | Include headers in output |
-| `rowNumber` | `string` | Row number for single row operations |
-| `addSheet` | `object` | Config for CREATE_WORKSHEET action |
+| Parameter               | Type      | Description                           |
+| ----------------------- | --------- | ------------------------------------- |
+| `spreadsheetId`         | `string`  | The spreadsheet ID (required)         |
+| `sheetTitle`            | `string`  | Sheet name/title                      |
+| `range`                 | `string`  | Range in A1 notation (e.g., "A1:D10") |
+| `data`                  | `string`  | JSON string of data to write          |
+| `extractFirstRowHeader` | `boolean` | Treat first row as headers            |
+| `headerRowNumber`       | `string`  | Header row number                     |
+| `preserveHeaderRow`     | `boolean` | Preserve headers when clearing        |
+| `includeHeaderRow`      | `boolean` | Include headers in output             |
+| `rowNumber`             | `string`  | Row number for single row operations  |
+| `addSheet`              | `object`  | Config for CREATE_WORKSHEET action    |
 
 ## Common Pitfalls
 
@@ -142,23 +149,30 @@ The `data` parameter expects a JSON string:
 
 ```typescript
 // CORRECT
-data: JSON.stringify([{ name: "John", email: "john@example.com" }])
+data: JSON.stringify([{ name: "John", email: "john@example.com" }]);
 
 // WRONG
-data: [{ name: "John", email: "john@example.com" }]
+data: [{ name: "John", email: "john@example.com" }];
 ```
 
 ## Error Handling
 
 ```typescript
-import { RestApiValidationError, IntegrationError } from "@superblocksteam/sdk-api";
+import {
+  RestApiValidationError,
+  IntegrationError,
+} from "@superblocksteam/sdk-api";
 
 try {
-  const rows = await sheets.run("READ_SPREADSHEET_RANGE", RowSchema, {
-    spreadsheetId: "...",
-    sheetTitle: "Sheet1",
-    range: "A1:C100",
-  });
+  const rows = await ctx.integrations.sheets.run(
+    "READ_SPREADSHEET_RANGE",
+    RowSchema,
+    {
+      spreadsheetId: "...",
+      sheetTitle: "Sheet1",
+      range: "A1:C100",
+    },
+  );
 } catch (error) {
   if (error instanceof RestApiValidationError) {
     console.error("Validation failed:", error.details.zodError);

package/src/integrations/gsheets/client.ts

@@ -4,19 +4,25 @@
  * Uses the native Google Sheets plugin type from @superblocksteam/types.
  */
 
-import type { z } from 'zod';
-import type { PartialMessage } from '@bufbuild/protobuf';
-import type { Plugin as GSheetsPlugin } from '@superblocksteam/types/dist/src/plugins/gsheets/v1/plugin_pb';
-import type { IntegrationConfig, IntegrationClientImpl } from '../types.js';
-import type { QueryExecutor } from '../registry.js';
-import { RestApiValidationError } from '../../errors.js';
-import { IntegrationError } from '../../runtime/errors.js';
-import type { GoogleSheetsClient, GoogleSheetsAction, GoogleSheetsParams } from './types.js';
+import type { z } from "zod";
+import type { PartialMessage } from "@bufbuild/protobuf";
+import type { Plugin as GSheetsPlugin } from "@superblocksteam/types/dist/src/plugins/gsheets/v1/plugin_pb";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
+import type { QueryExecutor } from "../registry.js";
+import { RestApiValidationError } from "../../errors.js";
+import { IntegrationError } from "../../runtime/errors.js";
+import type {
+  GoogleSheetsClient,
+  GoogleSheetsAction,
+  GoogleSheetsParams,
+} from "./types.js";
 
 /**
  * Internal implementation of GoogleSheetsClient.
  */
-export class GoogleSheetsClientImpl implements GoogleSheetsClient, IntegrationClientImpl {
+export class GoogleSheetsClientImpl
+  implements GoogleSheetsClient, IntegrationClientImpl
+{
   readonly config: IntegrationConfig;
   private readonly executeQuery: QueryExecutor;
 
@@ -94,7 +100,9 @@ export class GoogleSheetsClientImpl implements GoogleSheetsClient, IntegrationCl
     const request = this.buildRequest(action, params);
 
     try {
-      const result = await this.executeQuery(request as Record<string, unknown>);
+      const result = await this.executeQuery(
+        request as Record<string, unknown>,
+      );
 
       // Validate result against schema
       const parseResult = schema.safeParse(result);
@@ -118,7 +126,7 @@ export class GoogleSheetsClientImpl implements GoogleSheetsClient, IntegrationCl
         throw error;
       }
 
-      throw new IntegrationError(this.config.name, 'run', error);
+      throw new IntegrationError(this.config.name, "run", error);
     }
   }
 }

package/src/integrations/gsheets/index.ts

@@ -8,5 +8,5 @@ export type {
   GoogleSheetsClient,
   GoogleSheetsAction,
   GoogleSheetsParams,
-} from './types.js';
-export { GoogleSheetsClientImpl } from './client.js';
+} from "./types.js";
+export { GoogleSheetsClientImpl } from "./client.js";

package/src/integrations/gsheets/types.ts

@@ -2,19 +2,19 @@
  * Google Sheets client types.
  */
 
-import type { z } from 'zod';
-import type { BaseIntegrationClient } from '../../types.js';
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
 
 /**
  * Google Sheets action types.
  */
 export type GoogleSheetsAction =
-  | 'READ_SPREADSHEET'
-  | 'READ_SPREADSHEET_RANGE'
-  | 'APPEND_SPREADSHEET'
-  | 'CREATE_SPREADSHEET_ROWS'
-  | 'CLEAR_SPREADSHEET'
-  | 'CREATE_WORKSHEET';
+  | "READ_SPREADSHEET"
+  | "READ_SPREADSHEET_RANGE"
+  | "APPEND_SPREADSHEET"
+  | "CREATE_SPREADSHEET_ROWS"
+  | "CLEAR_SPREADSHEET"
+  | "CREATE_WORKSHEET";
 
 /**
  * Parameters for Google Sheets operations.
@@ -59,7 +59,8 @@ export interface GoogleSheetsParams {
  *
  * @example
  * ```typescript
- * const sheets = ctx.gsheets('Production Google Sheets');
+ * // Declare in api(): integrations: { sheets: gsheets(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.sheets
  *
  * // Read a range
  * const RowSchema = z.array(z.object({
@@ -67,7 +68,7 @@ export interface GoogleSheetsParams {
  *   email: z.string(),
  * }));
  *
- * const data = await sheets.run('READ_SPREADSHEET_RANGE', RowSchema, {
+ * const data = await ctx.integrations.sheets.run('READ_SPREADSHEET_RANGE', RowSchema, {
  *   spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms',
  *   sheetTitle: 'Sheet1',
  *   range: 'A1:B10',
@@ -75,7 +76,7 @@ export interface GoogleSheetsParams {
  * });
  *
  * // Append rows
- * await sheets.run('APPEND_SPREADSHEET', z.any(), {
+ * await ctx.integrations.sheets.run('APPEND_SPREADSHEET', z.any(), {
  *   spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms',
  *   sheetTitle: 'Sheet1',
  *   data: JSON.stringify([{ name: 'John', email: 'john@example.com' }]),