@superblocksteam/sdk-api 0.0.6 → 0.0.8

package/src/integrations/graphql/client.test.ts

@@ -0,0 +1,220 @@
+/**
+ * Tests for GraphQLClientImpl.
+ *
+ * Validates:
+ * - The proto request built by query()/mutation() matches the
+ *   graphql.v1.Plugin shape expected by the orchestrator.
+ * - Optional per-request headers are forwarded as the proto's repeated
+ *   `headers` field (key/value Property entries) so dynamic values like
+ *   Authorization tokens can be sent from API code.
+ * - Variables are serialized into the proto `custom.variables` Property.
+ * - Trace metadata is passed through to the executeQuery callback.
+ * - Response Zod validation throws RestApiValidationError on mismatch.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { z } from "zod";
+
+import { RestApiValidationError } from "../../errors.js";
+import type { IntegrationConfig } from "../types.js";
+import { GraphQLClientImpl } from "./client.js";
+
+const TEST_CONFIG: IntegrationConfig = {
+  id: "graphql-test-id",
+  name: "Test GraphQL",
+  pluginId: "graphqlintegration",
+  configuration: {},
+};
+
+function createClient(mockResult: unknown) {
+  const executeQuery = vi.fn().mockResolvedValue(mockResult);
+  const client = new GraphQLClientImpl(TEST_CONFIG, executeQuery);
+  return { client, executeQuery };
+}
+
+const UserResponseSchema = z.object({
+  data: z.object({
+    user: z.object({
+      id: z.string(),
+      name: z.string(),
+    }),
+  }),
+});
+
+const SAMPLE_QUERY = `query GetUser($id: ID!) {
+  user(id: $id) { id name }
+}`;
+
+const SAMPLE_MUTATION = `mutation CreateUser($name: String!) {
+  createUser(name: $name) { id name }
+}`;
+
+describe("GraphQLClientImpl", () => {
+  describe("query()", () => {
+    it("returns validated data on a successful response", async () => {
+      const { client } = createClient({
+        data: { user: { id: "u1", name: "Alice" } },
+      });
+
+      const result = await client.query(
+        SAMPLE_QUERY,
+        { response: UserResponseSchema },
+        { id: "u1" },
+      );
+
+      expect(result.data.user).toEqual({ id: "u1", name: "Alice" });
+    });
+
+    it("builds the proto request with body, variables, and defaults", async () => {
+      const { client, executeQuery } = createClient({
+        data: { user: { id: "u1", name: "Alice" } },
+      });
+
+      await client.query(
+        SAMPLE_QUERY,
+        { response: UserResponseSchema },
+        { id: "u1" },
+      );
+
+      expect(executeQuery).toHaveBeenCalledOnce();
+      const request = executeQuery.mock.calls[0][0];
+      expect(request.body).toBe(SAMPLE_QUERY);
+      expect(request.verboseHttpOutput).toBe(false);
+      expect(request.failOnGraphqlErrors).toBe(true);
+      expect(request.custom).toEqual({
+        variables: {
+          key: "variables",
+          value: JSON.stringify({ id: "u1" }),
+        },
+      });
+      expect(request.headers).toBeUndefined();
+    });
+
+    it("omits custom when no variables are provided", async () => {
+      const { client, executeQuery } = createClient({
+        data: { user: { id: "u1", name: "Alice" } },
+      });
+
+      await client.query(SAMPLE_QUERY, { response: UserResponseSchema });
+
+      const request = executeQuery.mock.calls[0][0];
+      expect(request.custom).toBeUndefined();
+    });
+
+    it("forwards per-request headers into the proto headers field", async () => {
+      const { client, executeQuery } = createClient({
+        data: { user: { id: "u1", name: "Alice" } },
+      });
+
+      await client.query(
+        SAMPLE_QUERY,
+        { response: UserResponseSchema },
+        { id: "u1" },
+        undefined,
+        {
+          Authorization: "Bearer abc123",
+          "X-Trace-Id": "trace-1",
+        },
+      );
+
+      const request = executeQuery.mock.calls[0][0];
+      expect(request.headers).toEqual([
+        { key: "Authorization", value: "Bearer abc123" },
+        { key: "X-Trace-Id", value: "trace-1" },
+      ]);
+    });
+
+    it("does not set headers when an empty headers object is passed", async () => {
+      const { client, executeQuery } = createClient({
+        data: { user: { id: "u1", name: "Alice" } },
+      });
+
+      await client.query(
+        SAMPLE_QUERY,
+        { response: UserResponseSchema },
+        undefined,
+        undefined,
+        {},
+      );
+
+      const request = executeQuery.mock.calls[0][0];
+      expect(request.headers).toBeUndefined();
+    });
+
+    it("passes trace metadata through to executeQuery", async () => {
+      const { client, executeQuery } = createClient({
+        data: { user: { id: "u1", name: "Alice" } },
+      });
+
+      await client.query(
+        SAMPLE_QUERY,
+        { response: UserResponseSchema },
+        undefined,
+        { label: "graphql.getUser", description: "Fetch a user by id" },
+      );
+
+      expect(executeQuery).toHaveBeenCalledWith(expect.any(Object), undefined, {
+        label: "graphql.getUser",
+        description: "Fetch a user by id",
+      });
+    });
+
+    it("throws RestApiValidationError when the response fails schema validation", async () => {
+      const { client } = createClient({
+        data: { user: { id: "u1" /* missing name */ } },
+      });
+
+      await expect(
+        client.query(SAMPLE_QUERY, { response: UserResponseSchema }),
+      ).rejects.toThrow(RestApiValidationError);
+    });
+  });
+
+  describe("mutation()", () => {
+    it("returns validated data on a successful response", async () => {
+      const { client } = createClient({
+        data: { createUser: { id: "u2", name: "Bob" } },
+      });
+
+      const Schema = z.object({
+        data: z.object({
+          createUser: z.object({ id: z.string(), name: z.string() }),
+        }),
+      });
+
+      const result = await client.mutation(
+        SAMPLE_MUTATION,
+        { response: Schema },
+        { name: "Bob" },
+      );
+
+      expect(result.data.createUser).toEqual({ id: "u2", name: "Bob" });
+    });
+
+    it("forwards per-request headers into the proto headers field", async () => {
+      const { client, executeQuery } = createClient({
+        data: { createUser: { id: "u2", name: "Bob" } },
+      });
+
+      const Schema = z.object({
+        data: z.object({
+          createUser: z.object({ id: z.string(), name: z.string() }),
+        }),
+      });
+
+      await client.mutation(
+        SAMPLE_MUTATION,
+        { response: Schema },
+        { name: "Bob" },
+        undefined,
+        { Authorization: "Bearer xyz" },
+      );
+
+      const request = executeQuery.mock.calls[0][0];
+      expect(request.body).toBe(SAMPLE_MUTATION);
+      expect(request.headers).toEqual([
+        { key: "Authorization", value: "Bearer xyz" },
+      ]);
+    });
+  });
+});

package/src/integrations/graphql/docs.manifest.json

@@ -0,0 +1,10 @@
+{
+  "pluginId": "graphql",
+  "base": "README.md",
+  "overlays": [
+    {
+      "file": "overlays/dynamic-headers.md",
+      "sdkVersionRange": ">=0.0.2"
+    }
+  ]
+}

package/src/integrations/graphql/overlays/dynamic-headers.md

@@ -0,0 +1,34 @@
+## @replace: Methods
+
+| Method                                                           | Description                                                |
+| ---------------------------------------------------------------- | ---------------------------------------------------------- |
+| `query<T>(query, schema, variables?, metadata?, headers?)`       | Execute a GraphQL query with required schema validation    |
+| `mutation<T>(mutation, schema, variables?, metadata?, headers?)` | Execute a GraphQL mutation with required schema validation |
+
+## @replace: Trace Metadata
+
+All methods accept an optional `metadata` parameter for diagnostics labeling. See the [root SDK README](../../../README.md#trace-metadata) for details.
+
+## Dynamic Headers
+
+Static headers (e.g. a fixed `X-API-Version`) and auth headers (e.g. Bearer tokens, API keys) should be configured on the GraphQL integration in the Superblocks UI so they apply to every call automatically.
+
+For values that change per request — for example a bearer token derived from the API's input or from `ctx.env` — pass an optional `headers` map as the final argument to `query()` or `mutation()`:
+
+```typescript
+const MeResponseSchema = z.object({
+  data: z.object({
+    me: z.object({ id: z.string(), email: z.string() }),
+  }),
+});
+
+const result = await ctx.integrations.graphql.query(
+  `query { me { id email } }`,
+  { response: MeResponseSchema },
+  undefined, // no variables
+  undefined, // no trace metadata
+  { Authorization: `Bearer ${ctx.env.UPSTREAM_TOKEN}` },
+);
+```
+
+Since both `variables` and `metadata` accept plain objects, pass `undefined` for any of them that you do not need.

package/src/integrations/graphql/types.ts

@@ -2,9 +2,10 @@
  * GraphQL client types.
  */
 
+import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
-import type { z } from "zod";
 
 /**
  * GraphQL client for executing queries and mutations.
@@ -61,6 +62,17 @@ import type { z } from "zod";
  *   { response: MutationResponseSchema },
  *   { name: 'John Doe' }
  * );
+ *
+ * // Send per-request headers (e.g. a dynamic Authorization token).
+ * // Static headers and auth configured on the integration apply automatically;
+ * // use this parameter only for values that vary per request.
+ * await graphql.query(
+ *   `query { me { id } }`,
+ *   { response: z.object({ data: z.object({ me: z.object({ id: z.string() }) }) }) },
+ *   undefined,
+ *   undefined,
+ *   { Authorization: `Bearer ${token}` },
+ * );
  * ```
  */
 export interface GraphQLClient extends BaseIntegrationClient {
@@ -73,6 +85,10 @@ export interface GraphQLClient extends BaseIntegrationClient {
    *   `metadata` accept plain objects, pass `undefined` for variables when you only need metadata:
    *   `query(q, schema, undefined, { label: "..." })`
    * @param metadata - Optional trace metadata for observability
+   * @param headers - Optional HTTP headers to include on this request. Static
+   *   headers and auth configured on the integration apply automatically; use
+   *   this parameter only for values that vary per request (e.g. a bearer token
+   *   derived from the API's input).
    * @returns Validated query result
    *
    * @example
@@ -94,6 +110,7 @@ export interface GraphQLClient extends BaseIntegrationClient {
     schema: { response: z.ZodSchema<TResponse> },
     variables?: Record<string, unknown>,
     metadata?: TraceMetadata,
+    headers?: Record<string, string>,
   ): Promise<TResponse>;
 
   /**
@@ -105,6 +122,10 @@ export interface GraphQLClient extends BaseIntegrationClient {
    *   `metadata` accept plain objects, pass `undefined` for variables when you only need metadata:
    *   `mutation(m, schema, undefined, { label: "..." })`
    * @param metadata - Optional trace metadata for observability
+   * @param headers - Optional HTTP headers to include on this request. Static
+   *   headers and auth configured on the integration apply automatically; use
+   *   this parameter only for values that vary per request (e.g. a bearer token
+   *   derived from the API's input).
    * @returns Validated mutation result
    *
    * @example
@@ -127,5 +148,6 @@ export interface GraphQLClient extends BaseIntegrationClient {
     schema: { response: z.ZodSchema<TResponse> },
     variables?: Record<string, unknown>,
     metadata?: TraceMetadata,
+    headers?: Record<string, string>,
   ): Promise<TResponse>;
 }

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,9 +85,9 @@ 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",
+          model: "llama-3.3-70b-versatile",
           messages: [
             { role: "system", content: "You are a helpful assistant." },
             { role: "user", content: prompt },
@@ -79,13 +105,13 @@ export default api({
 ### Using Different Models
 
 ```typescript
-// Llama 3.1 70B - Best balance of speed and quality
+// Llama 3.3 70B - Best balance of speed and quality
 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",
+      model: "llama-3.3-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" }],
@@ -105,13 +131,13 @@ const llama8b = await ctx.integrations.groq.apiRequest(
   { response: ChatCompletionResponseSchema },
 );
 
-// Mixtral 8x7B - Good for code and reasoning
-const mixtral = await ctx.integrations.groq.apiRequest(
+// GPT-OSS 120B - Good for code and reasoning
+const gptOss = await ctx.integrations.groq.apiRequest(
   {
     method: "POST",
-    path: "/openai/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
-      model: "mixtral-8x7b-32768",
+      model: "openai/gpt-oss-120b",
       messages: [{ role: "user", content: "Hello" }],
     },
   },
@@ -150,9 +176,9 @@ 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",
+      model: "llama-3.3-70b-versatile",
       messages: [{ role: "user", content: "What's the weather in Tokyo?" }],
       tools: [
         {
@@ -200,9 +226,9 @@ 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",
+      model: "llama-3.3-70b-versatile",
       messages: [
         {
           role: "user",
@@ -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/groq/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "groq",
+  "base": "README.md",
+  "overlays": []
+}

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/gsheets/client.ts

@@ -4,13 +4,15 @@
  * Uses the native Google Sheets plugin type from @superblocksteam/types.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 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 { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import type {
   GoogleSheetsClient,
   GoogleSheetsAction,

package/src/integrations/gsheets/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "gsheets",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/gsheets/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 

package/src/integrations/hubspot/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "hubspot",
+  "base": "README.md",
+  "overlays": []
+}