import type * as Credentials from "@distilled.cloud/aws/Credentials";
import type * as SigV4 from "@distilled.cloud/aws/SigV4";
import * as Binding from "alchemy/Binding";
import * as Data from "effect/Data";
import type * as Effect from "effect/Effect";
import type { GraphqlApi } from "./GraphqlApi.ts";
/**
* The GraphQL endpoint returned a non-2xx response or an unparseable body.
* GraphQL *field* errors do NOT fail the effect — they are surfaced on
* {@link GraphQLResult.errors} alongside any partial `data`.
*/
export class GraphQLApiError extends Data.TaggedError("GraphQLApiError")<{
/** HTTP status of the failed request (0 when the request never left). */
readonly status: number;
/** The raw response body (or the underlying failure message). */
readonly body: string;
}> {}
/** A single entry of the standard GraphQL `errors` array. */
export interface GraphQLErrorItem {
message: string;
path?: ReadonlyArray<string | number>;
locations?: ReadonlyArray<{ line: number; column: number }>;
errorType?: string;
[key: string]: unknown;
}
/** The standard GraphQL response envelope. */
export interface GraphQLResult<T = unknown> {
/** The (possibly partial) result data. */
data?: T;
/** GraphQL field/validation errors, if any. */
errors?: ReadonlyArray<GraphQLErrorItem>;
extensions?: Record<string, unknown>;
}
/** A GraphQL operation to execute against the API. */
export interface GraphQLRequest {
/** The GraphQL document, e.g. `query($a: Int!) { add(a: $a, b: 1) }`. */
query: string;
/** Values for the document's variables. */
variables?: Record<string, unknown>;
/** Which operation to run when the document defines several. */
operationName?: string;
}
export interface GraphQLClient {
/**
* Execute a GraphQL operation (query or mutation), SigV4-signed with the
* host Function's credentials. Fails only on transport/HTTP errors —
* GraphQL field errors are returned on `result.errors`.
*/
execute<T = unknown>(
request: GraphQLRequest,
): Effect.Effect<
GraphQLResult<T>,
GraphQLApiError | Credentials.CredentialsError | SigV4.SigningError
>;
}
/**
* Runtime binding for the `appsync:GraphQL` data-plane action — execute
* GraphQL operations against a {@link GraphqlApi}'s endpoint from a Lambda
* (or other AWS runtime), SigV4-signed with the host Function's IAM role.
*
* The API must accept `AWS_IAM` authentication (as its primary mode or an
* additional provider). Provide `AppSync.GraphQLHttp` on the hosting
* function's Effect to implement the binding.
*
* ### Executing GraphQL Operations
* **Example:** Query an IAM-authenticated API
* ```typescript
* const api = yield* AppSync.GraphqlApi("Api", {
* authenticationType: "AWS_IAM",
* schema,
* });
* const graphql = yield* AppSync.GraphQL(api);
*
* const result = yield* graphql.execute<{ add: number }>({
* query: "query($a: Int!, $b: Int!) { add(a: $a, b: $b) }",
* variables: { a: 2, b: 3 },
* });
* // result.data?.add === 5; field errors appear on result.errors
* ```
*
* @binding
*/
export interface GraphQL extends Binding.Service<
GraphQL,
"AWS.AppSync.GraphQL",
(api: GraphqlApi) => Effect.Effect<GraphQLClient>
> {}
export const GraphQL = Binding.Service<GraphQL>("AWS.AppSync.GraphQL");