Type Declarations for [some of?] Adobe's custom CEP APIs

cep.d.ts

/**
 * cep.d.ts - Type declarations for Adobe's CEPEngine APIs. These APIs are used by Adobe's 
 * [CEPEngine_extensions.js](https://github.com/Adobe-CEP/CEP-Resources/blob/master/CEP_11.x/CEPEngine_extensions.js)
 * but may be used directly in CEP contexts as well.
 * 
 * **WARNING:** These declarations are not guaranteed to be exhaustive.
 */


/**
 * The root namespace for special CEP APIs.
 */
declare namespace cep {
    /**
     * The namespace for CEP's File System APIs.
     */
    namespace fs {
        /**
         * No error.
         */
        const NO_ERROR = 0;

        /**
         * Unknown error occurred.
         */
        const ERR_UNKNOWN: 1;

        /**
         * Invalid parameters passed to function.
         */
        const ERR_INVALID_PARAMS: 2;

        /**
         * File or directory was not found.
         */
        const ERR_NOT_FOUND: 3;

        /**
         * File or directory could not be read.
         */
        const ERR_CANT_READ: 4;

        /**
         * An unsupported encoding value was specified.
         */
        const ERR_UNSUPPORTED_ENCODING: 5;

        /**
         * File could not be written.
         */
        const ERR_CANT_WRITE: 6;

        /**
         * Target directory is out of space. File could not be written.
         */
        const ERR_OUT_OF_SPACE: 7;

        /**
         * Specified path does not point to a file.
         */
        const ERR_NOT_FILE: 8;

        /**
         * Specified path does not point to a directory.
         */
        const ERR_NOT_DIRECTORY: 9;

        /**
         * Specified file already exists.
         */
        const ERR_FILE_EXISTS: 10;

        /**
         * Displays the OS File Open dialog, allowing the user to select files or directories.
         * 
         * @param allowMultipleSelection When `true`, multiple files/folders can be selected.
         * @param chooseDirectory When `true`, only folders can be selected. When `false`, only
         *        files can be selected.
         * @param title Title of the open dialog.
         * @param initialPath Initial path to display in the dialog. Pass `null` or `""` to
         *        display the last path chosen.
         * @param fileTypes The file extensions (without the dot) for the types
         *      of files that can be selected. Ignored when `chooseDirectory=true`.
         */
        function showOpenDialog(allowMultipleSelection: boolean, chooseDirectory: boolean, title: string, initialPath: null | string, fileTypes?: string[]): {
            /** An array of the full names of the selected files. */
            data: string[],
            /** The status of the operation. */
            err: typeof cep.fs.NO_ERROR | typeof cep.fs.ERR_INVALID_PARAMS,
        };

        /**
         * Displays the OS File Open dialog, allowing the user to select files or directories.
         * 
         * @param allowMultipleSelection When `true`, multiple files/folders can be selected.
         * @param chooseDirectory When `true`, only folders can be selected. When `false`, only
         *        files can be selected.
         * @param title Title of the open dialog.
         * @param initialPath Initial path to display in the dialog. Pass `null` or `""` to
         *        display the last path chosen.
         * @param fileTypes The file extensions (without the dot) for the types
         *      of files that can be selected. Ignored when `chooseDirectory=true`.
         * @param friendlyFilePrefix String to put in front of the extensions
         *      of files that can be selected. Ignored when `chooseDirectory=true`. (win only)
         * 
         *      For example: 
         *         - `fileTypes = ["gif", "jpg", "jpeg", "png", "bmp", "webp", "svg"];`
         *         - `friendlyFilePrefix = "Images (*.gif;*.jpg;*.jpeg;*.png;*.bmp;*.webp;*.svg)";`
         * @param prompt String for OK button (mac only, default is `"Open"` on mac, `"Open"` or `"Select Folder"` on win).
         */
        function showOpenDialogEx(allowMultipleSelection: boolean, chooseDirectory: boolean, title: string, initialPath: null | string, fileTypes?: string[], friendlyFilePrefix?: string, prompt?: string): {
            /** An array of the full names of the selected files. */
            data: string[],
            /** The status of the operation. */
            err: typeof cep.fs.NO_ERROR | typeof cep.fs.ERR_INVALID_PARAMS,
        };

        /**
         * Displays the OS File Save dialog, allowing the user to type in a file name.
         * 
         * @param title Title of the save dialog.
         * @param initialPath Initial path to display in the dialog. Pass `null` or `""` to
         *        display the last path chosen.
         * @param fileTypes The file extensions (without the dot) for the types
         *      of files that can be selected.
         * @param defaultName String to start with for the file name.
         * @param friendlyFilePrefix String to put in front of the extensions of files that can be selected. (win only)
         * 
         *      For example: 
         *         - `fileTypes = ["gif", "jpg", "jpeg", "png", "bmp", "webp", "svg"];`
         *         - `friendlyFilePrefix = "Images (*.gif;*.jpg;*.jpeg;*.png;*.bmp;*.webp;*.svg)";`
         * @param prompt String for Save button (mac only, default is `"Save"` on mac and win).
         * @param nameFieldLabel String displayed in front of the file name text field (mac only, `"File name:"` on win).
         */
        function showSaveDialogEx(title: string, initialPath: string, fileTypes: string[], defaultName: string, friendlyFilePrefix: string, prompt: string, nameFieldLabel: string): {
            /** The file path selected to save at or `""` if canceled */
            data: string[],
            /** The status of the operation. */
            err: typeof cep.fs.NO_ERROR | typeof cep.fs.ERR_INVALID_PARAMS,
        };

        /**
         * Reads the contents of a folder.
         *
         * @param path The path of the folder to read.
         */
        function readdir(path: string): {
            /** An array of the names of the contained files (excluding `.` and `..`). */
            data: string[],
            /** The status of the operation. */
            err: typeof NO_ERROR | typeof ERR_UNKNOWN | typeof ERR_INVALID_PARAMS | typeof ERR_NOT_FOUND | typeof ERR_CANT_READ,
        };

        /**
         * Creates a new folder.
         *
         * @param path The path of the folder to create.
         */
        function makedir(path: string): {
            /** The status of the operation. */
            err: typeof NO_ERROR | typeof ERR_UNKNOWN | typeof ERR_INVALID_PARAMS,
        };

        /**
         * Renames a file or folder.
         *
         * @param oldPath The old name of the file or folder.
         * @param newPath The new name of the file or folder.
         */
        function rename(oldPath: string, newPath: string): {
            /** The status of the operation. */
            err: typeof NO_ERROR | typeof ERR_UNKNOWN | typeof ERR_INVALID_PARAMS | typeof ERR_NOT_FOUND | typeof ERR_FILE_EXISTS,
        };

        /**
         * Reports whether the specified path is a file or folder and its modified time.
         * 
         * @param path The path of the file or folder.
         */
        function stat(path: string): {
            /** Status information for the requested path. */
            data: {
                /** Returns `true` if the path resolves to a directory, `false` otherwise. */
                isDirectory(): boolean,
                /** Returns `true` if the path resolves to a file, `false` otherwise. */
                isFile(): boolean,
                /** Modification DateTime */
                mtime: Date,
            },
            /** The status of the operation. */
            err: typeof NO_ERROR | typeof ERR_UNKNOWN | typeof ERR_INVALID_PARAMS | typeof ERR_NOT_FOUND,
        };

        /**
         * Reads the entire contents of a file.
         *
         * @param path The path of the file to read.
         * @param encoding The encoding of the contents of file, one of
         *      UTF8 (the default) or Base64.
         */
        function readFile(path: string, encoding?: typeof cep.encoding.UTF8 | typeof cep.encoding.Base64): {
            /** The file contents. */
            data: string,
            /** The status of the operation. */
            err: typeof NO_ERROR | typeof ERR_UNKNOWN | typeof ERR_INVALID_PARAMS | typeof ERR_NOT_FOUND | typeof ERR_CANT_READ | typeof ERR_UNSUPPORTED_ENCODING,
        };

        /**
         * Writes data to a file, replacing the file if it already exists.
         *
         * @param path The path of the file to write.
         * @param data The data to write to the file.
         * @param encoding The encoding of the contents of file, one of
         *      UTF8 (the default) or Base64.
         */
        function writeFile(path: string, data: string, encoding?: typeof cep.encoding.UTF8 | typeof cep.encoding.Base64): {
            /** The status of the operation. */
            err: typeof NO_ERROR | typeof ERR_UNKNOWN | typeof ERR_INVALID_PARAMS | typeof ERR_UNSUPPORTED_ENCODING | typeof ERR_CANT_WRITE | typeof ERR_OUT_OF_SPACE,
        };

        /**
         * Sets permissions for a file or folder.
         *
         * @param path The path of the file or folder.
         * @param mode The permissions in numeric format (for example, 0777).
         */
        function chmod(path: string, mode: number): {
            /** The status of the operation. */
            err: typeof NO_ERROR | typeof ERR_UNKNOWN | typeof ERR_INVALID_PARAMS | typeof ERR_CANT_WRITE,
        };

        /**
         * Deletes a file.
         *
         * @param path The path of the file to delete.
         */
        function deleteFile(path: string): {
            /** The status of the operation. */
            err: typeof NO_ERROR | typeof ERR_UNKNOWN | typeof ERR_INVALID_PARAMS | typeof ERR_NOT_FOUND | typeof ERR_NOT_FILE,
        };
    }

    /**
     * The namespace for CEP's Process APIs.
     */
    namespace process {
        /**
         * The maximum number of processes has been exceeded.
         */
        const ERR_EXCEED_MAX_NUM_PROCESS: 101;

        /**
         * The specified PID is invalid.
         * 
         * **NOTE:** This constant does not actually exist. This type
         * declaration merely adds a name to the returned value.
         */
        type ERR_INVALID_PROCESS_ID = 102;

        /**
         * Creates a process.
         * 
         * @param exePath The full path of the executable.
         * @param args The arguments of the executable.
         */
        function createProcess(exePath: string, ...args: string[]): {
            /** The pid of the process, or -1 on error. */
            data: number,
            /** The status of the operation. */
            err: typeof cep.fs.NO_ERROR | typeof cep.fs.ERR_UNKNOWN | typeof cep.fs.ERR_INVALID_PARAMS | typeof ERR_EXCEED_MAX_NUM_PROCESS | typeof cep.fs.ERR_NOT_FOUND | typeof cep.fs.ERR_NOT_FILE,
        };

        /**
         * Registers a standard-output handler for a process.
         * 
         * @param pid The pid of the process (an integer).
         * @param callback The handler function for the standard output callback.
         */
        function stdout(pid: number, callback: Function): {
            /** The status of the operation. */
            err: typeof cep.fs.NO_ERROR | typeof cep.fs.ERR_UNKNOWN | typeof cep.fs.ERR_INVALID_PARAMS | ERR_INVALID_PROCESS_ID,
        };

        /**
         * Registers up a standard-error handler for a process.
         * 
         * @param pid The pid of the process (an integer).
         * @param callback The handler function for the standard error callback.
         */
        function stderr(pid: number, callback: Function): {
            /** The status of the operation. */
            err: typeof cep.fs.NO_ERROR | typeof cep.fs.ERR_UNKNOWN | typeof cep.fs.ERR_INVALID_PARAMS | ERR_INVALID_PROCESS_ID,
        };

        /**
         * Writes data to the standard input of a process.
         * 
         * @param pid The pid of the process (an integer).
         * @param data The data to write.
         */
        function stdin(pid: number, data: string): {
            /** The status of the operation. */
            err: typeof cep.fs.NO_ERROR | typeof cep.fs.ERR_UNKNOWN | typeof cep.fs.ERR_INVALID_PARAMS | ERR_INVALID_PROCESS_ID,
        };

        /**
         * Retrieves the working directory of a process.
         * 
         * @param pid The pid of the process (an integer).
         */
        function getWorkingDirectory(pid: number): {
            /** The path of the working directory. */
            data: string,
            /** The status of the operation. */
            err: typeof cep.fs.NO_ERROR | typeof cep.fs.ERR_UNKNOWN | typeof cep.fs.ERR_INVALID_PARAMS | ERR_INVALID_PROCESS_ID,
        };

        /**
         * Waits for a process to quit.
         * 
         * @param pid The pid of the process (an integer).
         */
        function waitfor(pid: number): {
            /** The status of the operation. */
            err: typeof cep.fs.NO_ERROR | typeof cep.fs.ERR_UNKNOWN | typeof cep.fs.ERR_INVALID_PARAMS | ERR_INVALID_PROCESS_ID,
        };

        /**
         * Registers a handler for the onquit callback of a process.
         * 
         * @param pid The pid of the process (an integer).
         * @param callback The handler function.
         */
        function onquit(pid: number, callback: Function): {
            /** The status of the operation. */
            err: typeof cep.fs.NO_ERROR | typeof cep.fs.ERR_UNKNOWN | typeof cep.fs.ERR_INVALID_PARAMS | ERR_INVALID_PROCESS_ID,
        };

        /**
         * Reports whether a process is currently running.
         * 
         * @param pid The pid of the process (an integer).
         */
        function isRunning(pid: number): {
            /** `true` if the process is running, `false` otherwise. */
            data: boolean,
            /** The status of the operation. */
            err: typeof cep.fs.NO_ERROR | typeof cep.fs.ERR_UNKNOWN | typeof cep.fs.ERR_INVALID_PARAMS | ERR_INVALID_PROCESS_ID,
        };

        /**
         * Terminates a process.
         * 
         * @param pid The pid of the process (an integer).
         */
        function terminate(pid: number): {
            /** The status of the operation. */
            err: typeof cep.fs.NO_ERROR | typeof cep.fs.ERR_UNKNOWN | typeof cep.fs.ERR_INVALID_PARAMS | ERR_INVALID_PROCESS_ID,
        };
    }

    /**
     * The namespace for CEP's Util APIs.
     */
    namespace util {
        /**
         * Invalid URL.
         */
        const ERR_INVALID_URL: 201;

        /**
         * Deprecated API.
         */
        const DEPRECATED_API: 202;

        /**
         * Opens a page in the default system browser.
         * 
         * @param url The URL of the page/file to open, or the email address.
         * Must use HTTP/HTTPS/file/mailto. For example:
         * - http://www.adobe.com
         * - https://github.com
         * - file:///C:/log.txt
         * - mailto:test@adobe.com
         */
        function openURLInDefaultBrowser(url: string): {
            /** The status of the operation. */
            err: typeof cep.fs.NO_ERROR | typeof cep.fs.ERR_UNKNOWN | typeof cep.fs.ERR_INVALID_PARAMS,
        };

        /**
         * Registers a callback function for extension unload. If called more than once,
         * the last callback that is successfully registered is used.
         * 
         * @param callback The handler function.
         * 
         * @deprecated since CEP version 6.0.0.
         */
        function registerExtensionUnloadCallback(callback: Function): {
            /** The status of the operation. */
            err: typeof cep.fs.NO_ERROR | typeof cep.fs.ERR_INVALID_PARAMS,
        };

        /**
         * Stores the user's proxy credentials.
         * 
         * @param username proxy username
         * @param password proxy password
         */
        function storeProxyCredentials(username: string, password: string): {
            /** The status of the operation. */
            err: typeof cep.fs.NO_ERROR | typeof cep.fs.ERR_INVALID_PARAMS,
        };
    }

    /**
     * The namespace for CEP's Encoding APIs.
     */
    namespace encoding {
        /**
         * UTF8 encoding type.
         */
        const UTF8: "UTF-8";

        /**
         * Base64 encoding type.
         */
        const Base64: "Base64";

        /**
         * Encoding conversions.
         * 
         * **NOTE:** This is not a misspelling.
         */
        namespace convertion {
            function utf8_to_b64(str: string): string;
            function b64_to_utf8(base64str: string): string;
            function binary_to_b64(binary: string): string;
            function b64_to_binary(base64str: string): string;
            function ascii_to_b64(ascii: string): string;
            function b64_to_ascii(base64str: string): string;
        }
    }
}