@zero-transfer/sdk 0.4.2 → 0.4.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/README.md +25 -22
- package/dist/index.cjs +724 -46
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.mts +141 -15
- package/dist/index.d.ts +141 -15
- package/dist/index.mjs +714 -38
- 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";
|
|
@@ -189,7 +189,7 @@ scheduler.start();
|
|
|
189
189
|
|
|
190
190
|
## Connection profiles
|
|
191
191
|
|
|
192
|
-
Every operation that touches a remote system takes a [`ConnectionProfile`](docs/api-md/interfaces/ConnectionProfile.md). Profiles are provider-neutral data
|
|
192
|
+
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
193
|
|
|
194
194
|
### Required fields
|
|
195
195
|
|
|
@@ -217,7 +217,7 @@ Every operation that touches a remote system takes a [`ConnectionProfile`](docs/
|
|
|
217
217
|
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
218
|
|
|
219
219
|
```ts
|
|
220
|
-
// Inline string
|
|
220
|
+
// Inline string - fine for tests, avoid in production.
|
|
221
221
|
password: "hunter2";
|
|
222
222
|
|
|
223
223
|
// Read from an environment variable.
|
|
@@ -287,7 +287,7 @@ const dropboxProfile: ConnectionProfile = {
|
|
|
287
287
|
|
|
288
288
|
### Security guidance
|
|
289
289
|
|
|
290
|
-
- **Pin host keys for SSH/SFTP.** Without `ssh.knownHosts` or `ssh.pinnedHostKeySha256` the SSH session accepts any key the server presents
|
|
290
|
+
- **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
291
|
- **Pin TLS fingerprints when you control the server.** `tls.pinnedFingerprint256` is defence-in-depth on top of `rejectUnauthorized: true` and a CA bundle.
|
|
292
292
|
- **Never set `tls.rejectUnauthorized: false` in production.** Pair self-signed servers with `tls.ca` instead.
|
|
293
293
|
- **Prefer `{ env }`, `{ path }`, or callback secrets** over inline strings or hard-coded values.
|
|
@@ -301,19 +301,19 @@ Every provider advertises its own [`CapabilitySet`](docs/api-md/interfaces/Capab
|
|
|
301
301
|
|
|
302
302
|
| Provider | Streaming | Resume | Server-side copy | Multipart upload | Checksum exposed |
|
|
303
303
|
| ------------- | :-------: | :------------------------------: | :--------------: | :--------------: | :----------------------: |
|
|
304
|
-
| FTP | ✅ | ⬆/⬇ via REST |
|
|
305
|
-
| FTPS | ✅ | ⬆/⬇ via REST |
|
|
306
|
-
| SFTP | ✅ | ⬆/⬇ | rename |
|
|
307
|
-
| HTTP(S) | ✅ (read) | ⬇ via Range |
|
|
308
|
-
| WebDAV | ✅ | ⬇ via Range | COPY |
|
|
304
|
+
| FTP | ✅ | ⬆/⬇ via REST | - | - | - |
|
|
305
|
+
| FTPS | ✅ | ⬆/⬇ via REST | - | - | - |
|
|
306
|
+
| SFTP | ✅ | ⬆/⬇ | rename | - | - |
|
|
307
|
+
| HTTP(S) | ✅ (read) | ⬇ via Range | - | - | ETag |
|
|
308
|
+
| WebDAV | ✅ | ⬇ via Range | COPY | - | ETag |
|
|
309
309
|
| 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 | ✅ | ⬆/⬇ |
|
|
310
|
+
| Azure Blob | ✅ | ⬇ via Range | - | ✅ | md5 |
|
|
311
|
+
| GCS | ✅ | ⬇ via Range | - | ✅ | crc32c / md5 |
|
|
312
|
+
| Google Drive | ✅ | ⬇ via Range | - | - | md5 |
|
|
313
|
+
| Dropbox | ✅ | ⬇ via Range | - | - | content_hash |
|
|
314
|
+
| OneDrive | ✅ | ⬇ via Range | - | ✅ | sha256 / sha1 / quickXor |
|
|
315
|
+
| Local | ✅ | ⬆/⬇ | - | - | - |
|
|
316
|
+
| Memory | ✅ | ⬆/⬇ | - | - | - |
|
|
317
317
|
|
|
318
318
|
## Examples
|
|
319
319
|
|
|
@@ -323,10 +323,13 @@ Real-world examples live in [`examples/`](https://github.com/tonywied17/zero-tra
|
|
|
323
323
|
| --------------------------------------------------------------------------- | ----------------------------------------------------------------- |
|
|
324
324
|
| [`local-copy-file.ts`](examples/local-copy-file.ts) | Zero-config local-to-local copy via `copyBetween`. |
|
|
325
325
|
| [`ftp-basic.ts`](examples/ftp-basic.ts) | Plain FTP upload + download round-trip with username/password. |
|
|
326
|
+
| [`ftp-directory-ops.ts`](examples/ftp-directory-ops.ts) | FTP `session.fs`: list, stat, mkdir, rename, remove, rmdir. |
|
|
326
327
|
| [`ftps-basic.ts`](examples/ftps-basic.ts) | FTPS with username/password over a public-CA endpoint. |
|
|
327
328
|
| [`ftps-client-certificate.ts`](examples/ftps-client-certificate.ts) | FTPS hardened: mTLS + private CA bundle + fingerprint pinning. |
|
|
329
|
+
| [`ftps-directory-ops.ts`](examples/ftps-directory-ops.ts) | FTPS `session.fs`: list, stat, mkdir, rename, remove, rmdir. |
|
|
328
330
|
| [`sftp-basic.ts`](examples/sftp-basic.ts) | Minimal SFTP with username/password (no host-key pinning). |
|
|
329
331
|
| [`sftp-private-key.ts`](examples/sftp-private-key.ts) | SFTP hardened: private-key auth + pinned host-key SHA-256. |
|
|
332
|
+
| [`sftp-directory-ops.ts`](examples/sftp-directory-ops.ts) | SFTP `session.fs`: list, stat, mkdir, rename, remove, rmdir. |
|
|
330
333
|
| [`ssh-exec-command.ts`](examples/ssh-exec-command.ts) | Standalone SSH stack: handshake, auth, run a remote command. |
|
|
331
334
|
| [`s3-compatible-upload.ts`](examples/s3-compatible-upload.ts) | S3 multipart upload with cross-process resume store. |
|
|
332
335
|
| [`webdav-sync.ts`](examples/webdav-sync.ts) | WebDAV diff + sync plan with deterministic ordering. |
|
|
@@ -342,10 +345,10 @@ Real-world examples live in [`examples/`](https://github.com/tonywied17/zero-tra
|
|
|
342
345
|
|
|
343
346
|
## Documentation
|
|
344
347
|
|
|
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)
|
|
348
|
+
- [Full API reference (HTML)](https://tonywied17.github.io/zero-transfer/) - TypeDoc HTML site, deployed from `main` on every push.
|
|
349
|
+
- [Full API reference (Markdown)](docs/api-md/README.md) - every public symbol with parameter / property / type tables.
|
|
350
|
+
- [Per-scope pages](docs/scopes/README.md) - one page per `@zero-transfer/*` package.
|
|
351
|
+
- [Examples directory](https://github.com/tonywied17/zero-transfer/tree/main/examples) - runnable real-world flows.
|
|
349
352
|
|
|
350
353
|
Regenerate everything locally:
|
|
351
354
|
|
|
@@ -355,7 +358,7 @@ npm run docs:all # HTML + Markdown api refs + per-scope pages + per-package
|
|
|
355
358
|
|
|
356
359
|
## Project status
|
|
357
360
|
|
|
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.
|
|
361
|
+
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
362
|
|
|
360
363
|
## Contributing
|
|
361
364
|
|
|
@@ -367,7 +370,7 @@ npm run ci # lint, format check, typecheck, tests with coverage, build,
|
|
|
367
370
|
npm run test:watch # iterate
|
|
368
371
|
```
|
|
369
372
|
|
|
370
|
-
Issues and PRs welcome. Provider integration tests are gated behind opt-in env vars
|
|
373
|
+
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
374
|
|
|
372
375
|
## License
|
|
373
376
|
|