sfiledl 2.2.3 → 2.2.5

package/readme.md

@@ -1,19 +1,19 @@
 # sfiledl
 
-> Automate file downloads from [sfile.co](https://sfile.co/) — reliable, retry‑aware, and fully typed.
-
-[![npm version](https://img.shields.io/npm/v/sfiledl.svg?style=flat-square&logo=npm)](https://www.npmjs.com/package/sfiledl)
-[![npm downloads](https://img.shields.io/npm/dm/sfiledl?style=flat-square&logo=npm)](https://www.npmjs.com/package/sfiledl)
-[![license](https://img.shields.io/github/license/neuxdotdev/sfiledl?style=flat-square)](https://github.com/neuxdotdev/sfiledl/blob/main/license)
-[![build](https://img.shields.io/github/actions/workflow/status/neuxdotdev/sfiledl/build.yml?branch=main&style=flat-square&logo=github)](https://github.com/neuxdotdev/sfiledl/actions)
-[![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org)
-[![Playwright](https://img.shields.io/badge/Playwright-1.59-green?style=flat-square&logo=playwright)](https://playwright.dev)
-[![Bun](https://img.shields.io/badge/Bun-1.3+-black?style=flat-square&logo=bun)](https://bun.sh)
-[![Node](https://img.shields.io/badge/Node-%3E%3D24-green?style=flat-square&logo=node.js)](https://nodejs.org)
-[![code style](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square&logo=prettier)](https://prettier.io)
-[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
-<<<<<<< HEAD
-=======
+> **Automate file downloads from [sfile.co](https://sfile.co) — reliable, retry‑aware, and fully typed.**
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/sfiledl"><img src="https://img.shields.io/npm/v/sfiledl.svg?style=flat-square&logo=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/sfiledl"><img src="https://img.shields.io/npm/dm/sfiledl?style=flat-square&logo=npm" alt="npm downloads"></a>
+  <a href="https://github.com/neuxdotdev/sfiledl/blob/main/license"><img src="https://img.shields.io/github/license/neuxdotdev/sfiledl?style=flat-square" alt="license"></a>
+  <a href="https://github.com/neuxdotdev/sfiledl/actions"><img src="https://img.shields.io/github/actions/workflow/status/neuxdotdev/sfiledl/build.yml?branch=main&style=flat-square&logo=github" alt="build"></a>
+  <a href="https://www.typescriptlang.org"><img src="https://img.shields.io/badge/TypeScript-6.0-blue?style=flat-square&logo=typescript" alt="TypeScript"></a>
+  <a href="https://playwright.dev"><img src="https://img.shields.io/badge/Playwright-1.59-green?style=flat-square&logo=playwright" alt="Playwright"></a>
+  <a href="https://bun.sh"><img src="https://img.shields.io/badge/Bun-1.3+-black?style=flat-square&logo=bun" alt="Bun"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-%3E%3D18-green?style=flat-square&logo=node.js" alt="Node"></a>
+  <a href="https://prettier.io"><img src="https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square&logo=prettier" alt="code style"></a>
+  <a href="http://makeapullrequest.com"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" alt="PRs welcome"></a>
+</p>
 
 ---
 
@@ -21,12 +21,15 @@
 
 - [Installation](#installation)
 - [Quick Start](#quick-start)
-- [API Reference](#api-reference)
-    - [downloadSfile](#downloadsfile)
-    - [downloadSfileSafe](#downloadsfilesafe)
-    - [createDownloader](#createdownloader)
-    - [DownloadOptions](#downloadoptions)
-    - [DownloadResult](#downloadresult)
+- [CLI Usage](#cli-usage)
+    - [Command Line Options](#command-line-options)
+    - [Configuration File](#configuration-file)
+- [Library API](#library-api)
+    - [`downloadSfile`](#downloadsfile)
+    - [`downloadSfileSafe`](#downloadsfilesafe)
+    - [`createDownloader`](#createdownloader)
+    - [`DownloadOptions`](#downloadoptions)
+    - [`DownloadResult`](#downloadresult)
 - [Error Handling](#error-handling)
     - [Error Types](#error-types)
     - [Retryable Errors](#retryable-errors)
@@ -38,7 +41,6 @@
     - [Scripts](#scripts)
 - [Contributing](#contributing)
 - [License](#license)
->>>>>>> 91ae467 (docs: imrpoving documentation)
 
 ---
 
@@ -51,16 +53,18 @@ bun add sfiledl
 # Using npm
 npm install sfiledl
 
-# Install Playwright browser (required)
+# Install Playwright browser (required once)
 bunx playwright install chromium   # or npx playwright install chromium
 ```
 
-**Prerequisites:** Node.js >=24 or Bun >=1.3.
+**Prerequisites:** Node.js >=18 or Bun >=1.3.
 
 ---
 
 ## Quick Start
 
+### As a library
+
 ```typescript
 import { downloadSfile } from 'sfiledl'
 
@@ -77,25 +81,122 @@ console.log(result)
 // }
 ```
 
+### As a CLI tool
+
+```bash
+# Basic usage
+sfiledl https://sfile.co/abc123
+
+# Specify output directory
+sfiledl https://sfile.co/abc123 -o ~/Downloads
+
+# Show browser window and enable debug
+sfiledl https://sfile.co/abc123 --headed --debug
+
+# Adjust retries and delays
+sfiledl https://sfile.co/abc123 -r 5 -d 2000
+
+# See help
+sfiledl --help
+```
+
 ---
 
-## API Reference
+## CLI Usage
+
+The CLI provides a fully featured interface to the downloader.
+
+```bash
+sfiledl [options] <url>
+```
+
+### Command Line Options
+
+| Option                     | Alias | Type     | Default           | Description                            |
+| -------------------------- | ----- | -------- | ----------------- | -------------------------------------- |
+| `<url>`                    | –     | required | –                 | sfile.co download URL                  |
+| `--output <dir>`           | `-o`  | string   | `./downloads`     | Save directory                         |
+| `--headed`                 | –     | boolean  | `false`           | Show browser window (disable headless) |
+| `--timeout <ms>`           | `-t`  | number   | `60000`           | Navigation timeout (ms, ≥1000)         |
+| `--button-timeout <ms>`    | –     | number   | `30000`           | Download button wait timeout (ms)      |
+| `--retries <n>`            | `-r`  | number   | `3`               | Maximum retry attempts                 |
+| `--retry-delay <ms>`       | `-d`  | number   | `1000`            | Base retry delay (exponential backoff) |
+| `--debug`                  | –     | boolean  | `false`           | Enable debug logs and artifacts        |
+| `--ua, --user-agent <str>` | –     | string   | Chrome on Windows | Custom User‑Agent header               |
+| `--no-progress`            | –     | boolean  | `false`           | Disable progress spinner               |
+| `--log-file <path>`        | –     | string   | –                 | Write structured logs to file          |
+| `--no-artifacts`           | –     | boolean  | `true`            | Skip saving debug artifacts on error   |
+| `-v, --version`            | –     | –        | –                 | Show version                           |
+| `-h, --help`               | –     | –        | –                 | Show help                              |
+
+### Configuration File
+
+You can set default options using a JSON configuration file in the current working directory.  
+Supported files: `.sfiledlrc.json` or `.sfiledlrc` (`.json` takes precedence).
+
+Example `.sfiledlrc.json`:
+
+```json
+{
+	"output": "./downloads",
+	"retries": 5,
+	"debug": true,
+	"headless": false,
+	"timeout": 120000,
+	"userAgent": "MyCustomAgent/1.0"
+}
+```
+
+CLI options always override file configuration.
+
+---
+
+## Library API
+
+The library exports several functions and types for programmatic usage.
+
+### `downloadSfile`
+
+Main download function. Throws errors on failure.
 
-### `downloadSfile(url, saveDir, options?)`
+```typescript
+function downloadSfile(
+	url: string,
+	saveDir: string,
+	options?: DownloadOptions,
+): Promise<DownloadResult>
+```
+
+**Example:**
+
+```typescript
+import { downloadSfile } from 'sfiledl'
 
-Main download function. Throws errors on failure (see [Error Handling](#error-handling)).
+try {
+	const result = await downloadSfile('https://sfile.co/file/xyz', './out', {
+		headless: true,
+		retries: 2,
+		onProgress: (percent) => console.log(`${percent}%`),
+	})
+	console.log('Downloaded:', result.filePath)
+} catch (err) {
+	console.error('Failed:', err.message)
+}
+```
 
-| Param     | Type              | Description                            |
-| --------- | ----------------- | -------------------------------------- |
-| `url`     | `string`          | sfile.co URL (must contain the domain) |
-| `saveDir` | `string`          | Directory where the file will be saved |
-| `options` | `DownloadOptions` | Optional configuration                 |
+### `downloadSfileSafe`
 
-**Returns:** `Promise<DownloadResult>`
+Same as `downloadSfile` but never throws – returns a `Result` object.
 
-### `downloadSfileSafe(url, saveDir, options?)`
+```typescript
+function downloadSfileSafe(
+	url: string,
+	saveDir: string,
+	options?: DownloadOptions,
+): Promise<Result<DownloadResult, Error>>
+```
 
-Same as `downloadSfile` but never throws. Returns a `Result` object.
+**Example:**
 
 ```typescript
 import { downloadSfileSafe, isSuccess } from 'sfiledl'
@@ -108,19 +209,30 @@ if (isSuccess(res)) {
 }
 ```
 
-### `createDownloader(defaultOptions?)`
+### `createDownloader`
 
 Creates a reusable downloader with preset options.
 
 ```typescript
-const dl = createDownloader({ headless: false, debug: true })
-const result = await dl.download('https://sfile.co/file/xyz', './out')
+function createDownloader(defaultOptions?: DownloadOptions): {
+	download: (url: string, saveDir: string, options?: DownloadOptions) => Promise<DownloadResult>
+	downloadSafe: (
+		url: string,
+		saveDir: string,
+		options?: DownloadOptions,
+	) => Promise<Result<DownloadResult, Error>>
+	withOptions: (newDefaults: Partial<DownloadOptions>) => ReturnType<typeof createDownloader>
+}
+```
 
-// safe variant
-const safeResult = await dl.downloadSafe(url, './out')
+**Example:**
+
+```typescript
+const dl = createDownloader({ headless: false, debug: true })
+const result = await dl.download('https://sfile.co/file/abc', './downloads')
 
-// chain new defaults
 const quietDl = dl.withOptions({ debug: false })
+await quietDl.download('https://sfile.co/file/xyz', './downloads')
 ```
 
 ### `DownloadOptions`
@@ -156,7 +268,7 @@ All options are optional.
 
 ## Error Handling
 
-All errors extend `AppError` and include:
+All errors thrown by the library extend `AppError` and include:
 
 - `code` – unique string identifier
 - `retryable` – `true` for network/browser issues, `false` for validation/file errors
@@ -206,6 +318,8 @@ Set `debug: true` in options to enable:
 await downloadSfile(url, './out', { debug: true, saveDebugArtifacts: true })
 ```
 
+In the CLI, use `--debug` and `--no-artifacts` to control behavior.
+
 ---
 
 ## Logging & Correlation
@@ -258,53 +372,65 @@ cd sfiledl
 bun install
 bunx playwright install chromium
 
-# Full rebuild (clean, typecheck, build, format)
+# Full rebuild (clean, typecheck, bundle, format)
 bun run rebuild
 
-# Run tests (if available)
+# Run tests
 bun run test
+
+# Build only library (CJS, ESM, types)
+bun run build:lib
+
+# Build only CLI bundle
+bun run build:cli
+
+# Build everything (library + CLI)
+bun run build:all
 ```
 
 ### Project Structure
 
 ```
 .
-├── lib
-│   ├── browser
-│   │   ├── browser-manager.ts
-│   │   └── page-interactions.ts
-│   ├── config
-│   │   ├── defaults.ts
-│   │   └── schema.ts
-│   ├── core
-│   │   ├── downloader.ts
-│   │   └── validator.ts
-│   ├── errors
-│   │   ├── base.ts
-│   │   ├── errors.ts
-│   │   └── index.ts
-│   ├── utils
-│   │   ├── helpers.ts
-│   │   ├── logger.ts
-│   │   └── result.ts
-│   └── lib.ts
-├── build               # generated output (CJS, ESM, types)
+├── cli/                    # CLI entry point and utilities
+│   ├── cmd.ts              # Commander setup and action
+│   ├── config.ts           # Config file loading + CLI/merge logic
+│   ├── error.ts            # Exit codes and pretty error formatting
+│   ├── logger.ts           # File logger for CLI
+│   ├── main.ts             # Entry shim
+│   └── ui.ts               # Spinner, result printing, formatting
+├── lib/                    # Core library
+│   ├── browser/            # Playwright management & page interactions
+│   ├── config/             # Defaults and schema validation
+│   ├── core/               # Downloader logic & input validation
+│   ├── errors/             # Custom error classes and guards
+│   ├── utils/              # Helpers, logger, Result type
+│   └── lib.ts              # Public API barrel export
+├── build/                  # Generated output (CJS, ESM, types, CLI bundle)
+├── scripts/                # Build helper scripts
+├── docs/                   # Documentation site (docsify)
 ├── package.json
-└── tsconfig.json
+├── tsconfig.json
+└── rollup.config.mjs
 ```
 
 ### Scripts
 
-| Command                | Description                                         |
-| ---------------------- | --------------------------------------------------- |
-| `bun run clean`        | Remove `build/` and cache                           |
-| `bun run typecheck`    | Run `tsc --noEmit`                                  |
-| `bun run build:ts`     | Compile TypeScript to `build/`                      |
-| `bun run build:bundle` | Bundle with Rollup                                  |
-| `bun run build`        | Clean + typecheck + build:ts + build:bundle         |
-| `bun run rebuild`      | Full rebuild pipeline (clean-code + build + format) |
-| `bun run format`       | Format all files with Prettier                      |
-| `bun run test`         | Run tests (requires test files)                     |
+| Command                  | Description                                                 |
+| ------------------------ | ----------------------------------------------------------- |
+| `bun run clean`          | Remove `build/` and cache                                   |
+| `bun run typecheck`      | Run `tsc --noEmit`                                          |
+| `bun run format`         | Format all files with Prettier                              |
+| `bun run clean-code`     | Run `rmcm` to clean comments and format                     |
+| `bun run build:ts`       | Compile TypeScript to `build/` (without bundling)           |
+| `bun run build:bundle`   | Bundle library with Rollup (development)                    |
+| `bun run build:lib:prod` | Bundle library for production (minified)                    |
+| `bun run build:cli:prod` | Bundle CLI executable for production                        |
+| `bun run build:all:prod` | Bundle both library and CLI for production                  |
+| `bun run rebuild`        | Full rebuild pipeline (clean → clean-code → build → format) |
+| `bun run test`           | Run tests with Bun                                          |
+| `bun run version:patch`  | Bump patch version                                          |
+| `bun run release`        | Publish to npm (runs prepublishOnly)                        |
 
 ---
 
@@ -313,7 +439,10 @@ bun run test
 1. Fork the repository
 2. Create a feature branch (`git checkout -b feat/your-feature`)
 3. Commit changes using [Conventional Commits](https://www.conventionalcommits.org/)
-4. Push and open a Pull Request
+4. Run `bun run rebuild` to ensure everything builds and is formatted
+5. Push and open a Pull Request
+
+Please ensure your code passes type checking, formatting, and all tests.
 
 ---
 
@@ -334,4 +463,5 @@ This license ensures that any network‑distributed modifications remain open so
 
 > **Repository**: https://github.com/neuxdotdev/sfiledl  
 > **Issues**: https://github.com/neuxdotdev/sfiledl/issues  
-> **npm**: https://www.npmjs.com/package/sfiledl
+> **npm**: https://www.npmjs.com/package/sfiledl  
+> **Documentation**: https://neuxdotdev.github.io/sfiledl/