@zero-transfer/sdk 0.4.6 → 0.4.8
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 -11
- package/assets/zero-transfer-icon.svg +117 -0
- package/dist/index.cjs +641 -166
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.mts +302 -49
- package/dist/index.d.ts +302 -49
- package/dist/index.mjs +637 -165
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -8,23 +8,33 @@
|
|
|
8
8
|
</p>
|
|
9
9
|
|
|
10
10
|
<p align="center">
|
|
11
|
-
<a href="https://www.npmjs.com/package/@zero-transfer/sdk"><img src="https://
|
|
12
|
-
<a href="https://www.npmjs.com/package/@zero-transfer/sdk"><img src="https://
|
|
13
|
-
<a href="https://
|
|
14
|
-
<a href="https://github.com/tonywied17/zero-transfer/actions/workflows/ci.yml"><img src="https://
|
|
15
|
-
<a href="https://github.com/tonywied17/zero-transfer/actions/workflows/ci.yml"><img src="https://
|
|
16
|
-
<a href="https://
|
|
17
|
-
<a href="https://
|
|
18
|
-
<a href="https://
|
|
11
|
+
<a href="https://www.npmjs.com/package/@zero-transfer/sdk"><img src="https://raw.githubusercontent.com/tonywied17/tonywied17/main/.github/badges/zero-transfer-sdk-name-ztransfer.svg?v=b4a11882" alt="@zero-transfer/sdk"></a>
|
|
12
|
+
<a href="https://www.npmjs.com/package/@zero-transfer/sdk"><img src="https://raw.githubusercontent.com/tonywied17/tonywied17/main/.github/badges/zero-transfer-npm-ztransfer.svg?v=dcdd2f85" alt="npm version"></a>
|
|
13
|
+
<a href="https://www.npmjs.com/package/@zero-transfer/sdk"><img src="https://raw.githubusercontent.com/tonywied17/tonywied17/main/.github/badges/zero-transfer-dm-ztransfer.svg?v=95e529bf" alt="npm downloads"></a>
|
|
14
|
+
<a href="https://github.com/tonywied17/zero-transfer/actions/workflows/ci.yml"><img src="https://raw.githubusercontent.com/tonywied17/tonywied17/main/.github/badges/zero-transfer-ci-ztransfer.svg?v=0f1377d5" alt="CI"></a>
|
|
15
|
+
<a href="https://github.com/tonywied17/zero-transfer/actions/workflows/ci.yml"><img src="https://raw.githubusercontent.com/tonywied17/tonywied17/main/.github/badges/zero-transfer-tests-ztransfer.svg?v=bce5671a" alt="Tests"></a>
|
|
16
|
+
<a href="https://github.com/tonywied17/zero-transfer/actions/workflows/ci.yml"><img src="https://raw.githubusercontent.com/tonywied17/tonywied17/main/.github/badges/zero-transfer-coverage-ztransfer.svg?v=c9d77a5c" alt="Coverage"></a>
|
|
17
|
+
<a href="https://tonywied17.github.io/zero-transfer/"><img src="https://raw.githubusercontent.com/tonywied17/tonywied17/main/.github/badges/zero-transfer-docs-ztransfer.svg?v=6f97408c" alt="Docs"></a>
|
|
18
|
+
<a href="https://opensource.org/licenses/MIT"><img src="https://raw.githubusercontent.com/tonywied17/tonywied17/main/.github/badges/zero-transfer-license-ztransfer.svg?v=a2de3872" alt="License"></a>
|
|
19
|
+
<a href="https://nodejs.org"><img src="https://raw.githubusercontent.com/tonywied17/tonywied17/main/.github/badges/zero-transfer-node-ztransfer.svg?v=24b48ece" alt="Node.js"></a>
|
|
19
20
|
</p>
|
|
20
21
|
|
|
21
22
|
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
23
|
|
|
23
24
|
```ts
|
|
24
|
-
import {
|
|
25
|
+
import {
|
|
26
|
+
createDefaultRetryPolicy,
|
|
27
|
+
createS3ProviderFactory,
|
|
28
|
+
createTransferClient,
|
|
29
|
+
uploadFile,
|
|
30
|
+
} from "@zero-transfer/sdk";
|
|
25
31
|
|
|
26
32
|
const client = createTransferClient({
|
|
27
33
|
providers: [createS3ProviderFactory({ region: "us-east-1" })],
|
|
34
|
+
defaults: {
|
|
35
|
+
retry: createDefaultRetryPolicy(),
|
|
36
|
+
timeout: { stallTimeoutMs: 30_000 },
|
|
37
|
+
},
|
|
28
38
|
});
|
|
29
39
|
|
|
30
40
|
// One call, any provider you registered above.
|
|
@@ -49,7 +59,8 @@ await uploadFile({
|
|
|
49
59
|
|
|
50
60
|
- **One API, every provider.** Replace bespoke FTP, SFTP, S3, and cloud-drive code with a single `TransferClient` and provider-neutral sessions.
|
|
51
61
|
- **TypeScript-first.** Strict types, exact optional properties, exhaustive capability discovery, and typed errors for every protocol failure mode.
|
|
52
|
-
- **Streaming + resume.** Backpressure via `stream.pipeline`, byte-range downloads, multipart uploads, and cross-process resume stores for object storage.
|
|
62
|
+
- **Streaming + resume.** Backpressure via `stream.pipeline`, byte-range downloads, multipart uploads, and cross-process resume stores for object storage. Memory-bounded end to end - no whole-file buffering, and framing layers cap declared packet sizes.
|
|
63
|
+
- **Resilient by default.** `createDefaultRetryPolicy()` retries only retryable failures with exponential backoff + full jitter and honors `Retry-After` hints; job-scope and attempt-scope timeouts plus a stall watchdog catch connections that go silent; every receipt records per-attempt history.
|
|
53
64
|
- **Dry-run-first sync.** Diff remote trees, generate `TransferPlan`s, and review every step before any byte moves.
|
|
54
65
|
- **MFT batteries.** Routes, cron + interval schedules, audit logs, HMAC-signed webhooks, retention policies, and approval gates that block on human sign-off.
|
|
55
66
|
- **Security by default.** Profile redaction in every log, host-key pinning, certificate fingerprint pinning, OAuth refresh, and SecretSource adapters for vaults / env / files / commands.
|
|
@@ -73,6 +84,8 @@ Requires Node.js **>=20**.
|
|
|
73
84
|
|
|
74
85
|
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
86
|
|
|
87
|
+
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.
|
|
88
|
+
|
|
76
89
|
| Package | Summary | Docs |
|
|
77
90
|
| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | ----------------------------------------- |
|
|
78
91
|
| [`@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) |
|
|
@@ -335,6 +348,7 @@ Real-world examples live in [`examples/`](https://github.com/tonywied17/zero-tra
|
|
|
335
348
|
| [`webdav-sync.ts`](examples/webdav-sync.ts) | WebDAV diff + sync plan with deterministic ordering. |
|
|
336
349
|
| [`signed-url-download.ts`](examples/signed-url-download.ts) | HTTPS signed-URL download with progress reporting. |
|
|
337
350
|
| [`transfer-queue.ts`](examples/transfer-queue.ts) | Concurrent transfers with `TransferQueue` + executor. |
|
|
351
|
+
| [`retry-and-timeouts.ts`](examples/retry-and-timeouts.ts) | Retry policy, timeout scopes, stall watchdog, client defaults. |
|
|
338
352
|
| [`dry-run-sync.ts`](examples/dry-run-sync.ts) | Plan a sync, print a summary, never touch bytes. |
|
|
339
353
|
| [`mft-route.ts`](examples/mft-route.ts) | SFTP→S3 cron-scheduled MFT route with audit hooks. |
|
|
340
354
|
| [`profile-from-env.ts`](examples/profile-from-env.ts) | Build a `ConnectionProfile` from env / file / base64-env secrets. |
|
|
@@ -358,7 +372,7 @@ npm run docs:all # HTML + Markdown api refs + per-scope pages + per-package
|
|
|
358
372
|
|
|
359
373
|
## Project status
|
|
360
374
|
|
|
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
|
|
375
|
+
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 wired up across S3, Azure Blob, GCS, and OneDrive, and the resilience layer (default retry policy with backoff + jitter, job/attempt timeout scopes, stall detection, approval timeouts, redaction-safe error logging, memory-bounded streaming) is in place. Phase work in progress: unified checkpoint/resume, SFTP pipelining, and parallel multipart pools.
|
|
362
376
|
|
|
363
377
|
## Contributing
|
|
364
378
|
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200" width="200" height="200" role="img" aria-label="Zero Transfer Icon">
|
|
2
|
+
<defs>
|
|
3
|
+
<linearGradient id="gAccent" x1="0%" y1="0%" x2="100%" y2="0%">
|
|
4
|
+
<stop offset="0%" stop-color="#22d3ee">
|
|
5
|
+
<animate attributeName="stop-color"
|
|
6
|
+
values="#22d3ee;#818cf8;#22d3ee" dur="7s" repeatCount="indefinite"/>
|
|
7
|
+
</stop>
|
|
8
|
+
<stop offset="100%" stop-color="#c084fc">
|
|
9
|
+
<animate attributeName="stop-color"
|
|
10
|
+
values="#c084fc;#06b6d4;#c084fc" dur="7s" repeatCount="indefinite"/>
|
|
11
|
+
</stop>
|
|
12
|
+
</linearGradient>
|
|
13
|
+
|
|
14
|
+
<filter id="nucGlow" x="-100%" y="-100%" width="300%" height="300%">
|
|
15
|
+
<feGaussianBlur stdDeviation="4" result="b"/>
|
|
16
|
+
<feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge>
|
|
17
|
+
</filter>
|
|
18
|
+
</defs>
|
|
19
|
+
|
|
20
|
+
<g transform="translate(100,100)">
|
|
21
|
+
|
|
22
|
+
<circle r="70" fill="none" stroke="url(#gAccent)" stroke-width="1" opacity="0.06">
|
|
23
|
+
<animate attributeName="r" values="66;76;66" dur="5.5s" repeatCount="indefinite"/>
|
|
24
|
+
<animate attributeName="opacity" values="0.03;0.11;0.03" dur="5.5s" repeatCount="indefinite"/>
|
|
25
|
+
</circle>
|
|
26
|
+
|
|
27
|
+
<circle cx="-67" cy="-20" r="1.8" fill="#22d3ee">
|
|
28
|
+
<animate attributeName="opacity" values="0.12;0.65;0.12" dur="2.4s" repeatCount="indefinite"/>
|
|
29
|
+
</circle>
|
|
30
|
+
<circle cx="69" cy="14" r="1.4" fill="#c084fc">
|
|
31
|
+
<animate attributeName="opacity" values="0.08;0.5;0.08" dur="3.2s" begin="0.9s" repeatCount="indefinite"/>
|
|
32
|
+
</circle>
|
|
33
|
+
<circle cx="-28" cy="67" r="1.6" fill="#818cf8">
|
|
34
|
+
<animate attributeName="opacity" values="0.1;0.55;0.1" dur="2.9s" begin="1.6s" repeatCount="indefinite"/>
|
|
35
|
+
</circle>
|
|
36
|
+
<circle cx="44" cy="-60" r="1.4" fill="#22d3ee">
|
|
37
|
+
<animate attributeName="opacity" values="0.1;0.45;0.1" dur="3.7s" begin="0.5s" repeatCount="indefinite"/>
|
|
38
|
+
</circle>
|
|
39
|
+
<circle cx="55" cy="-38" r="1.2" fill="#c084fc">
|
|
40
|
+
<animate attributeName="opacity" values="0.08;0.4;0.08" dur="2.1s" begin="1.2s" repeatCount="indefinite"/>
|
|
41
|
+
</circle>
|
|
42
|
+
|
|
43
|
+
<g>
|
|
44
|
+
<animateTransform attributeName="transform" type="rotate"
|
|
45
|
+
from="0" to="360" dur="18s" repeatCount="indefinite"/>
|
|
46
|
+
<ellipse rx="62" ry="22" fill="none" stroke="#22d3ee" stroke-width="0.75" opacity="0.1"/>
|
|
47
|
+
<ellipse rx="62" ry="22" fill="none" stroke="#22d3ee" stroke-linecap="round">
|
|
48
|
+
<animate attributeName="ry"
|
|
49
|
+
values="22;56;22;5;22" keyTimes="0;0.25;0.5;0.75;1"
|
|
50
|
+
dur="7s" repeatCount="indefinite"
|
|
51
|
+
calcMode="spline"
|
|
52
|
+
keySplines="0.42 0 0.58 1;0.42 0 0.58 1;0.42 0 0.58 1;0.42 0 0.58 1"/>
|
|
53
|
+
<animate attributeName="stroke-width"
|
|
54
|
+
values="1.5;3.2;1.5;0.7;1.5" keyTimes="0;0.25;0.5;0.75;1" dur="7s" repeatCount="indefinite"/>
|
|
55
|
+
<animate attributeName="stroke-opacity"
|
|
56
|
+
values="0.28;0.95;0.28;0.5;0.28" keyTimes="0;0.25;0.5;0.75;1" dur="7s" repeatCount="indefinite"/>
|
|
57
|
+
</ellipse>
|
|
58
|
+
<ellipse rx="62" ry="22" fill="none" stroke="#22d3ee"
|
|
59
|
+
stroke-width="3" stroke-dasharray="68 232" stroke-linecap="round" opacity="0.85">
|
|
60
|
+
<animate attributeName="stroke-dashoffset" values="0;-300" dur="2.2s" repeatCount="indefinite"/>
|
|
61
|
+
</ellipse>
|
|
62
|
+
</g>
|
|
63
|
+
|
|
64
|
+
<g>
|
|
65
|
+
<animateTransform attributeName="transform" type="rotate"
|
|
66
|
+
from="60" to="-300" dur="24s" repeatCount="indefinite"/>
|
|
67
|
+
<ellipse rx="62" ry="22" fill="none" stroke="#818cf8" stroke-width="0.75" opacity="0.1"/>
|
|
68
|
+
<ellipse rx="62" ry="22" fill="none" stroke="#818cf8" stroke-linecap="round">
|
|
69
|
+
<animate attributeName="ry"
|
|
70
|
+
values="22;56;22;5;22" keyTimes="0;0.25;0.5;0.75;1"
|
|
71
|
+
dur="7s" begin="2.33s" repeatCount="indefinite"
|
|
72
|
+
calcMode="spline"
|
|
73
|
+
keySplines="0.42 0 0.58 1;0.42 0 0.58 1;0.42 0 0.58 1;0.42 0 0.58 1"/>
|
|
74
|
+
<animate attributeName="stroke-width"
|
|
75
|
+
values="1.5;3.2;1.5;0.7;1.5" keyTimes="0;0.25;0.5;0.75;1" dur="7s" begin="2.33s" repeatCount="indefinite"/>
|
|
76
|
+
<animate attributeName="stroke-opacity"
|
|
77
|
+
values="0.28;0.95;0.28;0.5;0.28" keyTimes="0;0.25;0.5;0.75;1" dur="7s" begin="2.33s" repeatCount="indefinite"/>
|
|
78
|
+
</ellipse>
|
|
79
|
+
<ellipse rx="62" ry="22" fill="none" stroke="#818cf8"
|
|
80
|
+
stroke-width="3" stroke-dasharray="68 232" stroke-linecap="round" opacity="0.85">
|
|
81
|
+
<animate attributeName="stroke-dashoffset" values="0;-300" dur="2.8s" repeatCount="indefinite"/>
|
|
82
|
+
</ellipse>
|
|
83
|
+
</g>
|
|
84
|
+
|
|
85
|
+
<g>
|
|
86
|
+
<animateTransform attributeName="transform" type="rotate"
|
|
87
|
+
from="120" to="480" dur="21s" repeatCount="indefinite"/>
|
|
88
|
+
<ellipse rx="62" ry="22" fill="none" stroke="#c084fc" stroke-width="0.75" opacity="0.1"/>
|
|
89
|
+
<ellipse rx="62" ry="22" fill="none" stroke="#c084fc" stroke-linecap="round">
|
|
90
|
+
<animate attributeName="ry"
|
|
91
|
+
values="22;56;22;5;22" keyTimes="0;0.25;0.5;0.75;1"
|
|
92
|
+
dur="7s" begin="4.67s" repeatCount="indefinite"
|
|
93
|
+
calcMode="spline"
|
|
94
|
+
keySplines="0.42 0 0.58 1;0.42 0 0.58 1;0.42 0 0.58 1;0.42 0 0.58 1"/>
|
|
95
|
+
<animate attributeName="stroke-width"
|
|
96
|
+
values="1.5;3.2;1.5;0.7;1.5" keyTimes="0;0.25;0.5;0.75;1" dur="7s" begin="4.67s" repeatCount="indefinite"/>
|
|
97
|
+
<animate attributeName="stroke-opacity"
|
|
98
|
+
values="0.28;0.95;0.28;0.5;0.28" keyTimes="0;0.25;0.5;0.75;1" dur="7s" begin="4.67s" repeatCount="indefinite"/>
|
|
99
|
+
</ellipse>
|
|
100
|
+
<ellipse rx="62" ry="22" fill="none" stroke="#c084fc"
|
|
101
|
+
stroke-width="3" stroke-dasharray="68 232" stroke-linecap="round" opacity="0.85">
|
|
102
|
+
<animate attributeName="stroke-dashoffset" values="0;-300" dur="3.4s" repeatCount="indefinite"/>
|
|
103
|
+
</ellipse>
|
|
104
|
+
</g>
|
|
105
|
+
|
|
106
|
+
<circle r="14" fill="#08111e"/>
|
|
107
|
+
<circle r="14" fill="none" stroke="url(#gAccent)" stroke-width="2" filter="url(#nucGlow)">
|
|
108
|
+
<animate attributeName="r" values="13;15;13" dur="4s" repeatCount="indefinite"/>
|
|
109
|
+
<animate attributeName="stroke-opacity" values="0.5;1;0.5" dur="4s" repeatCount="indefinite"/>
|
|
110
|
+
</circle>
|
|
111
|
+
<path d="M -7,-5 L 7,-5 L -7,5 L 7,5"
|
|
112
|
+
fill="none" stroke="url(#gAccent)"
|
|
113
|
+
stroke-width="2.3" stroke-linecap="round" stroke-linejoin="round">
|
|
114
|
+
<animate attributeName="opacity" values="0.65;1;0.65" dur="4s" repeatCount="indefinite"/>
|
|
115
|
+
</path>
|
|
116
|
+
</g>
|
|
117
|
+
</svg>
|