@aws-amplify/geo 1.2.5-unstable.7 → 1.3.0

package/src/Providers/AmazonLocationServiceProvider.ts

@@ -11,6 +11,7 @@
  * and limitations under the License.
  */
 import camelcaseKeys from 'camelcase-keys';
+
 import {
 	ConsoleLogger as Logger,
 	Credentials,
@@ -23,8 +24,23 @@ import {
 	SearchPlaceIndexForTextCommand,
 	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,
@@ -33,6 +49,16 @@ import {
 	Place,
 	AmazonLocationServiceMapStyle,
 	Coordinates,
+	GeofenceId,
+	GeofenceInput,
+	AmazonLocationServiceGeofenceOptions,
+	AmazonLocationServiceListGeofenceOptions,
+	ListGeofenceResults,
+	AmazonLocationServiceGeofenceStatus,
+	SaveGeofencesResults,
+	AmazonLocationServiceGeofence,
+	GeofencePolygon,
+	AmazonLocationServiceDeleteGeofencesResults,
 } from '../types';
 
 const logger = new Logger('AmazonLocationServiceProvider');
@@ -254,6 +280,339 @@ export class AmazonLocationServiceProvider implements GeoProvider {
 		return results;
 	}
 
+	/**
+	 * 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 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');
+		}
+
+		// Verify geofence collection exists in aws-config.js
+		try {
+			this._verifyGeofenceCollections(options?.collectionName);
+		} catch (error) {
+			logger.debug(error);
+			throw error;
+		}
+
+		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: [],
+		};
+
+		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(),
+		});
+
+		// 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
+		);
+
+		// Make API call
+		let response: ListGeofencesCommandOutput;
+		try {
+			response = await client.send(command);
+		} catch (error) {
+			logger.debug(error);
+			throw error;
+		}
+
+		// 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
 	 */
@@ -266,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;
 		}
 	}
@@ -274,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);
 		}
 	}
@@ -292,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[];
+};

package/src/types/Geo.ts

@@ -22,6 +22,10 @@ export interface GeoConfig {
 			items: string[];
 			default: string;
 		};
+		geofenceCollections?: {
+			items: string[];
+			default: string;
+		};
 	};
 }
 
@@ -31,10 +35,10 @@ export interface MapStyle {
 	style: string;
 }
 
-export type Latitude = number;
 export type Longitude = number;
+export type Latitude = number;
 
-// Coordinate point
+// Coordinates are a tuple of longitude and latitude
 export type Coordinates = [Longitude, Latitude];
 
 // SW Longitude point for bounding box
@@ -73,6 +77,7 @@ export type SearchByTextOptions =
 	| SearchByTextOptionsWithBiasPosition
 	| SearchByTextOptionsWithSearchAreaConstraints;
 
+// Options object for searchByCoordinates
 export type SearchByCoordinatesOptions = {
 	maxResults?: number;
 	searchIndexName?: string;
@@ -97,3 +102,70 @@ export interface Place {
 	street?: string;
 	subRegion?: string;
 }
+// Array of 4 or more coordinates, where the first and last coordinate are the same to form a closed boundary
+export type LinearRing = Coordinates[];
+
+// An array of one linear ring
+export type GeofencePolygon = LinearRing[];
+
+// Geometry object for Polygon
+export type PolygonGeometry = {
+	polygon: GeofencePolygon;
+};
+
+export type GeofenceId = string;
+
+// Geofence object used as input for saveGeofences
+export type GeofenceInput = {
+	geofenceId: GeofenceId;
+	geometry: PolygonGeometry;
+};
+
+// Options object for saveGeofences
+export type GeofenceOptions = {
+	providerName?: string;
+};
+
+// Error type for errors related to Geofence API calls
+export type GeofenceError = {
+	error: {
+		code: string;
+		message: string;
+	};
+	geofenceId: GeofenceId;
+};
+
+// Base geofence object
+type GeofenceBase = {
+	geofenceId: GeofenceId;
+	createTime?: Date;
+	updateTime?: Date;
+};
+
+// Results object for getGeofence
+export type Geofence = GeofenceBase & {
+	geometry: PolygonGeometry;
+};
+
+// Results object for saveGeofences
+export type SaveGeofencesResults = {
+	successes: GeofenceBase[];
+	errors: GeofenceError[];
+};
+
+// Options object for listGeofence
+export type ListGeofenceOptions = GeofenceOptions & {
+	nextToken?: string;
+};
+
+// Results options for listGeofence
+export type ListGeofenceResults = {
+	entries: Geofence[];
+	nextToken: string | undefined;
+};
+
+// Results object for deleteGeofence
+export type DeleteGeofencesResults = {
+	successes: GeofenceId[];
+	errors: GeofenceError[];
+};

package/src/types/Provider.ts

@@ -10,13 +10,20 @@
  * CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions
  * and limitations under the License.
  */
-
 import {
 	SearchByTextOptions,
 	SearchByCoordinatesOptions,
 	Coordinates,
 	Place,
 	MapStyle,
+	Geofence,
+	GeofenceId,
+	GeofenceInput,
+	GeofenceOptions,
+	ListGeofenceOptions,
+	ListGeofenceResults,
+	SaveGeofencesResults,
+	DeleteGeofencesResults,
 } from './Geo';
 
 export interface GeoProvider {
@@ -35,10 +42,33 @@ export interface GeoProvider {
 	// get the map resource listed as default
 	getDefaultMap(): MapStyle;
 
+	// search by a text string and return a list of places
 	searchByText(text: string, options?: SearchByTextOptions): Promise<Place[]>;
 
+	// search by coordinates and return a matching place
 	searchByCoordinates(
 		coordinates: Coordinates,
 		options?: SearchByCoordinatesOptions
 	): Promise<Place>;
+
+	// create geofences
+	saveGeofences(
+		geofences: GeofenceInput[],
+		options?: GeofenceOptions
+	): Promise<SaveGeofencesResults>;
+
+	// get a single geofence
+	getGeofence(
+		geofenceId: GeofenceId,
+		options?: ListGeofenceOptions
+	): Promise<Geofence>;
+
+	// list all geofences
+	listGeofences(options?: ListGeofenceOptions): Promise<ListGeofenceResults>;
+
+	// Delete geofences
+	deleteGeofences(
+		geofenceIds: string[],
+		options?: GeofenceOptions
+	): Promise<DeleteGeofencesResults>;
 }