deepl-node/dist/documentMinifier.d.ts

deepl-node is the official DeepL Node.js client library

interface IDocumentMinifier {
    /**
     * Minifies a given document by extracting it as a ZIP file and replacing all supported media files
     * with a small placeholder. Created file will be inside the `tempDir`. The filename can be retrieved by calling
     * {@link DocumentMinifier.getMinifiedDocFile} with tempDir as a parameter. Note: This method will minify the file without any checks. You should first call
     * {@link DocumentMinifier.canMinifyFile} on the input file. If `cleanup` is `true`, the extracted document will be deleted afterwards, and only
     * the original media and the minified file will remain in the `tempDir`.
     *
     * @param inputFilePath - Path to the file to be minified
     * @param cleanup - If true, will delete the extracted document files from the temporary directory.
     *                 Otherwise, the files will remain (useful for debugging).
     *                 Default behavior is not to cleanup.
     * @returns The path of the minified document. Can also be retrieved by calling
     *          {@link DocumentMinifier.getMinifiedDocFile}
     * @throws {DocumentMinificationError} If an error occurred during the minification process
     */
    minifyDocument(inputFilePath: string, cleanup?: boolean): string;
    /**
     * Deminifies a given file at `inputFilePath` by reinserting its original media in `tempDir` and stores
     * the resulting document in `outputFilePath`. If `cleanup` is set to `true`, it will delete the
     * `tempDir` afterwards; otherwise, nothing will happen after the deminification.
     *
     * @param inputFilePath Path to the document to be deminified with its media.
     * @param outputFilePath Where the final (deminified) document will be stored.
     * @param cleanup Determines if the `tempDir` is deleted at the end of this method. Default behavior is not to cleanup.
     * @throws {DocumentDeminificationError} If an error occurred during the deminification process.
     */
    deminifyDocument(inputFilePath: string, outputFilePath: string, cleanup?: boolean): void;
}
/**
 * Class that implements document minification: Stripping supported files like pptx and docx
 * of their media (images, videos, etc) before uploading them to the DeepL API to be translated.
 * This allows users to translate files that would usually hit the size limit for files.
 *
 * @note Please note the following:
 * 1. To use this class, you first need to check by calling {@link DocumentMinifier.canMinifyFile}
 *    if the file type is supported. This class performs no further checks.
 * 2. The {@link DocumentMinifier} is stateful, so you cannot use it to minify multiple documents at once.
 *    You need to create a new {@link DocumentMinifier} object per document.
 * 3. Be very careful when providing a custom `tempDir` when instantiating the class. For example,
 *    {@link DocumentMinifier.deminifyDocument} will delete the entire `tempDir` with
 *    `cleanup` set to `true` (disabled by default). In order not to lose any data, ideally always
 *    call `new DocumentMinifier()` in order to get a fresh temporary directory.
 * 4. If an error occurs during minification, either a {@link DocumentMinificationError} or a
 *    {@link DocumentDeminificationError} will be thrown, depending on which phase the error
 *    occurred in.
 *
 * The document minification process works in 2 phases:
 * 1. Minification: The document is extracted into a temporary directory, the media files are backed up,
 *    the media in the document is replaced with placeholders and a minified document is created.
 * 2. Deminification: The minified document is extracted into a temporary directory, the media backups are
 *    reinserted into the extracted document, and the document is deminified into the output path.
 *
 * If `cleanup` is enabled, the minification phase will delete the folder with the extracted document
 * and the deminification phase will delete the entire temporary directory.
 * Note that by default, the input file will be kept on disk, and as such no further backups of media etc.
 * are made (as they are all available from the input file).
 *
 * @example
 *     const inputFile = "/home/exampleUser/document.pptx";
 *     const outputFile = "/home/exampleUser/document_ES.pptx";
 *     const minifier = new DocumentMinifier();
 *     if (DocumentMinifier.canMinifyFile(inputFile)) {
 *       try {
 *         const minifiedFile = minifier.minifyDocument(inputFile, true);
 *         // process file minifiedFile, e.g. translate it with DeepL
 *         minifier.deminifyDocument(minifiedFile, outputFile, true);
 *         // process file outputFile
 *       } catch (e) {
 *         if (e instanceof DocumentMinificationError) {
 *           // handle error during minification, e.g. print list of media, clean up temporary directory, etc
 *         } else if (e instanceof DocumentDeminificationError) {
 *           // handle error during deminification, e.g. save minified document, clean up temporary directory, etc
 *         } else if (e instanceof DocumentTranslationError) {
 *           // handle general DocTrans error (mostly useful if document is translated between minification
 *           // and deminification)
 *         }
 *       }
 *     }
 */
export declare class DocumentMinifier implements IDocumentMinifier {
    /** Which input document types are supported for minification. */
    private static readonly SUPPORTED_DOCUMENT_TYPES;
    /** Which media formats in the documents are supported for minification. */
    private static readonly SUPPORTED_MEDIA_FORMATS;
    private static readonly EXTRACTED_DOC_DIR_NAME;
    private static readonly ORIGINAL_MEDIA_DIR_NAME;
    private static readonly MINIFIED_DOC_FILE_BASE_NAME;
    private static readonly MINIFIED_DOC_SIZE_LIMIT_WARNING;
    private static readonly MEDIA_PLACEHOLDER_TEXT;
    private readonly _tempDir;
    constructor(tempDir?: string);
    /**
     * Checks if a given file can be minified or not
     * @param inputFilePath The path to the file
     * @returns true if the file can be minified, otherwise false
     */
    static canMinifyFile(inputFilePath: string): boolean;
    /**
     * Gets the path for where the minified version of the input file will live
     * @param inputFilePath The path to the file
     * @returns The path to the minified version of the file
     */
    getMinifiedDocFile(inputFilePath: string): string;
    /**
     * Gets the path to the directory where the input file will be extracted to
     * @returns The path to the directory where the input file will be extracted to
     */
    getExtractedDocDirectory(): string;
    /**
     * Gets the path to the directory where the original media was extracted to
     * @returns The path to the media directory containing the original media
     */
    getOriginalMediaDirectory(): string;
    minifyDocument(inputFilePath: string, cleanup?: boolean): string;
    deminifyDocument(inputFilePath: string, outputFilePath: string, cleanup?: boolean): void;
    /**
     * Creates a temporary directory for use in the {@link DocumentMinifier}.
     * Uses the system's temporary directory.
     *
     * @returns The path of the created temporary directory
     * @throws {DocumentMinificationError} If the temporary directory could not be created
     */
    private static createTemporaryDirectory;
    /**
     * Extracts a zip file to a given directory
     * @param zippedDocumentPath The path to the zip file
     * @param extractionDir The path to the directory where the contents of the zip file will be extracted to
     */
    private extractZipToDirectory;
    /**
     * Creates a zip file from a given directory.
     * @param sourceDir The path to the directory that needs to be zipped
     * @param outputPath The path to the output zip file
     */
    private createZipFromDirectory;
    /**
     * Iterates through the inputDirectory and if it contains a supported media file, will export that media
     * to the mediaDirectory and replace the media in the inputDirectory with a placeholder. The
     * relative path will be preserved when moving the file to the mediaDirectory (e.g. a file located at
     * "/inputDirectory/foo/bar.png" will be exported to "/mediaDirectory/foo/bar.png")
     *
     * @param inputDirectory The path to the input directory
     * @param mediaDirectory The path to the directory where the supported media from inputDirectory will be exported to
     * @throws {DocumentMinificationError} If a problem occurred when exporting the original media from inputDirectory to mediaDirectory
     */
    private exportMediaToMediaDirAndReplace;
    /**
     * Iterates through `mediaDirectory` and moves all files into the `inputDirectory` while preserving
     * the relative paths. (e.g. /mediaDirectory/foo/bar.png will be moved to the path /inputDirectory/foo/bar.png
     * and replace any file if it exists at that path. Any subdirectories in `mediaDirectory` will also be
     * created in `inputDirectory`.
     *
     * @param inputDirectory The path to the input directory
     * @param mediaDirectory The path to the directory where the original media lives. This media will be reinserted back and replace any
     * placeholder media.
     * @throws {DocumentMinificationError} If a problem occurred when trying to reinsert the media
     */
    private replaceMediaInDir;
}
export {};