feat(graphql): expose response headers and X-GraphQL-Keys parser

[AssisrMatheus]

Summary

@perimetre/graphql minor (changeset included).

• Every executor (createApqExecutor, createTrustedDocumentExecutor, createPassthroughExecutor, and createWpGraphql().executeGraphqlRequest) now also exposes .withMeta(document, variables?, options?), resolving to { data, headers, transport, durationMs }. headers are the raw fetch Response.headers of the response that produced data — after an APQ miss that is the register POST's (or the fallback POST's), never the GET's that missed. The plain call is unchanged and still resolves to data only. New GraphqlExecutor type; ExecuteGraphqlRequest is untouched so custom executors keep compiling.
• GraphqlRequestPlugin.onResponse now receives headers and transport next to data / error / durationMs (GraphqlResponseOutcome). Headers are also recovered from a thrown graphql-request ClientError; undefined only when no response arrived.
• POST paths (mutations, unhashed documents, every fallback, passthrough) go through client.rawRequest so they carry headers too. Same middlewares and errorPolicy as client.request.
• New @perimetre/graphql/keys subpath (also re-exported from the root): parseGraphqlKeys(headers | string) → { nodeIds, lists, skipped, operation?, queryId?, root? }. Pure, dependency-free, never throws. lists / skipped stay in wire form (list:post, skipped:post) since those are the keys WPGraphQL Smart Cache purges by.
• Executor internals exported for custom transports: createExecutor, postViaClient, GraphqlTransport*, GraphqlResponseMeta, GraphqlExecuteResult, ExecuteGraphqlRequestWithMeta.
• Bun unit tests under packages/graphql/src/__tests__ (31 tests), wired as pnpm --filter @perimetre/graphql test and run before tsdown on build.

Also in this PR

• middlewares.ts: the two fetch wrappers are cast as typeof fetch — bun-types' typeof fetch requires preconnect, which a plain wrapper never implements. No behaviour change; tsc -p src/__tests__/tsconfig.json is now clean.
• CLAUDE.md, AGENTS.md, README.md still pointed at the LLMs/*.md guides deleted in 48f6c3e. They now point at the ai-toolkit perimetre-apps plugin (app-code-review/references/*.md, app-caching, seo).

Usage

// src/server/cms/cache.ts — a Next.js 'use cache: remote' reader tagged with what the CMS resolved
import { cacheLife, cacheTag } from 'next/cache';
import { parseGraphqlKeys } from '@perimetre/graphql/keys';
import { executeGraphqlRequest } from '@/server/graphql';

export async function getPage(uri: string) {
  'use cache: remote';
  cacheLife('max');
  const { data, headers } = await executeGraphqlRequest.withMeta(GetPageDocument, { uri });
  const { nodeIds, lists, skipped } = parseGraphqlKeys(headers);
  cacheTag('cms', ...nodeIds, ...lists, ...skipped);
  return data;
}

Test plan

• pnpm turbo run lint typecheck build --filter=@perimetre/graphql --force — 4/4 tasks successful
• pnpm --filter @perimetre/graphql test — 31 pass, 0 fail, 113 expect() calls, 4 files
• tsc -p packages/graphql/src/__tests__/tsconfig.json — exit 0 (previously 2 preconnect errors)
• pnpm install --frozen-lockfile — lockfile in sync

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
framework-ui	Ready	Preview	Oct 1, 2026 2:10pm UTC