@zero-transfer/sdk 0.4.7 → 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.
Files changed (9) hide show
  1. package/README.md +23 -11
  2. package/assets/zero-transfer-icon.svg +117 -0
  3. package/dist/index.cjs +638 -161
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.d.mts +297 -44
  6. package/dist/index.d.ts +297 -44
  7. package/dist/index.mjs +634 -161
  8. package/dist/index.mjs.map +1 -1
  9. 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://img.shields.io/npm/v/@zero-transfer/sdk.svg?style=for-the-badge&labelColor=0d1117&color=00b4d8&logo=npm&logoColor=white&label=%40zero-transfer%2Fsdk" alt="npm version"></a>
12
- <a href="https://www.npmjs.com/package/@zero-transfer/sdk"><img src="https://img.shields.io/npm/dm/@zero-transfer/sdk.svg?style=for-the-badge&labelColor=0d1117&color=00b4d8&logo=npm&logoColor=white" alt="npm downloads"></a>
13
- <a href="https://github.com/tonywied17/zero-transfer/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/tonywied17/zero-transfer/ci.yml?branch=main&style=for-the-badge&labelColor=0d1117&logo=githubactions&logoColor=white&label=CI" alt="CI"></a>
14
- <a href="https://github.com/tonywied17/zero-transfer/actions/workflows/ci.yml"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Ftonywied17.github.io%2Fzero-transfer%2Fbadges%2Ftests.json&style=for-the-badge&labelColor=0d1117&logo=vitest&logoColor=white" alt="Tests"></a>
15
- <a href="https://github.com/tonywied17/zero-transfer/actions/workflows/ci.yml"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Ftonywied17.github.io%2Fzero-transfer%2Fbadges%2Fcoverage.json&style=for-the-badge&labelColor=0d1117&logo=vitest&logoColor=white" alt="Coverage"></a>
16
- <a href="https://tonywied17.github.io/zero-transfer/"><img src="https://img.shields.io/badge/docs-typedoc-00b4d8?style=for-the-badge&labelColor=0d1117&logo=readthedocs&logoColor=white" alt="Docs"></a>
17
- <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-00b4d8?style=for-the-badge&labelColor=0d1117" alt="License"></a>
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>
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 { createS3ProviderFactory, createTransferClient, uploadFile } from "@zero-transfer/sdk";
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.
@@ -337,6 +348,7 @@ Real-world examples live in [`examples/`](https://github.com/tonywied17/zero-tra
337
348
  | [`webdav-sync.ts`](examples/webdav-sync.ts) | WebDAV diff + sync plan with deterministic ordering. |
338
349
  | [`signed-url-download.ts`](examples/signed-url-download.ts) | HTTPS signed-URL download with progress reporting. |
339
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. |
340
352
  | [`dry-run-sync.ts`](examples/dry-run-sync.ts) | Plan a sync, print a summary, never touch bytes. |
341
353
  | [`mft-route.ts`](examples/mft-route.ts) | SFTP→S3 cron-scheduled MFT route with audit hooks. |
342
354
  | [`profile-from-env.ts`](examples/profile-from-env.ts) | Build a `ConnectionProfile` from env / file / base64-env secrets. |
@@ -360,7 +372,7 @@ npm run docs:all # HTML + Markdown api refs + per-scope pages + per-package
360
372
 
361
373
  ## Project status
362
374
 
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.
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.
364
376
 
365
377
  ## Contributing
366
378
 
package/assets/zero-transfer-icon.svg ADDED
@@ -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>