@superblocksteam/sdk-api 0.0.4

package/src/integrations/groq/README.md

@@ -0,0 +1,315 @@
+# Groq Client
+
+Interact with Groq's ultra-fast inference API for LLM chat completions with low latency.
+
+## Methods
+
+| Method                                   | Description                                      |
+| ---------------------------------------- | ------------------------------------------------ |
+| `apiRequest(options, schema, metadata?)` | Make any Groq API request with schema validation |
+
+## Usage
+
+### Chat Completion
+
+```typescript
+import { api, z, groq } 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({
+  integrations: {
+    groq: groq(PROD_GROQ),
+  },
+  name: "GroqExample",
+  input: z.object({
+    prompt: z.string(),
+  }),
+  output: z.object({
+    response: z.string(),
+  }),
+  async run(ctx, { prompt }) {
+    const result = await ctx.integrations.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 ctx.integrations.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 ctx.integrations.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 ctx.integrations.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 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?" }],
+      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 ctx.integrations.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 ?? "{}");
+```
+
+## 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
+
+```typescript
+// WRONG - These methods do not exist
+await groq.chat({ ... });
+await groq.createChatCompletion({ ... });
+
+// CORRECT - Use apiRequest
+await ctx.integrations.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 ctx.integrations.groq.apiRequest(
+  { method: "POST", path: "/v1/chat/completions", body: { ... } },
+  { response: schema }
+);
+
+// CORRECT - Include /openai prefix
+await ctx.integrations.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 ctx.integrations.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 ctx.integrations.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,23 @@
+/**
+ * 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,35 @@
+/**
+ * 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
+ * // Declare in api(): integrations: { groq: groq(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.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,192 @@
+# Google Sheets Client
+
+Interact with Google Sheets with full type safety and runtime validation.
+
+## Methods
+
+| Method                                   | Description                       |
+| ---------------------------------------- | --------------------------------- |
+| `run(action, schema, params, metadata?)` | 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, 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(),
+  }),
+);
+
+export default api({
+  integrations: {
+    sheets: gsheets(PROD_GSHEETS),
+  },
+  name: "GoogleSheetsExample",
+  input: z.object({
+    spreadsheetId: z.string(),
+  }),
+  output: z.object({
+    rows: RowSchema,
+  }),
+  async run(ctx, { spreadsheetId }) {
+    const rows = await ctx.integrations.sheets.run(
+      "READ_SPREADSHEET_RANGE",
+      RowSchema,
+      {
+        spreadsheetId: spreadsheetId,
+        sheetTitle: "Sheet1",
+        range: "A1:C100",
+        extractFirstRowHeader: true,
+      },
+    );
+
+    return { rows };
+  },
+});
+```
+
+### Append Rows
+
+```typescript
+await ctx.integrations.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 ctx.integrations.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 ctx.integrations.sheets.run("CLEAR_SPREADSHEET", z.any(), {
+  spreadsheetId: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
+  sheetTitle: "Sheet1",
+  preserveHeaderRow: true,
+});
+```
+
+### Create New Worksheet
+
+```typescript
+await ctx.integrations.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    |
+
+## 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
+
+### 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 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);
+  } 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,135 @@
+/**
+ * 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, TraceMetadata } 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,
+    metadata?: TraceMetadata,
+  ): Promise<T> {
+    const request = this.buildRequest(action, params);
+
+    try {
+      const result = await this.executeQuery(
+        request as Record<string, unknown>,
+        undefined,
+        metadata,
+      );
+
+      // 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);
+    }
+  }
+}