@venturialstd/backblaze

Backblaze B2 client using the S3-Compatible API (no AWS SDK). Authentication via AWS Signature Version 4 using the aws4 library. Intended for use across multiple projects that need Backblaze storage.

Features

• Authentication: AWS Sig v4 (Application Key = access key + secret).
• Buckets: List Buckets (GET /), Create Bucket (PUT /bucket-name), Delete Bucket (DELETE /bucket-name), Head Bucket (HEAD /bucket-name).
• Objects: Put Object, Get Object, Delete Object, List Objects V2, Head Object.
• Credentials from SettingsModule or per-request via BackblazeOptions (includes region).
• S3 XML responses parsed to JSON (ListBuckets, ListObjectsV2).

Requirements

• Backblaze B2 Application Key (S3-compatible).
• Configure in settings: GLOBAL:BACKBLAZE:GENERAL:REGION, GLOBAL:BACKBLAZE:GENERAL:ACCESS_KEY_ID, GLOBAL:BACKBLAZE:GENERAL:SECRET_ACCESS_KEY.

Installation

npm install @venturialstd/backblaze
yarn add @venturialstd/backblaze

Basic usage

All bucket and object methods accept DTOs (e.g. CreateBucketDto, PutObjectDto, ListObjectsDto). When the API returns an error (4xx/5xx), the client throws BackblazeS3Error with the Backblaze/S3 Code, Message, and statusCode so the error message is visible to callers.

import {
  BackblazeModule,
  BackblazeBucketService,
  BackblazeObjectService,
  CreateBucketDto,
  PutObjectDto,
  ListObjectsDto,
  BucketAcl,
  ContentType,
} from '@venturialstd/backblaze';

@Module({
  imports: [BackblazeModule],
})
export class AppModule {}

@Injectable()
export class MyService {
  constructor(
    private readonly bucketService: BackblazeBucketService,
    private readonly objectService: BackblazeObjectService,
  ) {}

  async listBuckets() {
    const { buckets } = await this.bucketService.listBuckets();
    return buckets;
  }

  async createBucket(dto: CreateBucketDto) {
    await this.bucketService.createBucket(
      { ...dto, acl: dto.acl ?? BucketAcl.Private },
    );
  }

  async upload(bucketName: string, key: string, body: Buffer) {
    await this.objectService.putObject({
      bucketName,
      key,
      body,
      contentType: ContentType.ApplicationJson,
    });
  }

  async download(bucketName: string, key: string) {
    return this.objectService.getObject({ bucketName, key });
  }

  async listObjects(bucketName: string, prefix?: string) {
    return this.objectService.listObjectsV2({
      bucketName,
      prefix,
      maxKeys: 1000,
    });
  }
}

Error handling

On 4xx/5xx the client throws BackblazeS3Error with the parsed S3 Code, Message, and statusCode. Use it for programmatic handling:

import { BackblazeS3Error, BackblazeS3ErrorCode } from '@venturialstd/backblaze';

try {
  await this.objectService.getObject({ bucketName: 'b', key: 'k' });
} catch (err) {
  if (err instanceof BackblazeS3Error) {
    console.error(err.message); // Backblaze/S3 error message
    if (err.isNotFound) { /* ... */ }
    if (err.isAccessDenied) { /* ... */ }
  }
  throw err;
}

Per-request options

await this.bucketService.listBuckets({
  region: 'us-west-004',
  credentials: { accessKeyId: '...', secretAccessKey: '...' },
});

S3-Compatible API (official documentation)

• List Buckets: GET https://s3.<region>.backblazeb2.com/
• Create Bucket: PUT https://s3.<region>.backblazeb2.com/<bucket-name> (optional: CreateBucketConfiguration XML body, header x-amz-acl: private | public-read)
• Delete Bucket: DELETE https://s3.<region>.backblazeb2.com/<bucket-name>
• Head Bucket: HEAD https://s3.<region>.backblazeb2.com/<bucket-name>
• Put Object: PUT https://s3.<region>.backblazeb2.com/<bucket>/<key> (body = file)
• Get Object: GET https://s3.<region>.backblazeb2.com/<bucket>/<key>
• Delete Object: DELETE https://s3.<region>.backblazeb2.com/<bucket>/<key>
• List Objects V2: GET https://s3.<region>.backblazeb2.com/<bucket>?list-type=2&prefix=...&max-keys=...
• Head Object: HEAD https://s3.<region>.backblazeb2.com/<bucket>/<key>

Notes

• The AWS SDK is not used; requests are signed with aws4 and sent with HttpService.
• Backblaze only supports "private" and "public-read" ACLs at bucket level.
• DTOs: All operations use DTOs (CreateBucketDto, DeleteBucketDto, HeadBucketDto, PutObjectDto, GetObjectDto, DeleteObjectDto, HeadObjectDto, ListObjectsDto). Enums: BucketAcl, ContentType, BackblazeRegion. Normalized results: listBuckets(), listObjectsV2(). Raw: listBucketsRaw(), listObjectsV2Raw().
• Errors: On API errors the client throws BackblazeS3Error with the Backblaze/S3 message and code so the error is visible (e.g. in exception filters). Use BackblazeS3ErrorCode for known codes.
• Developed and maintained by Venturial.

License

MIT