@apiquest/plugin-graphql 1.0.2

package/README.md

@@ -0,0 +1,125 @@
+# @apiquest/plugin-graphql
+
+GraphQL protocol plugin for ApiQuest. Provides support for GraphQL queries, mutations, and subscriptions with variable support.
+
+## Installation
+
+```bash
+npm install -g @apiquest/plugin-graphql
+```
+
+## Features
+
+- GraphQL queries and mutations
+- Variable support
+- Operation name specification (for multi-operation documents)
+- Custom HTTP headers
+- Fragment support
+- Authentication integration (via `@apiquest/plugin-auth`)
+
+## Usage
+
+Set the collection protocol to `graphql`:
+
+```json
+{
+  "$schema": "https://apiquest.net/schemas/collection-v1.0.json",
+  "protocol": "graphql",
+  "items": [
+    {
+      "type": "request",
+      "id": "get-user",
+      "name": "Get User by ID",
+      "data": {
+        "url": "https://api.example.com/graphql",
+        "query": "query GetUser($id: ID!) {\n  user(id: $id) {\n    id\n    name\n    email\n  }\n}",
+        "variables": {
+          "id": "{{userId}}"
+        }
+      }
+    }
+  ]
+}
+```
+
+### Mutation Example
+
+```json
+{
+  "type": "request",
+  "id": "create-user",
+  "name": "Create User",
+  "data": {
+    "url": "https://api.example.com/graphql",
+    "mutation": "mutation CreateUser($input: UserInput!) {\n  createUser(input: $input) {\n    id\n    name\n    email\n  }\n}",
+    "variables": {
+      "input": {
+        "name": "John Doe",
+        "email": "john@example.com"
+      }
+    }
+  }
+}
+```
+
+### With Custom Headers
+
+```json
+{
+  "data": {
+    "url": "https://api.example.com/graphql",
+    "query": "{ users { id name } }",
+    "headers": {
+      "x-api-version": "2024-01-01",
+      "x-request-id": "{{$guid}}"
+    }
+  }
+}
+```
+
+### Multi-Operation Documents
+
+```json
+{
+  "data": {
+    "url": "https://api.example.com/graphql",
+    "query": "query GetUser { user { id } }\nquery GetPosts { posts { id } }",
+    "operationName": "GetUser"
+  }
+}
+```
+
+## Response Handling
+
+Access GraphQL response data in post-request scripts:
+
+```javascript
+quest.test('Query successful', () => {
+  expect(quest.response.status).to.equal(200);
+});
+
+quest.test('No GraphQL errors', () => {
+  const body = quest.response.json();
+  expect(body.errors).to.be.undefined;
+});
+
+quest.test('User data returned', () => {
+  const body = quest.response.json();
+  expect(body.data.user).to.be.an('object');
+  expect(body.data.user.id).to.be.a('string');
+});
+```
+
+## Compatibility
+
+- **Authentication:** Works with `@apiquest/plugin-auth` for Bearer, Basic, OAuth2, API Key
+- **Node.js:** Requires Node.js 20+
+
+## Documentation
+
+- [Fracture Documentation](https://apiquest.net/docs/fracture)
+- [Schema Reference](https://apiquest.net/schemas/collection-v1.0.json)
+
+## License
+
+Dual-licensed under AGPL-3.0-or-later and commercial license. See LICENSE.txt for details.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@apiquest/plugin-graphql",
+  "version": "1.0.2",
+  "description": "GraphQL protocol plugin for ApiQuest",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "rollup -c && tsc --emitDeclarationOnly",
+    "dev": "rollup -c --watch",
+    "test": "vitest"
+  },
+  "keywords": [
+    "apiquest",
+    "graphql",
+    "plugin"
+  ],
+  "author": "",
+  "license": "AGPL-3.0-or-later",
+  "dependencies": {
+    "@apiquest/types": "workspace:*",
+    "got": "^14.6.6"
+  },
+  "devDependencies": {
+    "@apiquest/types": "workspace:*",
+    "@rollup/plugin-commonjs": "^25.0.0",
+    "@rollup/plugin-node-resolve": "^15.0.0",
+    "@rollup/plugin-typescript": "^11.0.0",
+    "@types/node": "^20.10.6",
+    "rollup": "^4.0.0",
+    "typescript": "^5.3.3",
+    "vitest": "^4.0.18"
+  },
+  "apiquest": {
+    "type": "protocol",
+    "runtime": [
+      "fracture"
+    ],
+    "capabilities": {
+      "provides": {
+        "protocols": [
+          "graphql"
+        ]
+      },
+      "supports": {
+        "authTypes": [
+          "bearer",
+          "basic",
+          "oauth2",
+          "apikey"
+        ],
+        "strictAuthList": false
+      }
+    }
+  }
+}

package/rollup.config.js

@@ -0,0 +1,31 @@
+import typescript from '@rollup/plugin-typescript';
+import resolve from '@rollup/plugin-node-resolve';
+import commonjs from '@rollup/plugin-commonjs';
+
+export default {
+  input: 'src/index.ts',
+  output: {
+    file: 'dist/index.js',
+    format: 'esm',
+    sourcemap: true,
+  },
+  external: [
+    // Externalize peer dependencies
+    '@apiquest/fracture',
+  ],
+  plugins: [
+    // Resolve node modules
+    resolve({
+      preferBuiltins: true,  // Prefer Node.js built-in modules
+      exportConditions: ['node', 'import', 'default'],
+    }),
+    // Convert CommonJS to ESM (for any CJS dependencies)
+    commonjs(),
+    // Compile TypeScript
+    typescript({
+      tsconfig: './tsconfig.json',
+      sourceMap: true,
+      declaration: false, // We'll use tsc for declarations
+    }),
+  ],
+};

package/src/index.ts

@@ -0,0 +1,291 @@
+import got, { OptionsOfTextResponseBody, Response, RequestError } from 'got';
+import type { IProtocolPlugin, Request, ExecutionContext, ProtocolResponse, ValidationResult, ValidationError, RuntimeOptions, ILogger } from '@apiquest/types';
+
+// Helper functions for string validation
+function isNullOrEmpty(value: string | null | undefined): boolean {
+  return value === null || value === undefined || value === '';
+}
+
+function isNullOrWhitespace(value: string | null | undefined): boolean {
+  return value === null || value === undefined || value.trim() === '';
+}
+
+export const graphqlPlugin: IProtocolPlugin = {
+  name: 'GraphQL',
+  version: '1.0.0',
+  description: 'GraphQL query and mutation support',
+  protocols: ['graphql'],
+  supportedAuthTypes: ['bearer', 'basic', 'apikey', 'oauth2'],
+  strictAuthList: false,
+  dataSchema: {
+    type: 'object',
+    required: ['url'],
+    properties: {
+      url: {
+        type: 'string',
+        description: 'GraphQL endpoint URL'
+      },
+      query: {
+        type: 'string',
+        description: 'GraphQL query'
+      },
+      mutation: {
+        type: 'string',
+        description: 'GraphQL mutation'
+      },
+      variables: {
+        type: 'object',
+        description: 'GraphQL variables'
+      },
+      operationName: {
+        type: 'string',
+        description: 'Operation name (for multi-operation documents)'
+      },
+      headers: {
+        type: 'object',
+        description: 'Custom HTTP headers',
+        additionalProperties: { type: 'string' }
+      }
+    }
+  },
+
+  // Options schema for runtime configuration
+  optionsSchema: {
+    timeout: {
+      type: 'number',
+      default: 30000,
+      description: 'Request timeout in milliseconds'
+    },
+    validateCertificates: {
+      type: 'boolean',
+      default: true,
+      description: 'Validate SSL/TLS certificates'
+    }
+  },
+
+  validate(request: Request, options: RuntimeOptions): ValidationResult {
+    const errors: ValidationError[] = [];
+
+    // Check URL
+    if (typeof request.data.url !== 'string' || isNullOrWhitespace(request.data.url)) {
+      errors.push({
+        message: 'GraphQL endpoint URL is required',
+        location: '',
+        source: 'protocol'
+      });
+    }
+
+    // Check that either query or mutation is present
+    const hasQuery = typeof request.data.query === 'string' && !isNullOrEmpty(request.data.query);
+    const hasMutation = typeof request.data.mutation === 'string' && !isNullOrEmpty(request.data.mutation);
+
+    if (!hasQuery && !hasMutation) {
+      errors.push({
+        message: 'Either query or mutation is required',
+        location: '',
+        source: 'protocol'
+      });
+    }
+
+    if (hasQuery && hasMutation) {
+      errors.push({
+        message: 'Cannot have both query and mutation - use one or the other',
+        location: '',
+        source: 'protocol'
+      });
+    }
+
+    if (errors.length > 0) {
+      return {
+        valid: false,
+        errors
+      };
+    }
+
+    return { valid: true };
+  },
+
+  async execute(
+    request: Request,
+    context: ExecutionContext,
+    options: RuntimeOptions,
+    emitEvent?: (eventName: string, eventData: unknown) => Promise<void>,
+    logger?: ILogger
+  ): Promise<ProtocolResponse> {
+    const startTime = Date.now();
+    const url = String(request.data.url ?? '');
+
+    try {
+      if (isNullOrWhitespace(url)) {
+        logger?.error('GraphQL request missing URL');
+        throw new Error('GraphQL endpoint URL is required');
+      }
+
+      // Request configuration
+      const operation = request.data.query ?? request.data.mutation;
+
+      const graphqlBody: {
+        query: string;
+        variables?: Record<string, unknown>;
+        operationName?: string;
+      } = {
+        query: String(operation),
+      };
+
+      if (request.data.variables !== undefined && request.data.variables !== null) {
+        graphqlBody.variables = request.data.variables as Record<string, unknown>;
+      }
+
+      if (request.data.operationName !== undefined && request.data.operationName !== null) {
+        graphqlBody.operationName = String(request.data.operationName);
+      }
+
+      // Headers
+      const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+      };
+
+      if (typeof request.data.headers === 'object' && request.data.headers !== null) {
+        Object.entries(request.data.headers as Record<string, unknown>).forEach(([key, value]) => {
+          headers[key] = String(value);
+        });
+      }
+
+      const graphqlOptions: Record<string, unknown> = (options.plugins?.graphql as Record<string, unknown> | null | undefined) ?? {};
+      const graphqlTimeout = typeof graphqlOptions.timeout === 'number' ? graphqlOptions.timeout : null;
+      const timeout = options.timeout?.request ?? graphqlTimeout ?? 60000;
+      const graphqlValidateCerts = typeof graphqlOptions.validateCertificates === 'boolean' ? graphqlOptions.validateCertificates : null;
+      const validateCerts = options.ssl?.validateCertificates ?? graphqlValidateCerts ?? true;
+
+      logger?.debug('GraphQL request options resolved', { timeout, validateCerts });
+
+      // Cookie handling
+      const cookieHeader = context.cookieJar.getCookieHeader(url);
+      if (cookieHeader !== null) {
+        headers['Cookie'] = cookieHeader;
+        logger?.trace('Cookie header applied', { url });
+      }
+
+      const gotOptions: OptionsOfTextResponseBody = {
+        method: 'POST',
+        headers: { ...headers },
+        json: graphqlBody,
+        throwHttpErrors: false,
+        timeout: { request: timeout },
+        followRedirect: true,
+        https: {
+          rejectUnauthorized: validateCerts
+        }
+      };
+
+      // Dispatch
+      logger?.debug('GraphQL request dispatch', { url });
+      const response: Response = await got(url, gotOptions);
+      const duration = Date.now() - startTime;
+
+      // Response normalization
+      const normalizedHeaders: Record<string, string | string[]> = {};
+      if (typeof response.headers === 'object' && response.headers !== null) {
+        Object.entries(response.headers).forEach(([key, value]) => {
+          if (Array.isArray(value)) {
+            normalizedHeaders[key.toLowerCase()] = value.map(item => String(item));
+          } else if (value !== undefined && value !== null) {
+            normalizedHeaders[key.toLowerCase()] = String(value);
+          }
+        });
+      }
+
+      if (normalizedHeaders['set-cookie'] !== undefined) {
+        context.cookieJar.store(normalizedHeaders['set-cookie'], url);
+        logger?.trace('Cookies stored from response', { url });
+      }
+
+      let errorMsg: string | undefined = undefined;
+      try {
+        const responseData = JSON.parse(String(response.body)) as { errors?: Array<{ message: string }> };
+        if (responseData?.errors !== undefined && responseData.errors !== null && responseData.errors.length > 0) {
+          errorMsg = `GraphQL errors: ${responseData.errors.map((e: { message: string }) => e.message).join(', ')}`;
+        }
+      } catch (parseError) {
+        logger?.trace('GraphQL response body not JSON');
+      }
+
+      logger?.debug('GraphQL response received', { status: response.statusCode, duration });
+
+      return {
+        status: response.statusCode,
+        statusText: (response.statusMessage !== null && response.statusMessage !== undefined && response.statusMessage.length > 0) ? response.statusMessage : '',
+        headers: normalizedHeaders,
+        body: String(response.body),
+        duration,
+        error: errorMsg
+      };
+    } catch (err) {
+      const duration = Date.now() - startTime;
+      const error = err as RequestError;
+
+      if (error instanceof RequestError) {
+        if (error.response !== undefined) {
+          const normalizedHeaders: Record<string, string | string[]> = {};
+          if (typeof error.response.headers === 'object' && error.response.headers !== null) {
+            Object.entries(error.response.headers).forEach(([key, value]) => {
+              if (Array.isArray(value)) {
+                normalizedHeaders[key.toLowerCase()] = value.map(item => String(item));
+              } else if (value !== undefined && value !== null) {
+                normalizedHeaders[key.toLowerCase()] = String(value);
+              }
+            });
+          }
+
+          if (normalizedHeaders['set-cookie'] !== undefined) {
+            context.cookieJar.store(normalizedHeaders['set-cookie'], url);
+            logger?.trace('Cookies stored from error response', { url });
+          }
+
+          let errorResponseMsg: string | undefined = undefined;
+          try {
+            const responseData = JSON.parse(String(error.response.body)) as { errors?: Array<{ message: string }> };
+            if (responseData?.errors !== undefined && responseData.errors !== null && responseData.errors.length > 0) {
+              errorResponseMsg = `GraphQL errors: ${responseData.errors.map((e: { message: string }) => e.message).join(', ')}`;
+            }
+          } catch (parseError) {
+            logger?.trace('GraphQL error response body not JSON');
+          }
+
+          logger?.debug('GraphQL error response received', { status: error.response.statusCode, duration });
+
+          return {
+            status: error.response.statusCode,
+            statusText: (error.response.statusMessage !== null && error.response.statusMessage !== undefined && error.response.statusMessage.length > 0) ? error.response.statusMessage : '',
+            headers: normalizedHeaders,
+            body: String(error.response.body),
+            duration,
+            error: errorResponseMsg
+          };
+        } else {
+          logger?.warn('GraphQL network error', { message: error.message, duration });
+          return {
+            status: 0,
+            statusText: 'Network Error',
+            headers: {},
+            body: '',
+            duration,
+            error: !isNullOrEmpty(error.message) ? error.message : 'Network request failed'
+          };
+        }
+      }
+
+      logger?.error('GraphQL unexpected error', { error: err instanceof Error ? err.message : String(err), duration });
+      return {
+        status: 0,
+        statusText: 'Error',
+        headers: {},
+        body: '',
+        duration,
+        error: err instanceof Error ? err.message : String(err)
+      };
+    }
+  },
+};
+
+export default graphqlPlugin;

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022"],
+    "moduleResolution": "bundler",
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/tsconfig.test.json

@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["tests/**/*"],
+  "exclude": []
+}

package/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+    },
+  },
+});