feat(geo): add AWSLocationGeoPlugin (#1453)

* feat(geo): Adds AWSLocationGeoPlugin with support for maps and search capabilities.

Author: ameter

Amplify.xcodeproj/project.pbxproj

@@ -52,16 +52,14 @@ extension GeoCategory: GeoCategoryBehavior {
     // MARK: - Maps
 
     /// Retrieves metadata for available Map resources.
-    /// - Parameter completionHandler: The completion handler receives a Response
-    /// object.  The success case provides an array of available Map resources.
+    /// - Returns: Metadata for all available map resources.
     public func getAvailableMaps() -> [Geo.MapStyle] {
         plugin.getAvailableMaps()
     }
 
     /// Retrieves the default Map resource.
-    /// - Parameter completionHandler: The completion handler receives a Response
-    /// object.  The success case provides an array of available Map resources.
-    public func getDefaultMap() -> Geo.MapStyle {
+    /// - Returns: Metadata for the default map resource.
+    public func getDefaultMap() -> Geo.MapStyle? {
         plugin.getDefaultMap()
     }
 }

Amplify/Categories/Geo/GeoCategory+ClientBehavior.swift

@@ -44,12 +44,10 @@ public protocol GeoCategoryBehavior {
     // MARK: - Maps
 
     /// Retrieves metadata for available Map resources.
-    /// - Parameter completionHandler: The completion handler receives a Response
-    /// object.  The success case provides an array of available Map resources.
+    /// - Returns: Metadata for all available map resources.
     func getAvailableMaps() -> [Geo.MapStyle]
 
     /// Retrieves the default Map resource (first map in amplifyconfiguration.json).
-    /// - Parameter completionHandler: The completion handler receives a Response
-    /// object.  The success case provides an array of available Map resources.
-    func getDefaultMap() -> Geo.MapStyle
+    /// - Returns: Metadata for the default map resource.
+    func getDefaultMap() -> Geo.MapStyle?
 }

Amplify/Categories/Geo/GeoCategoryBehavior.swift

@@ -9,7 +9,7 @@ import Foundation
 
 public extension Geo {
     /// Identifies the name and style for a map resource.
-    struct MapStyle {
+    struct MapStyle: Equatable {
         /// The name of the map resource.
         public let mapName: String
         /// The map style selected from an available provider.

Amplify/Categories/Geo/Types/Geo+MapStyle.swift

@@ -55,6 +55,11 @@ Pod::Spec.new do |s|
     ss.dependency 'SQLite.swift', '0.12.2'
   end
 
+  s.subspec 'AWSLocationGeoPlugin' do |ss|
+    ss.source_files = 'AmplifyPlugins/Geo/AWSLocationGeoPlugin/**/*.swift'
+    ss.dependency 'AWSLocation', $OPTIMISTIC_AWS_SDK_VERSION
+  end
+
   s.subspec 'AWSPinpointAnalyticsPlugin' do |ss|
     ss.source_files = 'AmplifyPlugins/Analytics/AWSPinpointAnalyticsPlugin/**/*.swift'
     ss.dependency 'AWSPinpoint', $OPTIMISTIC_AWS_SDK_VERSION

AmplifyPlugins.podspec

@@ -0,0 +1,161 @@
+//
+// Copyright Amazon.com Inc. or its affiliates.
+// All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Amplify
+import Foundation
+
+#if COCOAPODS
+import AWSLocation
+#else
+import AWSLocationXCF
+#endif
+
+extension AWSLocationGeoPlugin {
+
+    // MARK: - Search
+
+    /// Search for places or points of interest.
+    /// - Parameters:
+    ///   - text: The place name or address to be used in the search. (case insensitive)
+    ///   - area: The area (.near or .boundingBox) for the search. (optional)
+    ///   - countries: Limits the search to the given a list of countries/regions. (optional)
+    ///   - maxResults: The maximum number of results returned per request. (optional)
+    ///   - placeIndexName: The name of the Place Index to query. (optional)
+    ///   - completionHandler: The completion handler receives a Response object.  The
+    ///   success case provides a Place array.
+    public func search(for text: String,
+                       area: Geo.SearchArea? = nil,
+                       countries: [Geo.Country]? = nil,
+                       maxResults: Int? = nil,
+                       placeIndexName: String? = nil,
+                       completionHandler: @escaping Geo.ResultsHandler<[Geo.Place]>) {
+
+        assert(pluginConfig.defaultSearchIndex != nil, GeoPluginConfigError.searchConfigMissing)
+
+        let request = AWSLocationSearchPlaceIndexForTextRequest()!
+        request.indexName = placeIndexName ?? pluginConfig.defaultSearchIndex
+        request.text = text
+
+        if let area = area {
+            switch area {
+            case .near(let coordinates):
+                request.biasPosition = [coordinates.longitude as NSNumber,
+                                        coordinates.latitude as NSNumber]
+            case .within(let boundingBox):
+                request.filterBBox = [boundingBox.southwest.longitude as NSNumber,
+                                      boundingBox.southwest.latitude as NSNumber,
+                                      boundingBox.northeast.longitude as NSNumber,
+                                      boundingBox.northeast.latitude as NSNumber]
+            }
+        }
+
+        if let countries = countries {
+            request.filterCountries = countries.map { country in
+                String(describing: country)
+            }
+        }
+
+        if let maxResults = maxResults {
+            request.maxResults = maxResults as NSNumber
+        }
+
+        locationService.searchPlaceIndex(forText: request) { response, error in
+            completionHandler(AWSLocationGeoPlugin.parsePlaceResponse(response: response, error: error))
+        }
+    }
+
+    /// Reverse geocodes a given pair of coordinates and returns a list of Places
+    /// closest to the specified position.
+    /// - Parameters:
+    ///   - coordinates: Specifies a coordinate for the query.
+    ///   - maxResults: The maximum number of results returned per request. (optional)
+    ///   - placeIndexName: The name of the Place Index to query. (optional)
+    ///   - completionHandler: The completion handler receives a Response object.  The
+    ///   success case provides a Place array.
+    public func search(for coordinates: Geo.Coordinates,
+                       maxResults: Int? = nil,
+                       placeIndexName: String? = nil,
+                       completionHandler: @escaping Geo.ResultsHandler<[Geo.Place]>) {
+
+        assert(pluginConfig.defaultSearchIndex != nil, GeoPluginConfigError.searchConfigMissing)
+
+        let request = AWSLocationSearchPlaceIndexForPositionRequest()!
+        request.indexName = placeIndexName ?? pluginConfig.defaultSearchIndex
+        request.position = [coordinates.longitude as NSNumber,
+                            coordinates.latitude as NSNumber]
+
+        if let maxResults = maxResults {
+            request.maxResults = maxResults as NSNumber
+        }
+
+        locationService.searchPlaceIndex(forPosition: request) { response, error in
+            completionHandler(AWSLocationGeoPlugin.parsePlaceResponse(response: response, error: error))
+        }
+    }
+
+    static private func parsePlaceResponse(response: AWSModel?, error: Error?) -> Result<[Geo.Place], Error> {
+        if let error = error {
+            return .failure(error)
+        }
+
+        var results = [AWSLocationPlace]()
+
+        if let responseResults = (response as? AWSLocationSearchPlaceIndexForTextResponse)?.results {
+            results = responseResults.compactMap {
+                $0.place
+            }
+        }
+
+        if let responseResults = (response as? AWSLocationSearchPlaceIndexForPositionResponse)?.results {
+            results = responseResults.compactMap {
+                $0.place
+            }
+        }
+
+        let places: [Geo.Place] = results.compactMap {
+            guard let long = $0.geometry?.point?.first as? Double,
+                  let lat = $0.geometry?.point?.last as? Double
+            else {
+                return nil
+            }
+
+            return Geo.Place(coordinates: Geo.Coordinates(latitude: lat, longitude: long),
+                             label: $0.label,
+                             addressNumber: $0.addressNumber,
+                             street: $0.street,
+                             municipality: $0.municipality,
+                             region: $0.region,
+                             subRegion: $0.subRegion,
+                             postalCode: $0.postalCode,
+                             country: $0.country)
+        }
+
+        return .success(places)
+    }
+
+    // MARK: - Maps
+
+    /// Retrieves metadata for available map resources.
+    /// - Returns: Metadata for all available map resources.
+    public func getAvailableMaps()  -> [Geo.MapStyle] {
+        let mapStyles = Array(pluginConfig.maps.values)
+        assert(!mapStyles.isEmpty, GeoPluginConfigError.mapConfigMissing)
+
+        return mapStyles
+    }
+
+    /// Retrieves the default map resource.
+    /// - Returns: Metadata for the default map resource.
+    public func getDefaultMap() -> Geo.MapStyle? {
+        guard let mapName = pluginConfig.defaultMap, let mapStyle = pluginConfig.maps[mapName] else {
+            assertionFailure(GeoPluginConfigError.mapConfigMissing)
+            return nil
+        }
+
+        return mapStyle
+    }
+}

AmplifyPlugins/Geo/AWSLocationGeoPlugin/AWSLocationGeoPlugin+ClientBehavior.swift

@@ -0,0 +1,67 @@
+//
+// Copyright Amazon.com Inc. or its affiliates.
+// All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Amplify
+import AWSPluginsCore
+import Foundation
+
+#if COCOAPODS
+import AWSLocation
+#else
+import AWSLocationXCF
+#endif
+
+extension AWSLocationGeoPlugin {
+    /// Configures AWSLocationPlugin with the specified configuration.
+    ///
+    /// This method will be invoked as part of the Amplify configuration flow.
+    ///
+    /// - Parameter configuration: The configuration specified for this plugin.
+    /// - Throws:
+    ///   - PluginError.pluginConfigurationError: If one of the configuration values is invalid or empty.
+    public func configure(using configuration: Any?) throws {
+        let pluginConfiguration = try AWSLocationGeoPluginConfiguration(config: configuration)
+        try configure(using: pluginConfiguration)
+    }
+
+    /// Configure AWSLocationPlugin programatically using AWSLocationPluginConfiguration
+    public func configure(using configuration: AWSLocationGeoPluginConfiguration) throws {
+        let authService = AWSAuthService()
+        let credentialsProvider = authService.getCredentialsProvider()
+        let region = configuration.region
+
+        let serviceConfiguration = AmplifyAWSServiceConfiguration(region: region,
+                                                                  credentialsProvider: credentialsProvider)
+        AWSLocation.register(with: serviceConfiguration,
+                             forKey: key)
+
+        let location = AWSLocation(forKey: key)
+        let locationService = AWSLocationAdapter(location: location)
+
+        configure(locationService: locationService,
+                  authService: authService,
+                  pluginConfig: configuration)
+    }
+
+    // MARK: - Internal
+
+    /// Internal configure method to set the properties of the plugin
+    ///
+    /// Called from the configure method which implements the Plugin protocol. Useful for testing by passing in mocks.
+    ///
+    /// - Parameters:
+    ///   - locationService: The location service object.
+    ///   - authService: The authentication service object.
+    ///   - pluginConfig: The configuration for the plugin.
+    func configure(locationService: AWSLocationBehavior,
+                   authService: AWSAuthServiceBehavior,
+                   pluginConfig: AWSLocationGeoPluginConfiguration) {
+        self.locationService = locationService
+        self.authService = authService
+        self.pluginConfig = pluginConfig
+    }
+}

AmplifyPlugins/Geo/AWSLocationGeoPlugin/AWSLocationGeoPlugin+Configure.swift

@@ -0,0 +1,10 @@
+//
+// Copyright Amazon.com Inc. or its affiliates.
+// All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Amplify
+
+extension AWSLocationGeoPlugin: DefaultLogger {}

AmplifyPlugins/Geo/AWSLocationGeoPlugin/AWSLocationGeoPlugin+DefaultLogger.swift

@@ -0,0 +1,24 @@
+//
+// Copyright Amazon.com Inc. or its affiliates.
+// All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Amplify
+import Foundation
+
+extension AWSLocationGeoPlugin {
+
+    /// Resets the state of the plugin.
+    ///
+    /// Sets stored objects to nil to allow deallocation, then calls onComplete closure
+    /// to signal the reset has completed.
+    public func reset(onComplete: @escaping (() -> Void)) {
+        locationService = nil
+        authService = nil
+        pluginConfig = nil
+
+        onComplete()
+    }
+}

AmplifyPlugins/Geo/AWSLocationGeoPlugin/AWSLocationGeoPlugin+Reset.swift

@@ -0,0 +1,44 @@
+//
+// Copyright Amazon.com Inc. or its affiliates.
+// All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Amplify
+import AWSPluginsCore
+import Foundation
+
+#if COCOAPODS
+import AWSLocation
+#else
+import AWSLocationXCF
+#endif
+
+/// The AWSLocationPlugin implements the Geo APIs for Amazon Location
+public final class AWSLocationGeoPlugin: GeoCategoryPlugin {
+    /// An instance of the AWS Location service
+    var locationService: AWSLocationBehavior!
+
+    /// An instance of the authentication service
+    public var authService: AWSAuthServiceBehavior!
+
+    /// A holder for the plugin configuration. This will be populated during the
+    /// configuration phase, and is clearable by `reset()`.
+    public var pluginConfig: AWSLocationGeoPluginConfiguration!
+
+    /// The unique key of the plugin within the location category
+    public let key: PluginKey = "awsLocationGeoPlugin"
+
+    /// Instantiates an instance of the AWSLocationPlugin
+    public init() {}
+
+    /// Retrieve the escape hatch to perform actions directly on AWSLocation.
+    ///
+    /// - Returns: AWSLocation instance
+    public func getEscapeHatch() -> AWSLocation {
+        locationService.getEscapeHatch()
+    }
+}
+
+extension AWSLocationGeoPlugin: AmplifyVersionable { }