@aws-amplify/api-graphql 0.0.0-unstable-1ca644b-20260128091132

package/src/internals/graphqlAuth.ts

@@ -0,0 +1,87 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { GraphQLAuthMode } from '@aws-amplify/core/internals/utils';
+import { AmplifyClassV6 } from '@aws-amplify/core';
+
+import { GraphQLApiError } from '../utils/errors';
+import {
+	NO_API_KEY,
+	NO_AUTH_TOKEN_HEADER,
+	NO_SIGNED_IN_USER,
+	NO_VALID_AUTH_TOKEN,
+	NO_VALID_CREDENTIALS,
+} from '../utils/errors/constants';
+
+export async function headerBasedAuth(
+	amplify: AmplifyClassV6,
+	authMode: GraphQLAuthMode,
+	apiKey: string | undefined,
+	additionalHeaders: Record<string, string> = {},
+) {
+	let headers = {};
+
+	switch (authMode) {
+		case 'apiKey':
+			if (!apiKey) {
+				throw new GraphQLApiError(NO_API_KEY);
+			}
+			headers = {
+				'X-Api-Key': apiKey,
+			};
+			break;
+		case 'iam': {
+			const session = await amplify.Auth.fetchAuthSession();
+			if (session.credentials === undefined) {
+				throw new GraphQLApiError(NO_VALID_CREDENTIALS);
+			}
+			break;
+		}
+		case 'oidc':
+		case 'userPool': {
+			let token: string | undefined;
+
+			try {
+				token = (
+					await amplify.Auth.fetchAuthSession()
+				).tokens?.accessToken.toString();
+			} catch (e) {
+				// fetchAuthSession failed
+				throw new GraphQLApiError({
+					...NO_SIGNED_IN_USER,
+					underlyingError: e,
+				});
+			}
+
+			// `fetchAuthSession()` succeeded but didn't return `tokens`.
+			// This may happen when unauthenticated access is enabled and there is
+			// no user signed in.
+			if (!token) {
+				throw new GraphQLApiError(NO_VALID_AUTH_TOKEN);
+			}
+
+			headers = {
+				Authorization: token,
+			};
+			break;
+		}
+		case 'lambda':
+			if (
+				typeof additionalHeaders === 'object' &&
+				!additionalHeaders.Authorization
+			) {
+				throw new GraphQLApiError(NO_AUTH_TOKEN_HEADER);
+			}
+
+			headers = {
+				Authorization: additionalHeaders.Authorization,
+			};
+			break;
+		case 'none':
+			break;
+		default:
+			break;
+	}
+
+	return headers;
+}

package/src/internals/graphqlRequest.ts

@@ -0,0 +1,30 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AmplifyUrl } from '@aws-amplify/core/internals/utils';
+import { AmplifyClassV6 } from '@aws-amplify/core';
+import {
+	// cancel as cancelREST,
+	post,
+	// updateRequestToBeCancellable,
+} from '@aws-amplify/api-rest/internals';
+
+export async function graphqlRequest(
+	amplify: AmplifyClassV6,
+	url: string,
+	options: any,
+	abortController: AbortController,
+	_post?: typeof post,
+) {
+	const p = _post ?? post;
+
+	const { body: responseBody } = await p(amplify, {
+		url: new AmplifyUrl(url),
+		options,
+		abortController,
+	});
+
+	const response = await responseBody.json();
+
+	return response;
+}

package/src/internals/index.ts

@@ -0,0 +1,10 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+export {
+	InternalGraphQLAPI,
+	InternalGraphQLAPIClass,
+} from './InternalGraphQLAPI';
+
+export { graphql, cancel, isCancelError } from './v6';
+export { generateClient } from './generateClient';
+export { CommonPublicClientOptions, DefaultCommonClientOptions } from './types';

package/src/internals/server/generateClientWithAmplifyInstance.ts

@@ -0,0 +1,73 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { addSchemaToClientWithInstance } from '@aws-amplify/data-schema/runtime';
+
+import {
+	CommonPublicClientOptions,
+	ServerClientGenerationParams,
+	V6ClientSSRCookies,
+	V6ClientSSRRequest,
+	__amplify,
+	__apiKey,
+	__authMode,
+	__authToken,
+	__endpoint,
+	__headers,
+	getInternals,
+} from '../../types';
+import { isApiGraphQLConfig } from '../utils/runtimeTypeGuards/isApiGraphQLProviderConfig';
+import { cancel, graphql, isCancelError } from '..';
+
+/**
+ * @private
+ *
+ * Used internally by `adapter-nextjs` package.
+ *
+ * Creates a client that can be used to make GraphQL requests, using a provided `AmplifyClassV6`
+ * compatible context object for config and auth fetching.
+ *
+ * @param params
+ * @returns
+ */
+export function generateClientWithAmplifyInstance<
+	T extends Record<any, any> = never,
+	ClientType extends
+		| V6ClientSSRRequest<T>
+		| V6ClientSSRCookies<T> = V6ClientSSRCookies<T>,
+>(
+	params: ServerClientGenerationParams & CommonPublicClientOptions,
+): ClientType {
+	const client = {
+		[__amplify]: params.amplify,
+		[__authMode]: params.authMode,
+		[__authToken]: params.authToken,
+		[__apiKey]: 'apiKey' in params ? params.apiKey : undefined,
+		[__endpoint]: 'endpoint' in params ? params.endpoint : undefined,
+		[__headers]: params.headers,
+		graphql,
+		cancel,
+		isCancelError,
+	} as any;
+
+	const apiGraphqlConfig = params.config?.API?.GraphQL;
+
+	if (client[__endpoint]) {
+		if (!client[__authMode]) {
+			throw new Error(
+				'generateClient() requires an explicit `authMode` when `endpoint` is provided.',
+			);
+		}
+		if (client[__authMode] === 'apiKey' && !client[__apiKey]) {
+			throw new Error(
+				"generateClient() requires an explicit `apiKey` when `endpoint` is provided and `authMode = 'apiKey'`.",
+			);
+		}
+	}
+
+	if (!client[__endpoint] && isApiGraphQLConfig(apiGraphqlConfig)) {
+		addSchemaToClientWithInstance<T>(client, params, getInternals);
+	}
+
+	return client as any;
+}

package/src/internals/server/index.ts

@@ -0,0 +1,4 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { generateClientWithAmplifyInstance } from './generateClientWithAmplifyInstance';

package/src/internals/types.ts

@@ -0,0 +1,42 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { AmplifyClassV6 } from '@aws-amplify/core';
+import { GraphQLAuthMode } from '@aws-amplify/core/internals/utils';
+import { CustomHeaders } from '@aws-amplify/data-schema/runtime';
+
+/**
+ * @private
+ *
+ * The knobs available for configuring `generateClient` internally.
+ */
+export type ClientGenerationParams = {
+	amplify: AmplifyClassV6;
+} & CommonPublicClientOptions;
+
+export interface DefaultCommonClientOptions {
+	endpoint?: never;
+	authMode?: GraphQLAuthMode;
+	apiKey?: string;
+	authToken?: string;
+	headers?: CustomHeaders;
+}
+
+/**
+ * Common options that can be used on public `generateClient()` interfaces.
+ */
+export type CommonPublicClientOptions =
+	| DefaultCommonClientOptions
+	| {
+			endpoint: string;
+			authMode: 'apiKey';
+			apiKey: string;
+			authToken?: string;
+			headers?: CustomHeaders;
+	  }
+	| {
+			endpoint: string;
+			authMode: Exclude<GraphQLAuthMode, 'apiKey'>;
+			apiKey?: string;
+			authToken?: string;
+			headers?: CustomHeaders;
+	  };

package/src/internals/utils/runtimeTypeGuards/isApiGraphQLProviderConfig.ts

@@ -0,0 +1,10 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { GraphQLProviderConfig } from '@aws-amplify/core/internals/utils';
+
+export function isApiGraphQLConfig(
+	apiGraphQLConfig: GraphQLProviderConfig['GraphQL'] | undefined,
+): apiGraphQLConfig is GraphQLProviderConfig['GraphQL'] {
+	return apiGraphQLConfig !== undefined;
+}

package/src/internals/utils/runtimeTypeGuards/isConfigureEventWithResourceConfig.ts

@@ -0,0 +1,13 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { HubCapsule, ResourcesConfig } from '@aws-amplify/core';
+
+export function isConfigureEventWithResourceConfig(
+	payload: HubCapsule<'core', { event: string; data?: unknown }>['payload'],
+): payload is {
+	event: 'configure';
+	data: ResourcesConfig;
+} {
+	return payload.event === 'configure';
+}

package/src/internals/utils/runtimeTypeGuards/isGraphQLResponseWithErrors.ts

@@ -0,0 +1,15 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { GraphQLResult } from '../../../types';
+
+export function isGraphQLResponseWithErrors(
+	response: unknown,
+): response is GraphQLResult {
+	if (!response) {
+		return false;
+	}
+	const r = response as GraphQLResult;
+
+	return Array.isArray(r.errors) && r.errors.length > 0;
+}

package/src/internals/v6.ts

@@ -0,0 +1,189 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { CustomHeaders } from '@aws-amplify/data-schema/runtime';
+
+import { GraphQLAPI } from '../GraphQLAPI';
+import {
+	CommonPublicClientOptions,
+	GraphQLOptions,
+	GraphQLOptionsV6,
+	GraphQLResponseV6,
+	V6Client,
+	getInternals,
+} from '../types';
+
+/**
+ * Invokes graphql operations against a graphql service, providing correct input and
+ * output types if Amplify-generated graphql from a recent version of the CLI/codegen
+ * are used *or* correct typing is provided via the type argument.
+ *
+ * Amplify-generated "branded" graphql queries will look similar to this:
+ *
+ * ```ts
+ *                               //
+ *                               // |-- branding
+ *                               // v
+ * export const getModel = `...` as GeneratedQuery<
+ * 	GetModelQueryVariables,
+ * 	GetModelQuery
+ * >;
+ * ```
+ *
+ * If this branding is not in your generated graphql, update to a newer version of
+ * CLI/codegen and regenerate your graphql using `amplify codegen`.
+ *
+ * ## Using Amplify-generated graphql
+ *
+ * ```ts
+ * import * as queries from './graphql/queries';
+ *
+ * //
+ * //    |-- correctly typed graphql response containing a Widget
+ * //    v
+ * const queryResult = await graphql({
+ * 	query: queries.getWidget,
+ * 	variables: {
+ * 		id: "abc", // <-- type hinted/enforced
+ * 	},
+ * });
+ *
+ * //
+ * //    |-- a correctly typed Widget
+ * //    v
+ * const fetchedWidget = queryResult.data?.getWidget!;
+ * ```
+ *
+ * ## Custom input + result types
+ *
+ * To provide input types (`variables`) and result types:
+ *
+ * ```ts
+ * type GetById_NameOnly = {
+ * 	variables: {
+ * 		id: string
+ * 	},
+ * 	result: Promise<{
+ * 		data: { getWidget: { name: string } }
+ * 	}>
+ * }
+ *
+ * //
+ * //    |-- type is GetById_NameOnly["result"]
+ * //    v
+ * const result = graphql<GetById_NameOnly>({
+ * 	query: "...",
+ * 	variables: { id: "abc" }  // <-- type of GetById_NameOnly["variables"]
+ * });
+ * ```
+ *
+ * ## Custom result type only
+ *
+ * To specify result types only, use a type that is *not* in the `{variables, result}` shape:
+ *
+ * ```ts
+ * type MyResultType = Promise<{
+ * 	data: {
+ * 		getWidget: { name: string }
+ * 	}
+ * }>
+ *
+ * //
+ * //    |-- type is MyResultType
+ * //    v
+ * const result = graphql<MyResultType>({query: "..."});
+ * ```
+ *
+ * @param options
+ * @param additionalHeaders
+ */
+export function graphql<
+	FALLBACK_TYPES = unknown,
+	TYPED_GQL_STRING extends string = string,
+	Options extends CommonPublicClientOptions = object,
+>(
+	this: V6Client,
+	options: GraphQLOptionsV6<FALLBACK_TYPES, TYPED_GQL_STRING, Options>,
+	additionalHeaders?: CustomHeaders,
+): GraphQLResponseV6<FALLBACK_TYPES, TYPED_GQL_STRING> {
+	// inject client-level auth
+	const internals = getInternals(this);
+
+	/**
+	 * The custom `endpoint` specific to the client
+	 */
+	const clientEndpoint = internals.endpoint;
+
+	/**
+	 * The `authMode` specific to the client.
+	 */
+	const clientAuthMode = internals.authMode;
+
+	/**
+	 * The `apiKey` specific to the client.
+	 */
+	const clientApiKey = internals.apiKey;
+
+	/**
+	 * The most specific `authMode` wins. Setting an `endpoint` value without also
+	 * setting an `authMode` value is invalid. This helps to prevent customers apps
+	 * from unexpectedly sending auth details to endpoints the auth details do not
+	 * belong to.
+	 *
+	 * This is especially pronounced for `apiKey`. When both an `endpoint` *and*
+	 * `authMode: 'apiKey'` are provided, an explicit `apiKey` override is required
+	 * to prevent inadvertent sending of an API's `apiKey` to an endpoint is does
+	 * not belong to.
+	 */
+	options.authMode = options.authMode || clientAuthMode;
+	options.apiKey = options.apiKey ?? clientApiKey;
+	options.authToken = options.authToken || internals.authToken;
+
+	if (clientEndpoint && options.authMode === 'apiKey' && !options.apiKey) {
+		throw new Error(
+			"graphql() requires an explicit `apiKey` for a custom `endpoint` when `authMode = 'apiKey'`.",
+		);
+	}
+
+	const headers = additionalHeaders || internals.headers;
+
+	/**
+	 * The correctness of these typings depends on correct string branding or overrides.
+	 * Neither of these can actually be validated at runtime. Hence, we don't perform
+	 * any validation or type-guarding here.
+	 */
+	const result = GraphQLAPI.graphql(
+		// TODO: move V6Client back into this package?
+		internals.amplify as any,
+		{
+			...options,
+			endpoint: clientEndpoint,
+		} as GraphQLOptions,
+		headers,
+	);
+
+	return result as any;
+}
+
+/**
+ * Cancels an inflight request. Only applicable for graphql queries and mutations
+ * @param {any} request - request to cancel
+ * @returns - A boolean indicating if the request was cancelled
+ */
+export function cancel(
+	this: V6Client,
+	promise: Promise<any>,
+	message?: string,
+): boolean {
+	return GraphQLAPI.cancel(promise, message);
+}
+
+/**
+ * Checks to see if an error thrown is from an api request cancellation
+ * @param {any} error - Any error
+ * @returns - A boolean indicating if the error was from an api request cancellation
+ */
+export function isCancelError(this: V6Client, error: any): boolean {
+	return GraphQLAPI.isCancelError(error);
+}
+
+export { GraphQLOptionsV6, GraphQLResponseV6 };

package/src/server/generateClient.ts

@@ -0,0 +1,68 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	AmplifyServer,
+	getAmplifyServerContext,
+} from '@aws-amplify/core/internals/adapter-core';
+import { ResourcesConfig } from '@aws-amplify/core';
+import { CustomHeaders } from '@aws-amplify/data-schema/runtime';
+
+import { generateClientWithAmplifyInstance } from '../internals/server';
+import {
+	GenerateServerClientParams,
+	GraphQLMethod,
+	GraphQLMethodSSR,
+	GraphQLOptionsV6,
+	V6ClientSSRRequest,
+	__amplify,
+} from '../types';
+
+/**
+ * Generates an GraphQL API client that works with Amplify server context.
+ *
+ * @example
+ * import config from './amplifyconfiguration.json';
+ * import { listPosts } from './graphql/queries';
+ *
+ * const client = generateServerClient({ config });
+ *
+ * const result = await runWithAmplifyServerContext({
+ *   nextServerContext: { request, response },
+ *   operation: (contextSpec) => client.graphql(contextSpec, {
+ *     query: listPosts,
+ *   }),
+ * });
+ */
+export function generateClient<
+	T extends Record<any, any> = never,
+	Options extends GenerateServerClientParams = { config: ResourcesConfig },
+>(options: Options): V6ClientSSRRequest<T, Options> {
+	// passing `null` instance because each (future model) method must retrieve a valid instance
+	// from server context
+	const client = generateClientWithAmplifyInstance<T, V6ClientSSRRequest<T>>({
+		amplify: null,
+		...options,
+	});
+
+	// TODO: improve this and the next type
+	const prevGraphql = client.graphql as unknown as GraphQLMethod<Options>;
+
+	const wrappedGraphql = (
+		contextSpec: AmplifyServer.ContextSpec,
+		innerOptions: GraphQLOptionsV6<unknown, string, Options>,
+		additionalHeaders?: CustomHeaders,
+	) => {
+		const amplifyInstance = getAmplifyServerContext(contextSpec).amplify;
+
+		return prevGraphql.call(
+			{ [__amplify]: amplifyInstance },
+			innerOptions,
+			additionalHeaders,
+		);
+	};
+
+	client.graphql = wrappedGraphql as unknown as GraphQLMethodSSR<Options>;
+
+	return client;
+}

package/src/server/index.ts

@@ -0,0 +1,4 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { generateClient } from './generateClient';

package/src/types/PubSub.ts

@@ -0,0 +1,57 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { Observer } from 'rxjs';
+
+export interface SubscriptionObserver<T> {
+	closed: boolean;
+	next(value: T): void;
+	error(errorValue: any): void;
+	complete(): void;
+}
+
+export enum CONTROL_MSG {
+	CONNECTION_CLOSED = 'Connection closed',
+	CONNECTION_FAILED = 'Connection failed',
+	REALTIME_SUBSCRIPTION_INIT_ERROR = 'AppSync Realtime subscription init error',
+	SUBSCRIPTION_ACK = 'Subscription ack',
+	TIMEOUT_DISCONNECT = 'Timeout disconnect',
+}
+
+/** @enum {string} */
+export enum ConnectionState {
+	/*
+	 * The connection is alive and healthy
+	 */
+	Connected = 'Connected',
+	/*
+	 * The connection is alive, but the connection is offline
+	 */
+	ConnectedPendingNetwork = 'ConnectedPendingNetwork',
+	/*
+	 * The connection has been disconnected while in use
+	 */
+	ConnectionDisrupted = 'ConnectionDisrupted',
+	/*
+	 * The connection has been disconnected and the network is offline
+	 */
+	ConnectionDisruptedPendingNetwork = 'ConnectionDisruptedPendingNetwork',
+	/*
+	 * The connection is in the process of connecting
+	 */
+	Connecting = 'Connecting',
+	/*
+	 * The connection is not in use and is being disconnected
+	 */
+	ConnectedPendingDisconnect = 'ConnectedPendingDisconnect',
+	/*
+	 * The connection is not in use and has been disconnected
+	 */
+	Disconnected = 'Disconnected',
+	/*
+	 * The connection is alive, but a keep alive message has been missed
+	 */
+	ConnectedPendingKeepAlive = 'ConnectedPendingKeepAlive',
+}
+
+export type PubSubContent = Record<string, unknown>;
+export type PubSubContentObserver = Observer<PubSubContent>;