@superblocksteam/sdk-api 0.0.4

package/src/integrations/graphql/README.md

@@ -0,0 +1,410 @@
+# GraphQL Client
+
+Execute GraphQL queries and mutations against configured GraphQL endpoints with full type safety and runtime validation.
+
+## Methods
+
+| Method                                                 | Description                                                |
+| ------------------------------------------------------ | ---------------------------------------------------------- |
+| `query<T>(query, schema, variables?, metadata?)`       | Execute a GraphQL query with required schema validation    |
+| `mutation<T>(mutation, schema, variables?, metadata?)` | Execute a GraphQL mutation with required schema validation |
+
+## Usage
+
+### Basic Query
+
+```typescript
+import { api, z, graphql } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_GRAPHQL = "a1b2c3d4-5678-90ab-cdef-graphql00001";
+
+// Schema must include the `data` wrapper that GraphQL returns
+const GetUserResponseSchema = z.object({
+  data: z.object({
+    user: z.object({
+      id: z.string(),
+      name: z.string(),
+      email: z.string().email(),
+    }),
+  }),
+});
+
+export default api({
+  integrations: {
+    graphql: graphql(PROD_GRAPHQL),
+  },
+  name: "GraphQLExample",
+  input: z.object({
+    userId: z.string(),
+  }),
+  output: z.object({
+    user: z.object({
+      id: z.string(),
+      name: z.string(),
+      email: z.string(),
+    }),
+  }),
+  async run(ctx, { userId }) {
+    const result = await ctx.integrations.graphql.query(
+      `query GetUser($id: ID!) {
+        user(id: $id) {
+          id
+          name
+          email
+        }
+      }`,
+      { response: GetUserResponseSchema },
+      { id: userId },
+    );
+
+    // Access data through the data property
+    return { user: result.data.user };
+  },
+});
+```
+
+### Query with List Results
+
+```typescript
+const ListUsersResponseSchema = z.object({
+  data: z.object({
+    users: z.array(
+      z.object({
+        id: z.string(),
+        name: z.string(),
+        role: z.enum(["admin", "user", "guest"]),
+      }),
+    ),
+    totalCount: z.number(),
+  }),
+});
+
+const result = await ctx.integrations.graphql.query(
+  `query ListUsers($limit: Int, $offset: Int) {
+    users(limit: $limit, offset: $offset) {
+      id
+      name
+      role
+    }
+    totalCount
+  }`,
+  { response: ListUsersResponseSchema },
+  { limit: 10, offset: 0 },
+);
+
+console.log(`Found ${result.data.totalCount} users`);
+result.data.users.forEach((user) => {
+  console.log(`${user.name} (${user.role})`);
+});
+```
+
+### Basic Mutation
+
+```typescript
+const CreateUserResponseSchema = z.object({
+  data: z.object({
+    createUser: z.object({
+      id: z.string(),
+      name: z.string(),
+      createdAt: z.string(),
+    }),
+  }),
+});
+
+const result = await graphql.mutation(
+  `mutation CreateUser($input: CreateUserInput!) {
+    createUser(input: $input) {
+      id
+      name
+      createdAt
+    }
+  }`,
+  { response: CreateUserResponseSchema },
+  {
+    input: {
+      name: "John Doe",
+      email: "john@example.com",
+    },
+  },
+);
+
+console.log(`Created user: ${result.data.createUser.id}`);
+```
+
+### Mutation with Complex Input Types
+
+```typescript
+const UpdateOrderResponseSchema = z.object({
+  data: z.object({
+    updateOrder: z.object({
+      id: z.string(),
+      status: z.string(),
+      items: z.array(
+        z.object({
+          productId: z.string(),
+          quantity: z.number(),
+        }),
+      ),
+    }),
+  }),
+});
+
+const result = await graphql.mutation(
+  `mutation UpdateOrder($id: ID!, $input: UpdateOrderInput!) {
+    updateOrder(id: $id, input: $input) {
+      id
+      status
+      items {
+        productId
+        quantity
+      }
+    }
+  }`,
+  { response: UpdateOrderResponseSchema },
+  {
+    id: "order-123",
+    input: {
+      status: "shipped",
+      items: [
+        { productId: "prod-1", quantity: 2 },
+        { productId: "prod-2", quantity: 1 },
+      ],
+    },
+  },
+);
+```
+
+### Handling Optional and Nullable Fields
+
+```typescript
+const UserProfileResponseSchema = z.object({
+  data: z.object({
+    user: z.object({
+      id: z.string(),
+      name: z.string(),
+      bio: z.string().nullable(), // Field can be null
+      avatar: z.string().optional(), // Field may not be present
+      settings: z
+        .object({
+          theme: z.string(),
+          notifications: z.boolean(),
+        })
+        .nullable(), // Entire object can be null
+    }),
+  }),
+});
+```
+
+## 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
+
+### Response Must Include `data` Wrapper
+
+GraphQL responses are wrapped in a `data` object. Your schema must account for this:
+
+```typescript
+// WRONG - Missing data wrapper
+const schema = z.object({
+  user: z.object({
+    id: z.string(),
+    name: z.string(),
+  }),
+});
+
+// CORRECT - Include data wrapper
+const schema = z.object({
+  data: z.object({
+    user: z.object({
+      id: z.string(),
+      name: z.string(),
+    }),
+  }),
+});
+```
+
+### Access Results Through `data` Property
+
+The result object includes the `data` wrapper, so you must access fields through it:
+
+```typescript
+const result = await ctx.integrations.graphql.query(
+  `query { user(id: "123") { name } }`,
+  {
+    response: ResponseSchema,
+  },
+);
+
+// WRONG - Direct access
+console.log(result.user.name); // undefined or error
+
+// CORRECT - Access through data
+console.log(result.data.user.name);
+```
+
+### Schema Parameter is Required
+
+Both `query()` and `mutation()` require a schema for validation:
+
+```typescript
+// WRONG - Missing schema
+const result = await ctx.integrations.graphql.query(
+  `query { users { id } }`,
+  { id: "123" }, // This looks like variables, not schema
+);
+
+// CORRECT - Schema is required
+const result = await ctx.integrations.graphql.query(
+  `query GetUser($id: ID!) { user(id: $id) { id } }`,
+  { response: ResponseSchema }, // Schema is required
+  { id: "123" }, // Variables are optional third parameter
+);
+```
+
+### Handling GraphQL Errors
+
+GraphQL errors are returned in the response, not thrown as exceptions. Consider including them in your schema:
+
+```typescript
+const ResponseSchema = z.object({
+  data: z
+    .object({
+      user: z.object({
+        id: z.string(),
+        name: z.string(),
+      }),
+    })
+    .nullable(), // data can be null if errors occur
+  errors: z
+    .array(
+      z.object({
+        message: z.string(),
+        locations: z
+          .array(
+            z.object({
+              line: z.number(),
+              column: z.number(),
+            }),
+          )
+          .optional(),
+        path: z.array(z.union([z.string(), z.number()])).optional(),
+      }),
+    )
+    .optional(),
+});
+
+const result = await ctx.integrations.graphql.query(query, {
+  response: ResponseSchema,
+});
+
+if (result.errors && result.errors.length > 0) {
+  console.error("GraphQL errors:", result.errors);
+}
+
+if (result.data) {
+  console.log("User:", result.data.user);
+}
+```
+
+### Variables Must Match GraphQL Types
+
+Ensure variable values match the expected GraphQL types:
+
+```typescript
+// GraphQL schema expects: query GetUser($id: ID!)
+
+// WRONG - Number instead of string
+const result = await ctx.integrations.graphql.query(
+  query,
+  { response: schema },
+  { id: 123 },
+);
+
+// CORRECT - ID type expects string
+const result = await ctx.integrations.graphql.query(
+  query,
+  { response: schema },
+  { id: "123" },
+);
+```
+
+### Handling Unions and Interfaces
+
+For GraphQL unions or interfaces, use discriminated unions in Zod:
+
+```typescript
+const SearchResultSchema = z.object({
+  data: z.object({
+    search: z.array(
+      z.discriminatedUnion("__typename", [
+        z.object({
+          __typename: z.literal("User"),
+          id: z.string(),
+          name: z.string(),
+        }),
+        z.object({
+          __typename: z.literal("Post"),
+          id: z.string(),
+          title: z.string(),
+        }),
+      ]),
+    ),
+  }),
+});
+
+const result = await ctx.integrations.graphql.query(
+  `query Search($term: String!) {
+    search(term: $term) {
+      __typename
+      ... on User {
+        id
+        name
+      }
+      ... on Post {
+        id
+        title
+      }
+    }
+  }`,
+  { response: SearchResultSchema },
+  { term: "john" },
+);
+
+result.data.search.forEach((item) => {
+  if (item.__typename === "User") {
+    console.log(`User: ${item.name}`);
+  } else {
+    console.log(`Post: ${item.title}`);
+  }
+});
+```
+
+## Error Handling
+
+### RestApiValidationError
+
+Thrown when the GraphQL response fails schema validation:
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await ctx.integrations.graphql.query(query, {
+    response: schema,
+  });
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.message);
+    console.error("Zod errors:", error.details.zodError);
+    console.error("Actual response:", error.details.data);
+  }
+}
+```
+
+## API Reference
+
+- [GraphQL Specification](https://spec.graphql.org/)
+- [GraphQL Learn](https://graphql.org/learn/)

package/src/integrations/graphql/client.ts

@@ -0,0 +1,23 @@
+/**
+ * GraphQL client implementation.
+ *
+ * Uses the proto-generated GraphQL Plugin type from @superblocksteam/types.
+ * GraphQL integrations use the GraphQL Integration plugin under the hood.
+ */
+
+import { GraphQLIntegrationClient } from "../base/graphql-integration-client.js";
+import type { GraphQLClient } from "./types.js";
+
+/**
+ * Internal implementation of GraphQLClient.
+ *
+ * Extends GraphQLIntegrationClient to inherit query() and mutation() methods.
+ * This implementation communicates with the orchestrator to execute
+ * GraphQL operations. At runtime, the orchestrator handles authentication
+ * and GraphQL request execution.
+ */
+export class GraphQLClientImpl
+  extends GraphQLIntegrationClient
+  implements GraphQLClient {
+  // Inherits: name, pluginId, config, executeQuery, query(), mutation()
+}

package/src/integrations/graphql/index.ts

@@ -0,0 +1,2 @@
+export { GraphQLClientImpl } from "./client.js";
+export type { GraphQLClient } from "./types.js";

package/src/integrations/graphql/types.ts

@@ -0,0 +1,131 @@
+/**
+ * GraphQL client types.
+ */
+
+import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
+import type { z } from "zod";
+
+/**
+ * GraphQL client for executing queries and mutations.
+ *
+ * Provides methods for executing GraphQL operations against configured
+ * GraphQL endpoints with required Zod schema validation.
+ *
+ * @example
+ * ```typescript
+ * // 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)
+ * const ResponseSchema = z.object({
+ *   data: z.object({
+ *     user: z.object({
+ *       id: z.string(),
+ *       name: z.string(),
+ *       email: z.string(),
+ *     }),
+ *   }),
+ * });
+ *
+ * const result = await graphql.query(
+ *   `query GetUser($id: ID!) {
+ *     user(id: $id) {
+ *       id
+ *       name
+ *       email
+ *     }
+ *   }`,
+ *   { response: ResponseSchema },
+ *   { id: '123' }
+ * );
+ * // Access data explicitly
+ * console.log(result.data.user.name);
+ *
+ * // Execute a mutation
+ * const MutationResponseSchema = z.object({
+ *   data: z.object({
+ *     createUser: z.object({
+ *       id: z.string(),
+ *     }),
+ *   }),
+ * });
+ *
+ * await graphql.mutation(
+ *   `mutation CreateUser($name: String!) {
+ *     createUser(name: $name) {
+ *       id
+ *     }
+ *   }`,
+ *   { response: MutationResponseSchema },
+ *   { name: 'John Doe' }
+ * );
+ * ```
+ */
+export interface GraphQLClient extends BaseIntegrationClient {
+  /**
+   * Execute a GraphQL query.
+   *
+   * @param query - GraphQL query string
+   * @param schema - Zod schema for response validation (REQUIRED)
+   * @param variables - Optional variables for the query. **Note:** since both `variables` and
+   *   `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
+   * @returns Validated query result
+   *
+   * @example
+   * ```typescript
+   * // Schema validates full GraphQL response (including data wrapper)
+   * const result = await graphql.query(
+   *   'query { users { id name } }',
+   *   { response: z.object({
+   *     data: z.object({
+   *       users: z.array(z.object({ id: z.string(), name: z.string() }))
+   *     })
+   *   }) }
+   * );
+   * // result.data.users is typed as Array<{ id: string; name: string }>
+   * ```
+   */
+  query<TResponse>(
+    query: string,
+    schema: { response: z.ZodSchema<TResponse> },
+    variables?: Record<string, unknown>,
+    metadata?: TraceMetadata,
+  ): Promise<TResponse>;
+
+  /**
+   * Execute a GraphQL mutation.
+   *
+   * @param mutation - GraphQL mutation string
+   * @param schema - Zod schema for response validation (REQUIRED)
+   * @param variables - Optional variables for the mutation. **Note:** since both `variables` and
+   *   `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
+   * @returns Validated mutation result
+   *
+   * @example
+   * ```typescript
+   * // Schema validates full GraphQL response (including data wrapper)
+   * const result = await graphql.mutation(
+   *   'mutation CreateUser($name: String!) { createUser(name: $name) { id } }',
+   *   { response: z.object({
+   *     data: z.object({
+   *       createUser: z.object({ id: z.string() })
+   *     })
+   *   }) },
+   *   { name: 'John' }
+   * );
+   * // result.data.createUser is typed as { id: string }
+   * ```
+   */
+  mutation<TResponse>(
+    mutation: string,
+    schema: { response: z.ZodSchema<TResponse> },
+    variables?: Record<string, unknown>,
+    metadata?: TraceMetadata,
+  ): Promise<TResponse>;
+}