@decaf-ts/integrations 0.11.0 → 0.14.0

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>>;
+}

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

@@ -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.mts";
+/**
+ * @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>>;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * @module integrations/io/graphql
+ * @summary Generic GraphQL endpoint client (queries and mutations).
+ * @description Re-exports the GraphQL client-based service and its types.
+ */
+export * from "./GraphqlService.d.cts";

package/lib/types/io/graphql/index.d.mts

@@ -0,0 +1,6 @@
+/**
+ * @module integrations/io/graphql
+ * @summary Generic GraphQL endpoint client (queries and mutations).
+ * @description Re-exports the GraphQL client-based service and its types.
+ */
+export * from "./GraphqlService.d.mts";

package/lib/types/io/index.d.cts

@@ -0,0 +1,17 @@
+/**
+ * @module integrations/io
+ * @summary IO integration services (Google Sheets, Airtable, GraphQL, Spreadsheet).
+ * @description Re-exports the data-source services, their per-service modules,
+ * and the shared `io` environment slice. Each sub-module is also available
+ * through its own package subpath export.
+ */
+export * from "./airtable/index.d.cts";
+export * from "./google-sheets/index.d.cts";
+export * from "./graphql/index.d.cts";
+export * from "./spreadsheet/index.d.cts";
+export * from "./microsoft-excel/index.d.cts";
+export * from "./confluence/index.d.cts";
+export * from "./jira/index.d.cts";
+export * from "./google-docs/index.d.cts";
+export * from "./microsoft-sharepoint/index.d.cts";
+export * from "./environment.d.cts";

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

@@ -0,0 +1,17 @@
+/**
+ * @module integrations/io
+ * @summary IO integration services (Google Sheets, Airtable, GraphQL, Spreadsheet).
+ * @description Re-exports the data-source services, their per-service modules,
+ * and the shared `io` environment slice. Each sub-module is also available
+ * through its own package subpath export.
+ */
+export * from "./airtable/index.d.mts";
+export * from "./google-sheets/index.d.mts";
+export * from "./graphql/index.d.mts";
+export * from "./spreadsheet/index.d.mts";
+export * from "./microsoft-excel/index.d.mts";
+export * from "./confluence/index.d.mts";
+export * from "./jira/index.d.mts";
+export * from "./google-docs/index.d.mts";
+export * from "./microsoft-sharepoint/index.d.mts";
+export * from "./environment.d.mts";