io.appium.settings 5.3.0 → 5.4.0

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+## [5.4.0](https://github.com/appium/io.appium.settings/compare/v5.3.1...v5.4.0) (2024-01-09)
+
+
+### Features
+
+* Add javascript wrappers over Settings App APIs ([#131](https://github.com/appium/io.appium.settings/issues/131)) ([bd56d5e](https://github.com/appium/io.appium.settings/commit/bd56d5ed958f243bb32c22197cf9526bfc6428f7))
+
+
+### Bug Fixes
+
+* Add missing packages ([#132](https://github.com/appium/io.appium.settings/issues/132)) ([7d3015a](https://github.com/appium/io.appium.settings/commit/7d3015a45c44e9cf7edd0ce2d918561571879ade))
+
+
+### Miscellaneous Chores
+
+* **deps:** bump org.apache.commons:commons-lang3 from 3.13.0 to 3.14.0 ([#130](https://github.com/appium/io.appium.settings/issues/130)) ([ae96723](https://github.com/appium/io.appium.settings/commit/ae96723d82f5f2436294bb74db0d4184fafe5c85))
+
+## [5.3.1](https://github.com/appium/io.appium.settings/compare/v5.3.0...v5.3.1) (2024-01-06)
+
+
+### Miscellaneous Chores
+
+* Bump Gradle version ([#129](https://github.com/appium/io.appium.settings/issues/129)) ([865c90f](https://github.com/appium/io.appium.settings/commit/865c90f65c0b5dfb2ff5dc89f0cc2c4b1bc9915d))
+
 ## [5.3.0](https://github.com/appium/io.appium.settings/compare/v5.2.0...v5.3.0) (2024-01-06)
 
 

package/build/lib/client.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @typedef {Object} SettingsAppOpts
+ * @property {import('appium-adb').ADB} adb
+ */
+export class SettingsApp {
+    /**
+     * @param {SettingsAppOpts} opts
+     */
+    constructor(opts: SettingsAppOpts);
+    /** @type {import('appium-adb').ADB} */
+    adb: import('appium-adb').ADB;
+    /** @type {import('npmlog').Logger} */
+    log: import('npmlog').Logger;
+    /**
+     * @typedef {Object} SettingsAppStartupOptions
+     * @property {number} [timeout=5000] The maximum number of milliseconds
+     * to wait until the app has started
+     * @property {boolean} [shouldRestoreCurrentApp=false] Whether to restore
+     * the activity which was the current one before Settings startup
+     */
+    /**
+     * Ensures that Appium Settings helper application is running
+     * and starts it if necessary
+     *
+     * @param {SettingsAppStartupOptions} [opts={}]
+     * @throws {Error} If Appium Settings has failed to start
+     * @returns {Promise<SettingsApp>} self instance for chaining
+     */
+    requireRunning(opts?: {
+        /**
+         * The maximum number of milliseconds
+         * to wait until the app has started
+         */
+        timeout?: number | undefined;
+        /**
+         * Whether to restore
+         * the activity which was the current one before Settings startup
+         */
+        shouldRestoreCurrentApp?: boolean | undefined;
+    } | undefined): Promise<SettingsApp>;
+    /**
+     * Parses the output in JSON format retrieved from
+     * the corresponding Appium Settings broadcast calls
+     *
+     * @param {string} output The actual command output
+     * @param {string} entityName The name of the entity which is
+     * going to be parsed
+     * @returns {Object} The parsed JSON object
+     * @throws {Error} If the output cannot be parsed
+     * as a valid JSON
+     */
+    _parseJsonData(output: string, entityName: string): any;
+    setAnimationState: typeof setAnimationState;
+    getClipboard: typeof getClipboard;
+    setGeoLocation: typeof setGeoLocation;
+    getGeoLocation: typeof getGeoLocation;
+    refreshGeoLocationCache: typeof refreshGeoLocationCache;
+    setDeviceSysLocale: typeof setDeviceSysLocale;
+    scanMedia: typeof scanMedia;
+    setDataState: typeof setDataState;
+    setWifiState: typeof setWifiState;
+    getNotifications: typeof getNotifications;
+    getSmsList: typeof getSmsList;
+    performEditorAction: typeof performEditorAction;
+    typeUnicode: typeof typeUnicode;
+}
+export type SettingsAppOpts = {
+    adb: import('appium-adb').ADB;
+};
+import { setAnimationState } from './commands/animation';
+import { getClipboard } from './commands/clipboard';
+import { setGeoLocation } from './commands/geolocation';
+import { getGeoLocation } from './commands/geolocation';
+import { refreshGeoLocationCache } from './commands/geolocation';
+import { setDeviceSysLocale } from './commands/locale';
+import { scanMedia } from './commands/media';
+import { setDataState } from './commands/network';
+import { setWifiState } from './commands/network';
+import { getNotifications } from './commands/notifications';
+import { getSmsList } from './commands/sms';
+import { performEditorAction } from './commands/typing';
+import { typeUnicode } from './commands/typing';
+//# sourceMappingURL=client.d.ts.map

package/build/lib/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../lib/client.js"],"names":[],"mappings":"AAcA;;;GAGG;AAGH;IAOE;;OAEG;IACH,kBAFW,eAAe,EAKzB;IAZD,uCAAuC;IACvC,KADW,OAAO,YAAY,EAAE,GAAG,CAC/B;IAEJ,sCAAsC;IACtC,KADW,OAAO,QAAQ,EAAE,MAAM,CAC9B;IAUJ;;;;;;OAMG;IAEH;;;;;;;OAOG;IACH;;;;;;;;;;;oBAFa,QAAQ,WAAW,CAAC,CA4ChC;IAED;;;;;;;;;;OAUG;IACH,uBAPW,MAAM,cACN,MAAM,OAgChB;IAED,4CAAsC;IAEtC,kCAA4B;IAE5B,sCAAgC;IAChC,sCAAgC;IAChC,wDAAkD;IAElD,8CAAwC;IAExC,4BAAsB;IAEtB,kCAA4B;IAC5B,kCAA4B;IAE5B,0CAAoC;IACpC,8BAAwB;IAExB,gDAA0C;IAC1C,gCAA0B;CAC3B;;SA1Ia,OAAO,YAAY,EAAE,GAAG;;kCAZJ,sBAAsB;6BAC3B,sBAAsB;+BACqB,wBAAwB;+BAAxB,wBAAwB;wCAAxB,wBAAwB;mCAC7D,mBAAmB;0BAC5B,kBAAkB;6BACD,oBAAoB;6BAApB,oBAAoB;iCAC9B,0BAA0B;2BAChC,gBAAgB;oCACM,mBAAmB;4BAAnB,mBAAmB"}

package/build/lib/client.js

@@ -0,0 +1,137 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SettingsApp = void 0;
+const logger_1 = require("./logger");
+const lodash_1 = __importDefault(require("lodash"));
+const asyncbox_1 = require("asyncbox");
+const constants_js_1 = require("./constants.js");
+const animation_1 = require("./commands/animation");
+const clipboard_1 = require("./commands/clipboard");
+const geolocation_1 = require("./commands/geolocation");
+const locale_1 = require("./commands/locale");
+const media_1 = require("./commands/media");
+const network_1 = require("./commands/network");
+const notifications_1 = require("./commands/notifications");
+const sms_1 = require("./commands/sms");
+const typing_1 = require("./commands/typing");
+/**
+ * @typedef {Object} SettingsAppOpts
+ * @property {import('appium-adb').ADB} adb
+ */
+class SettingsApp {
+    /**
+     * @param {SettingsAppOpts} opts
+     */
+    constructor(opts) {
+        this.setAnimationState = animation_1.setAnimationState;
+        this.getClipboard = clipboard_1.getClipboard;
+        this.setGeoLocation = geolocation_1.setGeoLocation;
+        this.getGeoLocation = geolocation_1.getGeoLocation;
+        this.refreshGeoLocationCache = geolocation_1.refreshGeoLocationCache;
+        this.setDeviceSysLocale = locale_1.setDeviceSysLocale;
+        this.scanMedia = media_1.scanMedia;
+        this.setDataState = network_1.setDataState;
+        this.setWifiState = network_1.setWifiState;
+        this.getNotifications = notifications_1.getNotifications;
+        this.getSmsList = sms_1.getSmsList;
+        this.performEditorAction = typing_1.performEditorAction;
+        this.typeUnicode = typing_1.typeUnicode;
+        this.adb = opts.adb;
+        this.log = logger_1.log;
+    }
+    /**
+     * @typedef {Object} SettingsAppStartupOptions
+     * @property {number} [timeout=5000] The maximum number of milliseconds
+     * to wait until the app has started
+     * @property {boolean} [shouldRestoreCurrentApp=false] Whether to restore
+     * the activity which was the current one before Settings startup
+     */
+    /**
+     * Ensures that Appium Settings helper application is running
+     * and starts it if necessary
+     *
+     * @param {SettingsAppStartupOptions} [opts={}]
+     * @throws {Error} If Appium Settings has failed to start
+     * @returns {Promise<SettingsApp>} self instance for chaining
+     */
+    async requireRunning(opts = {}) {
+        if (await this.adb.processExists(constants_js_1.SETTINGS_HELPER_ID)) {
+            return this;
+        }
+        this.log.debug(logger_1.LOG_PREFIX, 'Starting Appium Settings app');
+        const { timeout = 5000, shouldRestoreCurrentApp = false, } = opts;
+        let appPackage;
+        if (shouldRestoreCurrentApp) {
+            try {
+                ({ appPackage } = await this.adb.getFocusedPackageAndActivity());
+            }
+            catch (e) {
+                this.log.warn(logger_1.LOG_PREFIX, `The current application can not be restored: ${e.message}`);
+            }
+        }
+        await this.adb.startApp({
+            pkg: constants_js_1.SETTINGS_HELPER_ID,
+            activity: constants_js_1.SETTINGS_HELPER_MAIN_ACTIVITY,
+            action: 'android.intent.action.MAIN',
+            category: 'android.intent.category.LAUNCHER',
+            stopApp: false,
+            waitForLaunch: false,
+        });
+        try {
+            await (0, asyncbox_1.waitForCondition)(async () => await this.adb.processExists(constants_js_1.SETTINGS_HELPER_ID), {
+                waitMs: timeout,
+                intervalMs: 300,
+            });
+            if (shouldRestoreCurrentApp && appPackage) {
+                try {
+                    await this.adb.activateApp(appPackage);
+                }
+                catch (e) {
+                    logger_1.log.warn(`The current application can not be restored: ${e.message}`);
+                }
+            }
+            return this;
+        }
+        catch (err) {
+            throw new Error(`Appium Settings app is not running after ${timeout}ms`);
+        }
+    }
+    /**
+     * Parses the output in JSON format retrieved from
+     * the corresponding Appium Settings broadcast calls
+     *
+     * @param {string} output The actual command output
+     * @param {string} entityName The name of the entity which is
+     * going to be parsed
+     * @returns {Object} The parsed JSON object
+     * @throws {Error} If the output cannot be parsed
+     * as a valid JSON
+     */
+    _parseJsonData(output, entityName) {
+        if (!/\bresult=-1\b/.test(output) || !/\bdata="/.test(output)) {
+            this.log.debug(logger_1.LOG_PREFIX, output);
+            throw new Error(`Cannot retrieve ${entityName} from the device. ` +
+                'Check the server log for more details');
+        }
+        const match = /\bdata="(.+)",?/.exec(output);
+        if (!match) {
+            this.log.debug(logger_1.LOG_PREFIX, output);
+            throw new Error(`Cannot parse ${entityName} from the command output. ` +
+                'Check the server log for more details');
+        }
+        const jsonStr = lodash_1.default.trim(match[1]);
+        try {
+            return JSON.parse(jsonStr);
+        }
+        catch (e) {
+            logger_1.log.debug(jsonStr);
+            throw new Error(`Cannot parse ${entityName} from the resulting data string. ` +
+                'Check the server log for more details');
+        }
+    }
+}
+exports.SettingsApp = SettingsApp;
+//# sourceMappingURL=client.js.map

package/build/lib/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../lib/client.js"],"names":[],"mappings":"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"}

package/build/lib/commands/animation.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Change the state of animation on the device under test.
+ * Animation on the device is controlled by the following global properties:
+ * [ANIMATOR_DURATION_SCALE]{@link https://developer.android.com/reference/android/provider/Settings.Global.html#ANIMATOR_DURATION_SCALE},
+ * [TRANSITION_ANIMATION_SCALE]{@link https://developer.android.com/reference/android/provider/Settings.Global.html#TRANSITION_ANIMATION_SCALE},
+ * [WINDOW_ANIMATION_SCALE]{@link https://developer.android.com/reference/android/provider/Settings.Global.html#WINDOW_ANIMATION_SCALE}.
+ * This method sets all this properties to 0.0 to disable (1.0 to enable) animation.
+ *
+ * Turning off animation might be useful to improve stability
+ * and reduce tests execution time.
+ *
+ * @this {import('../client').SettingsApp}
+ * @param {boolean} on - True to enable and false to disable it.
+ */
+export function setAnimationState(this: import("../client").SettingsApp, on: boolean): Promise<void>;
+//# sourceMappingURL=animation.d.ts.map

package/build/lib/commands/animation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation.d.ts","sourceRoot":"","sources":["../../../lib/commands/animation.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,6EAFW,OAAO,iBASjB"}

package/build/lib/commands/animation.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setAnimationState = void 0;
+const constants_js_1 = require("../constants.js");
+/**
+ * Change the state of animation on the device under test.
+ * Animation on the device is controlled by the following global properties:
+ * [ANIMATOR_DURATION_SCALE]{@link https://developer.android.com/reference/android/provider/Settings.Global.html#ANIMATOR_DURATION_SCALE},
+ * [TRANSITION_ANIMATION_SCALE]{@link https://developer.android.com/reference/android/provider/Settings.Global.html#TRANSITION_ANIMATION_SCALE},
+ * [WINDOW_ANIMATION_SCALE]{@link https://developer.android.com/reference/android/provider/Settings.Global.html#WINDOW_ANIMATION_SCALE}.
+ * This method sets all this properties to 0.0 to disable (1.0 to enable) animation.
+ *
+ * Turning off animation might be useful to improve stability
+ * and reduce tests execution time.
+ *
+ * @this {import('../client').SettingsApp}
+ * @param {boolean} on - True to enable and false to disable it.
+ */
+async function setAnimationState(on) {
+    await this.adb.shell([
+        'am', 'broadcast',
+        '-a', constants_js_1.ANIMATION_SETTING_ACTION,
+        '-n', constants_js_1.ANIMATION_SETTING_RECEIVER,
+        '--es', 'setstatus', on ? 'enable' : 'disable'
+    ]);
+}
+exports.setAnimationState = setAnimationState;
+;
+//# sourceMappingURL=animation.js.map

package/build/lib/commands/animation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation.js","sourceRoot":"","sources":["../../../lib/commands/animation.js"],"names":[],"mappings":";;;AAAA,kDAAuF;AAEvF;;;;;;;;;;;;;GAaG;AACI,KAAK,UAAU,iBAAiB,CAAE,EAAE;IACzC,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;QACnB,IAAI,EAAE,WAAW;QACjB,IAAI,EAAE,uCAAwB;QAC9B,IAAI,EAAE,yCAA0B;QAChC,MAAM,EAAE,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;KAC/C,CAAC,CAAC;AACL,CAAC;AAPD,8CAOC;AAAA,CAAC"}

package/build/lib/commands/clipboard.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Retrieves the text content of the device's clipboard.
+ * The method works for Android below and above 29.
+ * It temorarily enforces the IME setting in order to workaround
+ * security limitations if needed.
+ * This method only works if Appium Settings v. 2.15+ is installed
+ * on the device under test
+ *
+ * @this {import('../client').SettingsApp}
+ * @returns {Promise<string>} The actual content of the main clipboard as
+ * base64-encoded string or an empty string if the clipboard is empty
+ * @throws {Error} If there was a problem while getting the
+ * clipboard contant
+ */
+export function getClipboard(this: import("../client").SettingsApp): Promise<string>;
+//# sourceMappingURL=clipboard.d.ts.map

package/build/lib/commands/clipboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clipboard.d.ts","sourceRoot":"","sources":["../../../lib/commands/clipboard.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;GAaG;AACH,qEALa,QAAQ,MAAM,CAAC,CA6B3B"}

package/build/lib/commands/clipboard.js

@@ -0,0 +1,51 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getClipboard = void 0;
+const lodash_1 = __importDefault(require("lodash"));
+const logger_1 = require("../logger");
+const constants_1 = require("../constants");
+/**
+ * Retrieves the text content of the device's clipboard.
+ * The method works for Android below and above 29.
+ * It temorarily enforces the IME setting in order to workaround
+ * security limitations if needed.
+ * This method only works if Appium Settings v. 2.15+ is installed
+ * on the device under test
+ *
+ * @this {import('../client').SettingsApp}
+ * @returns {Promise<string>} The actual content of the main clipboard as
+ * base64-encoded string or an empty string if the clipboard is empty
+ * @throws {Error} If there was a problem while getting the
+ * clipboard contant
+ */
+async function getClipboard() {
+    this.log.debug(logger_1.LOG_PREFIX, 'Getting the clipboard content');
+    await this.requireRunning({ shouldRestoreCurrentApp: true });
+    const retrieveClipboard = async () => await this.adb.shell([
+        'am', 'broadcast',
+        '-n', constants_1.CLIPBOARD_RECEIVER,
+        '-a', constants_1.CLIPBOARD_RETRIEVAL_ACTION,
+    ]);
+    let output;
+    try {
+        output = (await this.adb.getApiLevel() >= 29)
+            ? (await this.adb.runInImeContext(constants_1.APPIUM_IME, retrieveClipboard))
+            : (await retrieveClipboard());
+    }
+    catch (err) {
+        throw new Error(`Cannot retrieve the current clipboard content from the device. ` +
+            `Make sure the Appium Settings application is up to date. ` +
+            `Original error: ${err.message}`);
+    }
+    const match = /data="([^"]*)"/.exec(output);
+    if (!match) {
+        throw new Error(`Cannot parse the actual cliboard content from the command output: ${output}`);
+    }
+    return lodash_1.default.trim(match[1]);
+}
+exports.getClipboard = getClipboard;
+;
+//# sourceMappingURL=clipboard.js.map

package/build/lib/commands/clipboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clipboard.js","sourceRoot":"","sources":["../../../lib/commands/clipboard.js"],"names":[],"mappings":";;;;;;AAAA,oDAAuB;AACvB,sCAAuC;AACvC,4CAIsB;AAEtB;;;;;;;;;;;;;GAaG;AACI,KAAK,UAAU,YAAY;IAChC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,mBAAU,EAAE,+BAA+B,CAAC,CAAC;IAC5D,MAAM,IAAI,CAAC,cAAc,CAAC,EAAC,uBAAuB,EAAE,IAAI,EAAC,CAAC,CAAC;IAC3D,MAAM,iBAAiB,GAAG,KAAK,IAAI,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;QACzD,IAAI,EAAE,WAAW;QACjB,IAAI,EAAE,8BAAkB;QACxB,IAAI,EAAE,sCAA0B;KACjC,CAAC,CAAC;IACH,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC;YAC3C,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,sBAAU,EAAE,iBAAiB,CAAC,CAAC;YACjE,CAAC,CAAC,CAAC,MAAM,iBAAiB,EAAE,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,iEAAiE;YAC/E,2DAA2D;YAC3D,mBAAmB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,qEAAqE,MAAM,EAAE,CAAC,CAAC;IACjG,CAAC;IACD,OAAO,gBAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1B,CAAC;AAxBD,oCAwBC;AAAA,CAAC"}

package/build/lib/commands/geolocation.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @typedef {Object} Location
+ * @property {number|string} longitude - Valid longitude value.
+ * @property {number|string} latitude - Valid latitude value.
+ * @property {?number|string} [altitude] - Valid altitude value.
+ * @property {?number|string} [satellites=12] - Number of satellites being tracked (1-12).
+ * This value is ignored on real devices.
+ * @property {?number|string} [speed] - Valid speed value.
+ * Should be greater than 0.0 meters/second for real devices or 0.0 knots
+ * for emulators.
+ */
+/**
+ * Emulate geolocation coordinates on the device under test.
+ *
+ * @this {import('../client').SettingsApp}
+ * @param {Location} location - Location object. The `altitude` value is ignored
+ * while mocking the position.
+ * @param {boolean} [isEmulator=false] - Set it to true if the device under test
+ *                                       is an emulator rather than a real device.
+ */
+export function setGeoLocation(this: import("../client").SettingsApp, location: Location, isEmulator?: boolean | undefined): Promise<void>;
+/**
+ * Get the current cached GPS location from the device under test.
+ *
+ * @this {import('../client').SettingsApp}
+ * @returns {Promise<Location>} The current location
+ * @throws {Error} If the current location cannot be retrieved
+ */
+export function getGeoLocation(this: import("../client").SettingsApp): Promise<Location>;
+/**
+ * Sends an async request to refresh the GPS cache.
+ * This feature only works if the device under test has
+ * Google Play Services installed. In case the vanilla
+ * LocationManager is used the device API level must be at
+ * version 30 (Android R) or higher.
+ *
+ * @this {import('../client').SettingsApp}
+ * @param {number} timeoutMs The maximum number of milliseconds
+ * to block until GPS cache is refreshed. Providing zero or a negative
+ * value to it skips waiting completely.
+ *
+ * @throws {Error} If the GPS cache cannot be refreshed.
+ */
+export function refreshGeoLocationCache(this: import("../client").SettingsApp, timeoutMs?: number): Promise<void>;
+export type Location = {
+    /**
+     * - Valid longitude value.
+     */
+    longitude: number | string;
+    /**
+     * - Valid latitude value.
+     */
+    latitude: number | string;
+    /**
+     * - Valid altitude value.
+     */
+    altitude?: string | number | null | undefined;
+    /**
+     * - Number of satellites being tracked (1-12).
+     * This value is ignored on real devices.
+     */
+    satellites?: string | number | null | undefined;
+    /**
+     * - Valid speed value.
+     * Should be greater than 0.0 meters/second for real devices or 0.0 knots
+     * for emulators.
+     */
+    speed?: string | number | null | undefined;
+};
+//# sourceMappingURL=geolocation.d.ts.map

package/build/lib/commands/geolocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geolocation.d.ts","sourceRoot":"","sources":["../../../lib/commands/geolocation.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;GAUG;AAEH;;;;;;;;GAQG;AACH,gFALW,QAAQ,mDAoElB;AAED;;;;;;GAMG;AACH,uEAHa,QAAQ,QAAQ,CAAC,CA8B7B;AAED;;;;;;;;;;;;;GAaG;AACH,2FANW,MAAM,iBA+DhB;;;;;eA/La,MAAM,GAAC,MAAM;;;;cACb,MAAM,GAAC,MAAM"}