@zero-transfer/sdk 0.4.2 → 0.4.7
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/README.md +27 -22
- package/dist/index.cjs +727 -51
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.mts +146 -20
- package/dist/index.d.ts +146 -20
- package/dist/index.mjs +717 -42
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-339933?style=for-the-badge&labelColor=0d1117&logo=nodedotjs&logoColor=white" alt="Node.js"></a>
|
|
19
19
|
</p>
|
|
20
20
|
|
|
21
|
-
ZeroTransfer is a unified, TypeScript-first file transfer SDK for Node.js. One typed API speaks to every backend you actually deploy against
|
|
21
|
+
ZeroTransfer is a unified, TypeScript-first file transfer SDK for Node.js. One typed API speaks to every backend you actually deploy against - classic protocols, web endpoints, object storage, cloud drives, and local disks - with streaming, resume, verification, dry-run plans, MFT-style scheduling, audit logs, and webhook delivery built in.
|
|
22
22
|
|
|
23
23
|
```ts
|
|
24
24
|
import { createS3ProviderFactory, createTransferClient, uploadFile } from "@zero-transfer/sdk";
|
|
@@ -73,6 +73,8 @@ Requires Node.js **>=20**.
|
|
|
73
73
|
|
|
74
74
|
ZeroTransfer publishes 14 scoped packages under the [`@zero-transfer`](https://www.npmjs.com/org/zero-transfer) npm organization. [`@zero-transfer/sdk`](https://www.npmjs.com/package/@zero-transfer/sdk) is the batteries-included distribution; the other 13 are **narrowly scoped** packages that publish only the symbols listed in their [scope page](docs/scopes/README.md). Pick one to keep your dependency tree tight, or install the SDK if you want every provider in one go.
|
|
75
75
|
|
|
76
|
+
Every protocol-scoped package (everything except [`@zero-transfer/core`](https://www.npmjs.com/package/@zero-transfer/core) itself) automatically pulls in `@zero-transfer/core` as a transitive dependency and re-exports the full core surface (`createTransferClient`, `uploadFile`, `downloadFile`, profiles, errors, sync planner, …). A single `import { … } from "@zero-transfer/<scope>"` is all you need - no separate `@zero-transfer/core` install. If your app uses multiple protocols, install the umbrella [`@zero-transfer/sdk`](https://www.npmjs.com/package/@zero-transfer/sdk) instead of multiple scoped packages.
|
|
77
|
+
|
|
76
78
|
| Package | Summary | Docs |
|
|
77
79
|
| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | ----------------------------------------- |
|
|
78
80
|
| [`@zero-transfer/sdk`](https://www.npmjs.com/package/@zero-transfer/sdk) | Batteries-included distribution. Every provider, every helper. | [API reference](docs/api-md/README.md) |
|
|
@@ -189,7 +191,7 @@ scheduler.start();
|
|
|
189
191
|
|
|
190
192
|
## Connection profiles
|
|
191
193
|
|
|
192
|
-
Every operation that touches a remote system takes a [`ConnectionProfile`](docs/api-md/interfaces/ConnectionProfile.md). Profiles are provider-neutral data
|
|
194
|
+
Every operation that touches a remote system takes a [`ConnectionProfile`](docs/api-md/interfaces/ConnectionProfile.md). Profiles are provider-neutral data - you build one once and pass it to `client.connect()`, `uploadFile()`, `downloadFile()`, `copyBetween()`, MFT routes, and diagnostics. The same shape works for every provider; only the optional auth blocks (`ssh`, `tls`, `oauth`, `s3`, …) change.
|
|
193
195
|
|
|
194
196
|
### Required fields
|
|
195
197
|
|
|
@@ -217,7 +219,7 @@ Every operation that touches a remote system takes a [`ConnectionProfile`](docs/
|
|
|
217
219
|
Every credential field (`username`, `password`, `tls.ca`, `tls.key`, `ssh.privateKey`, `ssh.knownHosts`, `ssh.passphrase`, …) accepts a [`SecretSource`](docs/api-md/type-aliases/SecretSource.md). Inline strings work for prototypes, but production code should pull from the environment, a file, or a callback so secrets stay out of source control and out of process memory dumps.
|
|
218
220
|
|
|
219
221
|
```ts
|
|
220
|
-
// Inline string
|
|
222
|
+
// Inline string - fine for tests, avoid in production.
|
|
221
223
|
password: "hunter2";
|
|
222
224
|
|
|
223
225
|
// Read from an environment variable.
|
|
@@ -287,7 +289,7 @@ const dropboxProfile: ConnectionProfile = {
|
|
|
287
289
|
|
|
288
290
|
### Security guidance
|
|
289
291
|
|
|
290
|
-
- **Pin host keys for SSH/SFTP.** Without `ssh.knownHosts` or `ssh.pinnedHostKeySha256` the SSH session accepts any key the server presents
|
|
292
|
+
- **Pin host keys for SSH/SFTP.** Without `ssh.knownHosts` or `ssh.pinnedHostKeySha256` the SSH session accepts any key the server presents - a MITM risk.
|
|
291
293
|
- **Pin TLS fingerprints when you control the server.** `tls.pinnedFingerprint256` is defence-in-depth on top of `rejectUnauthorized: true` and a CA bundle.
|
|
292
294
|
- **Never set `tls.rejectUnauthorized: false` in production.** Pair self-signed servers with `tls.ca` instead.
|
|
293
295
|
- **Prefer `{ env }`, `{ path }`, or callback secrets** over inline strings or hard-coded values.
|
|
@@ -301,19 +303,19 @@ Every provider advertises its own [`CapabilitySet`](docs/api-md/interfaces/Capab
|
|
|
301
303
|
|
|
302
304
|
| Provider | Streaming | Resume | Server-side copy | Multipart upload | Checksum exposed |
|
|
303
305
|
| ------------- | :-------: | :------------------------------: | :--------------: | :--------------: | :----------------------: |
|
|
304
|
-
| FTP | ✅ | ⬆/⬇ via REST |
|
|
305
|
-
| FTPS | ✅ | ⬆/⬇ via REST |
|
|
306
|
-
| SFTP | ✅ | ⬆/⬇ | rename |
|
|
307
|
-
| HTTP(S) | ✅ (read) | ⬇ via Range |
|
|
308
|
-
| WebDAV | ✅ | ⬇ via Range | COPY |
|
|
306
|
+
| FTP | ✅ | ⬆/⬇ via REST | - | - | - |
|
|
307
|
+
| FTPS | ✅ | ⬆/⬇ via REST | - | - | - |
|
|
308
|
+
| SFTP | ✅ | ⬆/⬇ | rename | - | - |
|
|
309
|
+
| HTTP(S) | ✅ (read) | ⬇ via Range | - | - | ETag |
|
|
310
|
+
| WebDAV | ✅ | ⬇ via Range | COPY | - | ETag |
|
|
309
311
|
| S3-compatible | ✅ | ⬆ via multipart resume / ⬇ Range | CopyObject | ✅ | SHA-256 / md5 |
|
|
310
|
-
| Azure Blob | ✅ | ⬇ via Range |
|
|
311
|
-
| GCS | ✅ | ⬇ via Range |
|
|
312
|
-
| Google Drive | ✅ | ⬇ via Range |
|
|
313
|
-
| Dropbox | ✅ | ⬇ via Range |
|
|
314
|
-
| OneDrive | ✅ | ⬇ via Range |
|
|
315
|
-
| Local | ✅ | ⬆/⬇ |
|
|
316
|
-
| Memory | ✅ | ⬆/⬇ |
|
|
312
|
+
| Azure Blob | ✅ | ⬇ via Range | - | ✅ | md5 |
|
|
313
|
+
| GCS | ✅ | ⬇ via Range | - | ✅ | crc32c / md5 |
|
|
314
|
+
| Google Drive | ✅ | ⬇ via Range | - | - | md5 |
|
|
315
|
+
| Dropbox | ✅ | ⬇ via Range | - | - | content_hash |
|
|
316
|
+
| OneDrive | ✅ | ⬇ via Range | - | ✅ | sha256 / sha1 / quickXor |
|
|
317
|
+
| Local | ✅ | ⬆/⬇ | - | - | - |
|
|
318
|
+
| Memory | ✅ | ⬆/⬇ | - | - | - |
|
|
317
319
|
|
|
318
320
|
## Examples
|
|
319
321
|
|
|
@@ -323,10 +325,13 @@ Real-world examples live in [`examples/`](https://github.com/tonywied17/zero-tra
|
|
|
323
325
|
| --------------------------------------------------------------------------- | ----------------------------------------------------------------- |
|
|
324
326
|
| [`local-copy-file.ts`](examples/local-copy-file.ts) | Zero-config local-to-local copy via `copyBetween`. |
|
|
325
327
|
| [`ftp-basic.ts`](examples/ftp-basic.ts) | Plain FTP upload + download round-trip with username/password. |
|
|
328
|
+
| [`ftp-directory-ops.ts`](examples/ftp-directory-ops.ts) | FTP `session.fs`: list, stat, mkdir, rename, remove, rmdir. |
|
|
326
329
|
| [`ftps-basic.ts`](examples/ftps-basic.ts) | FTPS with username/password over a public-CA endpoint. |
|
|
327
330
|
| [`ftps-client-certificate.ts`](examples/ftps-client-certificate.ts) | FTPS hardened: mTLS + private CA bundle + fingerprint pinning. |
|
|
331
|
+
| [`ftps-directory-ops.ts`](examples/ftps-directory-ops.ts) | FTPS `session.fs`: list, stat, mkdir, rename, remove, rmdir. |
|
|
328
332
|
| [`sftp-basic.ts`](examples/sftp-basic.ts) | Minimal SFTP with username/password (no host-key pinning). |
|
|
329
333
|
| [`sftp-private-key.ts`](examples/sftp-private-key.ts) | SFTP hardened: private-key auth + pinned host-key SHA-256. |
|
|
334
|
+
| [`sftp-directory-ops.ts`](examples/sftp-directory-ops.ts) | SFTP `session.fs`: list, stat, mkdir, rename, remove, rmdir. |
|
|
330
335
|
| [`ssh-exec-command.ts`](examples/ssh-exec-command.ts) | Standalone SSH stack: handshake, auth, run a remote command. |
|
|
331
336
|
| [`s3-compatible-upload.ts`](examples/s3-compatible-upload.ts) | S3 multipart upload with cross-process resume store. |
|
|
332
337
|
| [`webdav-sync.ts`](examples/webdav-sync.ts) | WebDAV diff + sync plan with deterministic ordering. |
|
|
@@ -342,10 +347,10 @@ Real-world examples live in [`examples/`](https://github.com/tonywied17/zero-tra
|
|
|
342
347
|
|
|
343
348
|
## Documentation
|
|
344
349
|
|
|
345
|
-
- [Full API reference (HTML)](https://tonywied17.github.io/zero-transfer/)
|
|
346
|
-
- [Full API reference (Markdown)](docs/api-md/README.md)
|
|
347
|
-
- [Per-scope pages](docs/scopes/README.md)
|
|
348
|
-
- [Examples directory](https://github.com/tonywied17/zero-transfer/tree/main/examples)
|
|
350
|
+
- [Full API reference (HTML)](https://tonywied17.github.io/zero-transfer/) - TypeDoc HTML site, deployed from `main` on every push.
|
|
351
|
+
- [Full API reference (Markdown)](docs/api-md/README.md) - every public symbol with parameter / property / type tables.
|
|
352
|
+
- [Per-scope pages](docs/scopes/README.md) - one page per `@zero-transfer/*` package.
|
|
353
|
+
- [Examples directory](https://github.com/tonywied17/zero-transfer/tree/main/examples) - runnable real-world flows.
|
|
349
354
|
|
|
350
355
|
Regenerate everything locally:
|
|
351
356
|
|
|
@@ -355,7 +360,7 @@ npm run docs:all # HTML + Markdown api refs + per-scope pages + per-package
|
|
|
355
360
|
|
|
356
361
|
## Project status
|
|
357
362
|
|
|
358
|
-
ZeroTransfer is in **alpha** under the `alpha` npm dist-tag. The provider-neutral foundation, transfer engine, queue, sync planner, atomic deploy planner, MFT layer, friendly client surface, and diagnostics module are stable.
|
|
363
|
+
ZeroTransfer is in **alpha** under the `alpha` npm dist-tag. The provider-neutral foundation, transfer engine, queue, sync planner, atomic deploy planner, MFT layer, friendly client surface, and diagnostics module are stable. Multipart / resumable upload sessions are now wired up across S3, Azure Blob, GCS, and OneDrive. Phase work in progress: broader real-server compatibility coverage and the push to higher coverage targets.
|
|
359
364
|
|
|
360
365
|
## Contributing
|
|
361
366
|
|
|
@@ -367,7 +372,7 @@ npm run ci # lint, format check, typecheck, tests with coverage, build,
|
|
|
367
372
|
npm run test:watch # iterate
|
|
368
373
|
```
|
|
369
374
|
|
|
370
|
-
Issues and PRs welcome. Provider integration tests are gated behind opt-in env vars
|
|
375
|
+
Issues and PRs welcome. Provider integration tests are gated behind opt-in env vars - see [`test/integration/`](https://github.com/tonywied17/zero-transfer/tree/main/test/integration) for the full list.
|
|
371
376
|
|
|
372
377
|
## License
|
|
373
378
|
|