@aws-amplify/geo 1.2.4 → 1.2.5-geo.18

package/src/Providers/AmazonLocationServiceProvider.ts

@@ -11,6 +11,7 @@
  * and limitations under the License.
  */
 import camelcaseKeys from 'camelcase-keys';
+
 import {
 	ConsoleLogger as Logger,
 	Credentials,
@@ -18,15 +19,28 @@ import {
 } from '@aws-amplify/core';
 import {
 	Place as PlaceResult,
+	SearchPlaceIndexForTextCommandInput,
 	LocationClient,
 	SearchPlaceIndexForTextCommand,
-	SearchPlaceIndexForTextCommandInput,
-	SearchPlaceIndexForSuggestionsCommand,
-	SearchPlaceIndexForSuggestionsCommandInput,
 	SearchPlaceIndexForPositionCommand,
 	SearchPlaceIndexForPositionCommandInput,
+	BatchPutGeofenceCommand,
+	BatchPutGeofenceCommandInput,
+	BatchPutGeofenceRequestEntry,
+	BatchPutGeofenceCommandOutput,
+	GetGeofenceCommand,
+	GetGeofenceCommandInput,
+	GetGeofenceCommandOutput,
+	ListGeofencesCommand,
+	ListGeofencesCommandInput,
+	ListGeofencesCommandOutput,
+	BatchDeleteGeofenceCommand,
+	BatchDeleteGeofenceCommandInput,
+	BatchDeleteGeofenceCommandOutput,
 } from '@aws-sdk/client-location';
 
+import { validateGeofenceId, validateGeofencesInput } from '../util';
+
 import {
 	GeoConfig,
 	SearchByTextOptions,
@@ -35,7 +49,16 @@ import {
 	Place,
 	AmazonLocationServiceMapStyle,
 	Coordinates,
-	SearchForSuggestionsResults,
+	GeofenceId,
+	GeofenceInput,
+	AmazonLocationServiceGeofenceOptions,
+	AmazonLocationServiceListGeofenceOptions,
+	ListGeofenceResults,
+	AmazonLocationServiceGeofenceStatus,
+	SaveGeofencesResults,
+	AmazonLocationServiceGeofence,
+	GeofencePolygon,
+	AmazonLocationServiceDeleteGeofencesResults,
 } from '../types';
 
 const logger = new Logger('AmazonLocationServiceProvider');
@@ -199,16 +222,15 @@ export class AmazonLocationServiceProvider implements GeoProvider {
 	}
 
 	/**
-	 * Search for suggestions based on the input text
-	 * @param  {string} text - The text string that is to be searched for
-	 * @param  {SearchByTextOptions} options? - Optional parameters to the search
-	 * @returns {Promise<SearchForSuggestionsResults>} - Resolves to an array of search suggestion strings
+	 * Reverse geocoding search via a coordinate point on the map
+	 * @param coordinates - Coordinates array for the search input
+	 * @param options - Options parameters for the search
+	 * @returns {Promise<Place>} - Promise that resolves to a place matching search coordinates
 	 */
-
-	public async searchForSuggestions(
-		text: string,
-		options?: SearchByTextOptions
-	): Promise<SearchForSuggestionsResults> {
+	public async searchByCoordinates(
+		coordinates: Coordinates,
+		options?: SearchByCoordinatesOptions
+	): Promise<Place> {
 		const credentialsOK = await this._ensureCredentials();
 		if (!credentialsOK) {
 			throw new Error('No credentials');
@@ -216,36 +238,16 @@ export class AmazonLocationServiceProvider implements GeoProvider {
 
 		this._verifySearchIndex(options?.searchIndexName);
 
-		/**
-		 * Setup the searchInput
-		 */
-		const locationServiceInput: SearchPlaceIndexForSuggestionsCommandInput = {
-			Text: text,
+		const locationServiceInput: SearchPlaceIndexForPositionCommandInput = {
+			Position: coordinates,
 			IndexName: this._config.search_indices.default,
 		};
 
-		/**
-		 * Map search options to Amazon Location Service input object
-		 */
 		if (options) {
-			locationServiceInput.FilterCountries = options.countries;
-			locationServiceInput.MaxResults = options.maxResults;
-
 			if (options.searchIndexName) {
 				locationServiceInput.IndexName = options.searchIndexName;
 			}
-
-			if (options['biasPosition'] && options['searchAreaConstraints']) {
-				throw new Error(
-					'BiasPosition and SearchAreaConstraints are mutually exclusive, please remove one or the other from the options object'
-				);
-			}
-			if (options['biasPosition']) {
-				locationServiceInput.BiasPosition = options['biasPosition'];
-			}
-			if (options['searchAreaConstraints']) {
-				locationServiceInput.FilterBBox = options['searchAreaConstraints'];
-			}
+			locationServiceInput.MaxResults = options.maxResults;
 		}
 
 		const client = new LocationClient({
@@ -253,7 +255,7 @@ export class AmazonLocationServiceProvider implements GeoProvider {
 			region: this._config.region,
 			customUserAgent: getAmplifyUserAgent(),
 		});
-		const command = new SearchPlaceIndexForSuggestionsCommand(
+		const command = new SearchPlaceIndexForPositionCommand(
 			locationServiceInput
 		);
 
@@ -266,53 +268,234 @@ export class AmazonLocationServiceProvider implements GeoProvider {
 		}
 
 		/**
-		 * The response from Amazon Location Service is a "Results" array of objects with a single `Text` item.
-		 * Here we want to flatten that to an array of just the strings from those `Text` items.
+		 * The response from Amazon Location Service is a "Results" array with a single `Place` object
+		 * which are Place objects in PascalCase.
+		 * Here we want to flatten that to an array of results and change them to camelCase
 		 */
-		const results = response.Results.map(result => result.Text);
+		const PascalResults = response.Results.map(result => result.Place);
+		const results: Place = camelcaseKeys(PascalResults[0], {
+			deep: true,
+		}) as any as Place;
 
 		return results;
 	}
 
 	/**
-	 * Reverse geocoding search via a coordinate point on the map
-	 * @param coordinates - Coordinates array for the search input
-	 * @param options - Options parameters for the search
-	 * @returns {Promise<Place>} - Promise that resolves to a place matching search coordinates
+	 * Create geofences inside of a geofence collection
+	 * @param geofences - Array of geofence objects to create
+	 * @param options? - Optional parameters for creating geofences
+	 * @returns {Promise<AmazonLocationServiceSaveGeofencesResults>} - Promise that resolves to an object with:
+	 *   successes: list of geofences successfully created
+	 *   errors: list of geofences that failed to create
 	 */
-	public async searchByCoordinates(
-		coordinates: Coordinates,
-		options?: SearchByCoordinatesOptions
-	): Promise<Place> {
+	public async saveGeofences(
+		geofences: GeofenceInput[],
+		options?: AmazonLocationServiceGeofenceOptions
+	): Promise<SaveGeofencesResults> {
+		if (geofences.length < 1) {
+			throw new Error('Geofence input array is empty');
+		}
+
 		const credentialsOK = await this._ensureCredentials();
 		if (!credentialsOK) {
 			throw new Error('No credentials');
 		}
 
-		this._verifySearchIndex(options?.searchIndexName);
+		// Verify geofence collection exists in aws-config.js
+		try {
+			this._verifyGeofenceCollections(options?.collectionName);
+		} catch (error) {
+			logger.debug(error);
+			throw error;
+		}
 
-		const locationServiceInput: SearchPlaceIndexForPositionCommandInput = {
-			Position: coordinates,
-			IndexName: this._config.search_indices.default,
+		validateGeofencesInput(geofences);
+
+		// Convert geofences to PascalCase for Amazon Location Service format
+		const PascalGeofences: BatchPutGeofenceRequestEntry[] = geofences.map(
+			({ geofenceId, geometry: { polygon } }) => {
+				return {
+					GeofenceId: geofenceId,
+					Geometry: {
+						Polygon: polygon,
+					},
+				};
+			}
+		);
+		const results: SaveGeofencesResults = {
+			successes: [],
+			errors: [],
 		};
 
-		if (options) {
-			if (options.searchIndexName) {
-				locationServiceInput.IndexName = options.searchIndexName;
-			}
-			locationServiceInput.MaxResults = options.maxResults;
+		const geofenceBatches: BatchPutGeofenceRequestEntry[][] = [];
+
+		while (PascalGeofences.length > 0) {
+			// Splice off 10 geofences from input clone due to Amazon Location Service API limit
+			const apiLimit = 10;
+			geofenceBatches.push(PascalGeofences.splice(0, apiLimit));
 		}
 
+		await Promise.all(
+			geofenceBatches.map(async batch => {
+				// Make API call for the 10 geofences
+				let response: BatchPutGeofenceCommandOutput;
+				try {
+					response = await this._AmazonLocationServiceBatchPutGeofenceCall(
+						batch,
+						options?.collectionName || this._config.geofenceCollections.default
+					);
+				} catch (error) {
+					// If the API call fails, add the geofences to the errors array and move to next batch
+					batch.forEach(geofence => {
+						results.errors.push({
+							geofenceId: geofence.GeofenceId,
+							error: {
+								code: 'APIConnectionError',
+								message: error.message,
+							},
+						});
+					});
+					return;
+				}
+
+				// Push all successes to results
+				response.Successes.forEach(success => {
+					const { GeofenceId, CreateTime, UpdateTime } = success;
+					results.successes.push({
+						geofenceId: GeofenceId,
+						createTime: CreateTime,
+						updateTime: UpdateTime,
+					});
+				});
+
+				// Push all errors to results
+				response.Errors.forEach(error => {
+					const {
+						Error: { Code, Message },
+						GeofenceId,
+					} = error;
+					results.errors.push({
+						error: {
+							code: Code,
+							message: Message,
+						},
+						geofenceId: GeofenceId,
+					});
+				});
+			})
+		);
+
+		return results;
+	}
+
+	/**
+	 * Get geofence from a geofence collection
+	 * @param geofenceId:string
+	 * @param options?: Optional parameters for getGeofence
+	 * @returns {Promise<AmazonLocationServiceGeofence>} - Promise that resolves to a geofence object
+	 */
+	public async getGeofence(
+		geofenceId: GeofenceId,
+		options?: AmazonLocationServiceGeofenceOptions
+	): Promise<AmazonLocationServiceGeofence> {
+		const credentialsOK = await this._ensureCredentials();
+		if (!credentialsOK) {
+			throw new Error('No credentials');
+		}
+
+		// Verify geofence collection exists in aws-config.js
+		try {
+			this._verifyGeofenceCollections(options?.collectionName);
+		} catch (error) {
+			logger.debug(error);
+			throw error;
+		}
+
+		validateGeofenceId(geofenceId);
+
+		// Create Amazon Location Service Client
 		const client = new LocationClient({
 			credentials: this._config.credentials,
 			region: this._config.region,
 			customUserAgent: getAmplifyUserAgent(),
 		});
-		const command = new SearchPlaceIndexForPositionCommand(
-			locationServiceInput
+
+		// Create Amazon Location Service command
+		const commandInput: GetGeofenceCommandInput = {
+			GeofenceId: geofenceId,
+			CollectionName:
+				options?.collectionName || this._config.geofenceCollections.default,
+		};
+		const command = new GetGeofenceCommand(commandInput);
+
+		// Make API call
+		let response: GetGeofenceCommandOutput;
+		try {
+			response = await client.send(command);
+		} catch (error) {
+			logger.debug(error);
+			throw error;
+		}
+
+		// Convert response to camelCase for return
+		const { GeofenceId, CreateTime, UpdateTime, Status, Geometry } = response;
+		const geofence: AmazonLocationServiceGeofence = {
+			createTime: CreateTime,
+			geofenceId: GeofenceId,
+			geometry: {
+				polygon: Geometry.Polygon as GeofencePolygon,
+			},
+			status: Status as AmazonLocationServiceGeofenceStatus,
+			updateTime: UpdateTime,
+		};
+
+		return geofence;
+	}
+
+	/**
+	 * List geofences from a geofence collection
+	 * @param  options?: ListGeofenceOptions
+	 * @returns {Promise<ListGeofencesResults>} - Promise that resolves to an object with:
+	 *   entries: list of geofences - 100 geofences are listed per page
+	 *   nextToken: token for next page of geofences
+	 */
+	public async listGeofences(
+		options?: AmazonLocationServiceListGeofenceOptions
+	): Promise<ListGeofenceResults> {
+		const credentialsOK = await this._ensureCredentials();
+		if (!credentialsOK) {
+			throw new Error('No credentials');
+		}
+
+		// Verify geofence collection exists in aws-config.js
+		try {
+			this._verifyGeofenceCollections(options?.collectionName);
+		} catch (error) {
+			logger.debug(error);
+			throw error;
+		}
+
+		// Create Amazon Location Service Client
+		const client = new LocationClient({
+			credentials: this._config.credentials,
+			region: this._config.region,
+			customUserAgent: getAmplifyUserAgent(),
+		});
+
+		// Create Amazon Location Service input
+		const listGeofencesInput: ListGeofencesCommandInput = {
+			NextToken: options?.nextToken,
+			CollectionName:
+				options?.collectionName || this._config.geofenceCollections.default,
+		};
+
+		// Create Amazon Location Service command
+		const command: ListGeofencesCommand = new ListGeofencesCommand(
+			listGeofencesInput
 		);
 
-		let response;
+		// Make API call
+		let response: ListGeofencesCommandOutput;
 		try {
 			response = await client.send(command);
 		} catch (error) {
@@ -320,19 +503,116 @@ export class AmazonLocationServiceProvider implements GeoProvider {
 			throw error;
 		}
 
-		/**
-		 * The response from Amazon Location Service is a "Results" array with a single `Place` object
-		 * which are Place objects in PascalCase.
-		 * Here we want to flatten that to an array of results and change them to camelCase
-		 */
-		const PascalResults = response.Results.map(result => result.Place);
-		const results: Place = camelcaseKeys(PascalResults[0], {
-			deep: true,
-		}) as any as Place;
+		// Convert response to camelCase for return
+		const { NextToken, Entries } = response;
+
+		const results: ListGeofenceResults = {
+			entries: Entries.map(
+				({
+					GeofenceId,
+					CreateTime,
+					UpdateTime,
+					Status,
+					Geometry: { Polygon },
+				}) => {
+					return {
+						geofenceId: GeofenceId,
+						createTime: CreateTime,
+						updateTime: UpdateTime,
+						status: Status,
+						geometry: {
+							polygon: Polygon as GeofencePolygon,
+						},
+					};
+				}
+			),
+			nextToken: NextToken,
+		};
 
 		return results;
 	}
 
+	/**
+	 * Delete geofences from a geofence collection
+	 * @param geofenceIds: string|string[]
+	 * @param options?: GeofenceOptions
+	 * @returns {Promise<DeleteGeofencesResults>} - Promise that resolves to an object with:
+	 *  successes: list of geofences successfully deleted
+	 *  errors: list of geofences that failed to delete
+	 */
+	public async deleteGeofences(
+		geofenceIds: string[],
+		options?: AmazonLocationServiceGeofenceOptions
+	): Promise<AmazonLocationServiceDeleteGeofencesResults> {
+		if (geofenceIds.length < 1) {
+			throw new Error('GeofenceId input array is empty');
+		}
+
+		const credentialsOK = await this._ensureCredentials();
+		if (!credentialsOK) {
+			throw new Error('No credentials');
+		}
+
+		this._verifyGeofenceCollections(options?.collectionName);
+
+		// Validate all geofenceIds are valid
+		const badGeofenceIds = geofenceIds.filter(geofenceId => {
+			try {
+				validateGeofenceId(geofenceId);
+			} catch (error) {
+				return true;
+			}
+		});
+		if (badGeofenceIds.length > 0) {
+			throw new Error(`Invalid geofence ids: ${badGeofenceIds.join(', ')}`);
+		}
+
+		const results: AmazonLocationServiceDeleteGeofencesResults = {
+			successes: [],
+			errors: [],
+		};
+
+		const geofenceIdBatches: string[][] = [];
+
+		let count = 0;
+		while (count < geofenceIds.length) {
+			geofenceIdBatches.push(geofenceIds.slice(count, (count += 10)));
+		}
+
+		await Promise.all(
+			geofenceIdBatches.map(async batch => {
+				let response;
+				try {
+					response = await this._AmazonLocationServiceBatchDeleteGeofenceCall(
+						batch,
+						options?.collectionName || this._config.geofenceCollections.default
+					);
+				} catch (error) {
+					// If the API call fails, add the geofences to the errors array and move to next batch
+					batch.forEach(geofenceId => {
+						const errorObject = {
+							geofenceId,
+							error: {
+								code: error.message,
+								message: error.message,
+							},
+						};
+						results.errors.push(errorObject);
+					});
+					return;
+				}
+
+				const badGeofenceIds = response.Errors.map(
+					({ geofenceId }) => geofenceId
+				);
+				results.successes.push(
+					...batch.filter(Id => !badGeofenceIds.includes(Id))
+				);
+			})
+		);
+		return results;
+	}
+
 	/**
 	 * @private
 	 */
@@ -345,7 +625,7 @@ export class AmazonLocationServiceProvider implements GeoProvider {
 			this._config.credentials = cred;
 			return true;
 		} catch (error) {
-			logger.warn('Ensure credentials error. Credentials are:', error);
+			logger.debug('Ensure credentials error. Credentials are:', error);
 			return false;
 		}
 	}
@@ -353,14 +633,14 @@ export class AmazonLocationServiceProvider implements GeoProvider {
 	private _verifyMapResources() {
 		if (!this._config.maps) {
 			const errorString =
-				"No map resources found in amplify config, run 'amplify add geo' to create them and run `amplify push` after";
-			logger.warn(errorString);
+				"No map resources found in amplify config, run 'amplify add geo' to create one and run `amplify push` after";
+			logger.debug(errorString);
 			throw new Error(errorString);
 		}
 		if (!this._config.maps.default) {
 			const errorString =
 				"No default map resource found in amplify config, run 'amplify add geo' to create one and run `amplify push` after";
-			logger.warn(errorString);
+			logger.debug(errorString);
 			throw new Error(errorString);
 		}
 	}
@@ -371,9 +651,76 @@ export class AmazonLocationServiceProvider implements GeoProvider {
 			!optionalSearchIndex
 		) {
 			const errorString =
-				'No Search Index found, please run `amplify add geo` to add one and run `amplify push` after.';
-			logger.warn(errorString);
+				'No Search Index found in amplify config, please run `amplify add geo` to create one and run `amplify push` after.';
+			logger.debug(errorString);
 			throw new Error(errorString);
 		}
 	}
+
+	private _verifyGeofenceCollections(optionalGeofenceCollectionName?: string) {
+		if (
+			(!this._config.geofenceCollections ||
+				!this._config.geofenceCollections.default) &&
+			!optionalGeofenceCollectionName
+		) {
+			const errorString =
+				'No Geofence Collections found, please run `amplify add geo` to create one and run `amplify push` after.';
+			logger.debug(errorString);
+			throw new Error(errorString);
+		}
+	}
+
+	private async _AmazonLocationServiceBatchPutGeofenceCall(
+		PascalGeofences: BatchPutGeofenceRequestEntry[],
+		collectionName?: string
+	) {
+		// Create the BatchPutGeofence input
+		const geofenceInput: BatchPutGeofenceCommandInput = {
+			Entries: PascalGeofences,
+			CollectionName:
+				collectionName || this._config.geofenceCollections.default,
+		};
+
+		const client = new LocationClient({
+			credentials: this._config.credentials,
+			region: this._config.region,
+			customUserAgent: getAmplifyUserAgent(),
+		});
+		const command = new BatchPutGeofenceCommand(geofenceInput);
+
+		let response: BatchPutGeofenceCommandOutput;
+		try {
+			response = await client.send(command);
+		} catch (error) {
+			throw error;
+		}
+		return response;
+	}
+
+	private async _AmazonLocationServiceBatchDeleteGeofenceCall(
+		geofenceIds: string[],
+		collectionName?: string
+	): Promise<BatchDeleteGeofenceCommandOutput> {
+		// Create the BatchDeleteGeofence input
+		const deleteGeofencesInput: BatchDeleteGeofenceCommandInput = {
+			GeofenceIds: geofenceIds,
+			CollectionName:
+				collectionName || this._config.geofenceCollections.default,
+		};
+
+		const client = new LocationClient({
+			credentials: this._config.credentials,
+			region: this._config.region,
+			customUserAgent: getAmplifyUserAgent(),
+		});
+		const command = new BatchDeleteGeofenceCommand(deleteGeofencesInput);
+
+		let response: BatchDeleteGeofenceCommandOutput;
+		try {
+			response = await client.send(command);
+		} catch (error) {
+			throw error;
+		}
+		return response;
+	}
 }

package/src/types/AmazonLocationServiceProvider.ts

@@ -1,5 +1,60 @@
-import { MapStyle } from './Geo';
+import {
+	MapStyle,
+	GeofenceOptions,
+	ListGeofenceOptions,
+	Geofence,
+	DeleteGeofencesResults,
+	GeofenceError,
+} from './Geo';
 
+// Maps
 export interface AmazonLocationServiceMapStyle extends MapStyle {
 	region: string;
 }
+
+// Geofences
+export type AmazonLocationServiceGeofenceOptions = GeofenceOptions & {
+	collectionName?: string;
+};
+
+// Status types for Geofences
+export type AmazonLocationServiceGeofenceStatus =
+	| 'ACTIVE'
+	| 'PENDING'
+	| 'FAILED'
+	| 'DELETED'
+	| 'DELETING';
+
+export type AmazonLocationServiceGeofence = Omit<Geofence, 'status'> & {
+	status: AmazonLocationServiceGeofenceStatus;
+};
+
+// List Geofences
+export type AmazonLocationServiceListGeofenceOptions = ListGeofenceOptions & {
+	collectionName?: string;
+};
+
+// Delete Geofences
+export type AmazonLocationServiceBatchGeofenceErrorMessages =
+	| 'AccessDeniedException'
+	| 'InternalServerException'
+	| 'ResourceNotFoundException'
+	| 'ThrottlingException'
+	| 'ValidationException';
+
+export type AmazonLocationServiceBatchGeofenceError = Omit<
+	GeofenceError,
+	'error'
+> & {
+	error: {
+		code: string;
+		message: AmazonLocationServiceBatchGeofenceErrorMessages;
+	};
+};
+
+export type AmazonLocationServiceDeleteGeofencesResults = Omit<
+	DeleteGeofencesResults,
+	'errors'
+> & {
+	errors: AmazonLocationServiceBatchGeofenceError[];
+};