@capawesome/capacitor-maps-launcher 0.0.1

package/android/src/main/java/io/capawesome/capacitorjs/plugins/mapslauncher/MapsLauncherPlugin.java

@@ -0,0 +1,117 @@
+package io.capawesome.capacitorjs.plugins.mapslauncher;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+import com.getcapacitor.Logger;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+import io.capawesome.capacitorjs.plugins.mapslauncher.classes.CustomException;
+import io.capawesome.capacitorjs.plugins.mapslauncher.classes.options.NavigateOptions;
+import io.capawesome.capacitorjs.plugins.mapslauncher.classes.results.GetAvailableAppsResult;
+import io.capawesome.capacitorjs.plugins.mapslauncher.classes.results.GetDefaultAppResult;
+import io.capawesome.capacitorjs.plugins.mapslauncher.interfaces.EmptyCallback;
+import io.capawesome.capacitorjs.plugins.mapslauncher.interfaces.NonEmptyResultCallback;
+import io.capawesome.capacitorjs.plugins.mapslauncher.interfaces.Result;
+
+@CapacitorPlugin(name = "MapsLauncher")
+public class MapsLauncherPlugin extends Plugin {
+
+    public static final String ERROR_UNKNOWN_ERROR = "An unknown error has occurred.";
+    public static final String TAG = "MapsLauncherPlugin";
+
+    private MapsLauncher implementation;
+
+    @Override
+    public void load() {
+        super.load();
+        this.implementation = new MapsLauncher(this);
+    }
+
+    @PluginMethod
+    public void getAvailableApps(PluginCall call) {
+        try {
+            NonEmptyResultCallback<GetAvailableAppsResult> callback = new NonEmptyResultCallback<>() {
+                @Override
+                public void success(@NonNull GetAvailableAppsResult result) {
+                    resolveCall(call, result);
+                }
+
+                @Override
+                public void error(Exception exception) {
+                    rejectCall(call, exception);
+                }
+            };
+            implementation.getAvailableApps(callback);
+        } catch (Exception exception) {
+            rejectCall(call, exception);
+        }
+    }
+
+    @PluginMethod
+    public void getDefaultApp(PluginCall call) {
+        try {
+            NonEmptyResultCallback<GetDefaultAppResult> callback = new NonEmptyResultCallback<>() {
+                @Override
+                public void success(@NonNull GetDefaultAppResult result) {
+                    resolveCall(call, result);
+                }
+
+                @Override
+                public void error(Exception exception) {
+                    rejectCall(call, exception);
+                }
+            };
+            implementation.getDefaultApp(callback);
+        } catch (Exception exception) {
+            rejectCall(call, exception);
+        }
+    }
+
+    @PluginMethod
+    public void navigate(PluginCall call) {
+        try {
+            NavigateOptions options = new NavigateOptions(call);
+            EmptyCallback callback = new EmptyCallback() {
+                @Override
+                public void success() {
+                    resolveCall(call);
+                }
+
+                @Override
+                public void error(Exception exception) {
+                    rejectCall(call, exception);
+                }
+            };
+            implementation.navigate(options, callback);
+        } catch (Exception exception) {
+            rejectCall(call, exception);
+        }
+    }
+
+    private void rejectCall(@NonNull PluginCall call, @NonNull Exception exception) {
+        String message = exception.getMessage();
+        if (message == null) {
+            message = ERROR_UNKNOWN_ERROR;
+        }
+        String code = null;
+        if (exception instanceof CustomException) {
+            code = ((CustomException) exception).getCode();
+        }
+        Logger.error(TAG, message, exception);
+        call.reject(message, code);
+    }
+
+    private void resolveCall(@NonNull PluginCall call) {
+        call.resolve();
+    }
+
+    private void resolveCall(@NonNull PluginCall call, @Nullable Result result) {
+        if (result == null) {
+            call.resolve();
+        } else {
+            call.resolve(result.toJSObject());
+        }
+    }
+}

package/android/src/main/java/io/capawesome/capacitorjs/plugins/mapslauncher/classes/CustomException.java

@@ -0,0 +1,20 @@
+package io.capawesome.capacitorjs.plugins.mapslauncher.classes;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+
+public class CustomException extends Exception {
+
+    @Nullable
+    private final String code;
+
+    public CustomException(@Nullable String code, @NonNull String message) {
+        super(message);
+        this.code = code;
+    }
+
+    @Nullable
+    public String getCode() {
+        return code;
+    }
+}

package/android/src/main/java/io/capawesome/capacitorjs/plugins/mapslauncher/classes/CustomExceptions.java

@@ -0,0 +1,15 @@
+package io.capawesome.capacitorjs.plugins.mapslauncher.classes;
+
+public class CustomExceptions {
+
+    public static final CustomException APP_NOT_AVAILABLE = new CustomException(
+        "APP_NOT_AVAILABLE",
+        "The requested navigation app is not installed or cannot be launched."
+    );
+    public static final CustomException DESTINATION_INVALID = new CustomException(
+        null,
+        "destination must contain either coordinates or an address, but not both."
+    );
+    public static final CustomException DESTINATION_MISSING = new CustomException(null, "destination must be provided.");
+    public static final CustomException LAUNCH_FAILED = new CustomException("LAUNCH_FAILED", "The navigation app could not be launched.");
+}

package/android/src/main/java/io/capawesome/capacitorjs/plugins/mapslauncher/classes/options/Destination.java

@@ -0,0 +1,57 @@
+package io.capawesome.capacitorjs.plugins.mapslauncher.classes.options;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+import io.capawesome.capacitorjs.plugins.mapslauncher.classes.CustomExceptions;
+import org.json.JSONObject;
+
+public class Destination {
+
+    @Nullable
+    private final String address;
+
+    @Nullable
+    private final Double latitude;
+
+    @Nullable
+    private final Double longitude;
+
+    public Destination(@NonNull JSONObject object) throws Exception {
+        boolean hasLatitude = object.has("latitude") && !object.isNull("latitude");
+        boolean hasLongitude = object.has("longitude") && !object.isNull("longitude");
+        boolean hasCoordinates = hasLatitude && hasLongitude;
+        String addressValue = object.isNull("address") ? null : object.optString("address", null);
+        boolean hasAddress = addressValue != null && !addressValue.trim().isEmpty();
+        if (hasCoordinates == hasAddress) {
+            throw CustomExceptions.DESTINATION_INVALID;
+        }
+        if (hasCoordinates) {
+            this.latitude = object.getDouble("latitude");
+            this.longitude = object.getDouble("longitude");
+            this.address = null;
+        } else {
+            this.latitude = null;
+            this.longitude = null;
+            this.address = addressValue;
+        }
+    }
+
+    @Nullable
+    public String getAddress() {
+        return address;
+    }
+
+    @Nullable
+    public Double getLatitude() {
+        return latitude;
+    }
+
+    @Nullable
+    public Double getLongitude() {
+        return longitude;
+    }
+
+    public boolean hasCoordinates() {
+        return latitude != null && longitude != null;
+    }
+}

package/android/src/main/java/io/capawesome/capacitorjs/plugins/mapslauncher/classes/options/NavigateOptions.java

@@ -0,0 +1,54 @@
+package io.capawesome.capacitorjs.plugins.mapslauncher.classes.options;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+import com.getcapacitor.JSObject;
+import com.getcapacitor.PluginCall;
+import io.capawesome.capacitorjs.plugins.mapslauncher.classes.CustomExceptions;
+
+public class NavigateOptions {
+
+    @Nullable
+    private final String app;
+
+    @NonNull
+    private final Destination destination;
+
+    @Nullable
+    private final Destination start;
+
+    @Nullable
+    private final String travelMode;
+
+    public NavigateOptions(@NonNull PluginCall call) throws Exception {
+        JSObject destinationObject = call.getObject("destination");
+        if (destinationObject == null) {
+            throw CustomExceptions.DESTINATION_MISSING;
+        }
+        this.destination = new Destination(destinationObject);
+        JSObject startObject = call.getObject("start");
+        this.start = startObject == null ? null : new Destination(startObject);
+        this.app = call.getString("app");
+        this.travelMode = call.getString("travelMode");
+    }
+
+    @Nullable
+    public String getApp() {
+        return app;
+    }
+
+    @NonNull
+    public Destination getDestination() {
+        return destination;
+    }
+
+    @Nullable
+    public Destination getStart() {
+        return start;
+    }
+
+    @Nullable
+    public String getTravelMode() {
+        return travelMode;
+    }
+}

package/android/src/main/java/io/capawesome/capacitorjs/plugins/mapslauncher/classes/results/GetAvailableAppsResult.java

@@ -0,0 +1,29 @@
+package io.capawesome.capacitorjs.plugins.mapslauncher.classes.results;
+
+import androidx.annotation.NonNull;
+import com.getcapacitor.JSArray;
+import com.getcapacitor.JSObject;
+import io.capawesome.capacitorjs.plugins.mapslauncher.interfaces.Result;
+import java.util.List;
+
+public class GetAvailableAppsResult implements Result {
+
+    @NonNull
+    private final List<String> apps;
+
+    public GetAvailableAppsResult(@NonNull List<String> apps) {
+        this.apps = apps;
+    }
+
+    @Override
+    @NonNull
+    public JSObject toJSObject() {
+        JSArray appsArray = new JSArray();
+        for (String app : apps) {
+            appsArray.put(app);
+        }
+        JSObject result = new JSObject();
+        result.put("apps", appsArray);
+        return result;
+    }
+}

package/android/src/main/java/io/capawesome/capacitorjs/plugins/mapslauncher/classes/results/GetDefaultAppResult.java

@@ -0,0 +1,25 @@
+package io.capawesome.capacitorjs.plugins.mapslauncher.classes.results;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+import com.getcapacitor.JSObject;
+import io.capawesome.capacitorjs.plugins.mapslauncher.interfaces.Result;
+import org.json.JSONObject;
+
+public class GetDefaultAppResult implements Result {
+
+    @Nullable
+    private final String app;
+
+    public GetDefaultAppResult(@Nullable String app) {
+        this.app = app;
+    }
+
+    @Override
+    @NonNull
+    public JSObject toJSObject() {
+        JSObject result = new JSObject();
+        result.put("app", app == null ? JSONObject.NULL : app);
+        return result;
+    }
+}

package/android/src/main/java/io/capawesome/capacitorjs/plugins/mapslauncher/interfaces/Callback.java

@@ -0,0 +1,5 @@
+package io.capawesome.capacitorjs.plugins.mapslauncher.interfaces;
+
+public interface Callback {
+    void error(Exception exception);
+}

package/android/src/main/java/io/capawesome/capacitorjs/plugins/mapslauncher/interfaces/EmptyCallback.java

@@ -0,0 +1,5 @@
+package io.capawesome.capacitorjs.plugins.mapslauncher.interfaces;
+
+public interface EmptyCallback extends Callback {
+    void success();
+}

package/android/src/main/java/io/capawesome/capacitorjs/plugins/mapslauncher/interfaces/NonEmptyResultCallback.java

@@ -0,0 +1,7 @@
+package io.capawesome.capacitorjs.plugins.mapslauncher.interfaces;
+
+import androidx.annotation.NonNull;
+
+public interface NonEmptyResultCallback<T extends Result> extends Callback {
+    void success(@NonNull T result);
+}

package/android/src/main/java/io/capawesome/capacitorjs/plugins/mapslauncher/interfaces/Result.java

@@ -0,0 +1,7 @@
+package io.capawesome.capacitorjs.plugins.mapslauncher.interfaces;
+
+import com.getcapacitor.JSObject;
+
+public interface Result {
+    JSObject toJSObject();
+}

package/dist/docs.json

@@ -0,0 +1,329 @@
+{
+  "api": {
+    "name": "MapsLauncherPlugin",
+    "slug": "mapslauncherplugin",
+    "docs": "",
+    "tags": [],
+    "methods": [
+      {
+        "name": "getAvailableApps",
+        "signature": "() => Promise<GetAvailableAppsResult>",
+        "parameters": [],
+        "returns": "Promise<GetAvailableAppsResult>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "0.1.0"
+          }
+        ],
+        "docs": "Get the navigation apps that are installed and can be launched.\n\nOn iOS, Apple Maps is always included. Google Maps and Waze are only\nincluded if the corresponding `LSApplicationQueriesSchemes` entries are\nadded to the `Info.plist` file of your app.\n\nOnly available on Android and iOS.",
+        "complexTypes": [
+          "GetAvailableAppsResult"
+        ],
+        "slug": "getavailableapps"
+      },
+      {
+        "name": "getDefaultApp",
+        "signature": "() => Promise<GetDefaultAppResult>",
+        "parameters": [],
+        "returns": "Promise<GetDefaultAppResult>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "0.1.0"
+          }
+        ],
+        "docs": "Get the navigation app that is configured as the default handler for\nnavigation intents.\n\nReturns `null` if the default app is not part of the curated list of\nsupported apps or if no default app is set (i.e. the system shows a\nchooser).\n\nOnly available on Android.",
+        "complexTypes": [
+          "GetDefaultAppResult"
+        ],
+        "slug": "getdefaultapp"
+      },
+      {
+        "name": "navigate",
+        "signature": "(options: NavigateOptions) => Promise<void>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "",
+            "type": "NavigateOptions"
+          }
+        ],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "0.1.0"
+          }
+        ],
+        "docs": "Launch a navigation app with turn-by-turn directions to a destination.\n\nIf no `app` is provided, the system default behavior is used (a chooser on\nAndroid, Apple Maps on iOS).\n\nOnly available on Android and iOS.",
+        "complexTypes": [
+          "NavigateOptions"
+        ],
+        "slug": "navigate"
+      }
+    ],
+    "properties": []
+  },
+  "interfaces": [
+    {
+      "name": "GetAvailableAppsResult",
+      "slug": "getavailableappsresult",
+      "docs": "",
+      "tags": [
+        {
+          "text": "0.1.0",
+          "name": "since"
+        }
+      ],
+      "methods": [],
+      "properties": [
+        {
+          "name": "apps",
+          "tags": [
+            {
+              "text": "0.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The navigation apps that are installed and can be launched.",
+          "complexTypes": [
+            "NavigationApp"
+          ],
+          "type": "NavigationApp[]"
+        }
+      ]
+    },
+    {
+      "name": "GetDefaultAppResult",
+      "slug": "getdefaultappresult",
+      "docs": "",
+      "tags": [
+        {
+          "text": "0.1.0",
+          "name": "since"
+        }
+      ],
+      "methods": [],
+      "properties": [
+        {
+          "name": "app",
+          "tags": [
+            {
+              "text": "0.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The navigation app that is configured as the default handler.\n\nReturns `null` if the default app is not part of the curated list of\nsupported apps or if no default app is set.",
+          "complexTypes": [
+            "NavigationApp"
+          ],
+          "type": "NavigationApp | null"
+        }
+      ]
+    },
+    {
+      "name": "NavigateOptions",
+      "slug": "navigateoptions",
+      "docs": "",
+      "tags": [
+        {
+          "text": "0.1.0",
+          "name": "since"
+        }
+      ],
+      "methods": [],
+      "properties": [
+        {
+          "name": "app",
+          "tags": [
+            {
+              "text": "0.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The navigation app to launch.\n\nIf not provided, the system default behavior is used (a chooser on\nAndroid, Apple Maps on iOS).",
+          "complexTypes": [
+            "NavigationApp"
+          ],
+          "type": "NavigationApp"
+        },
+        {
+          "name": "destination",
+          "tags": [
+            {
+              "text": "0.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The destination to navigate to.",
+          "complexTypes": [
+            "Destination"
+          ],
+          "type": "Destination"
+        },
+        {
+          "name": "start",
+          "tags": [
+            {
+              "text": "0.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The start location of the route.\n\nIf not provided, the current location of the device is used.\n\n**Note**: The support depends on the selected app. Apple Maps supports it\nfully, Google Maps opens the directions preview instead of starting\nturn-by-turn navigation, and Waze ignores it.",
+          "complexTypes": [
+            "Destination"
+          ],
+          "type": "Destination"
+        },
+        {
+          "name": "travelMode",
+          "tags": [
+            {
+              "text": "'driving'",
+              "name": "default"
+            },
+            {
+              "text": "0.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The travel mode to use for the directions.\n\n**Note**: The support depends on the selected app and is best-effort.\nWaze only supports driving and ignores this option.",
+          "complexTypes": [
+            "TravelMode"
+          ],
+          "type": "TravelMode"
+        }
+      ]
+    },
+    {
+      "name": "Destination",
+      "slug": "destination",
+      "docs": "A destination is either defined by its coordinates or by its address, but\nnot both.",
+      "tags": [
+        {
+          "text": "0.1.0",
+          "name": "since"
+        }
+      ],
+      "methods": [],
+      "properties": [
+        {
+          "name": "address",
+          "tags": [
+            {
+              "text": "'Apple Park, Cupertino, CA'",
+              "name": "example"
+            },
+            {
+              "text": "0.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The address of the destination.\n\nMust be provided without `latitude` and `longitude`.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "latitude",
+          "tags": [
+            {
+              "text": "37.3349",
+              "name": "example"
+            },
+            {
+              "text": "0.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The latitude of the destination.\n\nMust be provided together with `longitude` and without `address`.",
+          "complexTypes": [],
+          "type": "number | undefined"
+        },
+        {
+          "name": "longitude",
+          "tags": [
+            {
+              "text": "-122.009",
+              "name": "example"
+            },
+            {
+              "text": "0.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The longitude of the destination.\n\nMust be provided together with `latitude` and without `address`.",
+          "complexTypes": [],
+          "type": "number | undefined"
+        }
+      ]
+    }
+  ],
+  "enums": [
+    {
+      "name": "NavigationApp",
+      "slug": "navigationapp",
+      "members": [
+        {
+          "name": "AppleMaps",
+          "value": "'appleMaps'",
+          "tags": [
+            {
+              "text": "0.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Apple Maps.\n\nOnly available on iOS."
+        },
+        {
+          "name": "GoogleMaps",
+          "value": "'googleMaps'",
+          "tags": [
+            {
+              "text": "0.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Google Maps."
+        },
+        {
+          "name": "Waze",
+          "value": "'waze'",
+          "tags": [
+            {
+              "text": "0.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Waze."
+        }
+      ]
+    }
+  ],
+  "typeAliases": [
+    {
+      "name": "TravelMode",
+      "slug": "travelmode",
+      "docs": "The travel mode to use for the directions.\n\n- `driving`: Driving directions.\n- `walking`: Walking directions.\n- `bicycling`: Bicycling directions.\n- `transit`: Public transit directions.",
+      "types": [
+        {
+          "text": "'driving'",
+          "complexTypes": []
+        },
+        {
+          "text": "'walking'",
+          "complexTypes": []
+        },
+        {
+          "text": "'bicycling'",
+          "complexTypes": []
+        },
+        {
+          "text": "'transit'",
+          "complexTypes": []
+        }
+      ]
+    }
+  ],
+  "pluginConfigs": []
+}