@decaf-ts/integrations 0.11.0 → 0.12.0

package/lib/types/io/environment.d.mts

@@ -0,0 +1,67 @@
+/**
+ * @module integrations/io/environment
+ * @summary Environment contract and accumulated environment for the io integration services.
+ * @description Declares the `IoEnvironmentShape` consumed by the Airtable,
+ * Google Sheets, and GraphQL services' `configFromEnvironment()`
+ * implementations and the `IoEnvironment` singleton created via
+ * `LoggedEnvironment.accumulate`. Services read their credentials and
+ * defaults from the matching `io.<provider>` slice, using the
+ * `envString`/`envNumber` helpers from `shared/environmentValue` to reject
+ * unset-leaf proxies.
+ */
+/**
+ * @description Environment shape for the io integration services
+ * @summary Defines the `io` root with one slice per provider (`airtable`,
+ * `googleSheets`, `graphql`). Each slice carries the provider's required
+ * credentials (`token`, plus `baseId`/`apiKey`/`endpoint` where applicable)
+ * plus an optional `baseUrl` override and `timeout`. Fields are typed as
+ * required here so `LoggedEnvironment.accumulate` registers them; absent
+ * values resolve to proxy placeholders at runtime and must pass through
+ * `envString`/`envNumber`.
+ * @memberOf module:integrations/io/environment
+ */
+export interface IoEnvironmentShape {
+    io: {
+        airtable: {
+            token: string;
+            baseUrl: string;
+            baseId: string;
+            timeout?: number;
+        };
+        googleSheets: {
+            token: string;
+            apiKey: string;
+            baseUrl: string;
+            timeout?: number;
+        };
+        graphql: {
+            endpoint: string;
+            token: string;
+            timeout?: number;
+        };
+    };
+}
+/**
+ * @description Accumulated io environment singleton
+ * @summary The `LoggedEnvironment.accumulate`-registered instance backing the
+ * `IoEnvironmentShape` contract. IO services read their provider slice
+ * (e.g. `IoEnvironment.io.airtable`) inside `configFromEnvironment()` and
+ * translate it into an `HttpApiServiceConfig`-derived config. Credentials
+ * come from environment variables; for as-graph node usage those are provided
+ * as `GRAPH_CREDENTIAL_*` values (placeholders in this example).
+ * @example
+ * ```ts
+ * import { AirtableService } from "@decaf-ts/integrations/io/airtable";
+ *
+ * // with io.airtable.token / io.airtable.baseId configured in the environment
+ * const airtable = new AirtableService();
+ * await airtable.initialize();
+ * ```
+ * @constant {LoggedEnvironment} IoEnvironment
+ * @memberOf module:integrations/io/environment
+ */
+export declare const IoEnvironment: import("@decaf-ts/logging").AccumulatedEnvironment<{
+    app: string | undefined;
+} & import("@decaf-ts/logging").LoggingConfig<object> & {
+    env: any;
+} & IoEnvironmentShape>;

package/lib/types/io/google-sheets/GoogleSheetsService.d.cts

@@ -0,0 +1,204 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.cts";
+/**
+ * @description Configuration for the Google Sheets service
+ * @summary Extends {@link HttpApiServiceConfig} with either an OAuth token
+ * (preferred, sent as a bearer token) or an API key (sent as
+ * `X-Goog-Api-Key`; read-only against public spreadsheets). When omitted, the
+ * `io.googleSheets` environment slice supplies both (and optional
+ * `baseUrl`/`timeout`).
+ * @category IO
+ * @memberOf module:integrations/io/google-sheets/service
+ */
+export interface GoogleSheetsServiceConfig extends HttpApiServiceConfig {
+    /**
+     * @description Google OAuth access token
+     * @summary Sent as `Authorization: Bearer <token>`; takes precedence over the API key.
+     */
+    token?: string;
+    /**
+     * @description Google API key
+     * @summary Sent as `X-Goog-Api-Key` when no OAuth token is configured.
+     */
+    apiKey?: string;
+}
+/**
+ * @description Result of a Google Sheets values read or write
+ * @summary Echoes the target `spreadsheetId` and the A1 `range` Google
+ * actually served, the `majorDimension` of the payload, and the grid
+ * `values` as an array of rows (arrays of cell strings).
+ * @category IO
+ * @memberOf module:integrations/io/google-sheets/service
+ */
+export interface GoogleSheetsValuesResult {
+    spreadsheetId: string;
+    range: string;
+    majorDimension?: string;
+    values: string[][];
+}
+/**
+ * @description Input for writing values into a Google Sheets range
+ * @summary Carries the target `spreadsheetId` and A1 `range`, the row
+ * `values` to write, and the `valueInputOption` controlling how Google
+ * interprets the cells (`"RAW"` stores text as-is, `"USER_ENTERED"` applies
+ * spreadsheet parsing and formulas; defaults to `"USER_ENTERED"`).
+ * @category IO
+ * @memberOf module:integrations/io/google-sheets/service
+ */
+export interface GoogleSheetsWriteInput {
+    spreadsheetId: string;
+    range: string;
+    values: unknown[][];
+    valueInputOption?: "RAW" | "USER_ENTERED";
+}
+/**
+ * @description Google Sheets API integration service
+ * @summary An undecorated HTTP service for reading,
+ * updating, appending, and clearing values in A1 ranges of a spreadsheet, and
+ * for creating new spreadsheets. Every operation requires either an OAuth
+ * token or an API key (`requireAuth()`); ranges and spreadsheet IDs are
+ * URL-encoded, and transport failures are mapped to decaf errors via
+ * {@link httpError}.
+ * @class GoogleSheetsService
+ * @category IO
+ * @example
+ * ```ts
+ * import { GoogleSheetsService } from "@decaf-ts/integrations/io/google-sheets";
+ *
+ * const sheets = new GoogleSheetsService();
+ * await sheets.initialize({
+ *   token: process.env.GRAPH_CREDENTIAL_GOOGLE_SHEETS_TOKEN,
+ * });
+ * const created = await sheets.createSpreadsheet("Metrics");
+ * await sheets.updateValues({
+ *   spreadsheetId: created.spreadsheetId,
+ *   range: "Sheet1!A1:B2",
+ *   values: [
+ *     ["date", "count"],
+ *     ["2026-01-01", "42"],
+ *   ],
+ * });
+ * ```
+ * @memberOf module:integrations/io/google-sheets/service
+ */
+export declare class GoogleSheetsService extends HttpApiService<GoogleSheetsServiceConfig> {
+    /**
+     * @description The provider name used in error messages
+     */
+    protected readonly serviceName = "Google Sheets";
+    /**
+     * @description The Google Sheets v4 values API base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://sheets.googleapis.com/v4/spreadsheets"`.
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Builds the Google Sheets authorization headers
+     * @summary Returns the `Authorization: Bearer <token>` header when the
+     * config carries an OAuth token, otherwise the `X-Goog-Api-Key` header when
+     * an API key is configured, and no headers otherwise.
+     * @param {GoogleSheetsServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization headers (empty without a token or API key).
+     */
+    protected authHeaders(config: GoogleSheetsServiceConfig): Record<string, string>;
+    /**
+     * @description Reads the Google Sheets credentials and defaults from the environment
+     * @summary Reads the `io.googleSheets` environment slice and returns a
+     * partial config when a token or API key is configured, `undefined`
+     * otherwise. Values pass through `envString`/`envNumber` to reject
+     * unset-leaf proxies.
+     * @returns {Partial<GoogleSheetsServiceConfig> | undefined} A partial config, or `undefined` when neither token nor API key is configured.
+     */
+    protected configFromEnvironment(): Partial<GoogleSheetsServiceConfig> | undefined;
+    /**
+     * @description Asserts that the service was configured with OAuth credentials
+     * @summary Throws when the resolved config carries neither a `token` nor an
+     * `apiKey`; every operation calls this before issuing requests.
+     * @returns {void}
+     * @throws {InternalError} When neither an OAuth token nor an API key is configured.
+     */
+    protected requireAuth(): void;
+    /**
+     * @description URL-encodes an A1 range for the values API path
+     * @summary Ranges such as `Sheet1!A1:B2` contain characters that must be
+     * percent-encoded; all operations route the range through this helper.
+     * @param {string} range - The A1 notation range to encode.
+     * @returns {string} The URL-encoded range.
+     */
+    protected rangePath(range: string): string;
+    /**
+     * @description Reads values from an A1 range of a spreadsheet
+     * @summary `GET`s the values endpoint for the given `spreadsheetId` and
+     * `range` and returns the served range, major dimension, and the grid
+     * values (rows of cell strings). Requires credentials and both arguments.
+     * @param {string} spreadsheetId - The spreadsheet to read from.
+     * @param {string} range - The A1 notation range to read (e.g. `"Sheet1!A1:C10"`).
+     * @returns {Promise<GoogleSheetsValuesResult>} The served range and grid values.
+     * @throws {InternalError} When credentials are missing or the spreadsheet ID/range is empty.
+     * @throws {NotFoundError} When the spreadsheet does not exist (HTTP 404).
+     * @throws {ConflictError} When Google answers with HTTP 409.
+     * @throws {BadRequestError} When Google answers with any other HTTP error status (e.g. invalid range).
+     */
+    getValues(spreadsheetId: string, range: string): Promise<GoogleSheetsValuesResult>;
+    /**
+     * @description Overwrites values in an A1 range of a spreadsheet
+     * @summary `PUT`s the row values to the values endpoint for the given
+     * `spreadsheetId` and `range`. Cells are interpreted according to
+     * `valueInputOption` (`"USER_ENTERED"` by default, `"RAW"` to store text
+     * verbatim), and the existing range content is replaced.
+     * @param {GoogleSheetsWriteInput} input - The target spreadsheet, range, values, and input interpretation.
+     * @returns {Promise<GoogleSheetsValuesResult>} The served range and the written values.
+     * @throws {InternalError} When credentials are missing.
+     * @throws {NotFoundError} When the spreadsheet does not exist (HTTP 404).
+     * @throws {ConflictError} When Google answers with HTTP 409.
+     * @throws {BadRequestError} When Google answers with any other HTTP error status (e.g. invalid range).
+     */
+    updateValues(input: GoogleSheetsWriteInput): Promise<GoogleSheetsValuesResult>;
+    /**
+     * @description Appends values after the last row of an A1 range's table
+     * @summary `POST`s the row values to the `:append` endpoint for the given
+     * `spreadsheetId` and `range`, inserting new rows after existing table data
+     * (`insertDataOption: "INSERT_ROWS"`). Cells are interpreted according to
+     * `valueInputOption` (`"USER_ENTERED"` by default). Use a single-row or
+     * single-column A1 range to anchor the table; Google reports the range the
+     * data actually landed in.
+     * @param {GoogleSheetsWriteInput} input - The target spreadsheet, anchor range, values, and input interpretation.
+     * @returns {Promise<GoogleSheetsValuesResult>} The range the appended rows landed in and the appended values.
+     * @throws {InternalError} When credentials are missing.
+     * @throws {NotFoundError} When the spreadsheet does not exist (HTTP 404).
+     * @throws {ConflictError} When Google answers with HTTP 409.
+     * @throws {BadRequestError} When Google answers with any other HTTP error status (e.g. invalid range).
+     */
+    appendValues(input: GoogleSheetsWriteInput): Promise<GoogleSheetsValuesResult>;
+    /**
+     * @description Clears all values in an A1 range of a spreadsheet
+     * @summary `POST`s the `:clear` endpoint for the given `spreadsheetId` and
+     * `range`, emptying the cells while preserving formatting, and returns the
+     * range Google actually cleared.
+     * @param {string} spreadsheetId - The spreadsheet to clear values in.
+     * @param {string} range - The A1 notation range to clear.
+     * @returns {Promise<{spreadsheetId: string, clearedRange: string}>} The cleared range as reported by Google.
+     * @throws {InternalError} When credentials are missing.
+     * @throws {NotFoundError} When the spreadsheet does not exist (HTTP 404).
+     * @throws {ConflictError} When Google answers with HTTP 409.
+     * @throws {BadRequestError} When Google answers with any other HTTP error status (e.g. invalid range).
+     */
+    clearValues(spreadsheetId: string, range: string): Promise<{
+        spreadsheetId: string;
+        clearedRange: string;
+    }>;
+    /**
+     * @description Creates a new spreadsheet with the given title
+     * @summary `POST`s a spreadsheet resource with `properties.title` to the
+     * spreadsheets endpoint and returns the new spreadsheet's ID and URL.
+     * @param {string} title - The title for the new spreadsheet.
+     * @returns {Promise<{spreadsheetId: string, spreadsheetUrl?: string}>} The created spreadsheet's ID and URL.
+     * @throws {InternalError} When credentials are missing or the title is empty.
+     * @throws {NotFoundError} When Google answers with HTTP 404.
+     * @throws {ConflictError} When Google answers with HTTP 409.
+     * @throws {BadRequestError} When Google answers with any other HTTP error status.
+     */
+    createSpreadsheet(title: string): Promise<{
+        spreadsheetId: string;
+        spreadsheetUrl?: string;
+    }>;
+}

package/lib/types/io/google-sheets/GoogleSheetsService.d.mts

@@ -0,0 +1,204 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.mts";
+/**
+ * @description Configuration for the Google Sheets service
+ * @summary Extends {@link HttpApiServiceConfig} with either an OAuth token
+ * (preferred, sent as a bearer token) or an API key (sent as
+ * `X-Goog-Api-Key`; read-only against public spreadsheets). When omitted, the
+ * `io.googleSheets` environment slice supplies both (and optional
+ * `baseUrl`/`timeout`).
+ * @category IO
+ * @memberOf module:integrations/io/google-sheets/service
+ */
+export interface GoogleSheetsServiceConfig extends HttpApiServiceConfig {
+    /**
+     * @description Google OAuth access token
+     * @summary Sent as `Authorization: Bearer <token>`; takes precedence over the API key.
+     */
+    token?: string;
+    /**
+     * @description Google API key
+     * @summary Sent as `X-Goog-Api-Key` when no OAuth token is configured.
+     */
+    apiKey?: string;
+}
+/**
+ * @description Result of a Google Sheets values read or write
+ * @summary Echoes the target `spreadsheetId` and the A1 `range` Google
+ * actually served, the `majorDimension` of the payload, and the grid
+ * `values` as an array of rows (arrays of cell strings).
+ * @category IO
+ * @memberOf module:integrations/io/google-sheets/service
+ */
+export interface GoogleSheetsValuesResult {
+    spreadsheetId: string;
+    range: string;
+    majorDimension?: string;
+    values: string[][];
+}
+/**
+ * @description Input for writing values into a Google Sheets range
+ * @summary Carries the target `spreadsheetId` and A1 `range`, the row
+ * `values` to write, and the `valueInputOption` controlling how Google
+ * interprets the cells (`"RAW"` stores text as-is, `"USER_ENTERED"` applies
+ * spreadsheet parsing and formulas; defaults to `"USER_ENTERED"`).
+ * @category IO
+ * @memberOf module:integrations/io/google-sheets/service
+ */
+export interface GoogleSheetsWriteInput {
+    spreadsheetId: string;
+    range: string;
+    values: unknown[][];
+    valueInputOption?: "RAW" | "USER_ENTERED";
+}
+/**
+ * @description Google Sheets API integration service
+ * @summary An undecorated HTTP service for reading,
+ * updating, appending, and clearing values in A1 ranges of a spreadsheet, and
+ * for creating new spreadsheets. Every operation requires either an OAuth
+ * token or an API key (`requireAuth()`); ranges and spreadsheet IDs are
+ * URL-encoded, and transport failures are mapped to decaf errors via
+ * {@link httpError}.
+ * @class GoogleSheetsService
+ * @category IO
+ * @example
+ * ```ts
+ * import { GoogleSheetsService } from "@decaf-ts/integrations/io/google-sheets";
+ *
+ * const sheets = new GoogleSheetsService();
+ * await sheets.initialize({
+ *   token: process.env.GRAPH_CREDENTIAL_GOOGLE_SHEETS_TOKEN,
+ * });
+ * const created = await sheets.createSpreadsheet("Metrics");
+ * await sheets.updateValues({
+ *   spreadsheetId: created.spreadsheetId,
+ *   range: "Sheet1!A1:B2",
+ *   values: [
+ *     ["date", "count"],
+ *     ["2026-01-01", "42"],
+ *   ],
+ * });
+ * ```
+ * @memberOf module:integrations/io/google-sheets/service
+ */
+export declare class GoogleSheetsService extends HttpApiService<GoogleSheetsServiceConfig> {
+    /**
+     * @description The provider name used in error messages
+     */
+    protected readonly serviceName = "Google Sheets";
+    /**
+     * @description The Google Sheets v4 values API base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://sheets.googleapis.com/v4/spreadsheets"`.
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Builds the Google Sheets authorization headers
+     * @summary Returns the `Authorization: Bearer <token>` header when the
+     * config carries an OAuth token, otherwise the `X-Goog-Api-Key` header when
+     * an API key is configured, and no headers otherwise.
+     * @param {GoogleSheetsServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization headers (empty without a token or API key).
+     */
+    protected authHeaders(config: GoogleSheetsServiceConfig): Record<string, string>;
+    /**
+     * @description Reads the Google Sheets credentials and defaults from the environment
+     * @summary Reads the `io.googleSheets` environment slice and returns a
+     * partial config when a token or API key is configured, `undefined`
+     * otherwise. Values pass through `envString`/`envNumber` to reject
+     * unset-leaf proxies.
+     * @returns {Partial<GoogleSheetsServiceConfig> | undefined} A partial config, or `undefined` when neither token nor API key is configured.
+     */
+    protected configFromEnvironment(): Partial<GoogleSheetsServiceConfig> | undefined;
+    /**
+     * @description Asserts that the service was configured with OAuth credentials
+     * @summary Throws when the resolved config carries neither a `token` nor an
+     * `apiKey`; every operation calls this before issuing requests.
+     * @returns {void}
+     * @throws {InternalError} When neither an OAuth token nor an API key is configured.
+     */
+    protected requireAuth(): void;
+    /**
+     * @description URL-encodes an A1 range for the values API path
+     * @summary Ranges such as `Sheet1!A1:B2` contain characters that must be
+     * percent-encoded; all operations route the range through this helper.
+     * @param {string} range - The A1 notation range to encode.
+     * @returns {string} The URL-encoded range.
+     */
+    protected rangePath(range: string): string;
+    /**
+     * @description Reads values from an A1 range of a spreadsheet
+     * @summary `GET`s the values endpoint for the given `spreadsheetId` and
+     * `range` and returns the served range, major dimension, and the grid
+     * values (rows of cell strings). Requires credentials and both arguments.
+     * @param {string} spreadsheetId - The spreadsheet to read from.
+     * @param {string} range - The A1 notation range to read (e.g. `"Sheet1!A1:C10"`).
+     * @returns {Promise<GoogleSheetsValuesResult>} The served range and grid values.
+     * @throws {InternalError} When credentials are missing or the spreadsheet ID/range is empty.
+     * @throws {NotFoundError} When the spreadsheet does not exist (HTTP 404).
+     * @throws {ConflictError} When Google answers with HTTP 409.
+     * @throws {BadRequestError} When Google answers with any other HTTP error status (e.g. invalid range).
+     */
+    getValues(spreadsheetId: string, range: string): Promise<GoogleSheetsValuesResult>;
+    /**
+     * @description Overwrites values in an A1 range of a spreadsheet
+     * @summary `PUT`s the row values to the values endpoint for the given
+     * `spreadsheetId` and `range`. Cells are interpreted according to
+     * `valueInputOption` (`"USER_ENTERED"` by default, `"RAW"` to store text
+     * verbatim), and the existing range content is replaced.
+     * @param {GoogleSheetsWriteInput} input - The target spreadsheet, range, values, and input interpretation.
+     * @returns {Promise<GoogleSheetsValuesResult>} The served range and the written values.
+     * @throws {InternalError} When credentials are missing.
+     * @throws {NotFoundError} When the spreadsheet does not exist (HTTP 404).
+     * @throws {ConflictError} When Google answers with HTTP 409.
+     * @throws {BadRequestError} When Google answers with any other HTTP error status (e.g. invalid range).
+     */
+    updateValues(input: GoogleSheetsWriteInput): Promise<GoogleSheetsValuesResult>;
+    /**
+     * @description Appends values after the last row of an A1 range's table
+     * @summary `POST`s the row values to the `:append` endpoint for the given
+     * `spreadsheetId` and `range`, inserting new rows after existing table data
+     * (`insertDataOption: "INSERT_ROWS"`). Cells are interpreted according to
+     * `valueInputOption` (`"USER_ENTERED"` by default). Use a single-row or
+     * single-column A1 range to anchor the table; Google reports the range the
+     * data actually landed in.
+     * @param {GoogleSheetsWriteInput} input - The target spreadsheet, anchor range, values, and input interpretation.
+     * @returns {Promise<GoogleSheetsValuesResult>} The range the appended rows landed in and the appended values.
+     * @throws {InternalError} When credentials are missing.
+     * @throws {NotFoundError} When the spreadsheet does not exist (HTTP 404).
+     * @throws {ConflictError} When Google answers with HTTP 409.
+     * @throws {BadRequestError} When Google answers with any other HTTP error status (e.g. invalid range).
+     */
+    appendValues(input: GoogleSheetsWriteInput): Promise<GoogleSheetsValuesResult>;
+    /**
+     * @description Clears all values in an A1 range of a spreadsheet
+     * @summary `POST`s the `:clear` endpoint for the given `spreadsheetId` and
+     * `range`, emptying the cells while preserving formatting, and returns the
+     * range Google actually cleared.
+     * @param {string} spreadsheetId - The spreadsheet to clear values in.
+     * @param {string} range - The A1 notation range to clear.
+     * @returns {Promise<{spreadsheetId: string, clearedRange: string}>} The cleared range as reported by Google.
+     * @throws {InternalError} When credentials are missing.
+     * @throws {NotFoundError} When the spreadsheet does not exist (HTTP 404).
+     * @throws {ConflictError} When Google answers with HTTP 409.
+     * @throws {BadRequestError} When Google answers with any other HTTP error status (e.g. invalid range).
+     */
+    clearValues(spreadsheetId: string, range: string): Promise<{
+        spreadsheetId: string;
+        clearedRange: string;
+    }>;
+    /**
+     * @description Creates a new spreadsheet with the given title
+     * @summary `POST`s a spreadsheet resource with `properties.title` to the
+     * spreadsheets endpoint and returns the new spreadsheet's ID and URL.
+     * @param {string} title - The title for the new spreadsheet.
+     * @returns {Promise<{spreadsheetId: string, spreadsheetUrl?: string}>} The created spreadsheet's ID and URL.
+     * @throws {InternalError} When credentials are missing or the title is empty.
+     * @throws {NotFoundError} When Google answers with HTTP 404.
+     * @throws {ConflictError} When Google answers with HTTP 409.
+     * @throws {BadRequestError} When Google answers with any other HTTP error status.
+     */
+    createSpreadsheet(title: string): Promise<{
+        spreadsheetId: string;
+        spreadsheetUrl?: string;
+    }>;
+}

package/lib/types/io/google-sheets/index.d.cts

@@ -0,0 +1,6 @@
+/**
+ * @module integrations/io/google-sheets
+ * @summary Google Sheets REST v4 service (values read/write/append/clear, spreadsheet creation).
+ * @description Re-exports the Google Sheets client-based service and its types.
+ */
+export * from "./GoogleSheetsService.d.cts";

package/lib/types/io/google-sheets/index.d.mts

@@ -0,0 +1,6 @@
+/**
+ * @module integrations/io/google-sheets
+ * @summary Google Sheets REST v4 service (values read/write/append/clear, spreadsheet creation).
+ * @description Re-exports the Google Sheets client-based service and its types.
+ */
+export * from "./GoogleSheetsService.d.mts";

package/lib/types/io/graphql/GraphqlService.d.cts

@@ -0,0 +1,173 @@
+/**
+ * @module integrations/io/graphql/service
+ * @summary Generic GraphQL endpoint integration service for executing queries and mutations.
+ * @description Posts GraphQL documents to any endpoint as an undecorated
+ * client-based service built on {@link HttpApiService}.
+ * The endpoint is supplied as `endpoint` (an alias normalized to `baseUrl`
+ * during initialization) or the `io.graphql` environment slice; an optional
+ * bearer token is attached to every request, per-request headers can extend
+ * it, and failures are mapped to decaf errors via {@link httpError}. GraphQL
+ * field-level `errors` are returned in the response rather than thrown —
+ * callers decide how to handle partial results.
+ */
+import { type MaybeContextualArg } from "@decaf-ts/core";
+import type { AxiosInstance } from "axios";
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.cts";
+/**
+ * @description Configuration for the GraphQL service
+ * @summary Extends {@link HttpApiServiceConfig} with the GraphQL `endpoint`
+ * URL (normalized to `baseUrl` during initialization) and the optional bearer
+ * token. When omitted, the `io.graphql` environment slice supplies the
+ * endpoint (and optional `token`, `timeout`).
+ * @category IO
+ * @memberOf module:integrations/io/graphql/service
+ */
+export interface GraphqlServiceConfig extends HttpApiServiceConfig {
+    /**
+     * @description GraphQL endpoint URL
+     * @summary Aliased to `baseUrl` by {@link GraphqlService.initialize}; every
+     * request is posted to this URL.
+     */
+    endpoint?: string;
+    /**
+     * @description Bearer token for the endpoint
+     * @summary Sent as `Authorization: Bearer <token>` with every request.
+     */
+    token?: string;
+}
+/**
+ * @description Input for a GraphQL request
+ * @summary Carries the `query` document, the `variables` map referenced by
+ * it, the optional `operationName` when the document holds multiple named
+ * operations, and per-request `headers` merged into the client's defaults.
+ * @category IO
+ * @memberOf module:integrations/io/graphql/service
+ */
+export interface GraphqlRequest {
+    /**
+     * @description The GraphQL query or mutation document (required)
+     */
+    query: string;
+    /**
+     * @description Variable values for the document's declared variables
+     */
+    variables?: Record<string, unknown>;
+    /**
+     * @description The operation to execute when the document defines several
+     */
+    operationName?: string;
+    /**
+     * @description Extra headers merged over the client's defaults for this request
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * @description GraphQL response envelope
+ * @summary The standard GraphQL execution result: `data` when the operation
+ * produced results, field-level `errors` (message plus response path) when
+ * execution partially failed, and provider `extensions`.
+ * @template T - The expected type of the `data` payload.
+ * @category IO
+ * @memberOf module:integrations/io/graphql/service
+ */
+export interface GraphqlResponse<T = unknown> {
+    data?: T;
+    errors?: Array<{
+        message: string;
+        path?: Array<string | number>;
+    }>;
+    extensions?: Record<string, unknown>;
+}
+/**
+ * @description Generic GraphQL endpoint integration service
+ * @summary An undecorated HTTP service that `POST`s GraphQL
+ * documents to any endpoint. Unlike the other integration services there is
+ * no default base URL — the endpoint must come from the config (`endpoint` or
+ * `baseUrl`) or the `io.graphql` environment slice. Initialization normalizes
+ * the `endpoint` alias to `baseUrl` before delegating to the shared
+ * {@link HttpApiService.initialize}; the optional token is sent as a bearer
+ * header and per-request headers extend it. Transport failures are mapped to
+ * decaf errors via {@link httpError}, while GraphQL field-level `errors` are
+ * returned in the response for the caller to interpret.
+ * @class GraphqlService
+ * @category IO
+ * @example
+ * ```ts
+ * import { GraphqlService } from "@decaf-ts/integrations/io/graphql";
+ *
+ * const graphql = new GraphqlService();
+ * await graphql.initialize({
+ *   endpoint: "https://api.example.com/graphql",
+ *   token: process.env.GRAPH_CREDENTIAL_GRAPHQL_TOKEN,
+ * });
+ * const response = await graphql.request<{ user: { name: string } }>({
+ *   query: `query GetUser($id: ID!) {
+ *     user(id: $id) { name }
+ *   }`,
+ *   variables: { id: "123" },
+ * });
+ * ```
+ * @memberOf module:integrations/io/graphql/service
+ */
+export declare class GraphqlService extends HttpApiService<GraphqlServiceConfig> {
+    /**
+     * @description The provider name used in error messages
+     */
+    protected readonly serviceName = "GraphQL";
+    /**
+     * @description The absence of a default GraphQL endpoint
+     * @summary Returns an empty string because GraphQL endpoints are
+     * provider-specific; {@link GraphqlService.request} rejects execution when
+     * no endpoint was configured.
+     * @returns {string} An empty string.
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Normalizes the `endpoint` alias before shared initialization
+     * @summary When the provided config carries no `baseUrl` but an `endpoint`,
+     * copies `endpoint` into `baseUrl` and delegates to
+     * {@link HttpApiService.initialize}, which merges the environment slice and
+     * builds the Axios client.
+     * @param {...MaybeContextualArg<any>} args - An optional `Partial<GraphqlServiceConfig>`, optionally followed by a decaf `Context`.
+     * @returns {Promise<{config: GraphqlServiceConfig, client: AxiosInstance}>} The merged configuration and the configured Axios instance.
+     * @throws {InternalError} When no base URL can be resolved from the config or environment.
+     */
+    initialize(...args: MaybeContextualArg<any>): Promise<{
+        config: GraphqlServiceConfig;
+        client: AxiosInstance;
+    }>;
+    /**
+     * @description Builds the GraphQL bearer authorization headers
+     * @summary Returns the `Authorization: Bearer <token>` header when the
+     * config carries a token, and no headers otherwise.
+     * @param {GraphqlServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization headers (empty without a token).
+     */
+    protected authHeaders(config: GraphqlServiceConfig): Record<string, string>;
+    /**
+     * @description Reads the GraphQL endpoint and token from the environment
+     * @summary Reads the `io.graphql` environment slice and returns a partial
+     * config (with `endpoint` also mirrored to `baseUrl`) when an endpoint is
+     * configured, `undefined` otherwise. Values pass through
+     * `envString`/`envNumber` to reject unset-leaf proxies.
+     * @returns {Partial<GraphqlServiceConfig> | undefined} A partial config, or `undefined` when no GraphQL endpoint is configured.
+     */
+    protected configFromEnvironment(): Partial<GraphqlServiceConfig> | undefined;
+    /**
+     * @description Executes a GraphQL query or mutation against the configured endpoint
+     * @summary `POST`s the standard GraphQL request body (`query`,
+     * `variables`, `operationName`) to the resolved endpoint with the optional
+     * per-request headers merged over the client defaults. Requires a
+     * non-empty query and a configured endpoint. Returns the raw execution
+     * envelope: field-level `errors` are reported in `GraphqlResponse.errors`
+     * rather than thrown, so callers must inspect them for partial failures.
+     * @template T - The expected type of the `data` payload.
+     * @param {GraphqlRequest} input - The query document, variables, operation name, and per-request headers.
+     * @returns {Promise<GraphqlResponse<T>>} The execution envelope with `data`, `errors`, and `extensions`.
+     * @throws {InternalError} When the query is empty or no endpoint is configured.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When the endpoint answers with HTTP 409.
+     * @throws {BadRequestError} When the endpoint answers with any other HTTP error status.
+     */
+    request<T = unknown>(input: GraphqlRequest): Promise<GraphqlResponse<T>>;
+}