@glubean/graphql 0.1.7 → 0.2.2

package/dist/contract/types.d.ts

@@ -0,0 +1,358 @@
+/**
+ * GraphQL contract types.
+ *
+ * User-facing authoring types + adapter-level payload types for the
+ * GraphQL contract adapter (single-package model — see
+ * `internal/40-discovery/proposals/contract-grpc-graphql-expansion.md` §6.1).
+ *
+ * Structure mirrors `packages/grpc/src/contract/types.ts` where applicable,
+ * with GraphQL-specific design:
+ *
+ *   - **Target model:** GraphQL typically has a single `/graphql` endpoint,
+ *     so `endpoint` is spec-level (not per-case). `endpoint` is
+ *     **projection-only** in Phase 1 — it travels on `meta.endpoint`
+ *     for markdown / scanner / MCP display, but the adapter dispatches
+ *     through the supplied `GraphQLClient` whose endpoint was fixed at
+ *     construction time. Multi-endpoint is expressed by multiple
+ *     clients, not by per-contract endpoint strings. Contract identity
+ *     = `contractId + caseKey`, NOT operationName (proposal §3.2).
+ *
+ *   - **Selection-set-per-case coupling (proposal §3.2 b):** unlike
+ *     HTTP/gRPC where response shape is determined by endpoint/method,
+ *     GraphQL response shape is determined by the *query string* in each
+ *     case. Each case therefore carries its own `query` + `variables` +
+ *     `responseSchema` triple. A contract-level `responseSchema` may still
+ *     apply if all cases share the same selection set (rare).
+ *
+ *   - **Explicit type declarations (proposal §7b.2):** `types` is a
+ *     deferred projection hint for Phase 2 SDL generation. Phase 1 stores
+ *     it as opaque metadata — adapter / scanner carry it forward so
+ *     projection tooling can consume it later.
+ *
+ *   - **3-layer classifyFailure (proposal §3.2 c):**
+ *       transport (HTTP status 4xx/5xx/network)
+ *       → payload errors (GraphQL `errors` array, HTTP 200)
+ *       → data shape mismatch (schema validation on `data`)
+ *
+ *   - **Phase 1 scope:** query + mutation only (subscriptions deferred
+ *     to Phase 2 streaming work).
+ */
+import type { SchemaLike, TestContext } from "@glubean/sdk";
+import type { BaseCaseSpec, Extensions } from "@glubean/sdk";
+import type { GraphQLClient, GraphQLError } from "../index.js";
+/**
+ * Field-map declaration for a GraphQL type. Kept minimal and stringly-typed
+ * so the declaration surface can evolve without a breaking bump.
+ *
+ * Phase 1 stores this as opaque metadata. Phase 2 `.gql` projection will
+ * consume it — see proposal §7b.2.
+ *
+ * @example
+ * ```ts
+ * types: {
+ *   User: { id: "ID!", name: "String!", orders: "[Order!]!" },
+ *   Order: { id: "ID!", total: "Float!" },
+ * }
+ * ```
+ */
+export type GraphqlTypeDef = Record<string, string>;
+/**
+ * Map of type-name → field declaration. Optional; when present, projection
+ * tools can emit SDL alongside the per-case markdown.
+ */
+export type GraphqlTypeDefs = Record<string, GraphqlTypeDef>;
+/**
+ * Defaults for a GraphQL contract instance
+ * (`contract.graphql.with("name", {...})`).
+ *
+ * The `client` binding is the primary reason to use `.with`: supplying a
+ * pre-configured GraphQLClient lets the adapter call through it without
+ * rebuilding per contract. The GraphQLClient is itself bound to an
+ * endpoint at construction time (via `createGraphQLClient(http, { endpoint })`
+ * or the `graphql({ endpoint })` plugin factory) — the contract layer
+ * does not override that at runtime.
+ */
+export interface GraphqlContractDefaults {
+    /** Default GraphQL client for all contracts in this instance. */
+    client?: GraphQLClient;
+    /**
+     * Default endpoint **for projection / display only.**
+     *
+     * This value travels on the projection meta (`meta.endpoint`) so the
+     * scanner, `glubean contracts` markdown, and MCP surfaces can show
+     * which endpoint the contract points at. At runtime the adapter
+     * dispatches through the supplied `client`, whose endpoint was fixed
+     * at client-construction time. Changing `endpoint` here does **not**
+     * redirect the live call — use a different client instead
+     * (e.g. `api_v1 = graphql({endpoint: "/v1/graphql"})`,
+     *  `api_v2 = graphql({endpoint: "/v2/graphql"})`).
+     */
+    endpoint?: string;
+    /** Tags inherited by all contracts in this instance. */
+    tags?: string[];
+    /** Default feature grouping key. */
+    feature?: string;
+    /** Default headers merged into every case. */
+    headers?: Record<string, string>;
+    /** OpenAPI-style extensions (x-* keys). Inherited by all contracts. */
+    extensions?: Extensions;
+}
+export interface GraphqlContractExample<T = unknown> {
+    value: T;
+    summary?: string;
+    description?: string;
+}
+/**
+ * Sentinel values for the `errors` expectation.
+ *
+ * - `"absent"` — `errors` must be undefined or empty (strict success).
+ * - `"any"` — accept any errors (only useful with `data` partial match).
+ * - `GraphQLError[]` — match each listed error by `message` / `extensions.code`
+ *   (partial — unlisted errors still fail unless length check relaxed).
+ */
+export type GraphqlErrorsExpect = "absent" | "any" | Array<Partial<GraphQLError>>;
+/**
+ * Response expectations for a GraphQL case.
+ *
+ * GraphQL success is nuanced: `errors` may be present alongside `data`
+ * (partial success). The adapter's 3-layer `classifyFailure` handles the
+ * interpretation. At expect-time:
+ *
+ * - `data` — partial shape to match against `response.data`.
+ * - `errors` — sentinel or array (see `GraphqlErrorsExpect`).
+ * - `schema` — per-case Zod/Valibot schema for `data` (selection-set
+ *   coupling lives here — each case owns its response shape).
+ * - `httpStatus` — transport-layer assertion (4xx/5xx for negative cases).
+ */
+export interface GraphqlContractExpect<T = unknown> {
+    /** Expected HTTP status (from the underlying POST). Default: 200. */
+    httpStatus?: number;
+    /** Per-case response schema (selection-set-coupled). */
+    schema?: SchemaLike<T>;
+    /** Partial expected `data` shape (toMatchObject semantics). */
+    data?: Partial<T>;
+    /** Assertion on GraphQL `errors` array. Default: `"absent"`. */
+    errors?: GraphqlErrorsExpect;
+    /** Schema for response headers. */
+    headers?: SchemaLike<Record<string, string | string[]>>;
+    /** Partial expected response headers. */
+    headersMatch?: Record<string, string>;
+    /** Single response example (for docs / projection). */
+    example?: T;
+    /** Named response examples. */
+    examples?: Record<string, GraphqlContractExample<T>>;
+}
+/**
+ * One case on a GraphQL contract.
+ *
+ * Each case owns its own `query` string — the selection-set is
+ * per-case (proposal §3.2 b). Function-valued fields (`variables`,
+ * `headers`) reference case-local setup state; in flow mode these are
+ * rejected by `validateCaseForFlow`, same discipline as HTTP.
+ */
+export interface GraphqlContractCase<Vars = Record<string, unknown>, Res = unknown, S = void> extends BaseCaseSpec {
+    /** Per-case client override. */
+    client?: GraphQLClient;
+    /** Why this case exists — required. */
+    description: string;
+    /**
+     * Operation type. Defaults to `"query"` when omitted.
+     * Phase 1: `query | mutation`. `subscription` is Phase 2 (streaming).
+     */
+    operation?: "query" | "mutation";
+    /**
+     * GraphQL document. Required per case (selection-set is per-case).
+     *
+     * Can be authored inline, via the `gql` tagged template, or loaded from
+     * a `.gql` file via `fromGql()`.
+     */
+    query: string;
+    /** Optional operationName override. If omitted, parsed from `query`. */
+    operationName?: string;
+    /** Expected response. */
+    expect?: GraphqlContractExpect<Res>;
+    /**
+     * Variables. Object shorthand or a function of setup state.
+     * Merged deep-style over `defaults.variables` → `spec.defaultVariables`.
+     */
+    variables?: Vars | ((state: S) => Vars);
+    /** Per-call headers (merged with instance + contract defaults). */
+    headers?: Record<string, string> | ((state: S) => Record<string, string>);
+    /** Setup runs before the call. Return value flows to variables/headers fn + teardown. */
+    setup?: (ctx: TestContext) => Promise<S>;
+    /** Teardown runs after verify, even on failure. */
+    teardown?: (ctx: TestContext, state: S) => Promise<void>;
+    /** Business-logic verify — runs after transport + schema + data match. */
+    verify?: (ctx: TestContext, res: GraphqlCaseResult<Res>) => void | Promise<void>;
+}
+/**
+ * Result of running a single case. This is also the `CaseOutput` shape that
+ * flow `step.out(state, res)` lens receives.
+ *
+ * Mirrors `GraphQLResult<T>` from the transport layer (CG-10) plus the
+ * parsed `operationName` for display/routing. Kept as a distinct type so
+ * adapter-layer additions (e.g. assertion diagnostics) can grow
+ * independently of the transport envelope.
+ */
+export interface GraphqlCaseResult<Res = unknown> {
+    /** Decoded `data` field (null if all fields errored or transport failed). */
+    data: Res | null;
+    /** GraphQL `errors` array (undefined when absent). */
+    errors?: GraphQLError[];
+    /** GraphQL `extensions` (server-side tracing/cost/etc). */
+    extensions?: Record<string, unknown>;
+    /** HTTP status from the underlying POST. */
+    httpStatus: number;
+    /** Response headers (lowercased keys). */
+    headers: Record<string, string | string[]>;
+    /** Raw response body string (null on network error). */
+    rawBody: string | null;
+    /** Resolved operation name (from case.operationName or parsed from query). */
+    operationName: string;
+    /** Duration in ms. */
+    duration: number;
+}
+/**
+ * User-facing GraphQL contract specification.
+ *
+ * Contract identity = contract id (string) + case key. `operationName` is
+ * a display/routing hint, NOT an identity (proposal §5.3 — same rule as
+ * gRPC `Service/Method`).
+ */
+export interface GraphqlContractSpec<Vars extends Record<string, unknown> = Record<string, unknown>, Res = unknown, Cases extends Record<string, GraphqlContractCase<Vars, Res, any>> = Record<string, GraphqlContractCase<Vars, Res>>> {
+    /**
+     * Endpoint URL **for projection / display only.**
+     *
+     * Travels on the projection `meta.endpoint`. The adapter does NOT use
+     * this to redirect the runtime call — the call is dispatched through
+     * the supplied `client`, whose endpoint was fixed at construction time
+     * (see `GraphqlContractDefaults.endpoint` for the full rationale). To
+     * target a different endpoint at runtime, construct a separate client.
+     */
+    endpoint?: string;
+    /** Default GraphQL client for all cases. */
+    client?: GraphQLClient;
+    description?: string;
+    feature?: string;
+    /**
+     * Explicit type declarations (proposal §7b.2). Stored opaque in Phase 1;
+     * consumed by Phase 2 `.gql` projection. Safe to omit — nothing else
+     * depends on it at runtime.
+     */
+    types?: GraphqlTypeDefs;
+    /**
+     * Default operation type for cases that don't set their own.
+     * Default when both spec and case omit: `"query"`.
+     */
+    defaultOperation?: "query" | "mutation";
+    /**
+     * Contract-level variables schema. Per-case schemas (on `expect.schema`)
+     * cover response shape; variables often share structure so this sits at
+     * the contract level.
+     */
+    variablesSchema?: SchemaLike<Vars>;
+    /**
+     * Contract-level response schema — used when all cases share the same
+     * selection set. Per-case `expect.schema` overrides.
+     */
+    responseSchema?: SchemaLike<Res>;
+    /** Contract-level default variables (merged under each case's variables). */
+    defaultVariables?: Partial<Vars>;
+    /** Contract-level default headers (merged under each case's headers). */
+    defaultHeaders?: Record<string, string>;
+    tags?: string[];
+    deprecated?: string;
+    extensions?: Extensions;
+    /** Named spec cases. */
+    cases: Cases;
+}
+/**
+ * Runtime (live) payload shape for the GraphQL adapter. Contains SchemaLike
+ * references. Converted to `GraphqlSafeSchemas` by adapter.normalize.
+ *
+ * Per the selection-set coupling (proposal §3.2 b), the most important
+ * field here is `response` — it's the per-case response schema. `variables`
+ * and `request` (= the query document string) accompany it so the triple
+ * travels together through projection.
+ */
+export interface GraphqlPayloadSchemas {
+    /** Query document string (the "request" for GraphQL). */
+    query?: string;
+    /** Operation type (query / mutation). */
+    operation?: "query" | "mutation";
+    /** Resolved operationName (display/routing hint). */
+    operationName?: string;
+    /** Variables schema. */
+    variables?: SchemaLike<unknown>;
+    /** Per-case response schema (selection-set-coupled). */
+    response?: SchemaLike<unknown>;
+    /** Response headers schema. */
+    headers?: SchemaLike<Record<string, string | string[]>>;
+    /** Variables examples (for docs / projection). */
+    variablesExample?: unknown;
+    variablesExamples?: Record<string, GraphqlContractExample<unknown>>;
+}
+/**
+ * JSON-safe payload shape. Produced by adapter.normalize.
+ * SchemaLike references are converted to JSON Schema fragments.
+ */
+export interface GraphqlSafeSchemas {
+    query?: string;
+    operation?: "query" | "mutation";
+    operationName?: string;
+    variables?: Record<string, unknown>;
+    response?: Record<string, unknown>;
+    headers?: Record<string, unknown>;
+    variablesExample?: unknown;
+    variablesExamples?: Record<string, GraphqlContractExample<unknown>>;
+}
+/**
+ * Runtime contract-level meta. Carried on the projection so scanner / MCP /
+ * Cloud can surface structural info without needing the live spec.
+ *
+ * Note: explicit `types` map (when present) is JSON-safe by construction
+ * (stringly-typed field declarations), so it travels unchanged from
+ * runtime to safe meta.
+ */
+export interface GraphqlContractMeta {
+    /** Endpoint URL (normalized; may be undefined if transport-owned). */
+    endpoint?: string;
+    /** Default operation type for the contract. */
+    defaultOperation?: "query" | "mutation";
+    /** Contract-level default headers (for projection display). */
+    defaultHeaders?: Record<string, string>;
+    /** Explicit type declarations (Phase 2 projection hint). */
+    types?: GraphqlTypeDefs;
+    /** Contract instance name (contract.graphql.with("name")). */
+    instanceName?: string;
+}
+/**
+ * JSON-safe meta. Same shape as runtime meta (no live references).
+ */
+export type GraphqlContractSafeMeta = GraphqlContractMeta;
+/**
+ * What `executeCaseInFlow` returns, and what flow `step.out(state, res)`
+ * receives in its `res` parameter. Mirrors `GraphqlCaseResult` — kept as a
+ * distinct export to make the flow-output contract explicit (parallel to
+ * gRPC's `GrpcFlowCaseOutput` convention).
+ */
+export type GraphqlFlowCaseOutput<Res = unknown> = GraphqlCaseResult<Res>;
+/**
+ * Signature of `contract.graphql.with("name", defaults)`. Returns a contract
+ * factory that creates contracts under this instance's defaults.
+ *
+ * Actual implementation in `./factory.ts` (CG-12).
+ */
+export type GraphqlContractRoot = {
+    with: (instanceName: string, defaults?: GraphqlContractDefaults) => GraphqlContractFactory;
+};
+export type GraphqlContractFactory = <Vars extends Record<string, unknown>, Res, Cases extends Record<string, GraphqlContractCase<Vars, Res, any>>>(id: string, spec: GraphqlContractSpec<Vars, Res, Cases>) => unknown;
+/**
+ * Infer variables type from a GraphqlContractCase.
+ */
+export type InferGraphqlVariables<C> = C extends GraphqlContractCase<infer V, any, any> ? V : never;
+/**
+ * Infer response type from a GraphqlContractCase.
+ */
+export type InferGraphqlResponse<C> = C extends GraphqlContractCase<any, infer R, any> ? R : never;
+//# sourceMappingURL=types.d.ts.map

package/dist/contract/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/contract/types.ts"],"names":[],"mappings":"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"}

package/dist/contract/types.js

@@ -0,0 +1,41 @@
+/**
+ * GraphQL contract types.
+ *
+ * User-facing authoring types + adapter-level payload types for the
+ * GraphQL contract adapter (single-package model — see
+ * `internal/40-discovery/proposals/contract-grpc-graphql-expansion.md` §6.1).
+ *
+ * Structure mirrors `packages/grpc/src/contract/types.ts` where applicable,
+ * with GraphQL-specific design:
+ *
+ *   - **Target model:** GraphQL typically has a single `/graphql` endpoint,
+ *     so `endpoint` is spec-level (not per-case). `endpoint` is
+ *     **projection-only** in Phase 1 — it travels on `meta.endpoint`
+ *     for markdown / scanner / MCP display, but the adapter dispatches
+ *     through the supplied `GraphQLClient` whose endpoint was fixed at
+ *     construction time. Multi-endpoint is expressed by multiple
+ *     clients, not by per-contract endpoint strings. Contract identity
+ *     = `contractId + caseKey`, NOT operationName (proposal §3.2).
+ *
+ *   - **Selection-set-per-case coupling (proposal §3.2 b):** unlike
+ *     HTTP/gRPC where response shape is determined by endpoint/method,
+ *     GraphQL response shape is determined by the *query string* in each
+ *     case. Each case therefore carries its own `query` + `variables` +
+ *     `responseSchema` triple. A contract-level `responseSchema` may still
+ *     apply if all cases share the same selection set (rare).
+ *
+ *   - **Explicit type declarations (proposal §7b.2):** `types` is a
+ *     deferred projection hint for Phase 2 SDL generation. Phase 1 stores
+ *     it as opaque metadata — adapter / scanner carry it forward so
+ *     projection tooling can consume it later.
+ *
+ *   - **3-layer classifyFailure (proposal §3.2 c):**
+ *       transport (HTTP status 4xx/5xx/network)
+ *       → payload errors (GraphQL `errors` array, HTTP 200)
+ *       → data shape mismatch (schema validation on `data`)
+ *
+ *   - **Phase 1 scope:** query + mutation only (subscriptions deferred
+ *     to Phase 2 streaming work).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/contract/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/contract/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG"}

package/dist/index.d.ts

@@ -51,7 +51,7 @@
  *
  * @module graphql
  */
-import type { HttpClient, PluginFactory } from "@glubean/sdk";
+import type { ClientFactory, HttpClient, PluginManifest } from "@glubean/sdk";
 /**
  * A single GraphQL error as defined by the
  * [GraphQL spec](https://spec.graphql.org/October2021/#sec-Errors).
@@ -96,6 +96,25 @@ export interface GraphQLResponse<T = unknown> {
     /** Optional server extensions (e.g., tracing, cost). */
     extensions?: Record<string, unknown>;
 }
+/**
+ * Extended result type returned by the client. Contains the full
+ * `GraphQLResponse` shape plus transport envelope fields used by
+ * the contract adapter layer (negative-transport assertions,
+ * `classifyFailure`, flow `out` lens inspection).
+ *
+ * Additive since v0.2.0 — users who only destructure `{ data, errors }`
+ * see no change. Users who need transport info read the new fields.
+ *
+ * @template T Shape of the `data` field
+ */
+export interface GraphQLResult<T = unknown> extends GraphQLResponse<T> {
+    /** HTTP status from the underlying POST (200 on most GraphQL success, even with `errors`). */
+    httpStatus: number;
+    /** Response headers (lowercased keys). */
+    headers: Record<string, string | string[]>;
+    /** Raw response body string — present when available (null on network error). */
+    rawBody: string | null;
+}
 /**
  * Options for a single GraphQL request.
  */
@@ -179,7 +198,7 @@ export interface GraphQLClient {
      * `, { variables: { limit: 10 } });
      * ```
      */
-    query<T = unknown>(query: string, options?: GraphQLRequestOptions): Promise<GraphQLResponse<T>>;
+    query<T = unknown>(query: string, options?: GraphQLRequestOptions): Promise<GraphQLResult<T>>;
     /**
      * Execute a GraphQL mutation.
      *
@@ -200,7 +219,7 @@ export interface GraphQLClient {
      * `, { variables: { input: { name: "Alice" } } });
      * ```
      */
-    mutate<T = unknown>(mutation: string, options?: GraphQLRequestOptions): Promise<GraphQLResponse<T>>;
+    mutate<T = unknown>(mutation: string, options?: GraphQLRequestOptions): Promise<GraphQLResult<T>>;
 }
 /**
  * Extract the first named operation from a GraphQL query string.
@@ -320,6 +339,33 @@ export declare function createGraphQLClient(http: HttpClient, options: GraphQLCl
  * });
  * ```
  */
-export declare function graphql(options: GraphQLClientOptions): PluginFactory<GraphQLClient>;
+export declare function graphql(options: GraphQLClientOptions): ClientFactory<GraphQLClient>;
 export { fromGql } from "./data.js";
+/**
+ * Plugin manifest for `@glubean/graphql`. Declares:
+ *
+ *   - `matchers`   — 5 GraphQL-specific matchers (`toHaveGraphqlData`,
+ *                    `toHaveGraphqlNoErrors`, `toHaveGraphqlErrorCode`,
+ *                    `toHaveGraphqlExtension`, `toHaveHttpStatus`)
+ *   - `contracts`  — `graphql` protocol adapter
+ *   - `setup()`    — wraps the auto-attached `contract.graphql` dispatcher
+ *                    with `createGraphqlRoot` so `contract.graphql.with(...)`
+ *                    UX works
+ *
+ * Install explicitly in your project's `glubean.setup.ts`:
+ *
+ * ```ts
+ * import { installPlugin } from "@glubean/sdk";
+ * import graphqlPlugin from "@glubean/graphql";
+ * await installPlugin(graphqlPlugin);
+ * ```
+ *
+ * **Note:** top-level `import "@glubean/graphql"` is **no longer** a side-effect
+ * registration. The manifest must be explicitly installed (directly or via
+ * `bootstrap(projectRoot)` which loads `glubean.setup.ts`).
+ */
+declare const graphqlPlugin: PluginManifest;
+export default graphqlPlugin;
+export { graphqlAdapter, createGraphqlFactory, createGraphqlRoot, graphqlMatchers, } from "./contract/index.js";
+export type { GraphqlContractCase, GraphqlContractDefaults, GraphqlContractExample, GraphqlContractExpect, GraphqlContractFactory, GraphqlContractMeta, GraphqlContractRoot, GraphqlContractSafeMeta, GraphqlContractSpec, GraphqlCaseResult, GraphqlErrorsExpect, GraphqlFlowCaseOutput, GraphqlPayloadSchemas, GraphqlSafeSchemas, GraphqlTypeDef, GraphqlTypeDefs, InferGraphqlVariables, InferGraphqlResponse, } from "./contract/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -51,7 +51,10 @@
  *
  * @module graphql
  */
-import { definePlugin } from "@glubean/sdk/plugin";
+import { contract, defineClientFactory, definePlugin } from "@glubean/sdk";
+import { graphqlAdapter } from "./contract/adapter.js";
+import { createGraphqlRoot } from "./contract/factory.js";
+import { graphqlMatchers } from "./contract/matchers.js";
 /**
  * Error thrown when a GraphQL response contains errors and
  * `throwOnGraphQLErrors` is enabled.
@@ -186,17 +189,33 @@ export function createGraphQLClient(http, options) {
         if (opName !== "anonymous") {
             body.operationName = opName;
         }
-        const response = await http
-            .post(endpoint, {
+        const res = await http.post(endpoint, {
             json: body,
             headers: mergedHeaders,
             throwHttpErrors: false,
-        })
-            .json();
-        if (throwOnGraphQLErrors && response.errors && response.errors.length > 0) {
-            throw new GraphQLResponseError(response.errors, response);
+        });
+        const rawBody = await res.text();
+        const headers = {};
+        res.headers.forEach((value, key) => {
+            headers[key.toLowerCase()] = value;
+        });
+        let parsed;
+        try {
+            parsed = rawBody ? JSON.parse(rawBody) : { data: null };
         }
-        return response;
+        catch {
+            parsed = { data: null };
+        }
+        const result = {
+            ...parsed,
+            httpStatus: res.status,
+            headers,
+            rawBody,
+        };
+        if (throwOnGraphQLErrors && result.errors && result.errors.length > 0) {
+            throw new GraphQLResponseError(result.errors, result);
+        }
+        return result;
     }
     return {
         query: (query, options) => execute(query, options),
@@ -241,7 +260,7 @@ export function createGraphQLClient(http, options) {
  * ```
  */
 export function graphql(options) {
-    return definePlugin((runtime) => {
+    return defineClientFactory((runtime) => {
         const resolved = {
             ...options,
             endpoint: runtime.resolveTemplate(options.endpoint),
@@ -257,4 +276,45 @@ export function graphql(options) {
 }
 // Re-export data loader for convenience (spec: `import { fromGql } from "@glubean/graphql"`)
 export { fromGql } from "./data.js";
+// =============================================================================
+// Plugin manifest (default export)
+// =============================================================================
+/**
+ * Plugin manifest for `@glubean/graphql`. Declares:
+ *
+ *   - `matchers`   — 5 GraphQL-specific matchers (`toHaveGraphqlData`,
+ *                    `toHaveGraphqlNoErrors`, `toHaveGraphqlErrorCode`,
+ *                    `toHaveGraphqlExtension`, `toHaveHttpStatus`)
+ *   - `contracts`  — `graphql` protocol adapter
+ *   - `setup()`    — wraps the auto-attached `contract.graphql` dispatcher
+ *                    with `createGraphqlRoot` so `contract.graphql.with(...)`
+ *                    UX works
+ *
+ * Install explicitly in your project's `glubean.setup.ts`:
+ *
+ * ```ts
+ * import { installPlugin } from "@glubean/sdk";
+ * import graphqlPlugin from "@glubean/graphql";
+ * await installPlugin(graphqlPlugin);
+ * ```
+ *
+ * **Note:** top-level `import "@glubean/graphql"` is **no longer** a side-effect
+ * registration. The manifest must be explicitly installed (directly or via
+ * `bootstrap(projectRoot)` which loads `glubean.setup.ts`).
+ */
+const graphqlPlugin = definePlugin({
+    name: "@glubean/graphql",
+    matchers: graphqlMatchers,
+    contracts: { graphql: graphqlAdapter },
+    setup() {
+        // Replace the auto-attached dispatcher with the scoped-defaults factory
+        // so `contract.graphql.with("api", { client })("case", spec)` works.
+        // Runs after installPlugin calls contract.register().
+        const dispatcher = contract.graphql;
+        contract.graphql = createGraphqlRoot(dispatcher);
+    },
+});
+export default graphqlPlugin;
+// Re-export contract surface for type consumers
+export { graphqlAdapter, createGraphqlFactory, createGraphqlRoot, graphqlMatchers, } from "./contract/index.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}