feat: add gen2 path parameter to getProperties and getUrl

packages/storage/__tests__/providers/s3/apis/getProperties.test.ts

@@ -5,7 +5,10 @@ import { headObject } from '../../../../src/providers/s3/utils/client';
 import { getProperties } from '../../../../src/providers/s3';
 import { AWSCredentials } from '@aws-amplify/core/internals/utils';
 import { Amplify } from '@aws-amplify/core';
-import { GetPropertiesOptions } from '../../../../src/providers/s3/types';
+import {
+	GetPropertiesOptionsKey,
+	GetPropertiesOptionsPath,
+} from '../../../../src/providers/s3/types';
 
 jest.mock('../../../../src/providers/s3/utils/client');
 jest.mock('@aws-amplify/core', () => ({
@@ -30,10 +33,12 @@ const credentials: AWSCredentials = {
 	sessionToken: 'sessionToken',
 	secretAccessKey: 'secretAccessKey',
 };
+const key = 'key';
+const path = '/path';
 const targetIdentityId = 'targetIdentityId';
 const defaultIdentityId = 'defaultIdentityId';
 
-describe('getProperties api', () => {
+describe('getProperties with key', () => {
 	beforeAll(() => {
 		mockFetchAuthSession.mockResolvedValue({
 			credentials,
@@ -48,9 +53,9 @@ describe('getProperties api', () => {
 			},
 		});
 	});
-	describe('getProperties happy path ', () => {
+	describe('getProperties happy path with key', () => {
 		const expected = {
-			key: 'key',
+			key,
 			size: '100',
 			contentType: 'text/plain',
 			eTag: 'etag',
@@ -63,7 +68,6 @@ describe('getProperties api', () => {
 			region: 'region',
 			userAgentValue: expect.any(String),
 		};
-		const key = 'key';
 		beforeEach(() => {
 			mockHeadObject.mockReturnValueOnce({
 				ContentLength: '100',
@@ -111,7 +115,7 @@ describe('getProperties api', () => {
 				expect(
 					await getProperties({
 						key,
-						options: options as GetPropertiesOptions,
+						options: options as GetPropertiesOptionsKey,
 					}),
 				).toEqual(expected);
 				expect(headObject).toHaveBeenCalledTimes(1);
@@ -133,7 +137,7 @@ describe('getProperties api', () => {
 			);
 			expect.assertions(3);
 			try {
-				await getProperties({ key: 'keyed' });
+				await getProperties({ key });
 			} catch (error: any) {
 				expect(headObject).toHaveBeenCalledTimes(1);
 				expect(headObject).toHaveBeenCalledWith(
@@ -144,7 +148,114 @@ describe('getProperties api', () => {
 					},
 					{
 						Bucket: 'bucket',
-						Key: 'public/keyed',
+						Key: `public/${key}`,
+					},
+				);
+				expect(error.$metadata.httpStatusCode).toBe(404);
+			}
+		});
+	});
+});
+
+describe('getProperties with path', () => {
+	beforeAll(() => {
+		mockFetchAuthSession.mockResolvedValue({
+			credentials,
+			identityId: defaultIdentityId,
+		});
+		mockGetConfig.mockReturnValue({
+			Storage: {
+				S3: {
+					bucket,
+					region,
+				},
+			},
+		});
+	});
+	describe('getProperties with path', () => {
+		const expected = {
+			path,
+			size: '100',
+			contentType: 'text/plain',
+			eTag: 'etag',
+			metadata: { key: 'value' },
+			lastModified: 'last-modified',
+			versionId: 'version-id',
+		};
+		const config = {
+			credentials,
+			region: 'region',
+			useAccelerateEndpoint: true,
+			userAgentValue: expect.any(String),
+		};
+		beforeEach(() => {
+			mockHeadObject.mockReturnValueOnce({
+				ContentLength: '100',
+				ContentType: 'text/plain',
+				ETag: 'etag',
+				LastModified: 'last-modified',
+				Metadata: { key: 'value' },
+				VersionId: 'version-id',
+			});
+		});
+		afterEach(() => {
+			jest.clearAllMocks();
+		});
+		[
+			{
+				path: '/path',
+				expectedKey: '/path',
+			},
+			{
+				path: () => '/path',
+				expectedKey: '/path',
+			},
+		].forEach(({ path, expectedKey }) => {
+			it(`should getProperties with path ${path} and expectedKey ${expectedKey}`, async () => {
+				const headObjectOptions = {
+					Bucket: 'bucket',
+					Key: expectedKey,
+				};
+				expect.assertions(3);
+				expect(
+					await getProperties({
+						path,
+						options: {
+							useAccelerateEndpoint: true,
+						} as GetPropertiesOptionsPath,
+					}),
+				).toEqual(expected);
+				expect(headObject).toHaveBeenCalledTimes(1);
+				expect(headObject).toHaveBeenCalledWith(config, headObjectOptions);
+			});
+		});
+	});
+
+	describe('getProperties error path with path', () => {
+		afterEach(() => {
+			jest.clearAllMocks();
+		});
+		it('getProperties should return a not found error', async () => {
+			mockHeadObject.mockRejectedValueOnce(
+				Object.assign(new Error(), {
+					$metadata: { httpStatusCode: 404 },
+					name: 'NotFound',
+				}),
+			);
+			expect.assertions(3);
+			try {
+				await getProperties({ path });
+			} catch (error: any) {
+				expect(headObject).toHaveBeenCalledTimes(1);
+				expect(headObject).toHaveBeenCalledWith(
+					{
+						credentials,
+						region: 'region',
+						userAgentValue: expect.any(String),
+					},
+					{
+						Bucket: 'bucket',
+						Key: path,
 					},
 				);
 				expect(error.$metadata.httpStatusCode).toBe(404);

packages/storage/__tests__/providers/s3/apis/getUrl.test.ts

@@ -8,7 +8,10 @@ import {
 	getPresignedGetObjectUrl,
 	headObject,
 } from '../../../../src/providers/s3/utils/client';
-import { GetUrlOptions } from '../../../../src/providers/s3/types';
+import {
+	GetUrlOptionsKey,
+	GetUrlOptionsPath,
+} from '../../../../src/providers/s3/types';
 
 jest.mock('../../../../src/providers/s3/utils/client');
 jest.mock('@aws-amplify/core', () => ({
@@ -35,7 +38,7 @@ const credentials: AWSCredentials = {
 const targetIdentityId = 'targetIdentityId';
 const defaultIdentityId = 'defaultIdentityId';
 
-describe('getUrl test', () => {
+describe('getUrl test with key', () => {
 	beforeAll(() => {
 		mockFetchAuthSession.mockResolvedValue({
 			credentials,
@@ -112,7 +115,7 @@ describe('getUrl test', () => {
 					options: {
 						...options,
 						validateObjectExistence: true,
-					} as GetUrlOptions,
+					} as GetUrlOptionsKey,
 				});
 				expect(getPresignedGetObjectUrl).toHaveBeenCalledTimes(1);
 				expect(headObject).toHaveBeenCalledTimes(1);
@@ -147,3 +150,100 @@ describe('getUrl test', () => {
 		});
 	});
 });
+
+describe('getUrl test with path', () => {
+	beforeAll(() => {
+		mockFetchAuthSession.mockResolvedValue({
+			credentials,
+			identityId: defaultIdentityId,
+		});
+		mockGetConfig.mockReturnValue({
+			Storage: {
+				S3: {
+					bucket,
+					region,
+				},
+			},
+		});
+	});
+
+	describe('getUrl happy path', () => {
+		const config = {
+			credentials,
+			region,
+			userAgentValue: expect.any(String),
+		};
+		const path = '/path';
+		beforeEach(() => {
+			(headObject as jest.Mock).mockImplementation(() => {
+				return {
+					Key: path,
+					ContentLength: '100',
+					ContentType: 'text/plain',
+					ETag: 'etag',
+					LastModified: 'last-modified',
+					Metadata: { key: 'value' },
+				};
+			});
+			(getPresignedGetObjectUrl as jest.Mock).mockReturnValueOnce({
+				url: new URL('https://google.com'),
+			});
+		});
+		afterEach(() => {
+			jest.clearAllMocks();
+		});
+		[
+			{
+				path: '/path',
+				expectedKey: '/path',
+			},
+			{
+				path: () => '/path',
+				expectedKey: '/path',
+			},
+		].forEach(({ path, expectedKey }) => {
+			it(`should getUrl with path ${path} and expectedKey ${expectedKey}`, async () => {
+				const headObjectOptions = {
+					Bucket: bucket,
+					Key: expectedKey,
+				};
+				expect.assertions(4);
+				const result = await getUrl({
+					path,
+					options: {
+						validateObjectExistence: true,
+					} as GetUrlOptionsPath,
+				});
+				expect(getPresignedGetObjectUrl).toHaveBeenCalledTimes(1);
+				expect(headObject).toHaveBeenCalledTimes(1);
+				expect(headObject).toHaveBeenCalledWith(config, headObjectOptions);
+				expect(result.url).toEqual({
+					url: new URL('https://google.com'),
+				});
+			});
+		});
+	});
+	describe('getUrl error path', () => {
+		afterAll(() => {
+			jest.clearAllMocks();
+		});
+		it('should return not found error when the object is not found', async () => {
+			(headObject as jest.Mock).mockImplementation(() => {
+				throw Object.assign(new Error(), {
+					$metadata: { httpStatusCode: 404 },
+					name: 'NotFound',
+				});
+			});
+			expect.assertions(2);
+			try {
+				await getUrl({
+					path: '/invalid_key',
+					options: { validateObjectExistence: true },
+				});
+			} catch (error: any) {
+				expect(headObject).toHaveBeenCalledTimes(1);
+				expect(error.$metadata?.httpStatusCode).toBe(404);
+			}
+		});
+	});
+});

packages/storage/src/providers/s3/apis/getProperties.ts

@@ -3,7 +3,15 @@
 
 import { Amplify } from '@aws-amplify/core';
 
-import { GetPropertiesInput, GetPropertiesOutput, S3Exception } from '../types';
+import {
+	GetPropertiesInput,
+	GetPropertiesInputKey,
+	GetPropertiesInputPath,
+	GetPropertiesOutput,
+	GetPropertiesOutputKey,
+	GetPropertiesOutputPath,
+	S3Exception,
+} from '../types';
 import { StorageValidationErrorCode } from '../../../errors/types/validation';
 
 import { getProperties as getPropertiesInternal } from './internal/getProperties';
@@ -17,8 +25,37 @@
  * @throws A {@link S3Exception} when the underlying S3 service returned error.
  * @throws A {@link StorageValidationErrorCode} when API call parameters are invalid.
  */
-export const getProperties = (
+
+interface GetProperties {
+	/**
+	 * Gets the properties of a file. The properties include S3 system metadata and
+	 * the user metadata that was provided when uploading the file.
+	 *
+	 * @param input - The GetPropertiesInput object.
+	 * @returns Requested object properties.
+	 * @throws An {@link S3Exception} when the underlying S3 service returned error.
+	 * @throws A {@link StorageValidationErrorCode} when API call parameters are invalid.
+	 */
+	(input: GetPropertiesInputPath): Promise<GetPropertiesOutputPath>;
+	/**
+	 * @deprecated The `key` and `accessLevel` parameters are deprecated and may be removed in the next major version.
+	 * Please use {@link https://docs.amplify.aws/react/build-a-backend/storage/download/#downloaddata | path} instead.
+	 *
+	 * Gets the properties of a file. The properties include S3 system metadata and
+	 * the user metadata that was provided when uploading the file.
+	 *
+	 * @param input - The GetPropertiesInput object.
+	 * @returns Requested object properties.
+	 * @throws An {@link S3Exception} when the underlying S3 service returned error.
+	 * @throws A {@link StorageValidationErrorCode} when API call parameters are invalid.
+	 */
+	(input: GetPropertiesInputKey): Promise<GetPropertiesOutputKey>;
+}
+
+export const getProperties: GetProperties = <
+	Output extends GetPropertiesOutput,
+>(
 	input: GetPropertiesInput,
-): Promise<GetPropertiesOutput> => {
-	return getPropertiesInternal(Amplify, input);
+): Promise<Output> => {
+	return getPropertiesInternal(Amplify, input) as Promise<Output>;
 };