@superblocksteam/sdk-api 2.0.89-next.0

package/src/integrations/groq/README.md

@@ -0,0 +1,312 @@
+# Groq Client
+
+Interact with Groq's ultra-fast inference API for LLM chat completions with low latency.
+
+## Methods
+
+| Method | Description |
+| ------ | ----------- |
+| `apiRequest(options, schema)` | Make any Groq API request with schema validation |
+
+## Usage
+
+### Chat Completion
+
+```typescript
+import { api, z } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_GROQ = "a1b2c3d4-5678-90ab-cdef-groq00000001";
+
+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(),
+      }),
+      finish_reason: z.string(),
+    })
+  ),
+  usage: z.object({
+    prompt_tokens: z.number(),
+    completion_tokens: z.number(),
+    total_tokens: z.number(),
+    queue_time: z.number().optional(),
+    prompt_time: z.number().optional(),
+    completion_time: z.number().optional(),
+    total_time: z.number().optional(),
+  }),
+});
+
+export default api({
+  name: "GroqExample",
+  input: z.object({
+    prompt: z.string(),
+  }),
+  output: z.object({
+    response: z.string(),
+  }),
+  async run(ctx, { prompt }) {
+    const groq = ctx.groq(PROD_GROQ);
+
+    const result = await groq.apiRequest(
+      {
+        method: "POST",
+        path: "/openai/v1/chat/completions",
+        body: {
+          model: "llama-3.1-70b-versatile",
+          messages: [
+            { role: "system", content: "You are a helpful assistant." },
+            { role: "user", content: prompt },
+          ],
+        },
+      },
+      { response: ChatCompletionResponseSchema }
+    );
+
+    return { response: result.choices[0]?.message.content ?? "" };
+  },
+});
+```
+
+### Using Different Models
+
+```typescript
+// Llama 3.1 70B - Best balance of speed and quality
+const llama70b = await groq.apiRequest(
+  {
+    method: "POST",
+    path: "/openai/v1/chat/completions",
+    body: {
+      model: "llama-3.1-70b-versatile",
+      messages: [{ role: "user", content: "Hello" }],
+    },
+  },
+  { response: ChatCompletionResponseSchema }
+);
+
+// Llama 3.1 8B - Fastest, good for simple tasks
+const llama8b = await groq.apiRequest(
+  {
+    method: "POST",
+    path: "/openai/v1/chat/completions",
+    body: {
+      model: "llama-3.1-8b-instant",
+      messages: [{ role: "user", content: "Hello" }],
+    },
+  },
+  { response: ChatCompletionResponseSchema }
+);
+
+// Mixtral 8x7B - Good for code and reasoning
+const mixtral = await groq.apiRequest(
+  {
+    method: "POST",
+    path: "/openai/v1/chat/completions",
+    body: {
+      model: "mixtral-8x7b-32768",
+      messages: [{ role: "user", content: "Hello" }],
+    },
+  },
+  { response: ChatCompletionResponseSchema }
+);
+```
+
+### Tool Use (Function Calling)
+
+```typescript
+const ToolCallResponseSchema = 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(),
+              }),
+            })
+          )
+          .optional(),
+      }),
+      finish_reason: z.string(),
+    })
+  ),
+});
+
+const result = await 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?" },
+      ],
+      tools: [
+        {
+          type: "function",
+          function: {
+            name: "get_weather",
+            description: "Get current weather for a location",
+            parameters: {
+              type: "object",
+              properties: {
+                location: { type: "string" },
+              },
+              required: ["location"],
+            },
+          },
+        },
+      ],
+      tool_choice: "auto",
+    },
+  },
+  { response: ToolCallResponseSchema }
+);
+
+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);
+}
+```
+
+### JSON Mode
+
+```typescript
+const JSONResponseSchema = z.object({
+  id: z.string(),
+  choices: z.array(
+    z.object({
+      message: z.object({
+        content: z.string(), // Will be valid JSON
+      }),
+    })
+  ),
+});
+
+const result = await groq.apiRequest(
+  {
+    method: "POST",
+    path: "/openai/v1/chat/completions",
+    body: {
+      model: "llama-3.1-70b-versatile",
+      messages: [
+        {
+          role: "user",
+          content:
+            "List 3 programming languages with their use cases. Respond in JSON format.",
+        },
+      ],
+      response_format: { type: "json_object" },
+    },
+  },
+  { response: JSONResponseSchema }
+);
+
+const data = JSON.parse(result.choices[0]?.message.content ?? "{}");
+```
+
+## Common Pitfalls
+
+### No Specialized Methods
+
+```typescript
+// WRONG - These methods do not exist
+await groq.chat({ ... });
+await groq.createChatCompletion({ ... });
+
+// CORRECT - Use apiRequest
+await groq.apiRequest(
+  { method: "POST", path: "/openai/v1/chat/completions", body: { ... } },
+  { response: ChatCompletionResponseSchema }
+);
+```
+
+### OpenAI-Compatible Path
+
+Groq uses OpenAI-compatible endpoints with `/openai/v1/` prefix:
+
+```typescript
+// WRONG - Missing /openai prefix
+await groq.apiRequest(
+  { method: "POST", path: "/v1/chat/completions", body: { ... } },
+  { response: schema }
+);
+
+// CORRECT - Include /openai prefix
+await groq.apiRequest(
+  { method: "POST", path: "/openai/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 groq.apiRequest(
+  { method: "POST", path: "/openai/v1/chat/completions", body: { ... } },
+  { response: ChatCompletionResponseSchema }
+);
+
+console.log("Token usage:", result.usage);
+console.log("Completion time:", result.usage.completion_time, "seconds");
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await groq.apiRequest(
+    { method: "POST", path: "/openai/v1/chat/completions", body: { ... } },
+    { response: ChatCompletionResponseSchema }
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  }
+}
+```
+
+## API Reference
+
+- [Groq Documentation](https://console.groq.com/docs)
+- [Chat Completions](https://console.groq.com/docs/text-chat)
+- [Tool Use](https://console.groq.com/docs/tool-use)
+- [Models](https://console.groq.com/docs/models)

package/src/integrations/groq/client.ts

@@ -0,0 +1,21 @@
+/**
+ * Groq client implementation.
+ *
+ * Uses the proto-generated REST API Integration Plugin type from @superblocksteam/types.
+ * Groq integrations use the REST API Integration plugin under the hood.
+ */
+
+import { RestApiIntegrationClient } from '../base/index.js';
+import type { GroqClient } from './types.js';
+
+/**
+ * Internal implementation of GroqClient.
+ *
+ * Extends RestApiIntegrationClient to inherit the generic apiRequest() method.
+ * This implementation communicates with the orchestrator to execute
+ * Groq API calls. At runtime, the orchestrator handles authentication
+ * and API request execution.
+ */
+export class GroqClientImpl extends RestApiIntegrationClient implements GroqClient {
+  // Inherits: name, pluginId, config, executeQuery, apiRequest()
+}

package/src/integrations/groq/index.ts

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

package/src/integrations/groq/types.ts

@@ -0,0 +1,34 @@
+/**
+ * Groq client types.
+ */
+
+import type { BaseIntegrationClient } from '../../types.js';
+import type { SupportsApiRequest } from '../base/index.js';
+
+/**
+ * Groq client for API interactions.
+ *
+ * Provides generic API request method for interacting with Groq's API.
+ * Use apiRequest() to make calls to any Groq API endpoint.
+ *
+ * @example
+ * ```typescript
+ * const groq = ctx.groq('My Groq');
+ *
+ * // Make API requests
+ * const ResponseSchema = z.object({
+ *   // Define your response schema
+ * });
+ *
+ * const result = await groq.apiRequest(
+ *   {
+ *     method: 'POST',
+ *     path: '/chat/completions',
+ *   },
+ *   { response: ResponseSchema }
+ * );
+ * ```
+ */
+export interface GroqClient extends BaseIntegrationClient, SupportsApiRequest {
+  // apiRequest() method inherited from SupportsApiRequest
+}

package/src/integrations/gsheets/README.md

@@ -0,0 +1,174 @@
+# Google Sheets Client
+
+Interact with Google Sheets with full type safety and runtime validation.
+
+## Methods
+
+| 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 |
+| `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 |
+
+## Usage
+
+### Read Spreadsheet Data
+
+```typescript
+import { api, z } 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(),
+}));
+
+export default api({
+  name: "GoogleSheetsExample",
+  input: z.object({
+    spreadsheetId: z.string(),
+  }),
+  output: z.object({
+    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,
+    });
+
+    return { rows };
+  },
+});
+```
+
+### Append Rows
+
+```typescript
+await sheets.run("APPEND_SPREADSHEET", z.any(), {
+  spreadsheetId: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
+  sheetTitle: "Sheet1",
+  data: JSON.stringify([
+    { name: "John Doe", email: "john@example.com", status: "active" },
+    { name: "Jane Doe", email: "jane@example.com", status: "pending" },
+  ]),
+});
+```
+
+### Create Rows at Position
+
+```typescript
+await sheets.run("CREATE_SPREADSHEET_ROWS", z.any(), {
+  spreadsheetId: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
+  sheetTitle: "Sheet1",
+  rowNumber: "5",
+  data: JSON.stringify([
+    { name: "New Row", email: "new@example.com", status: "active" },
+  ]),
+});
+```
+
+### Clear Sheet
+
+```typescript
+await sheets.run("CLEAR_SPREADSHEET", z.any(), {
+  spreadsheetId: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
+  sheetTitle: "Sheet1",
+  preserveHeaderRow: true,
+});
+```
+
+### Create New Worksheet
+
+```typescript
+await sheets.run("CREATE_WORKSHEET", z.any(), {
+  spreadsheetId: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
+  addSheet: {
+    sheetTitle: "New Sheet",
+    rowCount: "100",
+    columnCount: "26",
+  },
+});
+```
+
+## 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 |
+
+## Common Pitfalls
+
+### Use extractFirstRowHeader for Objects
+
+To get data as objects instead of arrays:
+
+```typescript
+// With extractFirstRowHeader: true
+// Returns: [{ name: "John", email: "john@example.com" }, ...]
+
+// With extractFirstRowHeader: false
+// Returns: [["name", "email"], ["John", "john@example.com"], ...]
+```
+
+### Data Must Be JSON String
+
+The `data` parameter expects a JSON string:
+
+```typescript
+// CORRECT
+data: JSON.stringify([{ name: "John", email: "john@example.com" }])
+
+// WRONG
+data: [{ name: "John", email: "john@example.com" }]
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError, IntegrationError } from "@superblocksteam/sdk-api";
+
+try {
+  const rows = await 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);
+  } else if (error instanceof IntegrationError) {
+    console.error("Google Sheets error:", error.message);
+  }
+}
+```
+
+## API Reference
+
+- [Google Sheets API](https://developers.google.com/sheets/api)
+- [A1 Notation](https://developers.google.com/sheets/api/guides/concepts#a1_notation)

package/src/integrations/gsheets/client.ts

@@ -0,0 +1,124 @@
+/**
+ * Google Sheets client implementation.
+ *
+ * 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';
+
+/**
+ * Internal implementation of GoogleSheetsClient.
+ */
+export class GoogleSheetsClientImpl implements GoogleSheetsClient, IntegrationClientImpl {
+  readonly config: IntegrationConfig;
+  private readonly executeQuery: QueryExecutor;
+
+  constructor(config: IntegrationConfig, executeQuery: QueryExecutor) {
+    this.config = config;
+    this.executeQuery = executeQuery;
+  }
+
+  get name(): string {
+    return this.config.name;
+  }
+
+  get pluginId(): string {
+    return this.config.pluginId;
+  }
+
+  private buildRequest(
+    action: GoogleSheetsAction,
+    params: GoogleSheetsParams,
+  ): PartialMessage<GSheetsPlugin> {
+    const request: PartialMessage<GSheetsPlugin> = {
+      action,
+      spreadsheetId: params.spreadsheetId,
+    };
+
+    if (params.sheetTitle) {
+      request.sheetTitle = params.sheetTitle;
+    }
+    if (params.range) {
+      request.range = params.range;
+    }
+    if (params.rowNumber) {
+      request.rowNumber = params.rowNumber;
+    }
+    if (params.extractFirstRowHeader !== undefined) {
+      request.extractFirstRowHeader = params.extractFirstRowHeader;
+    }
+    if (params.headerRowNumber) {
+      request.headerRowNumber = params.headerRowNumber;
+    }
+    if (params.format) {
+      request.format = params.format;
+    }
+    if (params.data) {
+      request.data = params.data;
+    }
+    if (params.preserveHeaderRow !== undefined) {
+      request.preserveHeaderRow = params.preserveHeaderRow;
+    }
+    if (params.includeHeaderRow !== undefined) {
+      request.includeHeaderRow = params.includeHeaderRow;
+    }
+    if (params.writeToDestinationType) {
+      request.writeToDestinationType = params.writeToDestinationType;
+    }
+    if (params.body) {
+      request.body = params.body;
+    }
+    if (params.addSheet) {
+      request.addSheet = {
+        sheetTitle: params.addSheet.sheetTitle,
+        rowCount: params.addSheet.rowCount,
+        columnCount: params.addSheet.columnCount,
+      };
+    }
+
+    return request;
+  }
+
+  async run<T>(
+    action: GoogleSheetsAction,
+    schema: z.ZodSchema<T>,
+    params: GoogleSheetsParams,
+  ): Promise<T> {
+    const request = this.buildRequest(action, params);
+
+    try {
+      const result = await this.executeQuery(request as Record<string, unknown>);
+
+      // Validate result against schema
+      const parseResult = schema.safeParse(result);
+
+      if (!parseResult.success) {
+        throw new RestApiValidationError(
+          `Result validation failed: ${parseResult.error.message}`,
+          {
+            zodError: parseResult.error,
+            data: result,
+          },
+        );
+      }
+
+      return parseResult.data;
+    } catch (error) {
+      if (
+        error instanceof RestApiValidationError ||
+        error instanceof IntegrationError
+      ) {
+        throw error;
+      }
+
+      throw new IntegrationError(this.config.name, 'run', error);
+    }
+  }
+}

package/src/integrations/gsheets/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Google Sheets integration client.
+ *
+ * @module
+ */
+
+export type {
+  GoogleSheetsClient,
+  GoogleSheetsAction,
+  GoogleSheetsParams,
+} from './types.js';
+export { GoogleSheetsClientImpl } from './client.js';