Skip to main content
← back to extensions

B2 Bucket

@sntxrr/b2-bucketv2026.10.22.1· MIT· 13d agoBEHAVIORS
01README

Manage one Backblaze B2 bucket via the B2 Native API v4 — sync, create, update, idempotent delete, and get/set event notification rules — with first-class lifecycle rules so restic-pruned hidden file versions are actually deleted.

02Behaviors1
@sntxrr/b2/bucketv2026.08.05.3b2_bucket.ts

Global Arguments

ArgumentTypeDescription
applicationKeyIdstringB2 application key ID (master or scoped). Wire with ${{ vault.get(b2, B2_APPLICATION_KEY_ID) }}.
applicationKeystringB2 application key — supply via vault.get(), never inline.
authHost?stringOverride the B2 authorize host (testing only). Defaults to https://api.backblazeb2.com.
bucketNamestringName of the bucket this model manages. B2 bucket names are globally unique and 6-63 characters.
bucketId?stringB2 bucket ID. Optional: when omitted it is resolved from bucketName via b2_list_buckets, which costs one class-C transaction per run. Set it to avoid that call.
bucketType?enumDesired bucket type. `create` defaults to allPrivate when this is unset — a restic repository must never be allPublic. Deliberately NOT a schema-level default: a default here would make `update` send bucketType on every run, silently flipping an allPublic bucket private for an operator who only meant to set lifecycle rules.
lifecycleRules?arrayDesired lifecycle rules. For a restic bucket use [{ fileNamePrefix: "", daysFromUploadingToHiding: null, daysFromHidingToDeleting: 1 }].
corsRules?arrayDesired CORS rules. Omit to leave the bucket's CORS configuration untouched.
bucketInfo?recordDesired user-defined bucket metadata (also carries Cache-Control policies).
fileLockEnabled?booleanEnable Object Lock on the bucket. Requires the writeBucketRetentions capability. Object Lock cannot be disabled once enabled.
allowPublicBucket?booleanAcknowledge that this bucket may be allPublic. Without it, create and
allowUnprunedHiddenVersions?booleanSet true to acknowledge that this bucket intentionally retains hidden file versions forever, which disables the lifecycle-hidden-version-retention pre-flight check.
fn sync()
Read the managed bucket's current state (b2_list_buckets filtered by bucketName) and snapshot it. Records whether the bucket prunes hidden file versions. Requires the listBuckets capability.
fn create(allowPublicBucket?: boolean, bucketType?: enum, lifecycleRules?: array, corsRules?: array, bucketInfo?: record, fileLockEnabled?: boolean)
Create the managed bucket (b2_create_bucket) with the declared bucketType, lifecycleRules, corsRules, fileLockEnabled and defaultServerSideEncryption. Not idempotent: an existing name fails with duplicate_bucket_name rather than silently adopting a bucket with different settings. Requires writeBuckets (plus writeBucketRetentions for fileLockEnabled).
ArgumentTypeDescription
allowPublicBucket?booleanAcknowledge, for this run only, that bucketType may be allPublic.
bucketType?enumOverride globalArgs.bucketType for this run.
lifecycleRules?arrayOverride globalArgs.lifecycleRules for this run.
corsRules?arrayOverride globalArgs.corsRules for this run.
bucketInfo?recordOverride globalArgs.bucketInfo for this run.
fileLockEnabled?booleanOverride globalArgs.fileLockEnabled for this run.
fn update()
Update the managed bucket (b2_update_bucket): lifecycle rules, bucket type, CORS rules, replication configuration, Object Lock and default encryption/retention. Only fields you supply are sent; everything else is left untouched. Requires writeBuckets.
fn delete()
Delete the managed bucket (b2_delete_bucket). The bucket must already be empty. Idempotent: a 404, or a 400 with b2Code bad_bucket_id, is treated as success and still writes an exists=false snapshot. Requires deleteBuckets (and listBuckets unless globalArgs.bucketId is set).
fn get_notification_rules()
Read the bucket's event notification rules (b2_get_bucket_notification_rules — a GET with query parameters, not a POST) and snapshot them with signing secrets and header values redacted. Requires the readBucketNotifications capability.
fn set_notification_rules(rules: array)
Replace the bucket's event notification rules (b2_set_bucket_notification_rules, POST). The supplied list REPLACES all existing rules; pass [] to remove them. Requires writeBucketNotifications. NOTE: pre-flight checks do NOT run for this method — swamp only auto-runs them before methods named create/update/delete/action.
ArgumentTypeDescription
rulesarrayThe complete desired set of event notification rules. This REPLACES every existing rule on the bucket; pass [] to remove them all.

Resources

bucket(infinite)— Snapshot of the managed B2 bucket's configuration and state
notificationRules(infinite)— Snapshot of the bucket's event notification rules, with signing secrets and header values redacted
03Previous Versions4
2026.10.14.1MIT(was none)

Declare SPDX license (MIT) in manifest.

Modified 1 behaviors

2026.08.05.3

Gates making a bucket public: create and update now refuse bucketType=allPublic unless allowPublicBucket=true acknowledges it, as a method input or a global argument. Corrects the lifecycle check's error message, which claimed no rules were declared when they had been supplied via --input — swamp does not give pre-flight checks the method's inputs, so the check cannot see them. Documents that Event Notifications needs account-level enablement. Write paths verified end to end against live B2.

2026.08.05.2

Live-verification fixes. unprunedPrefixes now reports [""] rather than [] for a bucket with NO lifecycle rules: the old value read as 'nothing is accumulating hidden versions' when in fact every file is, hiding exactly the buckets a consumer queries for. Adds defaultRetentionPeriod so a snapshot can distinguish a 1-day Object Lock window from a 10-year one, aliases a bucket named 'latest' to bucket-latest, and stops bucketInfo/options hard-failing sync on an unexpected value type.

2026.08.05.1

First release. Manages one Backblaze B2 bucket via the Native API v4: sync, create, update, idempotent delete, and event notification rules. Models lifecycle rules precisely and surfaces prunesHiddenVersions, because restic-pruned pack files are billed forever without a daysFromHidingToDeleting rule. Notification-rule signing secrets and custom header values are stripped before any snapshot is written.

04Stats
A
100 / 100
Downloads
39
Archive size
33.1 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
Repository
https://github.com/sntxrr/swamp-backblaze
05Platforms
06Labels
#backblaze#b2#storage#bucket#lifecycle#restic