@superblocksteam/sdk-api 2.0.103 → 2.0.104-next.1

package/src/integrations/groq/README.md

@@ -10,7 +10,9 @@ Interact with Groq's ultra-fast inference API for LLM chat completions with low
 
 ## Usage
 
-### Chat Completion
+### Step 1: List Available Models
+
+Model availability varies by account and changes over time. Before making requests, validate which models are available:
 
 ```typescript
 import { api, z, groq } from "@superblocksteam/sdk-api";
@@ -18,6 +20,30 @@ import { api, z, groq } from "@superblocksteam/sdk-api";
 // Integration ID from the integrations panel
 const PROD_GROQ = "a1b2c3d4-5678-90ab-cdef-groq00000001";
 
+const ModelsResponseSchema = z.object({
+  data: z.array(
+    z.object({
+      id: z.string(),
+      object: z.string(),
+    }),
+  ),
+});
+
+const models = await ctx.integrations.groq.apiRequest(
+  {
+    method: "GET",
+    path: "/v1/models",
+  },
+  { response: ModelsResponseSchema },
+);
+
+// Use a model ID from the response in subsequent requests
+const availableModelId = models.data[0]?.id;
+```
+
+### Chat Completion
+
+```typescript
 const ChatCompletionResponseSchema = z.object({
   id: z.string(),
   object: z.literal("chat.completion"),
@@ -59,7 +85,7 @@ export default api({
     const result = await ctx.integrations.groq.apiRequest(
       {
         method: "POST",
-        path: "/openai/v1/chat/completions",
+        path: "/v1/chat/completions",
         body: {
           model: "llama-3.1-70b-versatile",
           messages: [
@@ -83,7 +109,7 @@ export default api({
 const llama70b = await ctx.integrations.groq.apiRequest(
   {
     method: "POST",
-    path: "/openai/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "llama-3.1-70b-versatile",
       messages: [{ role: "user", content: "Hello" }],
@@ -96,7 +122,7 @@ const llama70b = await ctx.integrations.groq.apiRequest(
 const llama8b = await ctx.integrations.groq.apiRequest(
   {
     method: "POST",
-    path: "/openai/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "llama-3.1-8b-instant",
       messages: [{ role: "user", content: "Hello" }],
@@ -109,7 +135,7 @@ const llama8b = await ctx.integrations.groq.apiRequest(
 const mixtral = await ctx.integrations.groq.apiRequest(
   {
     method: "POST",
-    path: "/openai/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "mixtral-8x7b-32768",
       messages: [{ role: "user", content: "Hello" }],
@@ -150,7 +176,7 @@ const ToolCallResponseSchema = z.object({
 const result = await ctx.integrations.groq.apiRequest(
   {
     method: "POST",
-    path: "/openai/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "llama-3.1-70b-versatile",
       messages: [{ role: "user", content: "What's the weather in Tokyo?" }],
@@ -200,7 +226,7 @@ const JSONResponseSchema = z.object({
 const result = await ctx.integrations.groq.apiRequest(
   {
     method: "POST",
-    path: "/openai/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "llama-3.1-70b-versatile",
       messages: [
@@ -234,55 +260,36 @@ await groq.createChatCompletion({ ... });
 
 // CORRECT - Use apiRequest
 await ctx.integrations.groq.apiRequest(
-  { method: "POST", path: "/openai/v1/chat/completions", body: { ... } },
+  { method: "POST", path: "/v1/chat/completions", body: { ... } },
   { response: ChatCompletionResponseSchema }
 );
 ```
 
 ### OpenAI-Compatible Path
 
-Groq uses OpenAI-compatible endpoints with `/openai/v1/` prefix:
+The integration's base URL already includes `https://api.groq.com/openai`, so paths should start with `/v1/`:
 
 ```typescript
-// WRONG - Missing /openai prefix
+// WRONG - Duplicates the /openai prefix (base URL already includes it)
 await ctx.integrations.groq.apiRequest(
-  { method: "POST", path: "/v1/chat/completions", body: { ... } },
+  { method: "POST", path: "/openai/v1/chat/completions", body: { ... } },
   { response: schema }
 );
 
-// CORRECT - Include /openai prefix
+// CORRECT - Start with /v1/ (the integration prepends /openai automatically)
 await ctx.integrations.groq.apiRequest(
-  { method: "POST", path: "/openai/v1/chat/completions", body: { ... } },
+  { method: "POST", path: "/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: { ... } },
+  { method: "POST", path: "/v1/chat/completions", body: { ... } },
   { response: ChatCompletionResponseSchema }
 );
 
@@ -297,7 +304,7 @@ import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
   const result = await ctx.integrations.groq.apiRequest(
-    { method: "POST", path: "/openai/v1/chat/completions", body: { ... } },
+    { method: "POST", path: "/v1/chat/completions", body: { ... } },
     { response: ChatCompletionResponseSchema }
   );
 } catch (error) {

package/src/integrations/gsheets/README.md

@@ -24,7 +24,7 @@ Interact with Google Sheets with full type safety and runtime validation.
 ### Read Spreadsheet Data
 
 ```typescript
-import { api, z, gsheets } from "@superblocksteam/sdk-api";
+import { api, z, googleSheets } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_GSHEETS = "a1b2c3d4-5678-90ab-cdef-gsheets00001";
@@ -39,7 +39,7 @@ const RowSchema = z.array(
 
 export default api({
   integrations: {
-    sheets: gsheets(PROD_GSHEETS),
+    sheets: googleSheets(PROD_GSHEETS),
   },
   name: "GoogleSheetsExample",
   input: z.object({

package/src/integrations/index.ts

@@ -168,7 +168,6 @@ export {
   SUPPORTED_PLUGINS,
   type SupportedPluginId,
   type QueryExecutor,
-  type StreamingQueryExecutor,
   type TraceMetadata,
   type CreateClientOptions,
 } from "./registry.js";

package/src/integrations/lakebase/types.ts

@@ -19,14 +19,14 @@ import type { TraceMetadata } from "../registry.js";
  *
  * // Parameterized query
  * const users = await lb.query(
- *   'SELECT * FROM users WHERE status = ?',
+ *   'SELECT * FROM users WHERE status = $1',
  *   UserSchema,
  *   ['active'],
  * );
  *
  * // Execute a mutation
  * const result = await lb.execute(
- *   'INSERT INTO users (name, email) VALUES (?, ?)',
+ *   'INSERT INTO users (name, email) VALUES ($1, $2)',
  *   ['Alice', 'alice@example.com'],
  * );
  * ```
@@ -35,7 +35,7 @@ export interface LakebaseClient extends BaseIntegrationClient {
   /**
    * Execute a SQL query and return validated rows.
    *
-   * @param sql - SQL query string with `?` placeholders for parameters
+   * @param sql - SQL query string with `$1`, `$2` placeholders for parameters
    * @param schema - Zod schema for validating each result row
    * @param params - Optional query parameters for server-side binding
    * @returns Array of validated rows
@@ -50,7 +50,7 @@ export interface LakebaseClient extends BaseIntegrationClient {
   /**
    * Execute a SQL statement (INSERT, UPDATE, DELETE).
    *
-   * @param sql - SQL statement with `?` placeholders for parameters
+   * @param sql - SQL statement with `$1`, `$2` placeholders for parameters
    * @param params - Optional query parameters for server-side binding
    * @returns The affected row count
    */

package/src/integrations/launchdarkly/README.md

@@ -13,7 +13,7 @@ Manage feature flags, get flag evaluations, and interact with LaunchDarkly's fea
 ### Get Feature Flag
 
 ```typescript
-import { api, z, launchdarkly } from "@superblocksteam/sdk-api";
+import { api, z, launchDarkly } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_LAUNCHDARKLY = "a1b2c3d4-5678-90ab-cdef-launchda0001";
@@ -44,7 +44,7 @@ const FlagSchema = z.object({
 
 export default api({
   integrations: {
-    launchdarkly: launchdarkly(PROD_LAUNCHDARKLY),
+    launchdarkly: launchDarkly(PROD_LAUNCHDARKLY),
   },
   name: "LaunchDarklyExample",
   input: z.object({

package/src/integrations/mariadb/README.md

@@ -39,7 +39,7 @@ export default api({
   }),
   async run(ctx, { status }) {
     const users = await ctx.integrations.mariadb.query(
-      "SELECT id, name, email, created_at FROM users WHERE status = $1",
+      "SELECT id, name, email, created_at FROM users WHERE status = ?",
       UserSchema,
       [status],
     );
@@ -54,13 +54,13 @@ export default api({
 ```typescript
 // INSERT
 await ctx.integrations.mariadb.execute(
-  "INSERT INTO users (name, email) VALUES ($1, $2)",
+  "INSERT INTO users (name, email) VALUES (?, ?)",
   ["John Doe", "john@example.com"],
 );
 
 // UPDATE
 const updateResult = await ctx.integrations.mariadb.execute(
-  "UPDATE users SET last_login = NOW() WHERE id = $1",
+  "UPDATE users SET last_login = NOW() WHERE id = ?",
   [userId],
 );
 console.log(`Updated ${updateResult.rowCount} rows`);

package/src/integrations/mariadb/types.ts

@@ -25,7 +25,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const users = await mariadb.query(
- *   'SELECT * FROM users WHERE status = $1',
+ *   'SELECT * FROM users WHERE status = ?',
  *   UserSchema,
  *   ['active']
  * );
@@ -35,7 +35,7 @@ export interface MariaDBClient extends BaseIntegrationClient {
   /**
    * Execute a SQL query and validate results against a Zod schema.
    *
-   * @param sql - SQL query string (use $1, $2, etc. for parameters)
+   * @param sql - SQL query string (use ? placeholders for parameters)
    * @param schema - Zod schema to validate the query results
    * @param params - Optional query parameters
    * @returns Promise resolving to validated query results

package/src/integrations/mistral/README.md

@@ -10,7 +10,9 @@ Interact with Mistral AI's APIs for chat completions, embeddings, and code gener
 
 ## Usage
 
-### Chat Completion
+### Step 1: List Available Models
+
+Model availability varies by account and API plan. Before making requests, validate which models you can access:
 
 ```typescript
 import { api, z, mistral } from "@superblocksteam/sdk-api";
@@ -18,6 +20,30 @@ import { api, z, mistral } from "@superblocksteam/sdk-api";
 // Integration ID from the integrations panel
 const PROD_MISTRAL = "a1b2c3d4-5678-90ab-cdef-mistral00001";
 
+const ModelsResponseSchema = z.object({
+  data: z.array(
+    z.object({
+      id: z.string(),
+      object: z.string(),
+    }),
+  ),
+});
+
+const models = await ctx.integrations.mistral.apiRequest(
+  {
+    method: "GET",
+    path: "/models",
+  },
+  { response: ModelsResponseSchema },
+);
+
+// Use a model ID from the response in subsequent requests
+const availableModelId = models.data[0]?.id;
+```
+
+### Chat Completion
+
+```typescript
 const ChatCompletionResponseSchema = z.object({
   id: z.string(),
   object: z.string(),
@@ -55,7 +81,7 @@ export default api({
     const result = await ctx.integrations.mistral.apiRequest(
       {
         method: "POST",
-        path: "/v1/chat/completions",
+        path: "/chat/completions",
         body: {
           model: "mistral-large-latest",
           messages: [{ role: "user", content: prompt }],
@@ -76,7 +102,7 @@ export default api({
 const large = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "mistral-large-latest",
       messages: [{ role: "user", content: "Complex analysis..." }],
@@ -89,7 +115,7 @@ const large = await ctx.integrations.mistral.apiRequest(
 const medium = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "mistral-medium-latest",
       messages: [{ role: "user", content: "General task..." }],
@@ -102,7 +128,7 @@ const medium = await ctx.integrations.mistral.apiRequest(
 const small = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "mistral-small-latest",
       messages: [{ role: "user", content: "Simple task..." }],
@@ -115,7 +141,7 @@ const small = await ctx.integrations.mistral.apiRequest(
 const codestral = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "codestral-latest",
       messages: [{ role: "user", content: "Write a function to..." }],
@@ -148,7 +174,7 @@ const EmbeddingsResponseSchema = z.object({
 const result = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/embeddings",
+    path: "/embeddings",
     body: {
       model: "mistral-embed",
       input: ["Hello world", "Bonjour le monde"],
@@ -193,7 +219,7 @@ const FunctionCallResponseSchema = z.object({
 const result = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "mistral-large-latest",
       messages: [{ role: "user", content: "What's the weather in London?" }],
@@ -227,7 +253,7 @@ const result = await ctx.integrations.mistral.apiRequest(
 const result = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "mistral-large-latest",
       messages: [
@@ -260,7 +286,7 @@ await mistral.embed({ ... });
 
 // CORRECT - Use apiRequest
 await ctx.integrations.mistral.apiRequest(
-  { method: "POST", path: "/v1/chat/completions", body: { ... } },
+  { method: "POST", path: "/chat/completions", body: { ... } },
   { response: ChatCompletionResponseSchema }
 );
 ```
@@ -288,7 +314,7 @@ Mistral has a safe mode for content moderation:
 const result = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "mistral-large-latest",
       messages: [{ role: "user", content: "..." }],
@@ -307,7 +333,7 @@ Mistral supports system messages:
 const result = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "mistral-large-latest",
       messages: [
@@ -327,7 +353,7 @@ import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
   const result = await ctx.integrations.mistral.apiRequest(
-    { method: "POST", path: "/v1/chat/completions", body: { ... } },
+    { method: "POST", path: "/chat/completions", body: { ... } },
     { response: ChatCompletionResponseSchema }
   );
 } catch (error) {

package/src/integrations/mssql/README.md

@@ -39,7 +39,7 @@ export default api({
   }),
   async run(ctx, { status }) {
     const users = await ctx.integrations.mssql.query(
-      "SELECT id, name, email, created_at FROM users WHERE status = $1",
+      "SELECT id, name, email, created_at FROM users WHERE status = @PARAM_1",
       UserSchema,
       [status],
     );
@@ -54,13 +54,13 @@ export default api({
 ```typescript
 // INSERT
 await ctx.integrations.mssql.execute(
-  "INSERT INTO users (name, email) VALUES ($1, $2)",
+  "INSERT INTO users (name, email) VALUES (@PARAM_1, @PARAM_2)",
   ["John Doe", "john@example.com"],
 );
 
 // UPDATE
 const updateResult = await ctx.integrations.mssql.execute(
-  "UPDATE users SET last_login = GETDATE() WHERE id = $1",
+  "UPDATE users SET last_login = GETDATE() WHERE id = @PARAM_1",
   [userId],
 );
 console.log(`Updated ${updateResult.rowCount} rows`);

package/src/integrations/mssql/types.ts

@@ -25,7 +25,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const users = await mssql.query(
- *   'SELECT * FROM users WHERE status = $1',
+ *   'SELECT * FROM users WHERE status = @PARAM_1',
  *   UserSchema,
  *   ['active']
  * );
@@ -35,7 +35,7 @@ export interface MSSQLClient extends BaseIntegrationClient {
   /**
    * Execute a SQL query and validate results against a Zod schema.
    *
-   * @param sql - SQL query string (use $1, $2, etc. for parameters)
+   * @param sql - SQL query string (use @PARAM_1, @PARAM_2, etc. for parameters)
    * @param schema - Zod schema to validate the query results
    * @param params - Optional query parameters
    * @returns Promise resolving to validated query results

package/src/integrations/mysql/README.md

@@ -39,7 +39,7 @@ export default api({
   }),
   async run(ctx, { status }) {
     const users = await ctx.integrations.mysql.query(
-      "SELECT id, name, email, created_at FROM users WHERE status = $1",
+      "SELECT id, name, email, created_at FROM users WHERE status = ?",
       UserSchema,
       [status],
     );
@@ -54,13 +54,13 @@ export default api({
 ```typescript
 // INSERT
 await ctx.integrations.mysql.execute(
-  "INSERT INTO users (name, email) VALUES ($1, $2)",
+  "INSERT INTO users (name, email) VALUES (?, ?)",
   ["John Doe", "john@example.com"],
 );
 
 // UPDATE
 const updateResult = await ctx.integrations.mysql.execute(
-  "UPDATE users SET last_login = NOW() WHERE id = $1",
+  "UPDATE users SET last_login = NOW() WHERE id = ?",
   [userId],
 );
 console.log(`Updated ${updateResult.rowCount} rows`);
@@ -90,7 +90,7 @@ const orders = await ctx.integrations.mysql.query(
     c.email as customer_email
   FROM orders o
   JOIN customers c ON o.customer_id = c.id
-  WHERE o.status = $1`,
+  WHERE o.status = ?`,
   OrderWithCustomerSchema,
   ["pending"],
 );

package/src/integrations/mysql/types.ts

@@ -25,7 +25,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const users = await mysql.query(
- *   'SELECT * FROM users WHERE status = $1',
+ *   'SELECT * FROM users WHERE status = ?',
  *   UserSchema,
  *   ['active']
  * );
@@ -35,7 +35,7 @@ export interface MySQLClient extends BaseIntegrationClient {
   /**
    * Execute a SQL query and validate results against a Zod schema.
    *
-   * @param sql - SQL query string (use $1, $2, etc. for parameters)
+   * @param sql - SQL query string (use ? placeholders for parameters)
    * @param schema - Zod schema to validate the query results
    * @param params - Optional query parameters
    * @returns Promise resolving to validated query results
@@ -52,7 +52,7 @@ export interface MySQLClient extends BaseIntegrationClient {
    * });
    *
    * const users = await mysql.query(
-   *   'SELECT * FROM users WHERE status = $1',
+   *   'SELECT * FROM users WHERE status = ?',
    *   UserSchema,
    *   ['active']
    * );
@@ -75,7 +75,7 @@ export interface MySQLClient extends BaseIntegrationClient {
    * @example
    * ```typescript
    * const result = await mysql.execute(
-   *   'UPDATE users SET last_login = NOW() WHERE id = $1',
+   *   'UPDATE users SET last_login = NOW() WHERE id = ?',
    *   [userId]
    * );
    * console.log(`Updated ${result.rowCount} rows`);