@aws-amplify/storage 6.0.28 → 6.0.29-gen2-storage.e54bfa9.0

package/src/providers/s3/types/index.ts

@@ -2,35 +2,58 @@
 // SPDX-License-Identifier: Apache-2.0
 
 export {
-	GetUrlOptions,
-	UploadDataOptions,
-	GetPropertiesOptions,
-	ListAllOptions,
-	ListPaginateOptions,
+	GetUrlOptionsWithKey,
+	GetUrlOptionsWithPath,
+	UploadDataOptionsWithPath,
+	UploadDataOptionsWithKey,
+	GetPropertiesOptionsWithKey,
+	GetPropertiesOptionsWithPath,
+	ListAllOptionsWithPrefix,
+	ListPaginateOptionsWithPrefix,
+	ListAllOptionsWithPath,
+	ListPaginateOptionsWithPath,
 	RemoveOptions,
-	DownloadDataOptions,
-	CopyDestinationOptions,
-	CopySourceOptions,
+	DownloadDataOptionsWithPath,
+	DownloadDataOptionsWithKey,
+	CopyDestinationOptionsWithKey,
+	CopySourceOptionsWithKey,
 } from './options';
 export {
-	DownloadDataOutput,
-	GetUrlOutput,
 	UploadDataOutput,
-	ListOutputItem,
+	UploadDataWithPathOutput,
+	DownloadDataOutput,
+	DownloadDataWithPathOutput,
+	RemoveOutput,
+	RemoveWithPathOutput,
 	ListAllOutput,
+	ListAllWithPathOutput,
 	ListPaginateOutput,
+	ListPaginateWithPathOutput,
 	GetPropertiesOutput,
+	GetPropertiesWithPathOutput,
 	CopyOutput,
-	RemoveOutput,
+	CopyWithPathOutput,
+	GetUrlOutput,
+	GetUrlWithPathOutput,
+	ListOutputItem,
+	ListOutputItemWithPath,
 } from './outputs';
 export {
 	CopyInput,
+	CopyWithPathInput,
 	GetPropertiesInput,
+	GetPropertiesWithPathInput,
 	GetUrlInput,
-	ListAllInput,
-	ListPaginateInput,
+	GetUrlWithPathInput,
+	RemoveWithPathInput,
 	RemoveInput,
 	DownloadDataInput,
+	DownloadDataWithPathInput,
 	UploadDataInput,
+	UploadDataWithPathInput,
+	ListAllInput,
+	ListPaginateInput,
+	ListAllWithPathInput,
+	ListPaginateWithPathInput,
 } from './inputs';
 export { S3Exception } from './errors';

package/src/providers/s3/types/inputs.ts

@@ -2,67 +2,136 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import {
-	StorageCopyInput,
-	StorageDownloadDataInput,
-	StorageGetPropertiesInput,
-	StorageGetUrlInput,
-	StorageListInput,
-	StorageRemoveInput,
-	StorageUploadDataInput,
+	StorageCopyInputWithKey,
+	StorageCopyInputWithPath,
+	StorageDownloadDataInputWithKey,
+	StorageDownloadDataInputWithPath,
+	StorageGetPropertiesInputWithKey,
+	StorageGetPropertiesInputWithPath,
+	StorageGetUrlInputWithKey,
+	StorageGetUrlInputWithPath,
+	StorageListInputWithPath,
+	StorageListInputWithPrefix,
+	StorageRemoveInputWithKey,
+	StorageRemoveInputWithPath,
+	StorageUploadDataInputWithKey,
+	StorageUploadDataInputWithPath,
 } from '../../../types';
 import {
-	CopyDestinationOptions,
-	CopySourceOptions,
-	DownloadDataOptions,
-	GetPropertiesOptions,
-	GetUrlOptions,
-	ListAllOptions,
-	ListPaginateOptions,
+	CopyDestinationOptionsWithKey,
+	CopySourceOptionsWithKey,
+	DownloadDataOptionsWithKey,
+	DownloadDataOptionsWithPath,
+	GetPropertiesOptionsWithKey,
+	GetPropertiesOptionsWithPath,
+	GetUrlOptionsWithKey,
+	GetUrlOptionsWithPath,
+	ListAllOptionsWithPath,
+	ListAllOptionsWithPrefix,
+	ListPaginateOptionsWithPath,
+	ListPaginateOptionsWithPrefix,
 	RemoveOptions,
-	UploadDataOptions,
+	UploadDataOptionsWithKey,
+	UploadDataOptionsWithPath,
 } from '../types';
 
 // TODO: support use accelerate endpoint option
 /**
+ * @deprecated Use {@link CopyWithPathInput} instead.
  * Input type for S3 copy API.
  */
-export type CopyInput = StorageCopyInput<
-	CopySourceOptions,
-	CopyDestinationOptions
+export type CopyInput = StorageCopyInputWithKey<
+	CopySourceOptionsWithKey,
+	CopyDestinationOptionsWithKey
 >;
+/**
+ * Input type with path for S3 copy API.
+ */
+export type CopyWithPathInput = StorageCopyInputWithPath;
 
 /**
+ * @deprecated Use {@link GetPropertiesWithPathInput} instead.
  * Input type for S3 getProperties API.
  */
 export type GetPropertiesInput =
-	StorageGetPropertiesInput<GetPropertiesOptions>;
+	StorageGetPropertiesInputWithKey<GetPropertiesOptionsWithKey>;
+/**
+ * Input type with for S3 getProperties API.
+ */
+export type GetPropertiesWithPathInput =
+	StorageGetPropertiesInputWithPath<GetPropertiesOptionsWithPath>;
 
 /**
+ * @deprecated Use {@link GetUrlWithPathInput} instead.
  * Input type for S3 getUrl API.
  */
-export type GetUrlInput = StorageGetUrlInput<GetUrlOptions>;
+export type GetUrlInput = StorageGetUrlInputWithKey<GetUrlOptionsWithKey>;
+/**
+ * Input type with path for S3 getUrl API.
+ */
+export type GetUrlWithPathInput =
+	StorageGetUrlInputWithPath<GetUrlOptionsWithPath>;
+
+/**
+ * Input type with path for S3 list API. Lists all bucket objects.
+ */
+export type ListAllWithPathInput =
+	StorageListInputWithPath<ListAllOptionsWithPath>;
+
+/**
+ * Input type with path for S3 list API. Lists bucket objects with pagination.
+ */
+export type ListPaginateWithPathInput =
+	StorageListInputWithPath<ListPaginateOptionsWithPath>;
 
 /**
+ * @deprecated Use {@link ListAllWithPathInput} instead.
  * Input type for S3 list API. Lists all bucket objects.
  */
-export type ListAllInput = StorageListInput<ListAllOptions>;
+export type ListAllInput = StorageListInputWithPrefix<ListAllOptionsWithPrefix>;
 
 /**
+ * @deprecated Use {@link ListPaginateWithPathInput} instead.
  * Input type for S3 list API. Lists bucket objects with pagination.
  */
-export type ListPaginateInput = StorageListInput<ListPaginateOptions>;
+export type ListPaginateInput =
+	StorageListInputWithPrefix<ListPaginateOptionsWithPrefix>;
+
+/**
+ * @deprecated Use {@link RemoveWithPathInput} instead.
+ * Input type with key for S3 remove API.
+ */
+export type RemoveInput = StorageRemoveInputWithKey<RemoveOptions>;
 
 /**
- * Input type for S3 remove API.
+ * Input type with path for S3 remove API.
  */
-export type RemoveInput = StorageRemoveInput<RemoveOptions>;
+export type RemoveWithPathInput = StorageRemoveInputWithPath<
+	Omit<RemoveOptions, 'accessLevel'>
+>;
 
 /**
+ * @deprecated Use {@link DownloadDataWithPathInput} instead.
  * Input type for S3 downloadData API.
  */
-export type DownloadDataInput = StorageDownloadDataInput<DownloadDataOptions>;
+export type DownloadDataInput =
+	StorageDownloadDataInputWithKey<DownloadDataOptionsWithKey>;
 
 /**
+ * Input type with path for S3 downloadData API.
+ */
+export type DownloadDataWithPathInput =
+	StorageDownloadDataInputWithPath<DownloadDataOptionsWithPath>;
+
+/**
+ * @deprecated Use {@link UploadDataWithPathInput} instead.
  * Input type for S3 uploadData API.
  */
-export type UploadDataInput = StorageUploadDataInput<UploadDataOptions>;
+export type UploadDataInput =
+	StorageUploadDataInputWithKey<UploadDataOptionsWithKey>;
+
+/**
+ * Input type with path for S3 uploadData API.
+ */
+export type UploadDataWithPathInput =
+	StorageUploadDataInputWithPath<UploadDataOptionsWithPath>;

package/src/providers/s3/types/options.ts

@@ -18,11 +18,22 @@ interface CommonOptions {
 	useAccelerateEndpoint?: boolean;
 }
 
+/** @deprecated This may be removed in the next major version. */
 type ReadOptions =
-	| { accessLevel?: 'guest' | 'private' }
-	| { accessLevel: 'protected'; targetIdentityId?: string };
-
+	| {
+			/** @deprecated This may be removed in the next major version. */
+			accessLevel?: 'guest' | 'private';
+	  }
+	| {
+			/** @deprecated This may be removed in the next major version. */
+			accessLevel: 'protected';
+			/** @deprecated This may be removed in the next major version. */
+			targetIdentityId?: string;
+	  };
+
+/** @deprecated This may be removed in the next major version. */
 interface WriteOptions {
+	/** @deprecated This may be removed in the next major version. */
 	accessLevel?: StorageAccessLevel;
 }
 
@@ -46,7 +57,9 @@ interface TransferOptions {
 /**
  * Input options type for S3 getProperties API.
  */
-export type GetPropertiesOptions = ReadOptions & CommonOptions;
+/** @deprecated Use {@link GetPropertiesOptionsWithPath} instead. */
+export type GetPropertiesOptionsWithKey = ReadOptions & CommonOptions;
+export type GetPropertiesOptionsWithPath = CommonOptions;
 
 /**
  * Input options type for S3 getProperties API.
@@ -54,46 +67,71 @@ export type GetPropertiesOptions = ReadOptions & CommonOptions;
 export type RemoveOptions = WriteOptions & CommonOptions;
 
 /**
- * Input options type for S3 list API.
+ * @deprecated Use {@link ListAllOptionsWithPath} instead.
+ * Input options type with prefix for S3 list all API.
  */
-export type ListAllOptions = StorageListAllOptions &
+export type ListAllOptionsWithPrefix = StorageListAllOptions &
 	ReadOptions &
 	CommonOptions;
 
 /**
- * Input options type for S3 list API.
+ * @deprecated Use {@link ListPaginateOptionsWithPath} instead.
+ * Input options type with prefix for S3 list API to paginate items.
  */
-export type ListPaginateOptions = StorageListPaginateOptions &
+export type ListPaginateOptionsWithPrefix = StorageListPaginateOptions &
 	ReadOptions &
 	CommonOptions;
 
+/**
+ * Input options type with path for S3 list all API.
+ */
+export type ListAllOptionsWithPath = Omit<
+	StorageListAllOptions,
+	'accessLevel'
+> &
+	CommonOptions;
+
+/**
+ * Input options type with path for S3 list API to paginate items.
+ */
+export type ListPaginateOptionsWithPath = Omit<
+	StorageListPaginateOptions,
+	'accessLevel'
+> &
+	CommonOptions;
+
 /**
  * Input options type for S3 getUrl API.
  */
-export type GetUrlOptions = ReadOptions &
-	CommonOptions & {
-		/**
-		 * Whether to head object to make sure the object existence before downloading.
-		 * @default false
-		 */
-		validateObjectExistence?: boolean;
-		/**
-		 * Number of seconds till the URL expires.
-		 * @default 900 (15 minutes)
-		 */
-		expiresIn?: number;
-	};
+export type GetUrlOptions = CommonOptions & {
+	/**
+	 * Whether to head object to make sure the object existence before downloading.
+	 * @default false
+	 */
+	validateObjectExistence?: boolean;
+	/**
+	 * Number of seconds till the URL expires.
+	 * @default 900 (15 minutes)
+	 */
+	expiresIn?: number;
+};
+
+/** @deprecated Use {@link GetUrlOptionsWithPath} instead. */
+export type GetUrlOptionsWithKey = ReadOptions & GetUrlOptions;
+export type GetUrlOptionsWithPath = GetUrlOptions;
 
 /**
  * Input options type for S3 downloadData API.
  */
-export type DownloadDataOptions = ReadOptions &
-	CommonOptions &
+export type DownloadDataOptions = CommonOptions &
 	TransferOptions &
 	BytesRangeOptions;
 
-export type UploadDataOptions = WriteOptions &
-	CommonOptions &
+/** @deprecated Use {@link DownloadDataOptionsWithPath} instead. */
+export type DownloadDataOptionsWithKey = ReadOptions & DownloadDataOptions;
+export type DownloadDataOptionsWithPath = DownloadDataOptions;
+
+export type UploadDataOptions = CommonOptions &
 	TransferOptions & {
 		/**
 		 * The default content-disposition header value of the file when downloading it.
@@ -117,11 +155,19 @@ export type UploadDataOptions = WriteOptions &
 		metadata?: Record<string, string>;
 	};
 
-export type CopySourceOptions = ReadOptions & {
+/** @deprecated Use {@link UploadDataOptionsWithPath} instead. */
+export type UploadDataOptionsWithKey = WriteOptions & UploadDataOptions;
+export type UploadDataOptionsWithPath = UploadDataOptions;
+
+/** @deprecated This may be removed in the next major version. */
+export type CopySourceOptionsWithKey = ReadOptions & {
+	/** @deprecated This may be removed in the next major version. */
 	key: string;
 };
 
-export type CopyDestinationOptions = WriteOptions & {
+/** @deprecated This may be removed in the next major version. */
+export type CopyDestinationOptionsWithKey = WriteOptions & {
+	/** @deprecated This may be removed in the next major version. */
 	key: string;
 };
 

package/src/providers/s3/types/outputs.ts

@@ -5,15 +5,16 @@ import {
 	DownloadTask,
 	StorageDownloadDataOutput,
 	StorageGetUrlOutput,
-	StorageItem,
+	StorageItemWithKey,
+	StorageItemWithPath,
 	StorageListOutput,
 	UploadTask,
 } from '../../../types';
 
 /**
- * type for S3 item.
+ * Base type for an S3 item.
  */
-export interface Item extends StorageItem {
+export interface ItemBase {
 	/**
 	 * VersionId used to reference a specific version of the object.
 	 */
@@ -25,36 +26,83 @@ export interface Item extends StorageItem {
 }
 
 /**
- * type for S3 list item.
+ * @deprecated Use {@link ListOutputItemWithPath} instead.
+ * type for S3 list item with key.
  */
-export type ListOutputItem = Omit<StorageItem, 'metadata'>;
+export type ListOutputItem = Omit<ItemWithKey, 'metadata'>;
+
+/**
+ * type for S3 list item with path.
+ */
+export type ListOutputItemWithPath = Omit<ItemWithPath, 'metadata'>;
+
+/**
+ * @deprecated Use {@link ItemWithPath} instead.
+ */
+export type ItemWithKey = ItemBase & StorageItemWithKey;
+
+/**
+ * type for S3 list item with path.
+ */
+export type ItemWithPath = ItemBase & StorageItemWithPath;
 
 /**
  * Output type for S3 downloadData API.
+ * @deprecated Use {@link DownloadDataWithPathOutput} instead.
+ */
+export type DownloadDataOutput = DownloadTask<
+	StorageDownloadDataOutput<ItemWithKey>
+>;
+/**
+ * Output type with path for S3 downloadData API.
  */
-export type DownloadDataOutput = DownloadTask<StorageDownloadDataOutput<Item>>;
+export type DownloadDataWithPathOutput = DownloadTask<
+	StorageDownloadDataOutput<ItemWithPath>
+>;
 
 /**
  * Output type for S3 getUrl API.
+ * @deprecated Use {@link GetUrlWithPathOutput} instead.
  */
 export type GetUrlOutput = StorageGetUrlOutput;
+/**
+ *  Output type with path for S3 getUrl API.
+ * */
+export type GetUrlWithPathOutput = StorageGetUrlOutput;
 
 /**
  * Output type for S3 uploadData API.
+ *  @deprecated Use {@link UploadDataWithPathOutput} instead.
  */
-export type UploadDataOutput = UploadTask<Item>;
+export type UploadDataOutput = UploadTask<ItemWithKey>;
+/**
+ *  Output type with path for S3 uploadData API.
+ * */
+export type UploadDataWithPathOutput = UploadTask<ItemWithPath>;
 
 /**
  * Output type for S3 getProperties API.
- */
-export type GetPropertiesOutput = Item;
+ * @deprecated Use {@link GetPropertiesWithPathOutput} instead.
+ * */
+export type GetPropertiesOutput = ItemBase & StorageItemWithKey;
+/**
+ *  Output type with path for S3 getProperties API.
+ * */
+export type GetPropertiesWithPathOutput = ItemBase & StorageItemWithPath;
 
 /**
+ * @deprecated Use {@link ListAllWithPathOutput} instead.
  * Output type for S3 list API. Lists all bucket objects.
  */
 export type ListAllOutput = StorageListOutput<ListOutputItem>;
 
 /**
+ * Output type with path for S3 list API. Lists all bucket objects.
+ */
+export type ListAllWithPathOutput = StorageListOutput<ListOutputItemWithPath>;
+
+/**
+ * @deprecated Use {@link ListPaginateWithPathOutput} instead.
  * Output type for S3 list API. Lists bucket objects with pagination.
  */
 export type ListPaginateOutput = StorageListOutput<ListOutputItem> & {
@@ -62,11 +110,30 @@ export type ListPaginateOutput = StorageListOutput<ListOutputItem> & {
 };
 
 /**
- * Output type for S3 copy API.
+ * Output type with path for S3 list API. Lists bucket objects with pagination.
+ */
+export type ListPaginateWithPathOutput =
+	StorageListOutput<ListOutputItemWithPath> & {
+		nextToken?: string;
+	};
+
+/**
+ *  Output type with path for S3 copy API.
+ * @deprecated Use {@link CopyWithPathOutput} instead.
+ */
+export type CopyOutput = Pick<ItemWithKey, 'key'>;
+/**
+ * Output type with path for S3 copy API.
+ */
+export type CopyWithPathOutput = Pick<ItemWithPath, 'path'>;
+
+/**
+ * @deprecated Use {@link RemoveWithPathOutput} instead.
+ * Output type with key for S3 remove API.
  */
-export type CopyOutput = Pick<Item, 'key'>;
+export type RemoveOutput = Pick<ItemWithKey, 'key'>;
 
 /**
- * Output type for S3 remove API.
+ * Output type with path for S3 remove API.
  */
-export type RemoveOutput = Pick<Item, 'key'>;
+export type RemoveWithPathOutput = Pick<ItemWithPath, 'path'>;

package/src/providers/s3/utils/client/utils/parsePayload.ts

@@ -39,7 +39,7 @@ export const parseXmlBody = async (response: HttpResponse): Promise<any> => {
 		try {
 			return parser.parse(data);
 		} catch (error) {
-			throw new Error('Failed to parse XML response.');
+			throw new Error(`Failed to parse XML response: ${error}`);
 		}
 	}
 

package/src/providers/s3/utils/constants.ts

@@ -19,3 +19,7 @@ export const MAX_PARTS_COUNT = 10000;
 export const DEFAULT_QUEUE_SIZE = 4;
 
 export const UPLOADS_STORAGE_KEY = '__uploadInProgress';
+
+export const STORAGE_INPUT_PREFIX = 'prefix';
+export const STORAGE_INPUT_KEY = 'key';
+export const STORAGE_INPUT_PATH = 'path';

package/src/providers/s3/utils/index.ts

@@ -4,3 +4,6 @@
 export { calculateContentMd5 } from './md5';
 export { resolveS3ConfigAndInput } from './resolveS3ConfigAndInput';
 export { createDownloadTask, createUploadTask } from './transferTask';
+export { validateStorageOperationInput } from './validateStorageOperationInput';
+export { validateStorageOperationInputWithPrefix } from './validateStorageOperationInputWithPrefix';
+export { isInputWithPath } from './isInputWithPath';

package/src/providers/s3/utils/isInputWithPath.ts

@@ -0,0 +1,13 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	StorageOperationInput,
+	StorageOperationInputWithPath,
+} from '../../../types/inputs';
+
+export const isInputWithPath = (
+	input: StorageOperationInput,
+): input is StorageOperationInputWithPath => {
+	return input.path !== undefined;
+};

package/src/providers/s3/utils/resolveS3ConfigAndInput.ts

@@ -5,7 +5,6 @@ import { AmplifyClassV6, StorageAccessLevel } from '@aws-amplify/core';
 
 import { assertValidationError } from '../../../errors/utils/assertValidationError';
 import { StorageValidationErrorCode } from '../../../errors/types/validation';
-import { StorageError } from '../../../errors/StorageError';
 import { resolvePrefix as defaultPrefixResolver } from '../../../utils/resolvePrefix';
 import { ResolvedS3Config } from '../types/options';
 
@@ -22,6 +21,7 @@ interface ResolvedS3ConfigAndInput {
 	bucket: string;
 	keyPrefix: string;
 	isObjectLockEnabled?: boolean;
+	identityId?: string;
 }
 
 /**
@@ -30,7 +30,7 @@ interface ResolvedS3ConfigAndInput {
  * @param {AmplifyClassV6} amplify The Amplify instance.
  * @param {S3ApiOptions} apiOptions The input options for S3 provider.
  * @returns {Promise<ResolvedS3ConfigAndInput>} The resolved common input options for S3 API handlers.
- * @throws A {@link StorageError} with `error.name` from {@link StorageValidationErrorCode} indicating invalid
+ * @throws A `StorageError` with `error.name` from `StorageValidationErrorCode` indicating invalid
  *   configurations or Amplify library options.
  *
  * @internal
@@ -84,6 +84,7 @@ export const resolveS3ConfigAndInput = async (
 		},
 		bucket,
 		keyPrefix,
+		identityId,
 		isObjectLockEnabled,
 	};
 };

package/src/providers/s3/utils/validateStorageOperationInput.ts

@@ -0,0 +1,39 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { StorageOperationInput as Input } from '../../../types/inputs';
+import { assertValidationError } from '../../../errors/utils/assertValidationError';
+import { StorageValidationErrorCode } from '../../../errors/types/validation';
+
+import { isInputWithPath } from './isInputWithPath';
+import { STORAGE_INPUT_KEY, STORAGE_INPUT_PATH } from './constants';
+
+export const validateStorageOperationInput = (
+	input: Input,
+	identityId?: string,
+) => {
+	assertValidationError(
+		// Key present without a path
+		(!!(input as Input).key && !(input as Input).path) ||
+			// Path present without a key
+			(!(input as Input).key && !!(input as Input).path),
+		StorageValidationErrorCode.InvalidStorageOperationInput,
+	);
+
+	if (isInputWithPath(input)) {
+		const { path } = input;
+		const objectKey = typeof path === 'string' ? path : path({ identityId });
+
+		assertValidationError(
+			!objectKey.startsWith('/'),
+			StorageValidationErrorCode.InvalidStoragePathInput,
+		);
+
+		return {
+			inputType: STORAGE_INPUT_PATH,
+			objectKey,
+		};
+	} else {
+		return { inputType: STORAGE_INPUT_KEY, objectKey: input.key };
+	}
+};