io.appium.settings 5.3.0 → 5.4.0

package/lib/commands/sms.js

@@ -0,0 +1,92 @@
+import { LOG_PREFIX } from '../logger.js';
+import { SMS_LIST_RECEIVER, SMS_LIST_RETRIEVAL_ACTION } from '../constants.js';
+
+/**
+ * @typedef {Object} SmsListOptions
+ * @property {number} [max=100] - The maximum count of recent messages
+ * to retrieve
+ */
+
+/**
+ * @typedef SmsListResult
+ * @property {SmsListResultItem[]} items
+ * @property {number} total
+ */
+
+/**
+ * @privateRemarks XXX: WAG
+ * @typedef SmsListResultItem
+ * @property {string} id
+ * @property {string} address
+ * @property {string|null} person
+ * @property {string} date
+ * @property {string} read
+ * @property {string} status
+ * @property {string} type
+ * @property {string|null} subject
+ * @property {string} body
+ * @property {string|null} serviceCenter
+ */
+
+/**
+ * Retrieves the list of the most recent SMS
+ * properties list via Appium Settings helper.
+ * Messages are sorted by date in descending order.
+ *
+ * @this {import('../client').SettingsApp}
+ * @param {SmsListOptions} opts
+ * @returns {Promise<SmsListResult>} The example output is:
+ * ```json
+ * {
+ *   "items":[
+ *     {
+ *       "id":"2",
+ *       "address":"+123456789",
+ *       "person":null,
+ *       "date":"1581936422203",
+ *       "read":"0",
+ *       "status":"-1",
+ *       "type":"1",
+ *       "subject":null,
+ *       "body":"\"text message2\"",
+ *       "serviceCenter":null
+ *     },
+ *     {
+ *       "id":"1",
+ *       "address":"+123456789",
+ *       "person":null,
+ *       "date":"1581936382740",
+ *       "read":"0",
+ *       "status":"-1",
+ *       "type":"1",
+ *       "subject":null,
+ *       "body":"\"text message\"",
+ *       "serviceCenter":null
+ *     }
+ *   ],
+ *   "total":2
+ * }
+ * ```
+ * @throws {Error} If there was an error while getting the SMS list
+ */
+export async function getSmsList (opts = {}) {
+  this.log.debug(LOG_PREFIX, 'Retrieving the recent SMS messages');
+  await this.requireRunning({shouldRestoreCurrentApp: true});
+  const args = [
+    'am', 'broadcast',
+    '-n', SMS_LIST_RECEIVER,
+    '-a', SMS_LIST_RETRIEVAL_ACTION,
+  ];
+  if (opts.max) {
+    args.push('--es', 'max', `${opts.max}`);
+  }
+  let output;
+  try {
+    output = await this.adb.shell(args);
+  } catch (err) {
+    throw new Error(`Cannot retrieve SMS list from the device. ` +
+      `Make sure the Appium Settings application is installed and is up to date. ` +
+      `Original error: ${err.message}`);
+  }
+  return this._parseJsonData(output, 'SMS list');
+};

package/lib/commands/typing.js

@@ -0,0 +1,46 @@
+import _ from 'lodash';
+import { APPIUM_IME, UNICODE_IME } from '../constants.js';
+import { imap } from './utf7';
+import { LOG_PREFIX } from '../logger.js';
+
+/**
+ * Performs the given editor action on the focused input field.
+ * This method requires Appium Settings helper to be installed on the device.
+ * No exception is thrown if there was a failure while performing the action.
+ * You must investigate the logcat output if something did not work as expected.
+ *
+ * @this {import('../client').SettingsApp}
+ * @param {string|number} action - Either action code or name. The following action
+ *                                 names are supported: `normal, unspecified, none,
+ *                                 go, search, send, next, done, previous`
+ */
+export async function performEditorAction (action) {
+  this.log.debug(LOG_PREFIX, `Performing editor action: ${action}`);
+  await this.adb.runInImeContext(APPIUM_IME,
+    async () => await this.adb.shell(['input', 'text', `/${action}/`]));
+};
+
+/**
+ * Types the given Unicode string.
+ * It is expected that the focus is already put
+ * to the destination input field before this method is called.
+ *
+ * @this {import('../client').SettingsApp}
+ * @param {string} text The string to type
+ * @returns {Promise<boolean>} `true` if the input text has been successfully sent to adb
+ */
+export async function typeUnicode (text) {
+  if (_.isNil(text)) {
+    return false;
+  }
+
+  text = `${text}`;
+  this.log.debug(LOG_PREFIX, `Typing ${text.length} character${text.length === 1 ? '' : 's'}`);
+  if (!text) {
+    return false;
+  }
+  await this.adb.runInImeContext(
+    UNICODE_IME, async () => await this.adb.inputText(imap.encode(text))
+  );
+  return true;
+};

package/lib/commands/utf7.js

@@ -0,0 +1,154 @@
+/*
+ * The code below has been adopted from https://www.npmjs.com/package/utf7
+ */
+
+/**
+ * @param {number} length
+ * @returns {Buffer}
+ */
+function allocateAsciiBuffer(length) {
+  return Buffer.alloc(length, 'ascii');
+}
+
+/**
+ * @param {string} str
+ * @returns {string}
+ */
+function _encode(str) {
+  const b = allocateAsciiBuffer(str.length * 2);
+  for (let i = 0, bi = 0; i < str.length; i++) {
+    // Note that we can't simply convert a UTF-8 string to Base64 because
+    // UTF-8 uses a different encoding. In modified UTF-7, all characters
+    // are represented by their two byte Unicode ID.
+    const c = str.charCodeAt(i);
+    // Upper 8 bits shifted into lower 8 bits so that they fit into 1 byte.
+    b[bi++] = c >> 8;
+    // Lower 8 bits. Cut off the upper 8 bits so that they fit into 1 byte.
+    b[bi++] = c & 0xFF;
+  }
+  // Modified Base64 uses , instead of / and omits trailing =.
+  return b.toString('base64').replace(/=+$/, '');
+}
+
+/**
+ * @param {string} str
+ * @returns {Buffer}
+ */
+function allocateBase64Buffer(str) {
+  return Buffer.from(str, 'base64');
+}
+
+/**
+ * @param {string} str
+ * @returns {string}
+ */
+function _decode(str) {
+  const b = allocateBase64Buffer(str);
+  const r = [];
+  for (let i = 0; i < b.length;) {
+    // Calculate charcode from two adjacent bytes.
+    r.push(String.fromCharCode(b[i++] << 8 | b[i++]));
+  }
+  return r.join('');
+}
+
+/**
+ * Escape RegEx from http://simonwillison.net/2006/Jan/20/escape/
+ *
+ * @param {string} chars
+ * @returns {string}
+ */
+function escape(chars) {
+  return chars.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, '\\$&');
+}
+
+// Character classes defined by RFC 2152.
+const setD = 'A-Za-z0-9' + escape(`'(),-./:?`);
+const setO = escape(`!"#$%&*;<=>@[]^_'{|}`);
+const setW = escape(` \r\n\t`);
+
+// Stores compiled regexes for various replacement pattern.
+/** @type {Record<string, RegExp>} */
+const regexes = {};
+const regexAll = new RegExp(`[^${setW}${setD}${setO}]+`, 'g');
+
+export const imap = {};
+
+/**
+ * RFC 2152 UTF-7 encoding.
+ *
+ * @param {string} str
+ * @param {string?} mask
+ * @returns {string}
+ */
+export const encode = function encode(str, mask = null) {
+  // Generate a RegExp object from the string of mask characters.
+  if (!mask) {
+    mask = '';
+  }
+  if (!regexes[mask]) {
+    regexes[mask] = new RegExp(`[^${setD}${escape(mask)}]+`, 'g');
+  }
+
+  // We replace subsequent disallowed chars with their escape sequence.
+  return str.replace(regexes[mask], (chunk) =>
+    // + is represented by an empty sequence +-, otherwise call encode().
+    `+${chunk === '+' ? '' : _encode(chunk)}-`
+  );
+};
+
+/**
+ * RFC 2152 UTF-7 encoding with all optionals.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+export function encodeAll(str) {
+  // We replace subsequent disallowed chars with their escape sequence.
+  return str.replace(regexAll, (chunk) =>
+    // + is represented by an empty sequence +-, otherwise call encode().
+    `+${chunk === '+' ? '' : _encode(chunk)}-`
+  );
+};
+
+/**
+ * RFC 3501, section 5.1.3 UTF-7 encoding.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+imap.encode = function encode(str) {
+  // All printable ASCII chars except for & must be represented by themselves.
+  // We replace subsequent non-representable chars with their escape sequence.
+  return str.replace(/&/g, '&-').replace(/[^\x20-\x7e]+/g, (chunk) => {
+    // & is represented by an empty sequence &-, otherwise call encode().
+    chunk = (chunk === '&' ? '' : _encode(chunk)).replace(/\//g, ',');
+    return `&${chunk}-`;
+  });
+};
+
+/**
+ * RFC 2152 UTF-7 decoding.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+export const decode = function decode(str) {
+  return str.replace(/\+([A-Za-z0-9/]*)-?/gi, (_, chunk) =>
+    // &- represents &.
+    chunk === '' ? '+' : _decode(chunk)
+  );
+};
+
+/**
+ * RFC 3501, section 5.1.3 UTF-7 decoding.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+imap.decode = function decode(str) {
+  return str.replace(/&([^-]*)-/g, (_, chunk) =>
+    // &- represents &.
+    chunk === '' ? '&' : _decode(chunk.replace(/,/g, '/'))
+  );
+};

package/lib/constants.js

@@ -0,0 +1,31 @@
+export const SETTINGS_HELPER_ID = 'io.appium.settings';
+export const SETTINGS_HELPER_MAIN_ACTIVITY = '.Settings';
+
+export const CLIPBOARD_RECEIVER = `${SETTINGS_HELPER_ID}/.receivers.ClipboardReceiver`;
+export const CLIPBOARD_RETRIEVAL_ACTION = `${SETTINGS_HELPER_ID}.clipboard.get`;
+
+export const APPIUM_IME = `${SETTINGS_HELPER_ID}/.AppiumIME`;
+export const UNICODE_IME = `${SETTINGS_HELPER_ID}/.UnicodeIME`;
+
+export const WIFI_CONNECTION_SETTING_RECEIVER = `${SETTINGS_HELPER_ID}/.receivers.WiFiConnectionSettingReceiver`;
+export const WIFI_CONNECTION_SETTING_ACTION = `${SETTINGS_HELPER_ID}.wifi`;
+export const DATA_CONNECTION_SETTING_RECEIVER = `${SETTINGS_HELPER_ID}/.receivers.DataConnectionSettingReceiver`;
+export const DATA_CONNECTION_SETTING_ACTION = `${SETTINGS_HELPER_ID}.data_connection`;
+
+export const ANIMATION_SETTING_RECEIVER = `${SETTINGS_HELPER_ID}/.receivers.AnimationSettingReceiver`;
+export const ANIMATION_SETTING_ACTION = `${SETTINGS_HELPER_ID}.animation`;
+
+export const LOCALE_SETTING_RECEIVER = `${SETTINGS_HELPER_ID}/.receivers.LocaleSettingReceiver`;
+export const LOCALE_SETTING_ACTION = `${SETTINGS_HELPER_ID}.locale`;
+
+export const LOCATION_SERVICE = `${SETTINGS_HELPER_ID}/.LocationService`;
+export const LOCATION_RECEIVER = `${SETTINGS_HELPER_ID}/.receivers.LocationInfoReceiver`;
+export const LOCATION_RETRIEVAL_ACTION = `${SETTINGS_HELPER_ID}.location`;
+
+export const NOTIFICATIONS_RETRIEVAL_ACTION = `${SETTINGS_HELPER_ID}.notifications`;
+
+export const SMS_LIST_RECEIVER = `${SETTINGS_HELPER_ID}/.receivers.SmsReader`;
+export const SMS_LIST_RETRIEVAL_ACTION = `${SETTINGS_HELPER_ID}.sms.read`;
+
+export const MEDIA_SCAN_RECEIVER = `${SETTINGS_HELPER_ID}/.receivers.MediaScannerReceiver`;
+export const MEDIA_SCAN_ACTION = `${SETTINGS_HELPER_ID}.scan_media`;

package/lib/logger.js

@@ -0,0 +1,14 @@
+import npmlog from 'npmlog';
+
+
+export const LOG_PREFIX = 'SettingsApp';
+
+function getLogger () {
+  const logger = global._global_npmlog || npmlog;
+  if (!logger.debug) {
+    logger.addLevel('debug', 1000, { fg: 'blue', bg: 'black' }, 'dbug');
+  }
+  return logger;
+}
+
+export const log = getLogger();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "io.appium.settings",
-  "version": "5.3.0",
+  "version": "5.4.0",
   "description": "App for dealing with Android settings",
   "main": "index.js",
   "scripts": {
@@ -9,10 +9,11 @@
     "js:lint": "eslint .",
     "js:lint:fix": "npm run lint -- --fix",
     "move-apks": "rm -rf apks && mkdir -p apks && cp app/build/outputs/apk/debug/settings_apk-debug.apk apks",
-    "build": "./gradlew clean assembleDebug && npm run move-apks",
+    "build": "tsc -b && ./gradlew clean assembleDebug && npm run move-apks",
     "prepare": "npm run build",
     "version": "npm run bump-gradle-version && npm run build",
-    "clean": "rm -rf node_modules && rm -f package-lock.json && npm install"
+    "clean": "npm run build -- --clean",
+    "js:test": "mocha --exit --timeout 1m \"./test/unit/**/*-specs.js\""
   },
   "repository": {
     "type": "git",
@@ -29,6 +30,8 @@
   ],
   "files": [
     "index.js",
+    "lib",
+    "build/lib",
     "apks",
     "!.DS_Store",
     "NOTICE.txt",
@@ -40,14 +43,47 @@
     "url": "https://github.com/appium/io.appium.settings/issues"
   },
   "homepage": "https://github.com/appium/io.appium.settings",
+  "dependencies": {
+    "asyncbox": "^3.0.0",
+    "bluebird": "^3.5.1",
+    "lodash": "^4.2.1",
+    "npmlog": "^7.0.1",
+    "semver": "^7.5.4",
+    "source-map-support": "^0.x",
+    "teen_process": "^2.0.0"
+  },
   "devDependencies": {
-    "@appium/eslint-config-appium": "^6.0.0",
-    "eslint": "^7.32.0",
-    "fancy-log": "^2.0.0",
-    "@semantic-release/git": "^10.0.1",
+    "@appium/eslint-config-appium": "^8.0.4",
+    "@appium/eslint-config-appium-ts": "^0.x",
+    "@appium/tsconfig": "^0.x",
+    "@appium/types": "^0.x",
     "@semantic-release/changelog": "^6.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@types/bluebird": "^3.5.38",
+    "@types/chai": "^4.3.5",
+    "@types/chai-as-promised": "^7.1.5",
+    "@types/lodash": "^4.14.196",
+    "@types/node": "^20.4.7",
+    "@types/teen_process": "^2.0.2",
+    "@typescript-eslint/eslint-plugin": "^6.9.0",
+    "@typescript-eslint/parser": "^6.9.0",
+    "appium-adb": "^11.0.0",
+    "chai": "^4.1.2",
+    "chai-as-promised": "^7.1.1",
     "conventional-changelog-conventionalcommits": "^7.0.1",
+    "eslint": "^8.46.0",
+    "eslint-config-prettier": "^9.0.0",
+    "eslint-import-resolver-typescript": "^3.5.5",
+    "eslint-plugin-import": "^2.28.0",
+    "eslint-plugin-mocha": "^10.1.0",
+    "eslint-plugin-promise": "^6.1.1",
+    "lint-staged": "^15.0.2",
+    "mocha": "^10.0.0",
+    "pre-commit": "^1.1.3",
+    "prettier": "^3.0.0",
     "semantic-release": "^22.0.5",
-    "semver": "^7.3.7"
+    "sinon": "^17.0.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.1.6"
   }
 }