expensify-common 2.0.187 → 2.0.189

package/dist/esm/APIDeferred.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @param {jquery.Deferred} promise
+ * @param {String} [extractedProperty]
+ *
+ * @returns {Object}
+ */
+export default function APIDeferred(promise: jquery.Deferred, extractedProperty?: string): Object;

package/dist/esm/APIDeferred.js

@@ -0,0 +1,216 @@
+/**
+ * ----------------------------------------------------------------------------------------------
+ * WIP, This is in the process of migration from web-e. Please add methods to this as is needed.|
+ * ----------------------------------------------------------------------------------------------
+ */
+import get from 'lodash/get';
+import once from 'lodash/once';
+import * as Utils from './utils';
+import * as Func from './Func';
+/**
+ * @param {jquery.Deferred} promise
+ * @param {String} [extractedProperty]
+ *
+ * @returns {Object}
+ */
+export default function APIDeferred(promise, extractedProperty) {
+    /**
+     * @private
+     */
+    const extractedPropertyName = extractedProperty || null;
+    let cachedResponse = null;
+    const doneCallbacks = [];
+    const alwaysCallbacks = [];
+    const unhandledCallbacks = [];
+    const failCallbacks = [];
+    const errorHandlers = {};
+    if (!promise) {
+        throw new Error('Cannot instantiate APIDeferred without a Deferred promise');
+    }
+    /**
+     * @private
+     * @param {Object} [response]
+     * @returns {?Number}
+     */
+    function extractJSONCode(response) {
+        return response ? response.jsonCode : null;
+    }
+    /**
+     * Called when the jsonCode is not 200 and invokes the appropriate callbacks for the jsonCode
+     * If no callback is defined for the jsonCode then the unhandledCallbacks are invoked
+     * The failCallbacks are always called
+     *
+     * @private
+     * @param {Number} jsonCode
+     * @param {Object} [response]
+     */
+    function handleError(jsonCode, response) {
+        // Look for handlers for this error code
+        const handlers = get(errorHandlers, jsonCode, []);
+        if (handlers.length > 0) {
+            Func.bulkInvoke(handlers, [jsonCode, response]);
+        }
+        else {
+            // No explicit handlers, call the unhandled callbacks
+            Func.bulkInvoke(unhandledCallbacks, [jsonCode, response]);
+        }
+        // Always run the "fail" callbacks in case of error
+        Func.bulkInvoke(failCallbacks, [jsonCode, response]);
+    }
+    /**
+     * Called when network call succeeds or when a callback is added via any of the following methods after the promise is resolved:
+     *      done(), always(), handle(), unhandled(), or fail()
+     *
+     * @private
+     * @param {Object} [response]
+     */
+    function handleDone(response) {
+        let returnedData;
+        // Figure out if we need to extract a property from the response, and if it is there.
+        const jsonCode = extractJSONCode(response);
+        const propertyRequested = extractedPropertyName && extractedPropertyName !== null;
+        const requestedPropertyPresent = propertyRequested && response && response[extractedPropertyName] !== undefined;
+        const propertyRequestedButMissing = propertyRequested && !requestedPropertyPresent;
+        // Save the response for any callbacks that might run in the future
+        cachedResponse = response;
+        // Handle three different success/failure scenarios: ok (jsonCode == 200), exception (jsonCode != 200), other error
+        if (jsonCode === 200 && (!propertyRequested || requestedPropertyPresent)) {
+            // Get the data that was requested
+            returnedData = propertyRequested && requestedPropertyPresent ? response[extractedPropertyName] : response;
+            // And then run the success callbacks
+            Func.bulkInvoke(doneCallbacks, [returnedData]);
+        }
+        else if (jsonCode !== null && jsonCode !== 200) {
+            // Exception thrown, handle it
+            handleError(jsonCode, response);
+        }
+        else {
+            // Edge cases:
+            // If a specific property was requested but is missing, or if we got a blank response, throw an error
+            if (propertyRequestedButMissing) {
+                throw new Error(`Requested property " ${extractedPropertyName}" missing from response`);
+            }
+            if (!response) {
+                throw new Error('Blank response returned from API');
+            }
+        }
+        // Always run the "always" callbacks
+        Func.bulkInvoke(alwaysCallbacks, [response]);
+    }
+    /**
+     * Re-runs the "done" flow with a saved response to ensure that all callbacks are invoked,
+     * even if they were added after the deferred was resolved
+     *
+     * @private
+     */
+    function ensureFutureCallbacksFire() {
+        if (promise.state() === 'pending') {
+            return;
+        }
+        // Re-run the done handler with the response we saved
+        handleDone(cachedResponse);
+    }
+    // Attach the function to be called when the promise is resolved
+    // See handleDone() for more details
+    promise.done(handleDone);
+    return {
+        /**
+         * Attaches a callback that will be invoked when the jsonCode is 200
+         *
+         * @param {Function} callback A function that takes the response as a parameter
+         *
+         * @returns {APIDeferred} itself, for chaining
+         */
+        done(callback) {
+            if (Utils.isFunction(callback)) {
+                doneCallbacks.push(once(callback));
+                ensureFutureCallbacksFire();
+            }
+            return this;
+        },
+        /**
+         * Attaches a callback that will always be invoked
+         *
+         * @param {Function} callback A function that takes the response as a parameter
+         *
+         * @returns {APIDeferred} itself, for chaining
+         */
+        always(callback) {
+            if (Utils.isFunction(callback)) {
+                alwaysCallbacks.push(once(callback));
+                ensureFutureCallbacksFire();
+            }
+            return this;
+        },
+        /**
+         * Attaches a callback that will be invoked on non-200 jsonCodes
+         * Callbacks for jsonCode 200 are expected to be attached with done() and are therefore ignored here
+         *
+         * @param {Number[]} jsonCodes A list of error codes to handle
+         * @param {Function} callback A function that takes the jsonCode and response as parameters
+         *
+         * @returns {APIDeferred} itself, for chaining
+         */
+        handle(jsonCodes, callback) {
+            if (Utils.isFunction(callback)) {
+                for (const code of jsonCodes) {
+                    if (code === 200) {
+                        continue;
+                    }
+                    if (!errorHandlers[code]) {
+                        errorHandlers[code] = [];
+                    }
+                    errorHandlers[code].push(once(callback));
+                }
+                ensureFutureCallbacksFire();
+            }
+            return this;
+        },
+        /**
+         * Attaches a callback that will be invoked on all errors not explicitly handled via handle()
+         *
+         * @param {Function} callback A function that takes the jsonCode and response as parameters
+         *
+         * @returns {APIDeferred} itself, for chaining
+         */
+        unhandled(callback) {
+            if (Utils.isFunction(callback)) {
+                unhandledCallbacks.push(once(callback));
+                ensureFutureCallbacksFire();
+            }
+            return this;
+        },
+        /**
+         * Attaches a callback that will be always be invoked when the API does NOT return jsonCode 200, regardless of
+         * handle() or unhandled()
+         *
+         * @param {Function} callback A function that takes the jsonCode and response as parameters
+         *
+         * @returns {APIDeferred} itself, for chaining
+         */
+        fail(callback) {
+            if (Utils.isFunction(callback)) {
+                failCallbacks.push(once(callback));
+                ensureFutureCallbacksFire();
+            }
+            return this;
+        },
+        /**
+         * Attaches a callback that will be invoked when this deferred resolves successfully
+         *
+         * @param {Function} callback A function that takes the response as a parameter
+         *
+         * @returns {APIDeferred} itself, for chaining
+         */
+        then(callback) {
+            return promise.then((response) => {
+                const responseCode = extractJSONCode(response);
+                if (responseCode !== 200 || !Utils.isFunction(callback)) {
+                    return;
+                }
+                Func.invoke(callback, [response]);
+                return this;
+            });
+        },
+    };
+}

package/dist/esm/BrowserDetect.d.ts

@@ -0,0 +1,19 @@
+declare namespace _default {
+    export { BROWSERS };
+    export { MOBILE_PLATFORMS };
+    export let browser: string;
+    export let mobileDevice: string;
+}
+export default _default;
+declare namespace BROWSERS {
+    let EDGE: string;
+    let CHROME: string;
+    let SAFARI: string;
+    let OPERA: string;
+    let EXPLORER: string;
+    let MOZILLA: string;
+}
+declare namespace MOBILE_PLATFORMS {
+    let iOS: string;
+    let android: string;
+}

package/dist/esm/BrowserDetect.js

@@ -0,0 +1,105 @@
+import * as Utils from './utils';
+const BROWSERS = {
+    EDGE: 'Edge',
+    CHROME: 'Chrome',
+    SAFARI: 'Safari',
+    OPERA: 'Opera',
+    EXPLORER: 'Explorer',
+    MOZILLA: 'Mozilla',
+};
+const MOBILE_PLATFORMS = {
+    iOS: 'iOS',
+    android: 'android',
+};
+function searchString() {
+    if (!Utils.isWindowAvailable() || !Utils.isNavigatorAvailable()) {
+        return '';
+    }
+    const data = [
+        {
+            string: navigator.userAgent,
+            subString: 'Edge',
+            identity: BROWSERS.EDGE,
+        },
+        {
+            string: navigator.userAgent,
+            subString: 'Chrome',
+            identity: BROWSERS.CHROME,
+        },
+        {
+            string: navigator.vendor,
+            subString: 'Apple',
+            identity: BROWSERS.SAFARI,
+        },
+        {
+            prop: window.opera,
+            identity: BROWSERS.OPERA,
+        },
+        {
+            string: navigator.userAgent,
+            subString: 'Edge',
+            identity: BROWSERS.EDGE,
+        },
+        {
+            string: navigator.userAgent,
+            subString: 'MSIE',
+            identity: BROWSERS.EXPLORER,
+        },
+        {
+            string: navigator.userAgent,
+            subString: '.NET',
+            identity: BROWSERS.EXPLORER,
+        },
+        {
+            string: navigator.userAgent,
+            subString: 'Gecko',
+            identity: BROWSERS.MOZILLA,
+        },
+    ];
+    let dataString;
+    let dataProp;
+    for (let i = 0; i < data.length; i++) {
+        dataString = data[i].string;
+        dataProp = data[i].prop;
+        if (dataString) {
+            if (dataString.indexOf(data[i].subString) !== -1) {
+                return data[i].identity;
+            }
+        }
+        else if (dataProp) {
+            return data[i].identity;
+        }
+    }
+    return '';
+}
+function getMobileDevice() {
+    if (!Utils.isNavigatorAvailable() || !navigator.userAgent) {
+        return '';
+    }
+    const data = [
+        {
+            devices: ['iPhone', 'iPad', 'iPod'],
+            identity: MOBILE_PLATFORMS.iOS,
+        },
+        {
+            devices: ['Android'],
+            identity: MOBILE_PLATFORMS.android,
+        },
+    ];
+    const dataString = navigator.userAgent;
+    for (let i = 0; i < data.length; i++) {
+        const { devices, identity } = data[i];
+        for (let j = 0; j < devices.length; j++) {
+            if (dataString.indexOf(devices[j]) !== -1) {
+                return identity;
+            }
+        }
+    }
+    return '';
+}
+export default {
+    BROWSERS,
+    MOBILE_PLATFORMS,
+    browser: searchString(),
+    mobileDevice: getMobileDevice(),
+};

package/dist/esm/CLI.d.ts

@@ -0,0 +1,160 @@
+import type { NonEmptyObject, NonEmptyTuple } from 'type-fest';
+/**
+ * A base CLI arg has only a description, which we will use in the help/usage message (built-in to any CLI).
+ */
+type CLIArg = {
+    description: string;
+};
+/**
+ * A boolean arg is characterized only by its presence or absence so has no other fields,
+ * but we'll create a type alias to clearly distinguish it from other argument types.
+ */
+type BooleanArg = CLIArg;
+/**
+ * Any other argument is provided raw in process.argv as a string.
+ * It can remain a string, or can be transformed into another type by a custom `parse` function.
+ * It can be optional (by providing a default) or required (no default value).
+ * It can also supersede other named arguments when provided.
+ */
+type StringArg<T = unknown> = CLIArg & {
+    default?: T;
+    parse?: (val: string) => T;
+    supersedes?: string[];
+    required?: boolean;
+};
+/**
+ * A positional argument is just a string arg, but also must be assigned a name which we will eventually expose the CLI consumer.
+ * If `variadic` is true, this must be the last positional arg and it collects all remaining positional args into a string[].
+ */
+type PositionalArg<T = unknown> = StringArg<T> & {
+    name: string;
+    variadic?: true;
+};
+/**
+ * This type represents the config for a CLI.
+ * The last positional arg can be marked `variadic: true` to collect all remaining positional args into a string[].
+ */
+type CLIConfig = NonEmptyObject<{
+    /**
+     * Record of named flags that are fully characterized by their presence or absence (present=true,absent=false).
+     * @example `--verbose`
+     */
+    flags?: Record<string, BooleanArg>;
+    /**
+     * Record of named arguments that are represented by a key and a value.
+     * @example `--threads=8`
+     * @example `--name Rory`
+     */
+    namedArgs?: Record<string, StringArg>;
+    /**
+     * Tuple of positional args.
+     * @example `myScript.ts arg1 arg2 arg3`
+     */
+    positionalArgs?: NonEmptyTuple<PositionalArg>;
+}>;
+/**
+ * Record of flags to boolean after parsing.
+ */
+type ParsedFlags<Flags extends CLIConfig['flags']> = {
+    [K in keyof NonNullable<Flags>]: boolean;
+};
+/**
+ * Utility type to infer the final value of a string param. Either:
+ * - it's a plain string, or
+ * - it has a parse function and the final value is inferred from the return type of that function
+ */
+type InferStringArgParsedValue<T extends StringArg> = T extends {
+    parse: (val: string) => infer R;
+} ? R : string;
+/**
+ * Record of named args after parsing.
+ */
+type ParsedNamedArgs<NamedArgs extends CLIConfig['namedArgs']> = {
+    [K in keyof NonNullable<NamedArgs>]: InferStringArgParsedValue<NonNullable<NamedArgs>[K]>;
+};
+/**
+ * Record of positional args after parsing.
+ * Variadic args are parsed as string[]; all others use InferStringArgParsedValue.
+ */
+type ParsedPositionalArgs<PositionalArgs extends CLIConfig['positionalArgs']> = {
+    [K in NonNullable<PositionalArgs>[number] as K['name']]: K extends {
+        variadic: true;
+    } ? string[] : InferStringArgParsedValue<K>;
+};
+/**
+ * Utility to parse command-line arguments to a script.
+ *
+ * @example
+ * ```
+ * const cli = new CLI({
+ *     flags: {
+ *         verbose: {
+ *             description: 'Enable verbose logging',
+ *         },
+ *     },
+ *     namedArgs: {
+ *         time: {
+ *             description: 'Time of day to greet (morning or evening)',
+ *             default: 'morning',
+ *             parse: (val) => {
+ *                 if (val !== 'morning' && val !== 'evening') {
+ *                     throw new Error('Must be "morning" or "evening"');
+ *                 }
+ *                 return val as 'morning' | 'evening';
+ *             },
+ *         },
+ *     },
+ *     positionalArgs: [
+ *         {
+ *             name: 'firstName'
+ *             description: 'First name to greet',
+ *         },
+ *         {
+ *             name: 'lastName',
+ *             description: 'Last name to greet',
+ *             default: '',
+ *         },
+ *     ],
+ * });
+ *
+ * let fullName = cli.positionalArgs.firstName;
+ * if (cli.flags.verbose) {
+ *     fullName += cli.positionalArgs.lastName;
+ * }
+ * console.log(fullName);
+ * console.log(cli.namedArgs.time);
+ * ```
+ */
+/**
+ * Built-in flags that are always available on any CLI.
+ */
+type BuiltInFlags = {
+    yes: boolean;
+    no: boolean;
+    help: boolean;
+};
+declare class CLI<TConfig extends CLIConfig> {
+    private readonly config;
+    /**
+     * Flags after parsing (includes built-in flags like --yes, --no, and --help).
+     */
+    readonly flags: ParsedFlags<TConfig['flags']> & BuiltInFlags;
+    /**
+     * Named args after parsing.
+     */
+    readonly namedArgs: ParsedNamedArgs<TConfig['namedArgs']>;
+    /**
+     * Positional args after parsing, collected into a record keyed by the name of each arg.
+     */
+    readonly positionalArgs: ParsedPositionalArgs<TConfig['positionalArgs']>;
+    constructor(config: TConfig);
+    private printHelp;
+    private static parseStringArg;
+    /**
+     * Prompts the user for confirmation and returns true if they confirm (y/yes), false otherwise.
+     * If --yes flag was passed, returns true immediately without prompting.
+     * If --no flag was passed, returns false immediately without prompting.
+     */
+    promptUserConfirmation(message: string): Promise<boolean>;
+}
+export default CLI;