feat: add low-level storage buckets API

[jgodlew]

Add HFBucket — Storage Buckets API client

Implements the HuggingFace Storage Buckets low-level API as a typed async Rust client, following the same handle pattern as HFRepository and HFSpace.

Scope

The HFBucket client struct interface is a low-level wrapper around the bucket APIs exposed by huggingface hub. It currently doesn't provide any higher-level functionality (such as high-level download, upload, or sync APIs). Those APIs might be added later on to provide parity with the huggingface_hub python library if needed. Because of this, this API is not documented in the README.md, nor exposed in the hfrs cli application.

What's new

HFBucket handle (client.bucket(namespace, repo))

Method	Description
get()	Fetch bucket metadata
delete()	Permanently delete the bucket
update_settings(params)	Update visibility or CDN config
batch_files(ops)	Add/remove files atomically (NDJSON, adds-before-deletes)
list_tree(path, params)	Stream directory entries with cursor-in-body pagination
get_paths_info(paths)	Fetch metadata for a batch of file paths
get_xet_write_token()	Short-lived JWT for Xet CAS uploads
get_xet_read_token()	Short-lived JWT for Xet CAS downloads
resolve_file(path)	Capture redirect URL + headers (X-Linked-Size, X-XET-Hash, Link)
xet_resolve_file(path) (feature = xet)	Resolve to XetFileInfo reconstruction metadata

HFClient methods

• client.bucket(namespace, repo) — create a bucket handle (no I/O)
• client.create_bucket(namespace, repo, params) — create a new bucket
• client.list_buckets(namespace) — paginated stream of BucketOverview

HFBucketSync (feature = blocking)

Blocking wrappers for all of the above. list_tree and list_buckets collect into Vec.

Error handling

Three new HFError variants to cover bucket-specific HTTP status codes:

• Forbidden (403)
• Conflict(String) (409) — carries the response body
• RateLimited (429)

A private check_bucket_response helper in api/buckets.rs maps these uniformly across all bucket endpoints.

New types (types/buckets.rs)

BucketInfo, BucketOverview, BucketCreated, CdnRegion, ResourceGroup, XetToken, PathInfo, TreeEntry, EntryType, BatchOp, AddFileOp, DeleteFileOp, BatchResult, BatchFailure, ResolvedFile, CreateBucketParams, UpdateBucketParams, ListTreeParams, XetFileInfo (feature = xet)

Tests

• Unit tests — 13 tests covering URL construction, serialization, deserialization, NDJSON ordering, and Link header parsing
• Integration tests — 4 tests in integration_test.rs that skip gracefully without HF_TOKEN; write tests also require HF_TEST_WRITE=1
  • test_list_buckets
  • test_create_and_delete_bucket — full create → get → update → delete → confirm-gone lifecycle
  • test_bucket_list_tree_empty
  • test_get_xet_write_and_read_token