@aws-amplify/api-rest 3.5.6-unstable.7762f1a.0 → 4.0.0

package/README.md

@@ -0,0 +1,3 @@
+> INTERNAL USE ONLY
+
+This package contains the AWS Amplify API REST category and is intended for internal use only. To integrate Amplify into your app, please use [aws-amplify](https://www.npmjs.com/package/aws-amplify).

package/internals/package.json

@@ -0,0 +1,8 @@
+{
+	"name": "@aws-amplify/api-rest/internals",
+	"types": "../lib-esm/internals/index.d.ts",
+	"main": "../lib/internals/index.js",
+	"module": "../lib-esm/internals/index.js",
+	"react-native": "../lib-esm/internals/index.js",
+	"sideEffects": false
+}

package/internals/server/package.json

@@ -0,0 +1,8 @@
+{
+	"name": "@aws-amplify/api-rest/internals/server",
+	"types": "../../lib-esm/internals/server.d.ts",
+	"main": "../../lib/internals/server.js",
+	"module": "../../lib-esm/internals/server.js",
+	"react-native": "../../lib-esm/internals/server.js",
+	"sideEffects": false
+}

package/lib/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/apis/common/handler.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transferHandler = void 0;
+const aws_client_utils_1 = require("@aws-amplify/core/internals/aws-client-utils");
+const utils_1 = require("../../utils");
+const normalizeHeaders_1 = require("../../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
+ */
+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 = {
+        ...(0, normalizeHeaders_1.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: (0, aws_client_utils_1.getRetryDecider)(utils_1.parseRestApiServiceError),
+        computeDelay: aws_client_utils_1.jitteredBackoff,
+        withCrossDomainCredentials: withCredentials,
+        abortSignal,
+    };
+    const isIamAuthApplicable = iamAuthApplicable(request, signingServiceInfo);
+    let response;
+    if (isIamAuthApplicable) {
+        const signingInfoFromUrl = (0, utils_1.parseSigningInfo)(url);
+        const signingService = signingServiceInfo?.service ?? signingInfoFromUrl.service;
+        const signingRegion = signingServiceInfo?.region ?? signingInfoFromUrl.region;
+        const credentials = await (0, utils_1.resolveCredentials)(amplify);
+        response = await (0, aws_client_utils_1.authenticatedHandler)(request, {
+            ...baseOptions,
+            credentials,
+            region: signingRegion,
+            service: signingService,
+        });
+    }
+    else {
+        response = await (0, aws_client_utils_1.unauthenticatedHandler)(request, {
+            ...baseOptions,
+        });
+    }
+    // Clean-up un-modeled properties from response.
+    return {
+        statusCode: response.statusCode,
+        headers: response.headers,
+        body: response.body,
+    };
+};
+exports.transferHandler = transferHandler;
+const iamAuthApplicable = ({ headers }, signingServiceInfo) => !headers.authorization && !headers['x-api-key'] && !!signingServiceInfo;

package/lib/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/apis/common/internalPost.js

@@ -0,0 +1,65 @@
+"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.updateRequestToBeCancellable = exports.cancel = exports.post = void 0;
+const handler_1 = require("./handler");
+const utils_1 = require("../../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
+ */
+const post = (amplify, { url, options, abortController }) => {
+    const controller = abortController ?? new AbortController();
+    const responsePromise = (0, utils_1.createCancellableOperation)(async () => {
+        const response = (0, handler_1.transferHandler)(amplify, {
+            url,
+            method: 'POST',
+            ...options,
+            abortSignal: controller.signal,
+        }, options?.signingServiceInfo);
+        return response;
+    }, controller);
+    const responseWithCleanUp = responsePromise.finally(() => {
+        cancelTokenMap.delete(responseWithCleanUp);
+    });
+    return responseWithCleanUp;
+};
+exports.post = post;
+/**
+ * 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.
+ */
+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;
+};
+exports.cancel = cancel;
+/**
+ * MUST be used to make a promise including internal `post` API call cancellable.
+ */
+const updateRequestToBeCancellable = (promise, controller) => {
+    cancelTokenMap.set(promise, controller);
+};
+exports.updateRequestToBeCancellable = updateRequestToBeCancellable;

package/lib/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/apis/common/publicApis.js

@@ -0,0 +1,44 @@
+"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.patch = exports.head = exports.del = exports.put = exports.post = exports.get = void 0;
+const utils_1 = require("../../utils");
+const handler_1 = require("./handler");
+const publicHandler = (amplify, options, method) => (0, utils_1.createCancellableOperation)(async (abortSignal) => {
+    const { apiName, options: apiOptions = {}, path: apiPath } = options;
+    const url = (0, utils_1.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 = (0, utils_1.parseSigningInfo)(url, {
+        amplify,
+        apiName,
+    });
+    utils_1.logger.debug(method, url, headers, `IAM signing options: ${JSON.stringify(signingServiceInfo)}`);
+    return (0, handler_1.transferHandler)(amplify, {
+        ...apiOptions,
+        url,
+        method,
+        headers,
+        abortSignal,
+    }, signingServiceInfo);
+});
+const get = (amplify, input) => publicHandler(amplify, input, 'GET');
+exports.get = get;
+const post = (amplify, input) => publicHandler(amplify, input, 'POST');
+exports.post = post;
+const put = (amplify, input) => publicHandler(amplify, input, 'PUT');
+exports.put = put;
+const del = (amplify, input) => publicHandler(amplify, input, 'DELETE');
+exports.del = del;
+const head = (amplify, input) => publicHandler(amplify, input, 'HEAD');
+exports.head = head;
+const patch = (amplify, input) => publicHandler(amplify, input, 'PATCH');
+exports.patch = patch;

package/lib/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;

package/lib/apis/index.js

@@ -0,0 +1,215 @@
+"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.patch = exports.head = exports.del = exports.put = exports.post = exports.get = void 0;
+const core_1 = require("@aws-amplify/core");
+const publicApis_1 = require("./common/publicApis");
+/**
+ * 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
+ *   }
+ *   //...
+ * }
+ * ```
+ */
+const get = (input) => (0, publicApis_1.get)(core_1.Amplify, input);
+exports.get = get;
+/**
+ * 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
+ *   }
+ *   //...
+ * }
+ * ```
+ */
+const post = (input) => (0, publicApis_1.post)(core_1.Amplify, input);
+exports.post = post;
+/**
+ * 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
+ *   }
+ * //...
+ * }
+ * ```
+ */
+const put = (input) => (0, publicApis_1.put)(core_1.Amplify, input);
+exports.put = put;
+/**
+ * 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;
+ * ```
+ */
+const del = (input) => (0, publicApis_1.del)(core_1.Amplify, input);
+exports.del = del;
+/**
+ * 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;
+ * ```
+ *
+ */
+const head = (input) => (0, publicApis_1.head)(core_1.Amplify, input);
+exports.head = head;
+/**
+ * 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
+ *  }
+ * //...
+ * }
+ * ```
+ */
+const patch = (input) => (0, publicApis_1.patch)(core_1.Amplify, input);
+exports.patch = patch;