B2 Transfer
Backblaze B2 data-plane transfers via the Native API v4 — the thirteen upload, download and large-file operations, guarded. Inventories the interrupted large uploads B2 bills for invisibly, proves a bucket is readable and writable end to end, and refuses to move more than 100 MB without an explicit override.
Global Arguments
| Argument | Type | Description |
|---|---|---|
| applicationKeyId | string | B2 application key ID (master or scoped). See the README for the |
| applicationKey | string | B2 application key — supply via vault.get(), never inline. |
| authHost? | string | Override the B2 authorize host (testing only). Defaults to |
| bucketName? | string | Bucket this model manages. Required by upload, download by name, |
| bucketId? | string | Bucket ID matching bucketName. Supplying it saves one class-C |
| maxTransferBytes? | number | Refuse any single upload or download larger than this many bytes. |
| allowTransferDestruction? | boolean | Acknowledge that delete cancels an in-flight large upload and discards |
| Argument | Type | Description |
|---|---|---|
| maxPages? | number | Hard cap on list pages per bucket. Defaults to 50. Hitting the cap is |
| countParts? | boolean | Also call b2_list_parts for every unfinished upload found, populating |
| Argument | Type | Description |
|---|---|---|
| fileName | string | Destination file name within the bucket. |
| content? | string | Inline UTF-8 content to upload. Use this for canaries and validation. |
| sourcePath? | string | Local file to upload. Requires Deno read permission for the path. |
| contentType? | string | MIME type. Defaults to "b2/x-auto", which lets B2 infer from the name. |
| fileInfo? | record | Custom metadata to attach. Stored by B2 and returned on every read, so |
| partSizeBytes? | number | Part size for the large-file path, in bytes. Defaults to B2's |
| forceLarge? | boolean | Use the start/part/finish large-file path even when the content would |
| maxTransferBytes? | number | Override globalArgs.maxTransferBytes for this run only. |
| Argument | Type | Description |
|---|---|---|
| fileId? | string | Download by file ID (b2_download_file_by_id). Exactly one of fileId or |
| fileName? | string | Download by name (b2_download_file_by_name), which resolves to the |
| destinationPath? | string | Write the payload to this local path. Omit to verify and discard, |
| verifySha1? | boolean | Compute the SHA-1 of what arrived and compare it to what B2 reports. |
| maxTransferBytes? | number | Override globalArgs.maxTransferBytes for this run only. |
| Argument | Type | Description |
|---|---|---|
| fileNamePrefix | string | Prefix to grant read access to. An empty string grants the whole |
| validDurationInSeconds? | number | Lifetime of the authorization. Defaults to 3600 (one hour). B2's |
| verify? | boolean | Exercise the minted token against B2 before reporting success. |
| Argument | Type | Description |
|---|---|---|
| fileId | string | The unfinished large file whose parts to list. |
| maxPages? | number | Hard cap on list pages. Defaults to 50 (up to 50,000 parts). |
| Argument | Type | Description |
|---|---|---|
| fileName | string | Name of the new file to assemble in this model's bucket. |
| sources | array | Sources to concatenate, in order — each becomes one part. B2 requires |
| contentType? | string | MIME type for the assembled file. Defaults to "b2/x-auto". |
| fileInfo? | record | Custom metadata to attach. Stored by B2 and returned on every read, so |
| Argument | Type | Description |
|---|---|---|
| fileId | string | The unfinished large file to cancel. Every part already uploaded is |
| allowTransferDestruction? | boolean | Per-run acknowledgement that this discards uploaded parts. Either this |
Resources
Declare SPDX license (MIT) in manifest.
Modified 1 behaviors
First publish of @sntxrr/b2/transfer — the B2 data plane, completing this suite's coverage of all 33 Native API v4 operations.
Thirteen operations across seven methods: scan, upload, download, authorize_download, list_parts, copy_part, delete.
Guarded on purpose. Streaming multi-gigabyte objects through a Deno subprocess produces no meaningful typed state, and restic already moves those bytes over S3, so upload and download refuse anything over maxTransferBytes (100 MB default) — checked before b2_authorize_account, which is itself class-C, so a refused transfer costs nothing at all. A pre-flight check also rejects a model-level cap above 1 GiB, because raising it permanently is how a guarded validation tool quietly becomes an unguarded data mover.
What it is for: proving a bucket is readable and writable independently of restic (upload a canary, download it, compare the SHA-1), and surfacing interrupted large uploads — which B2 stores and bills indefinitely, and which appear in neither b2_list_file_names nor the console's file browser. On the estate this was built for, scan found ten stuck since 2021.
The download authorization token is never persisted. Unlike an application key's one-shot secret it can be re-minted at will, so storing a copy is all risk and no benefit. Enforced as tokenPersisted: z.literal(false).
Honest nulls throughout: sha1Verified null means NOT CHECKED, distinct from false meaning checked-and-mismatched — branch on === false. partCount null means list_parts was never run, not zero parts.
Live-verified end to end in a purpose-built scratch bucket: small upload with SHA-1 verification, multi-part upload from a local file, download by id and by name, a byte-for-byte round trip, a minted-and-verified download authorization, server-side assembly from two source ranges compared byte-for-byte against a locally built expectation, plus ten real cancels and a repeat cancel on the production fleet.
Live exercise found three defects mocks could not: delete was not idempotent (B2 returns catch-all bad_request, not file_not_present, for an already-cancelled file); a pre-flight check gating delete on an acknowledgement made the documented per-run path impossible and forced arming destruction permanently; and copy_part was outright unreachable, so it now owns the whole start/copy/finish lifecycle.
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License2/2earned
- Verified public repository2/2earned