@glubean/graphql 0.1.3

package/dist/data.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Data loaders for GraphQL files.
+ *
+ * @module data
+ */
+/**
+ * Load a GraphQL query from a `.gql` or `.graphql` file.
+ *
+ * Using external `.gql` files instead of inline strings enables full IDE
+ * support: syntax highlighting, field autocomplete, and schema validation
+ * (when a `.graphqlrc` config points to your schema).
+ *
+ * @param path Path to the `.gql` / `.graphql` file, relative to project root
+ * @returns The query string (trimmed)
+ *
+ * @example
+ * ```ts
+ * import { fromGql } from "@glubean/graphql/data";
+ * import { graphql } from "@glubean/graphql";
+ * import { test, configure } from "@glubean/sdk";
+ *
+ * const GetUser = await fromGql("./queries/getUser.gql");
+ *
+ * const { gql } = configure({
+ *   plugins: {
+ *     gql: graphql({ endpoint: "{{graphql_url}}" }),
+ *   },
+ * });
+ *
+ * export const getUser = test("get-user", async (ctx) => {
+ *   const { data } = await gql.query(GetUser, { variables: { id: "1" } });
+ *   ctx.expect(data?.user.name).toBe("Alice");
+ * });
+ * ```
+ */
+export declare function fromGql(path: string): Promise<string>;
+//# sourceMappingURL=data.d.ts.map

package/dist/data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data.d.ts","sourceRoot":"","sources":["../src/data.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG3D"}

package/dist/data.js

@@ -0,0 +1,41 @@
+/**
+ * Data loaders for GraphQL files.
+ *
+ * @module data
+ */
+import { readFile } from "node:fs/promises";
+/**
+ * Load a GraphQL query from a `.gql` or `.graphql` file.
+ *
+ * Using external `.gql` files instead of inline strings enables full IDE
+ * support: syntax highlighting, field autocomplete, and schema validation
+ * (when a `.graphqlrc` config points to your schema).
+ *
+ * @param path Path to the `.gql` / `.graphql` file, relative to project root
+ * @returns The query string (trimmed)
+ *
+ * @example
+ * ```ts
+ * import { fromGql } from "@glubean/graphql/data";
+ * import { graphql } from "@glubean/graphql";
+ * import { test, configure } from "@glubean/sdk";
+ *
+ * const GetUser = await fromGql("./queries/getUser.gql");
+ *
+ * const { gql } = configure({
+ *   plugins: {
+ *     gql: graphql({ endpoint: "{{graphql_url}}" }),
+ *   },
+ * });
+ *
+ * export const getUser = test("get-user", async (ctx) => {
+ *   const { data } = await gql.query(GetUser, { variables: { id: "1" } });
+ *   ctx.expect(data?.user.name).toBe("Alice");
+ * });
+ * ```
+ */
+export async function fromGql(path) {
+    const content = await readFile(path, "utf-8");
+    return content.trim();
+}
+//# sourceMappingURL=data.js.map

package/dist/data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data.js","sourceRoot":"","sources":["../src/data.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAY;IACxC,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC9C,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;AACxB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,325 @@
+/**
+ * GraphQL plugin for Glubean tests.
+ *
+ * Provides a thin wrapper over `ctx.http` (or any `HttpClient`) that simplifies
+ * GraphQL query/mutation execution with auto-tracing, operationName extraction,
+ * and optional error-throwing behavior.
+ *
+ * ## Usage
+ *
+ * ### As a plugin via `configure()` (recommended)
+ *
+ * ```ts
+ * import { test, configure } from "@glubean/sdk";
+ * import { graphql } from "@glubean/graphql";
+ *
+ * const { gql } = configure({
+ *   plugins: {
+ *     gql: graphql({
+ *       endpoint: "{{graphql_url}}",
+ *       headers: { Authorization: "Bearer {{api_key}}" },
+ *     }),
+ *   },
+ * });
+ *
+ * export const getUser = test("get-user", async (ctx) => {
+ *   const { data, errors } = await gql.query<{ user: { name: string } }>(`
+ *     query GetUser($id: ID!) {
+ *       user(id: $id) { name }
+ *     }
+ *   `, { variables: { id: "1" } });
+ *
+ *   ctx.expect(errors).toBeUndefined();
+ *   ctx.expect(data?.user.name).toBe("Alice");
+ * });
+ * ```
+ *
+ * ### Standalone (without `configure()`)
+ *
+ * ```ts
+ * import { test } from "@glubean/sdk";
+ * import { createGraphQLClient } from "@glubean/graphql";
+ *
+ * export const quick = test("quick-gql", async (ctx) => {
+ *   const gql = createGraphQLClient(ctx.http, {
+ *     endpoint: "https://api.example.com/graphql",
+ *   });
+ *   const { data } = await gql.query(`{ health }`);
+ *   ctx.assert(data?.health === "ok", "Service healthy");
+ * });
+ * ```
+ *
+ * @module graphql
+ */
+import type { HttpClient, PluginFactory } from "@glubean/sdk";
+/**
+ * A single GraphQL error as defined by the
+ * [GraphQL spec](https://spec.graphql.org/October2021/#sec-Errors).
+ *
+ * @example
+ * ```ts
+ * // Typical error shape from a GraphQL server
+ * {
+ *   message: "User not found",
+ *   locations: [{ line: 2, column: 3 }],
+ *   path: ["user"],
+ *   extensions: { code: "NOT_FOUND" }
+ * }
+ * ```
+ */
+export interface GraphQLError {
+    /** Human-readable error description */
+    message: string;
+    /** Source locations in the query that caused this error */
+    locations?: {
+        line: number;
+        column: number;
+    }[];
+    /** Path to the field that produced the error */
+    path?: (string | number)[];
+    /** Server-defined extension data (e.g., error codes) */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Standard GraphQL response envelope.
+ *
+ * Per the spec, `data` is `null` when all requested fields errored,
+ * and `errors` is absent when there are no errors.
+ *
+ * @template T Shape of the `data` field
+ */
+export interface GraphQLResponse<T = unknown> {
+    /** The result of the query/mutation. `null` if all fields errored. */
+    data: T | null;
+    /** Array of errors, if any. Absent when no errors. */
+    errors?: GraphQLError[];
+    /** Optional server extensions (e.g., tracing, cost). */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Options for a single GraphQL request.
+ */
+export interface GraphQLRequestOptions {
+    /** Variables to pass to the query/mutation */
+    variables?: Record<string, unknown>;
+    /**
+     * Explicit operationName. If omitted, the client parses the first named
+     * operation from the query string (e.g., `query GetUser` -> `"GetUser"`).
+     */
+    operationName?: string;
+    /** Additional headers for this request only */
+    headers?: Record<string, string>;
+}
+/**
+ * Options for creating a GraphQL client.
+ */
+export interface GraphQLClientOptions {
+    /** The GraphQL endpoint URL (e.g., "https://api.example.com/graphql") */
+    endpoint: string;
+    /** Default headers sent with every request */
+    headers?: Record<string, string>;
+    /**
+     * If `true`, the client throws a `GraphQLResponseError` when the response
+     * contains `errors`, even though the HTTP status is 200.
+     *
+     * Default: `false` -- errors are returned in the response object.
+     *
+     * @example
+     * ```ts
+     * const gql = createGraphQLClient(ctx.http, {
+     *   endpoint: "https://api.example.com/graphql",
+     *   throwOnGraphQLErrors: true,
+     * });
+     *
+     * try {
+     *   const { data } = await gql.query(`{ me { name } }`);
+     * } catch (err) {
+     *   if (err instanceof GraphQLResponseError) {
+     *     console.log(err.errors); // GraphQLError[]
+     *   }
+     * }
+     * ```
+     */
+    throwOnGraphQLErrors?: boolean;
+}
+/**
+ * Error thrown when a GraphQL response contains errors and
+ * `throwOnGraphQLErrors` is enabled.
+ */
+export declare class GraphQLResponseError extends Error {
+    /** The GraphQL errors from the response */
+    readonly errors: GraphQLError[];
+    /** The original response (may contain partial `data`) */
+    readonly response: GraphQLResponse;
+    constructor(errors: GraphQLError[], response: GraphQLResponse);
+}
+/**
+ * A GraphQL client bound to a specific endpoint.
+ *
+ * All requests are auto-traced via the underlying `HttpClient`.
+ * The operation name is injected into traces via the `X-Glubean-Op` header,
+ * so the dashboard can distinguish between different GraphQL operations
+ * instead of showing a generic `POST /graphql`.
+ */
+export interface GraphQLClient {
+    /**
+     * Execute a GraphQL query.
+     *
+     * @template T Shape of the `data` field
+     * @param query The GraphQL query string
+     * @param options Variables, operationName, and extra headers
+     * @returns The parsed GraphQL response
+     *
+     * @example
+     * ```ts
+     * const { data, errors } = await gql.query<{ users: User[] }>(`
+     *   query ListUsers($limit: Int) {
+     *     users(limit: $limit) { id name }
+     *   }
+     * `, { variables: { limit: 10 } });
+     * ```
+     */
+    query<T = unknown>(query: string, options?: GraphQLRequestOptions): Promise<GraphQLResponse<T>>;
+    /**
+     * Execute a GraphQL mutation.
+     *
+     * Functionally identical to `query()` -- the distinction is purely semantic
+     * to improve readability in test code.
+     *
+     * @template T Shape of the `data` field
+     * @param mutation The GraphQL mutation string
+     * @param options Variables, operationName, and extra headers
+     * @returns The parsed GraphQL response
+     *
+     * @example
+     * ```ts
+     * const { data } = await gql.mutate<{ createUser: { id: string } }>(`
+     *   mutation CreateUser($input: CreateUserInput!) {
+     *     createUser(input: $input) { id }
+     *   }
+     * `, { variables: { input: { name: "Alice" } } });
+     * ```
+     */
+    mutate<T = unknown>(mutation: string, options?: GraphQLRequestOptions): Promise<GraphQLResponse<T>>;
+}
+/**
+ * Extract the first named operation from a GraphQL query string.
+ *
+ * Matches patterns like:
+ * - `query GetUser` -> "GetUser"
+ * - `mutation CreateUser` -> "CreateUser"
+ * - `subscription OnMessage` -> "OnMessage"
+ * - `query GetUser($id: ID!)` -> "GetUser"
+ *
+ * Returns `undefined` for anonymous operations (e.g., `{ users { id } }`).
+ *
+ * @internal
+ */
+export declare function parseOperationName(query: string): string | undefined;
+/**
+ * Tagged template literal for GraphQL queries.
+ *
+ * This is an identity function -- it returns the query string as-is.
+ * Its purpose is purely for IDE integration: the VSCode GraphQL extension
+ * recognizes the `gql` tag and enables syntax highlighting (and autocomplete
+ * when a `.graphqlrc` schema is configured).
+ *
+ * For full IDE support (autocomplete, validation), prefer `.gql` files
+ * loaded via `fromGql()`. Use `gql` for quick inline queries where a
+ * separate file would be overkill.
+ *
+ * @example
+ * ```ts
+ * import { gql } from "@glubean/graphql";
+ *
+ * const GET_USER = gql`
+ *   query GetUser($id: ID!) {
+ *     user(id: $id) { name email }
+ *   }
+ * `;
+ *
+ * const { data } = await client.query(GET_USER, { variables: { id: "1" } });
+ * ```
+ */
+export declare function gql(strings: TemplateStringsArray, ...values: unknown[]): string;
+/**
+ * Create a GraphQL client bound to a specific endpoint.
+ *
+ * The client wraps the provided `HttpClient` (typically `ctx.http`), so all
+ * requests inherit auto-tracing, auto-metrics, and retry behavior.
+ *
+ * The operation name is injected via the `X-Glubean-Op` request header.
+ * The runner's harness reads this header to set `trace.name`, making
+ * individual GraphQL operations distinguishable in the dashboard.
+ *
+ * @param http The base HTTP client (e.g., `ctx.http`)
+ * @param options Endpoint URL, default headers, error handling
+ * @returns A bound `GraphQLClient` instance
+ *
+ * @example Basic usage
+ * ```ts
+ * import { createGraphQLClient } from "@glubean/graphql";
+ *
+ * export const myTest = test("gql-test", async (ctx) => {
+ *   const gql = createGraphQLClient(ctx.http, {
+ *     endpoint: ctx.vars.require("GQL_URL"),
+ *     headers: { Authorization: `Bearer ${ctx.secrets.require("TOKEN")}` },
+ *   });
+ *
+ *   const { data } = await gql.query<{ user: { name: string } }>(`
+ *     query GetUser($id: ID!) { user(id: $id) { name } }
+ *   `, { variables: { id: "1" } });
+ *
+ *   ctx.expect(data?.user.name).toBe("Alice");
+ * });
+ * ```
+ *
+ * @example With throwOnGraphQLErrors
+ * ```ts
+ * const gql = createGraphQLClient(ctx.http, {
+ *   endpoint: ctx.vars.require("GQL_URL"),
+ *   throwOnGraphQLErrors: true,
+ * });
+ *
+ * // This will throw GraphQLResponseError if the response contains errors
+ * const { data } = await gql.query(`{ me { name } }`);
+ * ```
+ */
+export declare function createGraphQLClient(http: HttpClient, options: GraphQLClientOptions): GraphQLClient;
+/**
+ * Create a GraphQL plugin for use with `configure({ plugins })`.
+ *
+ * Resolves `{{template}}` placeholders in `endpoint` and `headers` using
+ * the Glubean runtime (vars and secrets). The returned `GraphQLClient` is
+ * lazily created on first access.
+ *
+ * @param options GraphQL client options (endpoint may use `{{var_name}}` templates)
+ * @returns A `PluginFactory` that produces a `GraphQLClient`
+ *
+ * @example
+ * ```ts
+ * import { test, configure } from "@glubean/sdk";
+ * import { graphql } from "@glubean/graphql";
+ *
+ * const { gql } = configure({
+ *   plugins: {
+ *     gql: graphql({
+ *       endpoint: "{{graphql_url}}",
+ *       headers: { Authorization: "Bearer {{api_key}}" },
+ *       throwOnGraphQLErrors: true,
+ *     }),
+ *   },
+ * });
+ *
+ * export const getUser = test("get-user", async (ctx) => {
+ *   const { data } = await gql.query<{ user: { name: string } }>(
+ *     `query GetUser($id: ID!) { user(id: $id) { name } }`,
+ *     { variables: { id: "1" } },
+ *   );
+ *   ctx.expect(data?.user.name).toBe("Alice");
+ * });
+ * ```
+ */
+export declare function graphql(options: GraphQLClientOptions): PluginFactory<GraphQLClient>;
+export { fromGql } from "./data.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAGH,OAAO,KAAK,EAAkB,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAM9E;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,SAAS,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC/C,gDAAgD;IAChD,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC3B,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C,sEAAsE;IACtE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACf,sDAAsD;IACtD,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;IACxB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC;IAChC,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;gBAEvB,MAAM,EAAE,YAAY,EAAE,EAAE,QAAQ,EAAE,eAAe;CAO9D;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,CAAC,GAAG,OAAO,EACf,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IAE/B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,CAAC,GAAG,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;CAChC;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGpE;AAMD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,GAAG,CACjB,OAAO,EAAE,oBAAoB,EAC7B,GAAG,MAAM,EAAE,OAAO,EAAE,GACnB,MAAM,CAMR;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,oBAAoB,GAC5B,aAAa,CA0Cf;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,OAAO,CACrB,OAAO,EAAE,oBAAoB,GAC5B,aAAa,CAAC,aAAa,CAAC,CAc9B;AAGD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,260 @@
+/**
+ * GraphQL plugin for Glubean tests.
+ *
+ * Provides a thin wrapper over `ctx.http` (or any `HttpClient`) that simplifies
+ * GraphQL query/mutation execution with auto-tracing, operationName extraction,
+ * and optional error-throwing behavior.
+ *
+ * ## Usage
+ *
+ * ### As a plugin via `configure()` (recommended)
+ *
+ * ```ts
+ * import { test, configure } from "@glubean/sdk";
+ * import { graphql } from "@glubean/graphql";
+ *
+ * const { gql } = configure({
+ *   plugins: {
+ *     gql: graphql({
+ *       endpoint: "{{graphql_url}}",
+ *       headers: { Authorization: "Bearer {{api_key}}" },
+ *     }),
+ *   },
+ * });
+ *
+ * export const getUser = test("get-user", async (ctx) => {
+ *   const { data, errors } = await gql.query<{ user: { name: string } }>(`
+ *     query GetUser($id: ID!) {
+ *       user(id: $id) { name }
+ *     }
+ *   `, { variables: { id: "1" } });
+ *
+ *   ctx.expect(errors).toBeUndefined();
+ *   ctx.expect(data?.user.name).toBe("Alice");
+ * });
+ * ```
+ *
+ * ### Standalone (without `configure()`)
+ *
+ * ```ts
+ * import { test } from "@glubean/sdk";
+ * import { createGraphQLClient } from "@glubean/graphql";
+ *
+ * export const quick = test("quick-gql", async (ctx) => {
+ *   const gql = createGraphQLClient(ctx.http, {
+ *     endpoint: "https://api.example.com/graphql",
+ *   });
+ *   const { data } = await gql.query(`{ health }`);
+ *   ctx.assert(data?.health === "ok", "Service healthy");
+ * });
+ * ```
+ *
+ * @module graphql
+ */
+import { definePlugin } from "@glubean/sdk/plugin";
+/**
+ * Error thrown when a GraphQL response contains errors and
+ * `throwOnGraphQLErrors` is enabled.
+ */
+export class GraphQLResponseError extends Error {
+    /** The GraphQL errors from the response */
+    errors;
+    /** The original response (may contain partial `data`) */
+    response;
+    constructor(errors, response) {
+        const summary = errors.map((e) => e.message).join("; ");
+        super(`GraphQL errors: ${summary}`);
+        this.name = "GraphQLResponseError";
+        this.errors = errors;
+        this.response = response;
+    }
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+/**
+ * Extract the first named operation from a GraphQL query string.
+ *
+ * Matches patterns like:
+ * - `query GetUser` -> "GetUser"
+ * - `mutation CreateUser` -> "CreateUser"
+ * - `subscription OnMessage` -> "OnMessage"
+ * - `query GetUser($id: ID!)` -> "GetUser"
+ *
+ * Returns `undefined` for anonymous operations (e.g., `{ users { id } }`).
+ *
+ * @internal
+ */
+export function parseOperationName(query) {
+    const match = query.match(/(?:query|mutation|subscription)\s+([A-Za-z_]\w*)/);
+    return match?.[1];
+}
+// =============================================================================
+// Tagged template
+// =============================================================================
+/**
+ * Tagged template literal for GraphQL queries.
+ *
+ * This is an identity function -- it returns the query string as-is.
+ * Its purpose is purely for IDE integration: the VSCode GraphQL extension
+ * recognizes the `gql` tag and enables syntax highlighting (and autocomplete
+ * when a `.graphqlrc` schema is configured).
+ *
+ * For full IDE support (autocomplete, validation), prefer `.gql` files
+ * loaded via `fromGql()`. Use `gql` for quick inline queries where a
+ * separate file would be overkill.
+ *
+ * @example
+ * ```ts
+ * import { gql } from "@glubean/graphql";
+ *
+ * const GET_USER = gql`
+ *   query GetUser($id: ID!) {
+ *     user(id: $id) { name email }
+ *   }
+ * `;
+ *
+ * const { data } = await client.query(GET_USER, { variables: { id: "1" } });
+ * ```
+ */
+export function gql(strings, ...values) {
+    let result = strings[0];
+    for (let i = 0; i < values.length; i++) {
+        result += String(values[i]) + strings[i + 1];
+    }
+    return result.replace(/\s+/g, " ").trim();
+}
+// =============================================================================
+// Client implementation
+// =============================================================================
+/**
+ * Create a GraphQL client bound to a specific endpoint.
+ *
+ * The client wraps the provided `HttpClient` (typically `ctx.http`), so all
+ * requests inherit auto-tracing, auto-metrics, and retry behavior.
+ *
+ * The operation name is injected via the `X-Glubean-Op` request header.
+ * The runner's harness reads this header to set `trace.name`, making
+ * individual GraphQL operations distinguishable in the dashboard.
+ *
+ * @param http The base HTTP client (e.g., `ctx.http`)
+ * @param options Endpoint URL, default headers, error handling
+ * @returns A bound `GraphQLClient` instance
+ *
+ * @example Basic usage
+ * ```ts
+ * import { createGraphQLClient } from "@glubean/graphql";
+ *
+ * export const myTest = test("gql-test", async (ctx) => {
+ *   const gql = createGraphQLClient(ctx.http, {
+ *     endpoint: ctx.vars.require("GQL_URL"),
+ *     headers: { Authorization: `Bearer ${ctx.secrets.require("TOKEN")}` },
+ *   });
+ *
+ *   const { data } = await gql.query<{ user: { name: string } }>(`
+ *     query GetUser($id: ID!) { user(id: $id) { name } }
+ *   `, { variables: { id: "1" } });
+ *
+ *   ctx.expect(data?.user.name).toBe("Alice");
+ * });
+ * ```
+ *
+ * @example With throwOnGraphQLErrors
+ * ```ts
+ * const gql = createGraphQLClient(ctx.http, {
+ *   endpoint: ctx.vars.require("GQL_URL"),
+ *   throwOnGraphQLErrors: true,
+ * });
+ *
+ * // This will throw GraphQLResponseError if the response contains errors
+ * const { data } = await gql.query(`{ me { name } }`);
+ * ```
+ */
+export function createGraphQLClient(http, options) {
+    const { endpoint, headers: defaultHeaders, throwOnGraphQLErrors } = options;
+    async function execute(query, requestOptions) {
+        const opName = requestOptions?.operationName ?? parseOperationName(query) ?? "anonymous";
+        const mergedHeaders = {
+            ...defaultHeaders,
+            ...requestOptions?.headers,
+            "X-Glubean-Op": opName,
+        };
+        const body = { query };
+        if (requestOptions?.variables) {
+            body.variables = requestOptions.variables;
+        }
+        if (opName !== "anonymous") {
+            body.operationName = opName;
+        }
+        const response = 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);
+        }
+        return response;
+    }
+    return {
+        query: (query, options) => execute(query, options),
+        mutate: (mutation, options) => execute(mutation, options),
+    };
+}
+// =============================================================================
+// Plugin factory
+// =============================================================================
+/**
+ * Create a GraphQL plugin for use with `configure({ plugins })`.
+ *
+ * Resolves `{{template}}` placeholders in `endpoint` and `headers` using
+ * the Glubean runtime (vars and secrets). The returned `GraphQLClient` is
+ * lazily created on first access.
+ *
+ * @param options GraphQL client options (endpoint may use `{{var_name}}` templates)
+ * @returns A `PluginFactory` that produces a `GraphQLClient`
+ *
+ * @example
+ * ```ts
+ * import { test, configure } from "@glubean/sdk";
+ * import { graphql } from "@glubean/graphql";
+ *
+ * const { gql } = configure({
+ *   plugins: {
+ *     gql: graphql({
+ *       endpoint: "{{graphql_url}}",
+ *       headers: { Authorization: "Bearer {{api_key}}" },
+ *       throwOnGraphQLErrors: true,
+ *     }),
+ *   },
+ * });
+ *
+ * export const getUser = test("get-user", async (ctx) => {
+ *   const { data } = await gql.query<{ user: { name: string } }>(
+ *     `query GetUser($id: ID!) { user(id: $id) { name } }`,
+ *     { variables: { id: "1" } },
+ *   );
+ *   ctx.expect(data?.user.name).toBe("Alice");
+ * });
+ * ```
+ */
+export function graphql(options) {
+    return definePlugin((runtime) => {
+        const resolved = {
+            ...options,
+            endpoint: runtime.resolveTemplate(options.endpoint),
+        };
+        if (options.headers) {
+            resolved.headers = {};
+            for (const [k, v] of Object.entries(options.headers)) {
+                resolved.headers[k] = runtime.resolveTemplate(v);
+            }
+        }
+        return createGraphQLClient(runtime.http, resolved);
+    });
+}
+// Re-export data loader for convenience (spec: `import { fromGql } from "@glubean/graphql"`)
+export { fromGql } from "./data.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@glubean/graphql",
+  "version": "0.1.3",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./data": {
+      "types": "./dist/data.d.ts",
+      "import": "./dist/data.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@glubean/sdk": "0.1.3"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.1",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run"
+  }
+}