Skip to main content

B2 Transfer

@sntxrr/b2-transferv2026.10.22.1· MIT· 1mo agoBEHAVIORS
01README

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.

02Behaviors1
@sntxrr/b2/transferv2026.08.06.1b2_transfer.ts

Global Arguments

ArgumentTypeDescription
applicationKeyIdstringB2 application key ID (master or scoped). See the README for the
applicationKeystringB2 application key — supply via vault.get(), never inline.
authHost?stringOverride the B2 authorize host (testing only). Defaults to
bucketName?stringBucket this model manages. Required by upload, download by name,
bucketId?stringBucket ID matching bucketName. Supplying it saves one class-C
maxTransferBytes?numberRefuse any single upload or download larger than this many bytes.
allowTransferDestruction?booleanAcknowledge that delete cancels an in-flight large upload and discards
fn scan(maxPages?: number, countParts?: boolean)
Factory discovery — inventory interrupted large uploads across every
ArgumentTypeDescription
maxPages?numberHard cap on list pages per bucket. Defaults to 50. Hitting the cap is
countParts?booleanAlso call b2_list_parts for every unfinished upload found, populating
fn upload(fileName: string, content?: string, sourcePath?: string, contentType?: string, fileInfo?: record, partSizeBytes?: number, forceLarge?: boolean, maxTransferBytes?: number)
Upload one object, via b2_upload_file for small content or the
ArgumentTypeDescription
fileNamestringDestination file name within the bucket.
content?stringInline UTF-8 content to upload. Use this for canaries and validation.
sourcePath?stringLocal file to upload. Requires Deno read permission for the path.
contentType?stringMIME type. Defaults to "b2/x-auto", which lets B2 infer from the name.
fileInfo?recordCustom metadata to attach. Stored by B2 and returned on every read, so
partSizeBytes?numberPart size for the large-file path, in bytes. Defaults to B2's
forceLarge?booleanUse the start/part/finish large-file path even when the content would
maxTransferBytes?numberOverride globalArgs.maxTransferBytes for this run only.
fn download(fileId?: string, fileName?: string, destinationPath?: string, verifySha1?: boolean, maxTransferBytes?: number)
Download one object by fileId (b2_download_file_by_id) or by name
ArgumentTypeDescription
fileId?stringDownload by file ID (b2_download_file_by_id). Exactly one of fileId or
fileName?stringDownload by name (b2_download_file_by_name), which resolves to the
destinationPath?stringWrite the payload to this local path. Omit to verify and discard,
verifySha1?booleanCompute the SHA-1 of what arrived and compare it to what B2 reports.
maxTransferBytes?numberOverride globalArgs.maxTransferBytes for this run only.
fn authorize_download(fileNamePrefix: string, validDurationInSeconds?: number, verify?: boolean)
Mint a b2_get_download_authorization token for a file-name prefix
ArgumentTypeDescription
fileNamePrefixstringPrefix to grant read access to. An empty string grants the whole
validDurationInSeconds?numberLifetime of the authorization. Defaults to 3600 (one hour). B2's
verify?booleanExercise the minted token against B2 before reporting success.
fn list_parts(fileId: string, maxPages?: number)
Size one interrupted large upload with b2_list_parts and update its
ArgumentTypeDescription
fileIdstringThe unfinished large file whose parts to list.
maxPages?numberHard cap on list pages. Defaults to 50 (up to 50,000 parts).
fn copy_part(fileName: string, sources: array, contentType?: string, fileInfo?: record)
Assemble a new file server-side from byte ranges of existing files
ArgumentTypeDescription
fileNamestringName of the new file to assemble in this model's bucket.
sourcesarraySources to concatenate, in order — each becomes one part. B2 requires
contentType?stringMIME type for the assembled file. Defaults to "b2/x-auto".
fileInfo?recordCustom metadata to attach. Stored by B2 and returned on every read, so
fn delete(fileId: string, allowTransferDestruction?: boolean)
Cancel an interrupted large upload with b2_cancel_large_file,
ArgumentTypeDescription
fileIdstringThe unfinished large file to cancel. Every part already uploaded is
allowTransferDestruction?booleanPer-run acknowledgement that this discards uploaded parts. Either this

Resources

unfinished-upload(infinite)— An interrupted large upload B2 is still storing and still billing, instance-named unfinished-upload-<fileId>
transfer(infinite)— The outcome of one upload, download or copy_part — its shape and integrity, never its payload
download-auth(infinite)— A minted download authorization's scope and expiry. Never its token — the token is regenerable and is deliberately not persisted
03Previous Versions2
2026.10.14.1MIT(was none)

Declare SPDX license (MIT) in manifest.

Modified 1 behaviors

2026.08.06.1

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.

04Stats
A
100 / 100
Downloads
88
Archive size
40.0 KB
  • 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
05Platforms
06Labels