feat(storage): internals list API

packages/storage/__tests__/internals/apis/list.test.ts

@@ -0,0 +1,55 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { AmplifyClassV6 } from '@aws-amplify/core';
+
+import { list as advancedList } from '../../../src/internals';
+import { list as listInternal } from '../../../src/providers/s3/apis/internal/list';
+import { ListAllWithPathOutput } from '../../../src';
+
+jest.mock('../../../src/providers/s3/apis/internal/list');
+const mockedListInternal = jest.mocked(listInternal);
+
+describe('list (internals)', () => {
+	beforeEach(() => {
+		jest.clearAllMocks();
+		mockedListInternal.mockResolvedValue({
+			items: [],
+		} as ListAllWithPathOutput);
+	});
+
+	it('should pass advanced option locationCredentialsProvider to internal list', async () => {
+		const useAccelerateEndpoint = true;
+		const bucket = { bucketName: 'bucket', region: 'us-east-1' };
+		const locationCredentialsProvider = async () => ({
+			credentials: {
+				accessKeyId: 'akid',
+				secretAccessKey: 'secret',
+				sessionToken: 'token',
+				expiration: new Date(),
+			},
+		});
+		const result = await advancedList({
+			path: 'input/path/to/mock/object',
+			options: {
+				useAccelerateEndpoint,
+				bucket,
+				locationCredentialsProvider,
+			},
+		});
+		expect(mockedListInternal).toHaveBeenCalledTimes(1);
+		expect(mockedListInternal).toHaveBeenCalledWith(
+			expect.any(AmplifyClassV6),
+			{
+				path: 'input/path/to/mock/object',
+				options: {
+					useAccelerateEndpoint,
+					bucket,
+					locationCredentialsProvider,
+				},
+			},
+		);
+		expect(result).toEqual({
+			items: [],
+		});
+	});
+});

packages/storage/src/internals/apis/list.ts

@@ -0,0 +1,19 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Amplify } from '@aws-amplify/core';
+
+import { list as listInternal } from '../../providers/s3/apis/internal/list';
+import { ListInputWithPath } from '../types/inputs';
+
+/**
+ * @internal
+ * List all or paginate files from S3 for a given `path`.
+ * @param input - The `ListWithPathInputAndAdvancedOptions` object.
+ * @returns A list of all objects with path and metadata
+ * @throws service: `S3Exception` - S3 service errors thrown when checking for existence of bucket
+ * @throws validation: `StorageValidationErrorCode`  - thrown when there are issues with credentials
+ */
+export function list(input?: ListInputWithPath) {
+	return listInternal(Amplify, input ?? {});
+}

packages/storage/src/internals/index.ts

@@ -14,6 +14,7 @@ export {
 	GetPropertiesInput,
 	GetUrlInput,
 	CopyInput,
+	ListInputWithPath,
 	RemoveInput,
 } from './types/inputs';
 export {
@@ -26,6 +27,7 @@ export {
 
 export { getDataAccess } from './apis/getDataAccess';
 export { listCallerAccessGrants } from './apis/listCallerAccessGrants';
+export { list } from './apis/list';
 export { getProperties } from './apis/getProperties';
 export { getUrl } from './apis/getUrl';
 export { remove } from './apis/remove';

packages/storage/src/internals/types/inputs.ts

@@ -12,6 +12,10 @@ import {
 	GetUrlWithPathInput,
 	RemoveWithPathInput,
 } from '../../providers/s3';
+import {
+	ListAllWithPathInput,
+	ListPaginateWithPathInput,
+} from '../../providers/s3/types/inputs';
 
 import { CredentialsProvider, ListLocationsInput } from './credentials';
 import { Permission, PrefixType, Privilege } from './common';
@@ -39,6 +43,16 @@ export interface GetDataAccessInput {
 	scope: string;
 }
 
+/**
+ * @internal
+ */
+export type ListInputWithPath = ExtendInputWithAdvancedOptions<
+	ListAllWithPathInput | ListPaginateWithPathInput,
+	{
+		locationCredentialsProvider?: CredentialsProvider;
+	}
+>;
+
 /**
  * @internal
  */

packages/storage/src/providers/s3/apis/internal/list.ts

@@ -5,15 +5,11 @@ import { AmplifyClassV6 } from '@aws-amplify/core';
 import { StorageAction } from '@aws-amplify/core/internals/utils';
 
 import {
-	ListAllInput,
 	ListAllOutput,
-	ListAllWithPathInput,
 	ListAllWithPathOutput,
 	ListOutputItem,
 	ListOutputItemWithPath,
-	ListPaginateInput,
 	ListPaginateOutput,
-	ListPaginateWithPathInput,
 	ListPaginateWithPathOutput,
 } from '../../types';
 import {
@@ -35,6 +31,9 @@ import { logger } from '../../../../utils';
 import { DEFAULT_DELIMITER, STORAGE_INPUT_PREFIX } from '../../utils/constants';
 import { CommonPrefix } from '../../utils/client/s3data/types';
 import { IntegrityError } from '../../../../errors/IntegrityError';
+import { ListAllInput, ListPaginateInput } from '../../types/inputs';
+// TODO: Remove this interface when we move to public advanced APIs.
+import { ListInputWithPath as ListWithPathInputAndAdvancedOptions } from '../../../../internals/types/inputs';
 
 const MAX_PAGE_SIZE = 1000;
 
@@ -46,11 +45,7 @@ interface ListInputArgs {
 
 export const list = async (
 	amplify: AmplifyClassV6,
-	input:
-		| ListAllInput
-		| ListPaginateInput
-		| ListAllWithPathInput
-		| ListPaginateWithPathInput,
+	input: ListAllInput | ListPaginateInput | ListWithPathInputAndAdvancedOptions,
 ): Promise<
 	| ListAllOutput
 	| ListPaginateOutput