patreon-dl 1.0.0

package/README.md

@@ -0,0 +1,422 @@
+<a href='https://ko-fi.com/C0C5RGOOP' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://storage.ko-fi.com/cdn/kofi2.png?v=3' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>
+
+# patreon-dl
+
+A Patreon downloader written in [Node.js](https://nodejs.org).
+
+#### Features
+- Access to patron-only content through cookie
+- Download posts by user, in a collection or single post
+- Download products (aka shop purchases)
+- Items included in downloads:
+    - videos
+    - images
+    - audio
+    - attachments
+- Save campaign and content info 
+- Extensively configurable
+
+You can run `patreon-dl` from the command-line or use it as a library for your project. Node.js v16.16.0 or higher required.
+
+#### Limitations
+
+- Embedded videos, i.e. those linked from YouTube, Vimeo, etc., are not supported. Only info about the embed is saved.
+- Likewise, embedded links are not followed; only info about the embed is saved.
+
+#### FFmpeg requirement
+[FFmpeg](https://ffmpeg.org) is required for downloading videos that are provided only in streaming format. Not all video downloads require FFmpeg, but you should have it installed on your system anyway.
+
+## Installation
+
+```
+npm i -g patreon-dl
+```
+
+The `-g` option is for installing `patreon-dl` globally and have the CLI executable added to the PATH. Depending on your usage, you might not need this.
+
+## CLI usage
+
+```
+$ patreon-dl [OPTION]... URL
+
+Options
+
+  -h, --help                 Display this usage guide                           
+  -C, --config-file <file>   Load configuration file for setting full options   
+  -c, --cookie <string>      Cookie for accessing patron-only content           
+  -f, --ffmpeg <string>      Path to FFmpeg executable                          
+  -o, --out-dir <dir>        Path to directory where content is saved           
+  -l, --log-level <level>    Log level of the console logger: 'info', 'debug',  
+                             'warn' or 'error'; set to 'none' to disable the    
+                             logger.                                            
+  -y, --no-prompt            Do not prompt for confirmation to proceed
+```
+
+#### Supported URL formats
+
+```
+// Product
+https://www.patreon.com/<creator>/shop/<slug>-<product_id>
+
+// Posts
+https://www.patreon.com/<creator>/posts
+
+// Single post
+https://www.patreon.com/posts/<slug>-<post_id>
+
+// Posts in collection
+https://www.patreon.com/collection/<collection_id>
+
+```
+
+Content is saved with the following directory structure:
+```
+out-dir
+    ├── campaign
+        ├── campaign_info
+        ├── posts
+        │   ├── post 1
+        │   │   ├── post_info
+        │   │   ├── images
+        │   │   ├── ...
+        │   ├── post 2
+        │       ├── post_info
+        │       ├── images
+        │       ├── ...
+        ├──shop
+            ├── product 1
+                ├── product_info
+                ├── content_media
+                ├── ...
+```
+
+
+### Configuration file
+
+Command-line options are limited. To access the full range of options, create a configuration file and pass it to `patreon-dl` with the (capital) `-C` option.
+
+Refer to the [example config](./example.conf) to see what options are offered. Also see [How to obtain Cookie](https://github.com/patrickkfkan/patreon-dl/wiki/How-to-obtain-Cookie).
+
+Note that you can override an option from a configuration file with one provided at the command-line, provided of course that a command-line equivalent is available.
+
+## Library usage
+
+To use `patreon-dl` in your own project:
+
+```
+import PatreonDownloader from 'patreon-dl';
+
+const url = '....';
+
+const downloader = await PatreonDownloader.getInstance(url, [options]);
+
+await downloader.start();
+```
+
+Here, we first obtain a downloader instance by calling `PatreonDownloader.getInstance()`, passing to it the URL we want to download from (one of the [supported URL formats](#supported-url-formats)) and [downloader options](#downloader-options), if any.
+
+Then, we call `start()` on the downloader instance to begin the download process. The `start()` method returns a Promise that resolves when the download process has ended.
+- To monitor status and progress, see [Workflow and Events](#workflow-and-events).
+- To abort a download process, see [Aborting](#aborting).
+
+### Downloader options
+
+An object with the following properties (all *optional*):
+
+| Option          | Description                                                 |
+|-----------------|-------------------------------------------------------------|
+| `cookie`          | Cookie to include in requests; required for accessing patron-only content. See [How to obtain Cookie](https://github.com/patrickkfkan/patreon-dl/wiki/How-to-obtain-Cookie). |
+| `useStatusCache`  | Whether to use status cache to quickly determine whether a target that had been downloaded before has changed since the last download. Default: `true` |
+| `pathToFFmpeg`    | Path to `ffmpeg` executable. If not specified, `ffmpeg` will be called directly when needed, so make sure it is in the PATH. |
+| `outDir`          | Path to directory where content is saved. Default: current working directory |
+| `dirNameFormat`   | How to name directories: (object)<ul><li>`campaign`: see [Campaign directory name format](#campaign-directory-name-format)</li><li>`content`: see [Content directory name format](#content-directory-name-format)</li></ul> |
+| `filenameFormat`  | Naming of files: (object)<ul><li>`media`: see [Media filename format](#media-filename-format) |
+| `include`         | What to include in the download: (object) <ul><li>`lockedContent`: whether to process locked content. Default: `true`</li><li>`campaignInfo`: whether to save campaign info. Default: `true`</li><li>`contentInfo`: whether to save content info. Default: `true`</li><li>`contentMedia`: whether to download content media (images, videos, audio, attachments, excluding previews). Default: `true`</li><li>`previewMedia`: whether to download preview media, if available. Default: `true`</li><li>`allMediaVariants`: whether to download all media variants, if available. If `false`, only the best quality variant will be downloaded. Default: `false`</li></ul> |
+| `request`         | Rate limiting and retry on error: (object)<ul><li>`maxRetries`: maximum number of retries if a request or download fails. Default: 3</li><li>`maxConcurrent`: maximum number of concurrent downloads. Default: 10</li><li>`minTime`: minimum time to wait between starting requests or downloads (milliseconds). Default: 333</li></ul> |
+| `fileExistsAction` | What to do when a target file already exists: (object)<ul><li>`info`: in the context of saving info (such as campaign or post info), the action to take when a file belonging to the info already exists. Default: `saveAsCopyIfNewer`</li><li>`infoAPI`: API data is saved as part of info. Because it changes frequently, and usually used for debugging purpose only, you can set a different action when saving an API data file that already exists. Default: `overwrite`</li><li>`content`: in the context of downloading content, the action to take when a file belonging to the content already exists. Default: `skip`</li></ul><p>Supported actions:<li>`overwrite`: overwrite existing file.</li><li>`skip`: skip saving the file.</li><li>`saveAsCopy`: save the file under incremented filename (e.g. "abc.jpg" becomes "abc (1).jpg").</li><li>`saveAsCopyIfNewer`: like `saveAsCopy`, but only do so if the contents have actually changed.</li></ul></p> |
+|`logger`           | See [Logger](#logger)                     | 
+
+#### Campaign directory name format
+
+Format to apply when naming campaign directories. A format is a string pattern consisting of fields enclosed in curly braces.
+
+> ***What is a campaign directory?***
+> <p>When you download content, a directory is created for the campaign that hosts the content. Content directories, which stores the downloaded content, are then placed under the campaign directory.
+> If campaign info could not be obtained from content, then content directory
+> will be created directly under <code>outDir</code>.</p>
+
+A format must contain at least one of the following fields:
+- `creator.vanity`
+- `creator.name`
+- `creator.id`
+- `campaign.name`
+- `campaign.id`
+
+Characters enclosed in square brackets followed by a question mark denote
+conditional separators. If the value of a field could not be obtained or
+is empty, the conditional separator immediately adjacent to it will be
+omitted from the name.
+
+Default: '{creator.vanity}[ - ]?{campaign.name}'</br>
+Fallback: 'campaign-{campaign.id}'
+
+#### Content directory name format
+
+Format to apply when naming content directories. A format is a string pattern consisting of fields enclosed in curly braces.
+
+> ***What is a content directory?***
+> <p>Content can be a post or product. A directory is created for each piece of content. Downloaded items for the content are placed under this directory.</p>
+
+A format must contain at least one of the following unique identifier fields:
+- `content.id`: ID of content
+- `content.slug`: last segment of the content URL
+
+In addition, a format can contain the following fields:
+- `content.name`: post title or product name
+- `content.type`: type of content ('product' or 'post')
+
+Characters enclosed in square brackets followed by a question mark denote conditional separators. If the value of a field could not be obtained or is empty, the conditional separator immediately adjacent to it will be omitted from the name.
+
+Default: '{content.id}[ - ]?{content.name}'</br>
+Fallback: '{content.type}-{content.id}'
+
+#### Media filename format
+
+Filename format of a downloaded item. A format is a string pattern consisting of fields enclosed in curly braces.
+
+A format must contain at least one of the following fields:
+- `media.id`: ID of the item downloaded (assigned by Patreon)
+- `media.filename`: can be one of the following, in order of availability:
+  - original filename included in the item's API data; or
+  - filename derived from the header of the response to the HTTP download request.
+
+In addition, a format can contain the following fields:
+- `media.type`: type of item (e.g. 'image' or 'video')
+- `media.variant`: where applicable, the variant of the item (e.g. 'original', 'thumbnailSmall'...for images)
+
+> If `media.variant` is not included in the format, it will be appended to it if `allMediaVariants` is `true`.
+
+Sometimes `media.filename` could not be obtained, in which case it will be replaced with `media.id`, unless it is already present in the format.
+
+Characters enclosed in square brackets followed by a question mark denote conditional separators. If the value of a field could not be obtained or is empty, the conditional separator immediately adjacent to it will be omitted from the name.
+
+Default: '{media.filename}'</br>
+Fallback: '{media.type}-{media.id}'
+
+### Logger
+
+Logging is optional, but provides useful information about the download process. You can implement your own logger by extending the `Logger` abstract class:
+
+```
+import { Logger } from 'patreon-dl';
+
+class MyLogger extends Logger {
+
+  log(entry) {
+    // Do something with log entry
+  }
+
+  // Called when downloader ends, so you can
+  // clean up the logger process if necessary.
+  end() {
+    // This is not an abstract function, so you don't have to
+    // implement it if there is no action to be taken here. Default is
+    // to resolve right away.
+    return Promise.resolve();
+  }
+}
+```
+
+Each entry passed to `log()` is an object with the following properties:
+- `level`: `info`, `debug`, `warn` or `error`, indicating the severity of the log message.
+- `originator`: (string or `undefined`) where the message is coming from.
+- `message`: array of elements comprising the message. An element can be anything such as a string, Error or object.
+
+#### Built-in loggers
+
+The `patreon-dl` library comes with the following `Logger` implementations that you may utilize:
+
+- `ConsoleLogger`
+
+    Outputs messages to the console:
+
+    ```
+    import { ConsoleLogger } from 'patreon-dl';
+
+    const myLogger = new ConsoleLogger([options]);
+
+    const downloader = await PatreonDownloader.getInstance(url, {
+        ...
+        logger: myLogger
+    });
+    
+    ```
+
+    `options`: (object)
+
+    | Option        | Description                                    |
+    |---------------|------------------------------------------------|
+    | `enabled`     | Whether to enable this logger. Default: `true` |
+    | `logLevel`    | <p>`info`, `debug`, `warn` or `error`. Default: `info`</p><p>Output messages up to the specified severity level.</p> |
+    | `include`     | What to include in log messages: (object)<ul><li>`dateTime`: show date / time of log messages. Default: `true`</li><li>`level`: show the severity level. Default: `true`</li><li>`originator`: show where the messsage came from. Default: `true`</li><li>`errorStack`: for Errors, whether to show the full error stack. Default: `false`</li></ul> |
+    | `dateTimeFormat` | <p>The pattern to format data-time strings, when `include.dateTime` is `true`.</p><p>Date-time formatting is provided by [dateformat](https://github.com/felixge/node-dateformat) library. Refer to the README of that project for pattern rules.</p><p>Default: 'mmm dd HH:MM:ss'</p> |
+
+
+- `FileLogger`
+
+    Like `ConsoleLogger`, but writes messages to file.
+
+    ```
+    import { FileLogger } from 'patreon-dl';
+
+    const myLogger = new FileLogger(init, [options]);
+
+    const downloader = await PatreonDownloader.getInstance(url, {
+        ...
+        logger: myLogger
+    });
+    ```
+
+    `init`: values that determine the name of the log file (object)
+    
+    | Property       | Description                                   |
+    |----------------|-----------------------------------------------|
+    | `targetURL`    | The url passed to `PatreonDownloader.getInstance()` |
+    | `outDir`       | Value of `outDir` specified in `PatreonDownloader.getInstance()` options, or `undefined` if none specified (in which case defaults to current working directory). |
+    | `date`         | <p>(*optional*) `Date` instance representing the creation date / time of the logger. Default: current date-time</p><p>You might want to provide this if you are creating multiple `FileLogger` instances and filenames are to be formatted with the date, otherwise the date-time part of the filenames might have different values.</p>|
+
+    `options`: all `ConsoleLogger` options plus the following:
+
+    | Option         | Description                                   |
+    |----------------|-----------------------------------------------|
+    | `logDir`       | <p>Path to directory of the log file.</p><p>The path can be a string pattern consisting of the following fields enclosed in curly braces:<ul><li>`out.dir`: value of `outDir` provided in `init` (or the default current working directory if none provided).</li><li>`target.url.path`: the pathname of `targetURL` provided in `init`, sanitized as necessary.</li><li>`datetime.<date-time format>`: the date-time of logger creation, as represented by `date` in `init` and formatted according to `<date-time format>` (using pattern rules defined by the [dateformat](https://github.com/felixge/node-dateformat) library).</li></ul></p> |
+    | `logFilename`  | <p>Name of the log file.</p><p>The path can be a string pattern consisting of the following fields enclosed in curly braces:<ul><li>`target.url.path`: the pathname of `targetURL` provided in `init`, sanitized as necessary.</li><li>`datetime.<date-time format>`: the date-time of logger creation, as represented by `date` in `init` and formatted according to `<date-time format>` (using pattern rules defined by the [dateformat](https://github.com/felixge/node-dateformat) library).</li></ul></p><p>Default: '{datetime.yyyymmdd}-{log.level}.log'</p> |
+    | `fileExistsAction` | <p>What to do if log file already exists? One of the following values: <ul><li>`append`: append logs to existing file</li><li>`overwrite`: overwrite the existing file</li></ul></p><p>Default: `append`</p> |
+
+- `ChainLogger`
+
+    Combines multiple loggers into one single logger.
+
+    ```
+    import { ConsoleLogger, FileLogger, ChainLogger } from 'patreon-dl';
+
+    const consoleLogger = new ConsoleLogger(...);
+    const fileLogger = new FileLogger(...);
+    const chainLogger = new ChainLogger([ consoleLogger, fileLogger ]);
+
+    const downloader = await PatreonDownloader.getInstance(url, {
+        ...
+        logger: chainLogger
+    });
+    ```
+
+### Aborting
+
+To prematurely end a download process, use `AbortController` to send an abort signal to the downloader instance.
+
+```
+const downloader = await PatreonDownloader.getInstance(...);
+const abortController = new AbortController();
+downloader.start({
+    signal: abortController.signal
+});
+
+...
+
+abortController.abort();
+
+// Downloader aborts current and pending tasks, then ends.
+```
+
+### Workflow and Events
+
+#### Workflow
+
+1. Downloader analyzes given URL and determines what targets to fetch.
+2. Downloader begins fetching data from Patreon servers. Emits `fetchBegin` event.
+2. Downloader obtains the target(s) from the fetched data for downloading.
+3. For each target (which can be a campaign, product or post):
+    1. Downloader emits `targetBegin` event.
+    2. Downloader determines whether the target needs to be downloaded, based on downloader configuration and target info such as accessibility.
+        - If target is to be skipped, downloader emits `targetEnd` event with `isSkipped: true`. It then proceeds to the next target, if any.
+    3. If target is to be downloaded, downloader saves target info (subject to downloader configuration), and emits `phaseBegin` event with `phase: saveInfo`. When done, downloader emits `phaseEnd` event.
+    3. Downloader begins saving media belonging to target (again, subject to downloader configuration). Emits `phaseBegin` event with `phase: saveMedia`.
+        1. Downloader saves files that do not need to be downloaded, e.g. embedded video / link info.
+        2. Downloader proceeds to download files (images, videos, audio, attachments, etc.) belonging to the target in batches. For each batch, downloader emits `phaseBegin` event with `phase: batchDownload`. When done, downloader emits `phaseEnd` event with `phase: batchDownload`.
+            - In this `phaseBegin` event, you can attach listeners to the download batch to monitor events for each download. See Download Task Batch.
+    4. Downloader emits `phaseEnd` event with `phase: saveMedia`.
+    5. Downloader emits `targetEnd` event with `isSkipped: false`, and proceeds to the next target.
+4. When there are no more targets to be processed, or a fatal error occurred, downloader ends with `end` event.
+
+#### Events
+
+```
+const downloader = await PatreonDownloader.getInstance(...);
+
+downloader.on('fetchBegin', (payload) => {
+    ...
+});
+
+downloader.start();
+```
+
+Each event emitted by a `PatreonDownloader` instance has a payload, which is an object with properties containing information about the event.
+
+
+| Event         | Description                                   |
+|---------------|-----------------------------------------------|
+| `fetchBegin`  | <p>Emitted when downloader begins fetching data about target(s).<p><p>Payload properties:<ul><li>`targetType`: the type of target being fetched; one of `product`, `post` or `post`.</li></ul></p> |
+| `targetBegin` | <p>Emitted when downloader begins processing a target.</p><p>Payload properties:<ul><li>`target`: the target being processed; one of [Campaign](./docs/api/interfaces/Campaign.md), [Product](./docs/api/interfaces/Product.md) or [Post](./docs/api/interfaces/Post.md).</li></ul></p> |
+| `targetEnd`   | <p>Emitted when downloader is done processing a target.</p><p>Payload properties:<ul><li>`target`: the target processed; one of [Campaign](./docs/api/interfaces/Campaign.md), [Product](./docs/api/interfaces/Product.md) or [Post](./docs/api/interfaces/Post.md).</li><li>`isSkipped`: whether target was skipped.</li></ul></p><p>If `isSkipped` is `true`, the following additional properties are available:<ul><li>`skipReason`: the reason for skipping the target; one of the following enums:<ul><li>`TargetSkipReason.Inaccessible`</li><li>`TargetSkipReason.AlreadyDownloaded`</li></ul></li><li>`skipMessage`: description of the skip reason.</li></ul></p> |
+| `phaseBegin`  | <p>Emitted when downloader begins a phase in the processing of a target.</p><p>Payload properties:<ul><li>`target`: the subject target of the phase; one of [Campaign](./docs/api/interfaces/Campaign.md), [Product](./docs/api/interfaces/Product.md) or [Post](./docs/api/interfaces/Post.md).</li><li>`phase`: the phase that is about to begin; one of `saveInfo` or `batchDownload`.</li></ul></p><p>If `phase` is `batchDownload`, the following additional property is available:<ul><li>`batch`: an object representing the batch of downloads to be executed by the downloader. For monitoring downloads in the batch, see Download Task Batch.</li></ul></p> |
+| `phaseEnd`    | <p>Emitted when a phase ends for a target.</p><p>Payload properties:<ul><li>`target`: the subject target of the phase; one of [Campaign](./docs/api/interfaces/Campaign.md), [Product](./docs/api/interfaces/Product.md) or [Post](./docs/api/interfaces/Post.md).</li><li>`phase`: the phase that has ended; one of `saveInfo` or `batchDownload`.</li></ul></p> |
+| `end`         | <p>Emitted when downloader ends.</p><p>Payload properties:<ul><li>`aborted`: boolean indicating whether the downloader is ending because of an abort request</li><li>`error`: if downloader ends because of an error, then `error` will be the captured error. Note that `error` is not necessarily an `Error` object; it can be anything other than `undefined`.</li></ul></p> |
+
+### Download Task Batch
+
+Files are downloaded in batches. Each batch is provided in the payload of `phaseBegin` event with `phase: batchDownload`. You can monitor events of individual downloads in the batch as follows:
+
+```
+downloader.on('phaseBegin', (payload) => {
+    if (payload.phase === 'batchDownload') {
+        const batch = payload.batch;
+        batch.on(event, listener);
+    }
+})
+```
+
+Note that you don't have to remove listeners yourself. They will be removed once the batch ends and is destroyed by the downloader.
+
+#### Download Task
+
+Each download task in a batch is represented by an object with the following properties:
+
+| Property      | Description                           |
+|---------------|---------------------------------------|
+| `id`          | ID assigned to the task.               |
+| `src`         | The source of the download; URL or otherwise file path if downloading video from a previously-downloaded `m3u8` playlist. |
+| `srcEntity`   | The [Downloadable](./docs/api/README.md#downloadable) item from which the download task was created. |
+| `retryCount`  | The current retry count if download failed previously. |
+| `resolvedDestFilename` | The resolved destination filename of the download, or `null` if it has not yet been resolved. |
+| `resolvedDestFilename` | The resolved destination file path of the download, or `null` if it has not yet been reoslved. |
+| `getProgress()` | Function that returns the download progress. |
+
+#### Events
+
+Each event emitted by a download task batch has a payload, which is an object with properties containing information about the event.
+
+| Event         | Description                           |
+|---------------|---------------------------------------|
+| `taskStart`   | <p>Emitted when a download starts.</p><p>Payload properties:<ul><li>`task`: the download task</li></ul></p> |
+| `taskProgress`| <p>Emitted when a download progress is updated.</p><p>Payload properties:<ul><li>`task`: the download task</li><li>`progress`: (object)<ul><li>`destFilename`: the destination filename of the download</li><li>`destFilePath`: the destination file path of the download</li><li>`lengthUnit`: the unit measuring the progress. Generally, it would be 'byte', but for videos the unit would be 'second'.</li><li>`length`: length downloaded, measured in `lengthUnit`.</li><li>`percent`: percent downloaded</li><li>`sizeDownloaded`: size of file downloaded (kb)</li><li>`speed`: download speed (kb/s)</li></ul></li></ul></p> |
+| `taskComplete` | <p>Emitted when a download is complete.</p><p>Payload properties:<ul><li>`task`: the download task</li></ul></p> |
+| `taskError` | <p>Emitted when a download error occurs.</p><p>Payload properties:<ul><li>`error`: (object)<ul><li>`task`: the download task</li><li>`cause`: `Error` object or `undefined`</li></ul></li><li>`willRetry`: whether the download will be reattempted</li></ul></p> |
+| `taskAbort`   | <p>Emitted when a download is aborted.</p><p>Payload properties:<ul><li>`task`: the download task</li></ul></p> |
+| `taskSkip`    | <p>Emitted when a download is skipped.</p><p>Payload properties:<ul><li>`task`: the download task</li><li>`reason`: (object)<ul><li>`name`: `destFileExists` or `other`</li><li>`message`: string indicating the skip reason</li></ul></li></ul></p><p>If `reason.name` is `destFileExists`, `reason` will also contain the following property:<ul><li>`existingDestFilePath`: the existing file path that is causing the download to skip</li></ul></p> |
+| `taskSpawn`   | <p>Emitted when a download task is spawned from another task.</p><p>Payload properties:<ul><li>`origin`: the original download task</li><li>`spawn`: the spawned download task</li></ul></p> |
+| `complete` | <p>Emitted when the batch is complete and there are no more downloads pending.</p><p>Payload properties: *none*</p> |
+
+## Changelog
+
+v1.0.0
+- Initial release

package/bin/patreon-dl.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import PatreonDownloaderCLI from '../dist/cli/index.js';
+
+(new PatreonDownloaderCLI()).start();

package/dist/cli/CLIOptionValidator.d.ts

@@ -0,0 +1,9 @@
+import { CLIOptionParserEntry } from './CLIOptions.js';
+export default class CLIOptionValidator {
+    #private;
+    static validateRequired(entry?: CLIOptionParserEntry, errMsg?: string): string;
+    static validateString<T extends string[]>(entry?: CLIOptionParserEntry, ...match: T): T[number] | undefined;
+    static validateBoolean(entry?: CLIOptionParserEntry): boolean | undefined;
+    static validateNumber(entry?: CLIOptionParserEntry, min?: number, max?: number): number | undefined;
+}
+//# sourceMappingURL=CLIOptionValidator.d.ts.map

package/dist/cli/CLIOptionValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CLIOptionValidator.d.ts","sourceRoot":"","sources":["../../src/cli/CLIOptionValidator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAOvD,MAAM,CAAC,OAAO,OAAO,kBAAkB;;IAErC,MAAM,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,oBAAoB,EAAE,MAAM,CAAC,EAAE,MAAM;IAarE,MAAM,CAAC,cAAc,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,KAAK,CAAC,EAAE,oBAAoB,EAAE,GAAG,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,GAAG,SAAS;IAW3G,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,oBAAoB;IA0BnD,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,oBAAoB,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM;CA0B/E"}

package/dist/cli/CLIOptionValidator.js

@@ -0,0 +1,85 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _a, _CLIOptionValidator_logEntryKey;
+const CLI_OPTION_SRC_NAME = {
+    cli: 'Command-line',
+    cfg: 'Config file'
+};
+export default class CLIOptionValidator {
+    static validateRequired(entry, errMsg) {
+        if (entry && entry.value) {
+            return entry.value;
+        }
+        if (errMsg) {
+            throw Error(errMsg);
+        }
+        if (entry) {
+            throw Error(`${__classPrivateFieldGet(this, _a, "m", _CLIOptionValidator_logEntryKey).call(this, entry)} requires a value`);
+        }
+        throw Error('A required option missing');
+    }
+    static validateString(entry, ...match) {
+        if (!entry) {
+            return undefined;
+        }
+        const value = entry.value || undefined;
+        if (match.length > 0 && value && !match.includes(value)) {
+            throw Error(`${__classPrivateFieldGet(this, _a, "m", _CLIOptionValidator_logEntryKey).call(this, entry)} must be one of ${match.map((m) => `'${m}'`).join(', ')}`);
+        }
+        return value;
+    }
+    static validateBoolean(entry) {
+        if (!entry) {
+            return undefined;
+        }
+        const value = entry.value || undefined;
+        const trueValues = ['yes', '1', ' true'];
+        const falseValues = ['no', '0', 'false'];
+        let sanitized;
+        if (value) {
+            if (trueValues.includes(value.toLowerCase())) {
+                sanitized = true;
+            }
+            else if (falseValues.includes(value.toLowerCase())) {
+                sanitized = false;
+            }
+            else {
+                const allowedValues = [...trueValues, ...falseValues];
+                throw Error(`${__classPrivateFieldGet(this, _a, "m", _CLIOptionValidator_logEntryKey).call(this, entry)} must be one of ${allowedValues.map((m) => `'${m}'`).join(', ')}; currently '${value}'`);
+            }
+        }
+        else {
+            sanitized = undefined;
+        }
+        return sanitized;
+    }
+    static validateNumber(entry, min, max) {
+        if (!entry) {
+            return undefined;
+        }
+        const value = entry.value || undefined;
+        const sanitized = value ? parseInt(value, 10) : undefined;
+        if (sanitized !== undefined) {
+            if (isNaN(sanitized)) {
+                throw Error(`${__classPrivateFieldGet(this, _a, "m", _CLIOptionValidator_logEntryKey).call(this, entry)} is not a valid number`);
+            }
+            else if (min !== undefined && sanitized < min) {
+                throw Error(`${__classPrivateFieldGet(this, _a, "m", _CLIOptionValidator_logEntryKey).call(this, entry)} must not be less than ${min}`);
+            }
+            else if (max !== undefined && sanitized > max) {
+                throw Error(`${__classPrivateFieldGet(this, _a, "m", _CLIOptionValidator_logEntryKey).call(this, entry)} must not be greater than ${max}`);
+            }
+        }
+        return sanitized;
+    }
+}
+_a = CLIOptionValidator, _CLIOptionValidator_logEntryKey = function _CLIOptionValidator_logEntryKey(entry) {
+    const keyStr = entry.src === 'cli' ?
+        entry.key :
+        `[${entry.section}]->${entry.key}`;
+    return `${CLI_OPTION_SRC_NAME[entry.src]} option '${keyStr}'`;
+};
+//# sourceMappingURL=CLIOptionValidator.js.map

package/dist/cli/CLIOptionValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CLIOptionValidator.js","sourceRoot":"","sources":["../../src/cli/CLIOptionValidator.ts"],"names":[],"mappings":"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","sourcesContent":["import { CLIOptionParserEntry } from './CLIOptions.js';\n\nconst CLI_OPTION_SRC_NAME = {\n  cli: 'Command-line',\n  cfg: 'Config file'\n};\n\nexport default class CLIOptionValidator {\n\n  static validateRequired(entry?: CLIOptionParserEntry, errMsg?: string) {\n    if (entry && entry.value) {\n      return entry.value;\n    }\n    if (errMsg) {\n      throw Error(errMsg);\n    }\n    if (entry) {\n      throw Error(`${this.#logEntryKey(entry)} requires a value`);\n    }\n    throw Error('A required option missing');\n  }\n\n  static validateString<T extends string[]>(entry?: CLIOptionParserEntry, ...match: T): T[number] | undefined {\n    if (!entry) {\n      return undefined;\n    }\n    const value = entry.value || undefined;\n    if (match.length > 0 && value && !match.includes(value)) {\n      throw Error(`${this.#logEntryKey(entry)} must be one of ${match.map((m) => `'${m}'`).join(', ')}`);\n    }\n    return value;\n  }\n\n  static validateBoolean(entry?: CLIOptionParserEntry) {\n    if (!entry) {\n      return undefined;\n    }\n    const value = entry.value || undefined;\n    const trueValues = [ 'yes', '1', ' true' ];\n    const falseValues = [ 'no', '0', 'false' ];\n    let sanitized: boolean | undefined;\n    if (value) {\n      if (trueValues.includes(value.toLowerCase())) {\n        sanitized = true;\n      }\n      else if (falseValues.includes(value.toLowerCase())) {\n        sanitized = false;\n      }\n      else {\n        const allowedValues = [ ...trueValues, ...falseValues ];\n        throw Error(`${this.#logEntryKey(entry)} must be one of ${allowedValues.map((m) => `'${m}'`).join(', ')}; currently '${value}'`);\n      }\n    }\n    else {\n      sanitized = undefined;\n    }\n    return sanitized;\n  }\n\n  static validateNumber(entry?: CLIOptionParserEntry, min?: number, max?: number) {\n    if (!entry) {\n      return undefined;\n    }\n    const value = entry.value || undefined;\n    const sanitized = value ? parseInt(value, 10) : undefined;\n    if (sanitized !== undefined) {\n      if (isNaN(sanitized)) {\n        throw Error(`${this.#logEntryKey(entry)} is not a valid number`);\n      }\n      else if (min !== undefined && sanitized < min) {\n        throw Error(`${this.#logEntryKey(entry)} must not be less than ${min}`);\n      }\n      else if (max !== undefined && sanitized > max) {\n        throw Error(`${this.#logEntryKey(entry)} must not be greater than ${max}`);\n      }\n    }\n    return sanitized;\n  }\n\n  static #logEntryKey(entry: CLIOptionParserEntry) {\n    const keyStr = entry.src === 'cli' ?\n      entry.key :\n      `[${entry.section}]->${entry.key}`;\n    return `${CLI_OPTION_SRC_NAME[entry.src]} option '${keyStr}'`;\n  }\n}\n"]}

package/dist/cli/CLIOptions.d.ts

@@ -0,0 +1,20 @@
+import { DownloaderOptions } from '../downloaders/DownloaderOptions.js';
+import { ConsoleLoggerOptions } from '../utils/logging/ConsoleLogger.js';
+import { FileLoggerOptions } from '../utils/logging/FileLogger.js';
+export interface CLIOptions extends Omit<DownloaderOptions, 'logger'> {
+    targetURL: string;
+    noPrompt: boolean;
+    consoleLogger: ConsoleLoggerOptions;
+    fileLoggers?: FileLoggerOptions[];
+}
+export type CLIOptionParserEntry = ({
+    src: 'cli';
+} | {
+    src: 'cfg';
+    section: string;
+}) & {
+    key: string;
+    value?: string;
+};
+export declare function getCLIOptions(): CLIOptions;
+//# sourceMappingURL=CLIOptions.d.ts.map

package/dist/cli/CLIOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CLIOptions.d.ts","sourceRoot":"","sources":["../../src/cli/CLIOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAExE,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAKnE,MAAM,WAAW,UAAW,SAAQ,IAAI,CAAC,iBAAiB,EAAE,QAAQ,CAAC;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa,EAAE,oBAAoB,CAAC;IACpC,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACnC;AAED,MAAM,MAAM,oBAAoB,GAAG,CAAC;IAClC,GAAG,EAAE,KAAK,CAAA;CACX,GAAG;IACF,GAAG,EAAE,KAAK,CAAC;IACX,OAAO,EAAE,MAAM,CAAA;CAChB,CAAC,GAAG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAA;AAED,wBAAgB,aAAa,IAAI,UAAU,CAyE1C"}