@aws-amplify/api-rest 3.5.6-api-v6-models.b3abc9b.0 → 4.0.0

package/lib/utils/parseSigningInfo.js

@@ -0,0 +1,41 @@
+"use strict";
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSigningInfo = void 0;
+const constants_1 = require("./constants");
+/**
+ * Infer the signing service and region from the given URL, and for REST API only, from the Amplify configuration.
+ * It supports raw API Gateway endpoint and AppSync endpoint.
+ *
+ * @internal
+ */
+const parseSigningInfo = (url, restApiOptions) => {
+    const { service: signingService = constants_1.DEFAULT_REST_IAM_SIGNING_SERVICE, region: signingRegion = constants_1.DEFAULT_IAM_SIGNING_REGION, } = restApiOptions?.amplify.getConfig()?.API?.REST?.[restApiOptions?.apiName] ??
+        {};
+    const { hostname } = url;
+    const [, service, region] = constants_1.APIG_HOSTNAME_PATTERN.exec(hostname) ?? [];
+    if (service === constants_1.DEFAULT_REST_IAM_SIGNING_SERVICE) {
+        // The configured endpoint is an API Gateway endpoint
+        // @see: https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-call-api.html
+        return {
+            service,
+            region: region ?? signingRegion,
+        };
+    }
+    else if (service === 'appsync-api') {
+        // AppSync endpoint is internally supported because GraphQL operation will send request using POST handler.
+        // example: https://xxxx.appsync-api.us-east-1.amazonaws.com/graphql
+        return {
+            service: 'appsync',
+            region: region ?? signingRegion,
+        };
+    }
+    else {
+        return {
+            service: signingService,
+            region: signingRegion,
+        };
+    }
+};
+exports.parseSigningInfo = parseSigningInfo;

package/lib/utils/resolveApiUrl.d.ts

@@ -0,0 +1,12 @@
+import { AmplifyClassV6 } from '@aws-amplify/core';
+/**
+ * Resolve the REST API request URL by:
+ * 1. Loading the REST API endpoint from the Amplify configuration with corresponding API name.
+ * 2. Appending the path to the endpoint.
+ * 3. Merge the query parameters from path and the queryParameter argument which is taken from the public REST API
+ *   options.
+ * 4. Validating the resulting URL string.
+ *
+ * @internal
+ */
+export declare const resolveApiUrl: (amplify: AmplifyClassV6, apiName: string, path: string, queryParams?: Record<string, string>) => URL;

package/lib/utils/resolveApiUrl.js

@@ -0,0 +1,40 @@
+"use strict";
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveApiUrl = void 0;
+const utils_1 = require("@aws-amplify/core/internals/utils");
+const errors_1 = require("../errors");
+/**
+ * Resolve the REST API request URL by:
+ * 1. Loading the REST API endpoint from the Amplify configuration with corresponding API name.
+ * 2. Appending the path to the endpoint.
+ * 3. Merge the query parameters from path and the queryParameter argument which is taken from the public REST API
+ *   options.
+ * 4. Validating the resulting URL string.
+ *
+ * @internal
+ */
+const resolveApiUrl = (amplify, apiName, path, queryParams) => {
+    const urlStr = amplify.getConfig()?.API?.REST?.[apiName]?.endpoint;
+    (0, errors_1.assertValidationError)(!!urlStr, errors_1.RestApiValidationErrorCode.InvalidApiName);
+    try {
+        const url = new utils_1.AmplifyUrl(urlStr + path);
+        if (queryParams) {
+            const mergedQueryParams = new utils_1.AmplifyUrlSearchParams(url.searchParams);
+            Object.entries(queryParams).forEach(([key, value]) => {
+                mergedQueryParams.set(key, value);
+            });
+            url.search = new utils_1.AmplifyUrlSearchParams(mergedQueryParams).toString();
+        }
+        return url;
+    }
+    catch (error) {
+        throw new errors_1.RestApiError({
+            name: errors_1.RestApiValidationErrorCode.InvalidApiName,
+            ...errors_1.validationErrorMap[errors_1.RestApiValidationErrorCode.InvalidApiName],
+            recoverySuggestion: `Please make sure the REST endpoint URL is a valid URL string. Got ${urlStr}`,
+        });
+    }
+};
+exports.resolveApiUrl = resolveApiUrl;

package/lib/utils/resolveCredentials.d.ts

@@ -0,0 +1,5 @@
+import { AmplifyClassV6 } from '@aws-amplify/core';
+/**
+ * @internal
+ */
+export declare const resolveCredentials: (amplify: AmplifyClassV6) => Promise<import("@aws-amplify/core/lib-esm/libraryUtils").AWSCredentials>;

package/lib/utils/resolveCredentials.js

@@ -0,0 +1,15 @@
+"use strict";
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCredentials = void 0;
+const errors_1 = require("../errors");
+/**
+ * @internal
+ */
+const resolveCredentials = async (amplify) => {
+    const { credentials } = await amplify.Auth.fetchAuthSession();
+    (0, errors_1.assertValidationError)(!!credentials && !!credentials.accessKeyId && !!credentials.secretAccessKey, errors_1.RestApiValidationErrorCode.NoCredentials);
+    return credentials;
+};
+exports.resolveCredentials = resolveCredentials;

package/lib/utils/serviceError.d.ts

@@ -0,0 +1,10 @@
+import { MetadataBearer } from '@aws-sdk/types';
+import { HttpResponse } from '@aws-amplify/core/internals/aws-client-utils';
+import { RestApiError } from '../errors';
+/**
+ * Internal-only method to create a new RestApiError from a service error.
+ *
+ * @internal
+ */
+export declare const buildRestApiServiceError: (error: Error) => RestApiError;
+export declare const parseRestApiServiceError: (response?: HttpResponse) => Promise<(RestApiError & MetadataBearer) | undefined>;

package/lib/utils/serviceError.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRestApiServiceError = exports.buildRestApiServiceError = void 0;
+const aws_client_utils_1 = require("@aws-amplify/core/internals/aws-client-utils");
+const errors_1 = require("../errors");
+/**
+ * Internal-only method to create a new RestApiError from a service error.
+ *
+ * @internal
+ */
+const buildRestApiServiceError = (error) => {
+    const restApiError = new errors_1.RestApiError({
+        name: error?.name,
+        message: error.message,
+        underlyingError: error,
+    });
+    return restApiError;
+};
+exports.buildRestApiServiceError = buildRestApiServiceError;
+const parseRestApiServiceError = async (response) => {
+    const parsedError = await (0, aws_client_utils_1.parseJsonError)(response);
+    if (!parsedError) {
+        // Response is not an error.
+        return;
+    }
+    return Object.assign((0, exports.buildRestApiServiceError)(parsedError), {
+        $metadata: parsedError.$metadata,
+    });
+};
+exports.parseRestApiServiceError = parseRestApiServiceError;

package/lib-esm/apis/common/handler.d.ts

@@ -0,0 +1,27 @@
+import { AmplifyClassV6 } from '@aws-amplify/core';
+import { HttpRequest, Headers } from '@aws-amplify/core/internals/aws-client-utils';
+import { DocumentType } from '@aws-amplify/core/internals/utils';
+import { RestApiResponse } from '../../types';
+type HandlerOptions = Omit<HttpRequest, 'body' | 'headers'> & {
+    body?: DocumentType | FormData;
+    headers?: Headers;
+    withCredentials?: boolean;
+};
+type SigningServiceInfo = {
+    service?: string;
+    region?: string;
+};
+/**
+ * Make REST API call with best-effort IAM auth.
+ * @param amplify Amplify instance to to resolve credentials and tokens. Should use different instance in client-side
+ *   and SSR
+ * @param options Options accepted from public API options when calling the handlers.
+ * @param signingServiceInfo Internal-only options enable IAM auth as well as to to overwrite the IAM signing service
+ *   and region. If specified, and NONE of API Key header or Auth header is present, IAM auth will be used.
+ *
+ * @internal
+ */
+export declare const transferHandler: (amplify: AmplifyClassV6, options: HandlerOptions & {
+    abortSignal: AbortSignal;
+}, signingServiceInfo?: SigningServiceInfo) => Promise<RestApiResponse>;
+export {};

package/lib-esm/apis/common/handler.js

@@ -0,0 +1,69 @@
+import { unauthenticatedHandler, getRetryDecider, jitteredBackoff, authenticatedHandler, } from '@aws-amplify/core/internals/aws-client-utils';
+import { parseRestApiServiceError, parseSigningInfo, resolveCredentials, } from '../../utils';
+import { normalizeHeaders } from '../../utils/normalizeHeaders';
+/**
+ * Make REST API call with best-effort IAM auth.
+ * @param amplify Amplify instance to to resolve credentials and tokens. Should use different instance in client-side
+ *   and SSR
+ * @param options Options accepted from public API options when calling the handlers.
+ * @param signingServiceInfo Internal-only options enable IAM auth as well as to to overwrite the IAM signing service
+ *   and region. If specified, and NONE of API Key header or Auth header is present, IAM auth will be used.
+ *
+ * @internal
+ */
+export const transferHandler = async (amplify, options, signingServiceInfo) => {
+    const { url, method, headers, body, withCredentials, abortSignal } = options;
+    const resolvedBody = body
+        ? body instanceof FormData
+            ? body
+            : JSON.stringify(body ?? '')
+        : undefined;
+    const resolvedHeaders = {
+        ...normalizeHeaders(headers),
+        ...(resolvedBody
+            ? {
+                'content-type': body instanceof FormData
+                    ? 'multipart/form-data'
+                    : 'application/json; charset=UTF-8',
+            }
+            : {}),
+    };
+    const request = {
+        url,
+        headers: resolvedHeaders,
+        method,
+        body: resolvedBody,
+    };
+    const baseOptions = {
+        retryDecider: getRetryDecider(parseRestApiServiceError),
+        computeDelay: jitteredBackoff,
+        withCrossDomainCredentials: withCredentials,
+        abortSignal,
+    };
+    const isIamAuthApplicable = iamAuthApplicable(request, signingServiceInfo);
+    let response;
+    if (isIamAuthApplicable) {
+        const signingInfoFromUrl = parseSigningInfo(url);
+        const signingService = signingServiceInfo?.service ?? signingInfoFromUrl.service;
+        const signingRegion = signingServiceInfo?.region ?? signingInfoFromUrl.region;
+        const credentials = await resolveCredentials(amplify);
+        response = await authenticatedHandler(request, {
+            ...baseOptions,
+            credentials,
+            region: signingRegion,
+            service: signingService,
+        });
+    }
+    else {
+        response = await unauthenticatedHandler(request, {
+            ...baseOptions,
+        });
+    }
+    // Clean-up un-modeled properties from response.
+    return {
+        statusCode: response.statusCode,
+        headers: response.headers,
+        body: response.body,
+    };
+};
+const iamAuthApplicable = ({ headers }, signingServiceInfo) => !headers.authorization && !headers['x-api-key'] && !!signingServiceInfo;

package/lib-esm/apis/common/internalPost.d.ts

@@ -0,0 +1,16 @@
+import { AmplifyClassV6 } from '@aws-amplify/core';
+import { InternalPostInput, RestApiResponse } from '../../types';
+/**
+ * @internal
+ */
+export declare const post: (amplify: AmplifyClassV6, { url, options, abortController }: InternalPostInput) => Promise<RestApiResponse>;
+/**
+ * Cancels a request given the promise returned by `post`.
+ * If the request is already completed, this function does nothing.
+ * It MUST be used after `updateRequestToBeCancellable` is called.
+ */
+export declare const cancel: (promise: Promise<RestApiResponse>, message?: string) => boolean;
+/**
+ * MUST be used to make a promise including internal `post` API call cancellable.
+ */
+export declare const updateRequestToBeCancellable: (promise: Promise<any>, controller: AbortController) => void;

package/lib-esm/apis/common/internalPost.js

@@ -0,0 +1,59 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { transferHandler } from './handler';
+import { createCancellableOperation } from '../../utils';
+/**
+ * This weak map provides functionality to cancel a request given the promise containing the `post` request.
+ *
+ * 1. For every GraphQL POST request, an abort controller is created and supplied to the request.
+ * 2. The promise fulfilled by GraphGL POST request is then mapped to that abort controller.
+ * 3. The promise is returned to the external caller.
+ * 4. The caller can either wait for the promise to fulfill or call `cancel(promise)` to cancel the request.
+ * 5. If `cancel(promise)` is called, then the corresponding abort controller is retrieved from the map below.
+ * 6. GraphQL POST request will be rejected with the error message provided during cancel.
+ * 7. Caller can check if the error is because of cancelling by calling `isCancelError(error)`.
+ */
+const cancelTokenMap = new WeakMap();
+/**
+ * @internal
+ */
+export const post = (amplify, { url, options, abortController }) => {
+    const controller = abortController ?? new AbortController();
+    const responsePromise = createCancellableOperation(async () => {
+        const response = transferHandler(amplify, {
+            url,
+            method: 'POST',
+            ...options,
+            abortSignal: controller.signal,
+        }, options?.signingServiceInfo);
+        return response;
+    }, controller);
+    const responseWithCleanUp = responsePromise.finally(() => {
+        cancelTokenMap.delete(responseWithCleanUp);
+    });
+    return responseWithCleanUp;
+};
+/**
+ * Cancels a request given the promise returned by `post`.
+ * If the request is already completed, this function does nothing.
+ * It MUST be used after `updateRequestToBeCancellable` is called.
+ */
+export const cancel = (promise, message) => {
+    const controller = cancelTokenMap.get(promise);
+    if (controller) {
+        controller.abort(message);
+        if (message && controller.signal.reason !== message) {
+            // In runtimes where `AbortSignal.reason` is not supported, we track the reason ourselves.
+            // @ts-expect-error reason is read-only property.
+            controller.signal['reason'] = message;
+        }
+        return true;
+    }
+    return false;
+};
+/**
+ * MUST be used to make a promise including internal `post` API call cancellable.
+ */
+export const updateRequestToBeCancellable = (promise, controller) => {
+    cancelTokenMap.set(promise, controller);
+};

package/lib-esm/apis/common/publicApis.d.ts

@@ -0,0 +1,8 @@
+import { AmplifyClassV6 } from '@aws-amplify/core';
+import { GetInput, GetOperation, PostInput, PostOperation, PutInput, PutOperation, DeleteInput, DeleteOperation, HeadInput, HeadOperation, PatchInput, PatchOperation } from '../../types';
+export declare const get: (amplify: AmplifyClassV6, input: GetInput) => GetOperation;
+export declare const post: (amplify: AmplifyClassV6, input: PostInput) => PostOperation;
+export declare const put: (amplify: AmplifyClassV6, input: PutInput) => PutOperation;
+export declare const del: (amplify: AmplifyClassV6, input: DeleteInput) => DeleteOperation;
+export declare const head: (amplify: AmplifyClassV6, input: HeadInput) => HeadOperation;
+export declare const patch: (amplify: AmplifyClassV6, input: PatchInput) => PatchOperation;

package/lib-esm/apis/common/publicApis.js

@@ -0,0 +1,35 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { resolveApiUrl, createCancellableOperation, logger, parseSigningInfo, } from '../../utils';
+import { transferHandler } from './handler';
+const publicHandler = (amplify, options, method) => createCancellableOperation(async (abortSignal) => {
+    const { apiName, options: apiOptions = {}, path: apiPath } = options;
+    const url = resolveApiUrl(amplify, apiName, apiPath, apiOptions?.queryParams);
+    const libraryOptionsHeaders = await amplify.libraryOptions?.API?.REST?.headers?.({
+        apiName,
+    });
+    const { headers: invocationHeaders = {} } = apiOptions;
+    const headers = {
+        // custom headers from invocation options should precede library options
+        ...libraryOptionsHeaders,
+        ...invocationHeaders,
+    };
+    const signingServiceInfo = parseSigningInfo(url, {
+        amplify,
+        apiName,
+    });
+    logger.debug(method, url, headers, `IAM signing options: ${JSON.stringify(signingServiceInfo)}`);
+    return transferHandler(amplify, {
+        ...apiOptions,
+        url,
+        method,
+        headers,
+        abortSignal,
+    }, signingServiceInfo);
+});
+export const get = (amplify, input) => publicHandler(amplify, input, 'GET');
+export const post = (amplify, input) => publicHandler(amplify, input, 'POST');
+export const put = (amplify, input) => publicHandler(amplify, input, 'PUT');
+export const del = (amplify, input) => publicHandler(amplify, input, 'DELETE');
+export const head = (amplify, input) => publicHandler(amplify, input, 'HEAD');
+export const patch = (amplify, input) => publicHandler(amplify, input, 'PATCH');

package/lib-esm/apis/index.d.ts

@@ -0,0 +1,203 @@
+import { DeleteInput, DeleteOperation, GetInput, GetOperation, HeadInput, HeadOperation, PatchInput, PatchOperation, PostInput, PostOperation, PutInput, PutOperation } from '../types';
+/**
+ * GET HTTP request
+ * @param {GetInput} input - Input for GET operation
+ * @returns {GetOperation} Operation for GET request
+ * @throws - {@link RestApiError}
+ * @example
+ * Send a GET request
+ * ```js
+ * import { get, isCancelError } from '@aws-amplify/api';
+ *
+ * const { body } = await get({
+ *   apiName,
+ *   path,
+ *   options: {
+ *     headers, // Optional, A map of custom header key/values
+ *     body, // Optional, JSON object or FormData
+ *     queryParams, // Optional, A map of query strings
+ *   }
+ * }).response;
+ * const data = await body.json();
+ * ```
+ * @example
+ * Cancel a GET request
+ *
+ * ```js
+ * import { get, isCancelError } from '@aws-amplify/api';
+ *
+ * const { response, cancel } = get({apiName, path, options});
+ * cancel(message);
+ * try {
+ *   await response;
+ * } cache (e) {
+ *   if (isCancelError(e)) {
+ *    // handle request cancellation
+ *   }
+ *   //...
+ * }
+ * ```
+ */
+export declare const get: (input: GetInput) => GetOperation;
+/**
+ * POST HTTP request
+ * @param {PostInput} input - Input for POST operation
+ * @returns {PostOperation} Operation for POST request
+ * @throws - {@link RestApiError}
+ * @example
+ * Send a POST request
+ * ```js
+ * import { post, isCancelError } from '@aws-amplify/api';
+ *
+ * const { body } = await post({
+ *   apiName,
+ *   path,
+ *   options: {
+ *     headers, // Optional, A map of custom header key/values
+ *     body, // Optional, JSON object or FormData
+ *     queryParams, // Optional, A map of query strings
+ *   }
+ * }).response;
+ * const data = await body.json();
+ * ```
+ * @example
+ * Cancel a POST request
+ *
+ * ```js
+ * import { post, isCancelError } from '@aws-amplify/api';
+ *
+ * const { response, cancel } = post({apiName, path, options});
+ * cancel(message);
+ * try {
+ *   await response;
+ * } cache (e) {
+ *   if (isCancelError(e)) {
+ *    // handle request cancellation
+ *   }
+ *   //...
+ * }
+ * ```
+ */
+export declare const post: (input: PostInput) => PostOperation;
+/**
+ * PUT HTTP request
+ * @param {PutInput} input - Input for PUT operation
+ * @returns {PutOperation} Operation for PUT request
+ * @throws - {@link RestApiError}
+ * @example
+ * Send a PUT request
+ * ```js
+ * import { put, isCancelError } from '@aws-amplify/api';
+ *
+ * const { body } = await put({
+ *   apiName,
+ *   path,
+ *   options: {
+ *     headers, // Optional, A map of custom header key/values
+ *     body, // Optional, JSON object or FormData
+ *     queryParams, // Optional, A map of query strings
+ *   }
+ * }).response;
+ * const data = await body.json();
+ * ```
+ * @example
+ * Cancel a PUT request
+ * ```js
+ * import { put, isCancelError } from '@aws-amplify/api';
+ *
+ * const { response, cancel } = put({apiName, path, options});
+ * cancel(message);
+ * try {
+ *  await response;
+ * } cache (e) {
+ *   if (isCancelError(e)) {
+ *     // handle request cancellation
+ *   }
+ * //...
+ * }
+ * ```
+ */
+export declare const put: (input: PutInput) => PutOperation;
+/**
+ * DELETE HTTP request
+ * @param {DeleteInput} input - Input for DELETE operation
+ * @returns {DeleteOperation} Operation for DELETE request
+ * @throws - {@link RestApiError}
+ * @example
+ * Send a DELETE request
+ * ```js
+ * import { del } from '@aws-amplify/api';
+ *
+ * const { statusCode } = await del({
+ *   apiName,
+ *   path,
+ *   options: {
+ *     headers, // Optional, A map of custom header key/values
+ *     queryParams, // Optional, A map of query strings
+ *   }
+ * }).response;
+ * ```
+ */
+export declare const del: (input: DeleteInput) => DeleteOperation;
+/**
+ * HEAD HTTP request
+ * @param {HeadInput} input - Input for HEAD operation
+ * @returns {HeadOperation} Operation for HEAD request
+ * @throws - {@link RestApiError}
+ * @example
+ * Send a HEAD request
+ * ```js
+ * import { head, isCancelError } from '@aws-amplify/api';
+ *
+ * const { headers, statusCode } = await head({
+ *   apiName,
+ *   path,
+ *   options: {
+ *     headers, // Optional, A map of custom header key/values
+ *     queryParams, // Optional, A map of query strings
+ *   }
+ * }),response;
+ * ```
+ *
+ */
+export declare const head: (input: HeadInput) => HeadOperation;
+/**
+ * PATCH HTTP request
+ * @param {PatchInput} input - Input for PATCH operation
+ * @returns {PatchOperation} Operation for PATCH request
+ * @throws - {@link RestApiError}
+ * @example
+ * Send a PATCH request
+ * ```js
+ * import { patch } from '@aws-amplify/api';
+ *
+ * const { body } = await patch({
+ *   apiName,
+ *   path,
+ *   options: {
+ *     headers, // Optional, A map of custom header key/values
+ *     body, // Optional, JSON object or FormData
+ *     queryParams, // Optional, A map of query strings
+ *   }
+ * }).response;
+ * const data = await body.json();
+ * ```
+ *
+ * @example
+ * Cancel a PATCH request
+ * ```js
+ * import { patch, isCancelError } from '@aws-amplify/api';
+ *
+ * const { response, cancel } = patch({apiName, path, options});
+ * cancel(message);
+ * try {
+ *  await response;
+ * } cache (e) {
+ *  if (isCancelError(e)) {
+ *   // handle request cancellation
+ *  }
+ * //...
+ * }
+ * ```
+ */
+export declare const patch: (input: PatchInput) => PatchOperation;