sfiledl 2.2.4 → 2.2.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,12 +1,15 @@
1
1
  {
2
2
  "name": "sfiledl",
3
- "version": "2.2.4",
3
+ "version": "2.2.6",
4
4
  "description": "Implement and automate downloading of any file from sfile.co with javascripts library, written entirely in typescripts",
5
5
  "type": "module",
6
6
  "main": "./build/lib.cjs",
7
7
  "module": "./build/lib.mjs",
8
8
  "types": "./build/lib.d.ts",
9
- "license": "AGPL-3.0-only",
9
+ "bin": {
10
+ "sfiledl": "./build/cli.mjs"
11
+ },
12
+ "license": "MIT",
10
13
  "files": [
11
14
  "build",
12
15
  "readme.md",
@@ -14,7 +17,7 @@
14
17
  ],
15
18
  "sideEffects": false,
16
19
  "engines": {
17
- "node": ">=24",
20
+ "node": ">=18",
18
21
  "bun": ">=1.3"
19
22
  },
20
23
  "publishConfig": {
@@ -30,22 +33,43 @@
30
33
  "scripts": {
31
34
  "clean": "rm -rf build node_modules/.cache",
32
35
  "typecheck": "tsc --noEmit",
33
- "build:ts": "tsc",
34
- "build:bundle": "rollup -c rollup.config.ts --configPlugin typescript",
35
- "build": "bun run clean && bun run typecheck && bun run build:ts && bun run build:bundle",
36
- "dev:ts": "tsc --emitDeclarationOnly --outDir build --watch",
37
- "build:prod": "NODE_ENV=production bun run build",
38
- "dev": "rollup -c -w --bundleConfigAsCjs",
39
- "format:build": "bun ./scripts/format-build.ts",
40
36
  "lint": "tsc --noEmit",
41
37
  "format": "prettier . --write",
42
38
  "format:check": "prettier . --check",
43
39
  "clean-code": "rmcm -l js -i -c 0 -r ./lib --verbose && bun run format",
44
- "rebuild": "bun run clean && bun run clean-code && bun run build && bun run format:build",
45
- "test": "bun test",
46
- "prepublishOnly": "bun run build && chmod +x build/lib.mjs",
40
+ "build:ts": "tsc",
41
+ "build:bundle": "NODE_ENV=rollup -c rollup.config.mjs",
42
+ "build:bundle:prod": "NODE_ENV=production rollup -c rollup.config.mjs",
43
+ "build:bundle:analyze": "ANALYZE=true rollup -c rollup.config.mjs",
44
+ "build:bundle:small": "PROFILE=small NODE_ENV=production rollup -c rollup.config.mjs",
45
+ "build:bundle:perf": "PROFILE=performance NODE_ENV=production rollup -c rollup.config.mjs",
46
+ "build:lib": "bun run typecheck && bun run build:bundle",
47
+ "build:lib:prod": "bun run typecheck && bun run build:bundle:prod",
48
+ "build:lib:analyze": "bun run build:bundle:analyze",
49
+ "build:cli": "TARGET=cli rollup -c rollup.config.mjs",
50
+ "build:cli:prod": "NODE_ENV=production TARGET=cli rollup -c rollup.config.mjs",
51
+ "build:cli:analyze": "ANALYZE=true TARGET=cli rollup -c rollup.config.mjs",
52
+ "build:all": "TARGET=all rollup -c rollup.config.mjs",
53
+ "build:all:prod": "NODE_ENV=production TARGET=all rollup -c rollup.config.mjs",
54
+ "build:all:analyze": "ANALYZE=true TARGET=all rollup -c rollup.config.mjs",
55
+ "build:browser": "BROWSER=true NODE_ENV=production TARGET=lib rollup -c rollup.config.mjs",
56
+ "compile:clitests/cli/error.spec.ts": "bun run scripts/compile-bin.ts",
57
+ "dev": "rollup -c rollup.config.mjs -w",
58
+ "dev:cli": "TARGET=cli rollup -c rollup.config.mjs -w",
59
+ "dev:lib": "rollup -c rollup.config.mjs -w",
60
+ "serve": "bun run build:lib && npx serve build",
61
+ "prepublishOnly": "bun run build:all:prod && chmod +x build/cli.mjs build/lib.mjs",
47
62
  "prepare": "husky install || true",
48
- "install:playwright": "bunx playwright install chromium"
63
+ "install:playwright": "bunx playwright install chromium",
64
+ "test": "bun test",
65
+ "test:coverage": "bun test --coverage",
66
+ "rebuild": "bun run clean && bun run clean-code && bun run clean-code-all-root &&bun run build:all:prod && bun run format:build",
67
+ "format:build": "bun ./scripts/format-build.ts",
68
+ "version:patch": "bun version patch",
69
+ "version:minor": "bun version minor",
70
+ "version:major": "bun version major",
71
+ "release": "bun run prepublishOnly && npm publish",
72
+ "clean-code-all-root": "rmcm -l js -i -r -c 0 ./lib/**/* ./cli/* && bun run format"
49
73
  },
50
74
  "keywords": [
51
75
  "sfile",
@@ -66,6 +90,10 @@
66
90
  },
67
91
  "homepage": "https://neuxdotdev.github.io/sfiledl/",
68
92
  "dependencies": {
93
+ "chalk": "^5.6.2",
94
+ "cli-progress": "^3.12.0",
95
+ "commander": "^14.0.3",
96
+ "ora": "^9.3.0",
69
97
  "playwright": "^1.59.1"
70
98
  },
71
99
  "devDependencies": {
@@ -73,18 +101,27 @@
73
101
  "@rollup/plugin-json": "^6.1.0",
74
102
  "@rollup/plugin-node-resolve": "^16.0.3",
75
103
  "@rollup/plugin-replace": "^6.0.3",
104
+ "@rollup/plugin-run": "^3.1.0",
105
+ "@rollup/plugin-strip": "^3.0.4",
76
106
  "@rollup/plugin-terser": "^1.0.0",
77
107
  "@rollup/plugin-typescript": "^12.3.0",
78
- "@types/node": "^25.5.0",
108
+ "@types/node": "^25.5.1",
79
109
  "@types/rollup-plugin-peer-deps-external": "^2.2.6",
80
110
  "docsify-cli": "^4.4.4",
81
111
  "dts-bundle-generator": "^9.5.1",
82
- "esbuild": "^0.27.5",
112
+ "esbuild": "^0.28.0",
83
113
  "husky": "^9.1.7",
84
114
  "prettier": "^3.8.1",
85
115
  "rollup": "^4.60.1",
116
+ "rollup-plugin-copy": "^3.5.0",
86
117
  "rollup-plugin-dts": "^6.4.1",
118
+ "rollup-plugin-filesize": "^10.0.0",
119
+ "rollup-plugin-generate-package-json": "^3.2.0",
120
+ "rollup-plugin-license": "^3.7.0",
121
+ "rollup-plugin-livereload": "^2.0.5",
122
+ "rollup-plugin-node-externals": "^8.1.2",
87
123
  "rollup-plugin-peer-deps-external": "^2.2.4",
124
+ "rollup-plugin-serve": "^3.0.0",
88
125
  "rollup-plugin-visualizer": "^7.0.1",
89
126
  "tslib": "^2.8.1",
90
127
  "typescript": "^6.0.2"
package/readme.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # sfiledl
2
2
 
3
- > Automate file downloads from [sfile.co](https://sfile.co/) — reliable, retry‑aware, and fully typed.
3
+ > **Automate file downloads from [sfile.co](https://sfile.co) — reliable, retry‑aware, and fully typed.**
4
4
 
5
5
  <p align="center">
6
6
  <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>
@@ -10,29 +10,26 @@
10
10
  <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>
11
11
  <a href="https://playwright.dev"><img src="https://img.shields.io/badge/Playwright-1.59-green?style=flat-square&logo=playwright" alt="Playwright"></a>
12
12
  <a href="https://bun.sh"><img src="https://img.shields.io/badge/Bun-1.3+-black?style=flat-square&logo=bun" alt="Bun"></a>
13
- <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-%3E%3D24-green?style=flat-square&logo=node.js" alt="Node"></a>
13
+ <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>
14
14
  <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>
15
15
  <a href="http://makeapullrequest.com"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" alt="PRs welcome"></a>
16
16
  </p>
17
17
 
18
- <p align="center">
19
- <a href="https://github.com/neuxdotdev/sfiledl/actions/workflows/build.yml"><img src="https://github.com/neuxdotdev/sfiledl/actions/workflows/build.yml/badge.svg" alt="Build"></a>
20
- <a href="https://github.com/neuxdotdev/sfiledl/actions/workflows/pages/pages-build-deployment"><img src="https://github.com/neuxdotdev/sfiledl/actions/workflows/pages/pages-build-deployment/badge.svg" alt="pages-build-deployment"></a>
21
- <a href="https://github.com/neuxdotdev/sfiledl/actions/workflows/rmcm-install.yml"><img src="https://github.com/neuxdotdev/sfiledl/actions/workflows/rmcm-install.yml/badge.svg" alt="Setup RMCM"></a>
22
- </p>
23
-
24
18
  ---
25
19
 
26
20
  ## Table of Contents
27
21
 
28
22
  - [Installation](#installation)
29
23
  - [Quick Start](#quick-start)
30
- - [API Reference](#api-reference)
31
- - [downloadSfile](#downloadsfile)
32
- - [downloadSfileSafe](#downloadsfilesafe)
33
- - [createDownloader](#createdownloader)
34
- - [DownloadOptions](#downloadoptions)
35
- - [DownloadResult](#downloadresult)
24
+ - [CLI Usage](#cli-usage)
25
+ - [Command Line Options](#command-line-options)
26
+ - [Configuration File](#configuration-file)
27
+ - [Library API](#library-api)
28
+ - [`downloadSfile`](#downloadsfile)
29
+ - [`downloadSfileSafe`](#downloadsfilesafe)
30
+ - [`createDownloader`](#createdownloader)
31
+ - [`DownloadOptions`](#downloadoptions)
32
+ - [`DownloadResult`](#downloadresult)
36
33
  - [Error Handling](#error-handling)
37
34
  - [Error Types](#error-types)
38
35
  - [Retryable Errors](#retryable-errors)
@@ -56,16 +53,18 @@ bun add sfiledl
56
53
  # Using npm
57
54
  npm install sfiledl
58
55
 
59
- # Install Playwright browser (required)
56
+ # Install Playwright browser (required once)
60
57
  bunx playwright install chromium # or npx playwright install chromium
61
58
  ```
62
59
 
63
- **Prerequisites:** Node.js >=24 or Bun >=1.3.
60
+ **Prerequisites:** Node.js >=18 or Bun >=1.3.
64
61
 
65
62
  ---
66
63
 
67
64
  ## Quick Start
68
65
 
66
+ ### As a library
67
+
69
68
  ```typescript
70
69
  import { downloadSfile } from 'sfiledl'
71
70
 
@@ -82,25 +81,122 @@ console.log(result)
82
81
  // }
83
82
  ```
84
83
 
84
+ ### As a CLI tool
85
+
86
+ ```bash
87
+ # Basic usage
88
+ sfiledl https://sfile.co/abc123
89
+
90
+ # Specify output directory
91
+ sfiledl https://sfile.co/abc123 -o ~/Downloads
92
+
93
+ # Show browser window and enable debug
94
+ sfiledl https://sfile.co/abc123 --headed --debug
95
+
96
+ # Adjust retries and delays
97
+ sfiledl https://sfile.co/abc123 -r 5 -d 2000
98
+
99
+ # See help
100
+ sfiledl --help
101
+ ```
102
+
85
103
  ---
86
104
 
87
- ## API Reference
105
+ ## CLI Usage
88
106
 
89
- ### `downloadSfile(url, saveDir, options?)`
107
+ The CLI provides a fully featured interface to the downloader.
90
108
 
91
- Main download function. Throws errors on failure (see [Error Handling](#error-handling)).
109
+ ```bash
110
+ sfiledl [options] <url>
111
+ ```
112
+
113
+ ### Command Line Options
114
+
115
+ | Option | Alias | Type | Default | Description |
116
+ | -------------------------- | ----- | -------- | ----------------- | -------------------------------------- |
117
+ | `<url>` | – | required | – | sfile.co download URL |
118
+ | `--output <dir>` | `-o` | string | `./downloads` | Save directory |
119
+ | `--headed` | – | boolean | `false` | Show browser window (disable headless) |
120
+ | `--timeout <ms>` | `-t` | number | `60000` | Navigation timeout (ms, ≥1000) |
121
+ | `--button-timeout <ms>` | – | number | `30000` | Download button wait timeout (ms) |
122
+ | `--retries <n>` | `-r` | number | `3` | Maximum retry attempts |
123
+ | `--retry-delay <ms>` | `-d` | number | `1000` | Base retry delay (exponential backoff) |
124
+ | `--debug` | – | boolean | `false` | Enable debug logs and artifacts |
125
+ | `--ua, --user-agent <str>` | – | string | Chrome on Windows | Custom User‑Agent header |
126
+ | `--no-progress` | – | boolean | `false` | Disable progress spinner |
127
+ | `--log-file <path>` | – | string | – | Write structured logs to file |
128
+ | `--no-artifacts` | – | boolean | `true` | Skip saving debug artifacts on error |
129
+ | `-v, --version` | – | – | – | Show version |
130
+ | `-h, --help` | – | – | – | Show help |
131
+
132
+ ### Configuration File
133
+
134
+ You can set default options using a JSON configuration file in the current working directory.
135
+ Supported files: `.sfiledlrc.json` or `.sfiledlrc` (`.json` takes precedence).
136
+
137
+ Example `.sfiledlrc.json`:
138
+
139
+ ```json
140
+ {
141
+ "output": "./downloads",
142
+ "retries": 5,
143
+ "debug": true,
144
+ "headless": false,
145
+ "timeout": 120000,
146
+ "userAgent": "MyCustomAgent/1.0"
147
+ }
148
+ ```
149
+
150
+ CLI options always override file configuration.
151
+
152
+ ---
153
+
154
+ ## Library API
155
+
156
+ The library exports several functions and types for programmatic usage.
92
157
 
93
- | Param | Type | Description |
94
- | --------- | ----------------- | -------------------------------------- |
95
- | `url` | `string` | sfile.co URL (must contain the domain) |
96
- | `saveDir` | `string` | Directory where the file will be saved |
97
- | `options` | `DownloadOptions` | Optional configuration |
158
+ ### `downloadSfile`
98
159
 
99
- **Returns:** `Promise<DownloadResult>`
160
+ Main download function. Throws errors on failure.
100
161
 
101
- ### `downloadSfileSafe(url, saveDir, options?)`
162
+ ```typescript
163
+ function downloadSfile(
164
+ url: string,
165
+ saveDir: string,
166
+ options?: DownloadOptions,
167
+ ): Promise<DownloadResult>
168
+ ```
102
169
 
103
- Same as `downloadSfile` but never throws. Returns a `Result` object.
170
+ **Example:**
171
+
172
+ ```typescript
173
+ import { downloadSfile } from 'sfiledl'
174
+
175
+ try {
176
+ const result = await downloadSfile('https://sfile.co/file/xyz', './out', {
177
+ headless: true,
178
+ retries: 2,
179
+ onProgress: (percent) => console.log(`${percent}%`),
180
+ })
181
+ console.log('Downloaded:', result.filePath)
182
+ } catch (err) {
183
+ console.error('Failed:', err.message)
184
+ }
185
+ ```
186
+
187
+ ### `downloadSfileSafe`
188
+
189
+ Same as `downloadSfile` but never throws – returns a `Result` object.
190
+
191
+ ```typescript
192
+ function downloadSfileSafe(
193
+ url: string,
194
+ saveDir: string,
195
+ options?: DownloadOptions,
196
+ ): Promise<Result<DownloadResult, Error>>
197
+ ```
198
+
199
+ **Example:**
104
200
 
105
201
  ```typescript
106
202
  import { downloadSfileSafe, isSuccess } from 'sfiledl'
@@ -113,19 +209,30 @@ if (isSuccess(res)) {
113
209
  }
114
210
  ```
115
211
 
116
- ### `createDownloader(defaultOptions?)`
212
+ ### `createDownloader`
117
213
 
118
214
  Creates a reusable downloader with preset options.
119
215
 
120
216
  ```typescript
121
- const dl = createDownloader({ headless: false, debug: true })
122
- const result = await dl.download('https://sfile.co/file/xyz', './out')
217
+ function createDownloader(defaultOptions?: DownloadOptions): {
218
+ download: (url: string, saveDir: string, options?: DownloadOptions) => Promise<DownloadResult>
219
+ downloadSafe: (
220
+ url: string,
221
+ saveDir: string,
222
+ options?: DownloadOptions,
223
+ ) => Promise<Result<DownloadResult, Error>>
224
+ withOptions: (newDefaults: Partial<DownloadOptions>) => ReturnType<typeof createDownloader>
225
+ }
226
+ ```
227
+
228
+ **Example:**
123
229
 
124
- // safe variant
125
- const safeResult = await dl.downloadSafe(url, './out')
230
+ ```typescript
231
+ const dl = createDownloader({ headless: false, debug: true })
232
+ const result = await dl.download('https://sfile.co/file/abc', './downloads')
126
233
 
127
- // chain new defaults
128
234
  const quietDl = dl.withOptions({ debug: false })
235
+ await quietDl.download('https://sfile.co/file/xyz', './downloads')
129
236
  ```
130
237
 
131
238
  ### `DownloadOptions`
@@ -161,7 +268,7 @@ All options are optional.
161
268
 
162
269
  ## Error Handling
163
270
 
164
- All errors extend `AppError` and include:
271
+ All errors thrown by the library extend `AppError` and include:
165
272
 
166
273
  - `code` – unique string identifier
167
274
  - `retryable` – `true` for network/browser issues, `false` for validation/file errors
@@ -211,6 +318,8 @@ Set `debug: true` in options to enable:
211
318
  await downloadSfile(url, './out', { debug: true, saveDebugArtifacts: true })
212
319
  ```
213
320
 
321
+ In the CLI, use `--debug` and `--no-artifacts` to control behavior.
322
+
214
323
  ---
215
324
 
216
325
  ## Logging & Correlation
@@ -263,53 +372,65 @@ cd sfiledl
263
372
  bun install
264
373
  bunx playwright install chromium
265
374
 
266
- # Full rebuild (clean, typecheck, build, format)
375
+ # Full rebuild (clean, typecheck, bundle, format)
267
376
  bun run rebuild
268
377
 
269
- # Run tests (if available)
378
+ # Run tests
270
379
  bun run test
380
+
381
+ # Build only library (CJS, ESM, types)
382
+ bun run build:lib
383
+
384
+ # Build only CLI bundle
385
+ bun run build:cli
386
+
387
+ # Build everything (library + CLI)
388
+ bun run build:all
271
389
  ```
272
390
 
273
391
  ### Project Structure
274
392
 
275
393
  ```
276
394
  .
277
- ├── lib
278
- │ ├── browser
279
- ├── browser-manager.ts
280
- │ └── page-interactions.ts
281
- │ ├── config
282
- ├── defaults.ts
283
- └── schema.ts
284
- ├── core
285
- ├── downloader.ts
286
- │ └── validator.ts
287
- │ ├── errors
288
- ├── base.ts
289
- ├── errors.ts
290
- └── index.ts
291
- ├── utils
292
- │ │ ├── helpers.ts
293
- │ │ ├── logger.ts
294
- │ │ └── result.ts
295
- │ └── lib.ts
296
- ├── build # generated output (CJS, ESM, types)
395
+ ├── cli/ # CLI entry point and utilities
396
+ │ ├── cmd.ts # Commander setup and action
397
+ │ ├── config.ts # Config file loading + CLI/merge logic
398
+ ├── error.ts # Exit codes and pretty error formatting
399
+ │ ├── logger.ts # File logger for CLI
400
+ │ ├── main.ts # Entry shim
401
+ │ └── ui.ts # Spinner, result printing, formatting
402
+ ├── lib/ # Core library
403
+ │ ├── browser/ # Playwright management & page interactions
404
+ ├── config/ # Defaults and schema validation
405
+ │ ├── core/ # Downloader logic & input validation
406
+ │ ├── errors/ # Custom error classes and guards
407
+ │ ├── utils/ # Helpers, logger, Result type
408
+ │ └── lib.ts # Public API barrel export
409
+ ├── build/ # Generated output (CJS, ESM, types, CLI bundle)
410
+ ├── scripts/ # Build helper scripts
411
+ ├── docs/ # Documentation site (docsify)
297
412
  ├── package.json
298
- └── tsconfig.json
413
+ ├── tsconfig.json
414
+ └── rollup.config.mjs
299
415
  ```
300
416
 
301
417
  ### Scripts
302
418
 
303
- | Command | Description |
304
- | ---------------------- | --------------------------------------------------- |
305
- | `bun run clean` | Remove `build/` and cache |
306
- | `bun run typecheck` | Run `tsc --noEmit` |
307
- | `bun run build:ts` | Compile TypeScript to `build/` |
308
- | `bun run build:bundle` | Bundle with Rollup |
309
- | `bun run build` | Clean + typecheck + build:ts + build:bundle |
310
- | `bun run rebuild` | Full rebuild pipeline (clean-code + build + format) |
311
- | `bun run format` | Format all files with Prettier |
312
- | `bun run test` | Run tests (requires test files) |
419
+ | Command | Description |
420
+ | ------------------------ | ----------------------------------------------------------- |
421
+ | `bun run clean` | Remove `build/` and cache |
422
+ | `bun run typecheck` | Run `tsc --noEmit` |
423
+ | `bun run format` | Format all files with Prettier |
424
+ | `bun run clean-code` | Run `rmcm` to clean comments and format |
425
+ | `bun run build:ts` | Compile TypeScript to `build/` (without bundling) |
426
+ | `bun run build:bundle` | Bundle library with Rollup (development) |
427
+ | `bun run build:lib:prod` | Bundle library for production (minified) |
428
+ | `bun run build:cli:prod` | Bundle CLI executable for production |
429
+ | `bun run build:all:prod` | Bundle both library and CLI for production |
430
+ | `bun run rebuild` | Full rebuild pipeline (clean → clean-code → build → format) |
431
+ | `bun run test` | Run tests with Bun |
432
+ | `bun run version:patch` | Bump patch version |
433
+ | `bun run release` | Publish to npm (runs prepublishOnly) |
313
434
 
314
435
  ---
315
436
 
@@ -318,13 +439,16 @@ bun run test
318
439
  1. Fork the repository
319
440
  2. Create a feature branch (`git checkout -b feat/your-feature`)
320
441
  3. Commit changes using [Conventional Commits](https://www.conventionalcommits.org/)
321
- 4. Push and open a Pull Request
442
+ 4. Run `bun run rebuild` to ensure everything builds and is formatted
443
+ 5. Push and open a Pull Request
444
+
445
+ Please ensure your code passes type checking, formatting, and all tests.
322
446
 
323
447
  ---
324
448
 
325
449
  ## License
326
450
 
327
- **AGPL-3.0-only** – see [LICENSE](license) for details.
451
+ **MIT LICENSE** – see [LICENSE](license) for details.
328
452
  This license ensures that any network‑distributed modifications remain open source.
329
453
 
330
454
  ---
@@ -339,4 +463,5 @@ This license ensures that any network‑distributed modifications remain open so
339
463
 
340
464
  > **Repository**: https://github.com/neuxdotdev/sfiledl
341
465
  > **Issues**: https://github.com/neuxdotdev/sfiledl/issues
342
- > **npm**: https://www.npmjs.com/package/sfiledl
466
+ > **npm**: https://www.npmjs.com/package/sfiledl
467
+ > **Documentation**: https://neuxdotdev.github.io/sfiledl/