@backblaze-labs/b2-sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const client = require("./client.cjs");
+const bucket = require("./bucket.cjs");
+const object = require("./object.cjs");
+const raw_index = require("./raw/index.cjs");
+const errors_index = require("./errors/index.cjs");
+const inMemory = require("./auth/in-memory.cjs");
+const hash = require("./streams/hash.cjs");
+const source = require("./streams/source.cjs");
+const transport = require("./http/transport.cjs");
+const urlGuard = require("./http/url-guard.cjs");
+const encryption = require("./types/encryption.cjs");
+const paginator = require("./util/paginator.cjs");
+const bucket$1 = require("./types/bucket.cjs");
+const auth = require("./types/auth.cjs");
+const notifications = require("./types/notifications.cjs");
+const file = require("./types/file.cjs");
+const lock = require("./types/lock.cjs");
+const ids = require("./types/ids.cjs");
+const version = require("./version.cjs");
+exports.B2Client = client.B2Client;
+exports.Bucket = bucket.Bucket;
+exports.B2Object = object.B2Object;
+exports.RawClient = raw_index.RawClient;
+exports.AccessDeniedError = errors_index.AccessDeniedError;
+exports.B2Error = errors_index.B2Error;
+exports.B2InsufficientCapabilityError = errors_index.B2InsufficientCapabilityError;
+exports.B2SsrfError = errors_index.B2SsrfError;
+exports.BadAuthTokenError = errors_index.BadAuthTokenError;
+exports.BadRequestError = errors_index.BadRequestError;
+exports.BadUploadUrlError = errors_index.BadUploadUrlError;
+exports.CapExceededError = errors_index.CapExceededError;
+exports.ChecksumMismatchError = errors_index.ChecksumMismatchError;
+exports.DuplicateBucketNameError = errors_index.DuplicateBucketNameError;
+exports.ExpiredAuthTokenError = errors_index.ExpiredAuthTokenError;
+exports.FileNotPresentError = errors_index.FileNotPresentError;
+exports.NetworkError = errors_index.NetworkError;
+exports.RequestTimeoutError = errors_index.RequestTimeoutError;
+exports.ServiceUnavailableError = errors_index.ServiceUnavailableError;
+exports.TooManyRequestsError = errors_index.TooManyRequestsError;
+exports.classifyError = errors_index.classifyError;
+exports.InMemoryAccountInfo = inMemory.InMemoryAccountInfo;
+exports.IncrementalSha1 = hash.IncrementalSha1;
+exports.sha1Hex = hash.sha1Hex;
+exports.BlobSource = source.BlobSource;
+exports.BufferSource = source.BufferSource;
+exports.StreamSource = source.StreamSource;
+exports.toContentSource = source.toContentSource;
+exports.FetchTransport = transport.FetchTransport;
+exports.RetryTransport = transport.RetryTransport;
+exports.UrlGuard = urlGuard.UrlGuard;
+exports.deriveAllowedSuffixes = urlGuard.deriveAllowedSuffixes;
+exports.EncryptionAlgorithm = encryption.EncryptionAlgorithm;
+exports.EncryptionKey = encryption.EncryptionKey;
+exports.EncryptionMode = encryption.EncryptionMode;
+exports.SSE_B2 = encryption.SSE_B2;
+exports.SSE_NONE = encryption.SSE_NONE;
+exports.sseCustomer = encryption.sseCustomer;
+exports.paginateItems = paginator.paginateItems;
+exports.paginatePages = paginator.paginatePages;
+exports.BucketRetentionMode = bucket$1.BucketRetentionMode;
+exports.BucketType = bucket$1.BucketType;
+exports.CorsOperation = bucket$1.CorsOperation;
+exports.Capability = auth.Capability;
+exports.EventType = notifications.EventType;
+exports.FileAction = file.FileAction;
+exports.MetadataDirective = file.MetadataDirective;
+exports.LegalHoldValue = lock.LegalHoldValue;
+exports.RetentionMode = lock.RetentionMode;
+exports.accountId = ids.accountId;
+exports.applicationKeyId = ids.applicationKeyId;
+exports.bucketId = ids.bucketId;
+exports.fileId = ids.fileId;
+exports.keyId = ids.keyId;
+exports.largeFileId = ids.largeFileId;
+exports.VERSION = version.VERSION;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/index.d.cts

@@ -0,0 +1,39 @@
+/**
+ * Backblaze B2 Cloud Storage SDK for TypeScript/JavaScript.
+ *
+ * The root module re-exports the high-level facade ({@link B2Client}, {@link Bucket},
+ * {@link B2Object}), error types, auth backends, streaming utilities, HTTP transport,
+ * and all request/response type definitions. Most applications only need this import.
+ *
+ * @packageDocumentation
+ */
+export { B2Client, type B2ClientOptions, type CapabilityCheckResult } from './client.js';
+export { Bucket, type DeleteAllDeleteEvent, type DeleteAllErrorEvent, type DeleteAllEvent, type DeleteAllSkipEvent, type DeleteError, type DeleteManyResult, type DeleteTarget, } from './bucket.js';
+export { B2Object, type DownloadCallOptions, type HeadCallOptions } from './object.js';
+export type { UploadWriteHandle } from './upload/stream.js';
+export { RawClient, type RawClientOptions, type DownloadFileOptions, type SseCDownloadKey, } from './raw/index.js';
+export { B2Error, ExpiredAuthTokenError, BadAuthTokenError, ServiceUnavailableError, RequestTimeoutError, TooManyRequestsError, CapExceededError, AccessDeniedError, FileNotPresentError, DuplicateBucketNameError, BadRequestError, BadUploadUrlError, ChecksumMismatchError, B2InsufficientCapabilityError, B2SsrfError, NetworkError, classifyError, } from './errors/index.js';
+export { InMemoryAccountInfo } from './auth/in-memory.js';
+export type { AccountInfo, UploadUrlEntry } from './auth/account-info.js';
+export { IncrementalSha1, sha1Hex } from './streams/hash.js';
+export { toContentSource, BlobSource, BufferSource, StreamSource } from './streams/source.js';
+export type { ContentSource } from './streams/source.js';
+export type { ProgressEvent, ProgressListener } from './streams/progress.js';
+export { FetchTransport, RetryTransport } from './http/transport.js';
+export type { HttpTransport, HttpRequest, HttpResponse, RetryTransportOptions, } from './http/transport.js';
+export { UrlGuard, deriveAllowedSuffixes } from './http/url-guard.js';
+export type { RetryOptions } from './http/retry.js';
+export type { DownloadResult, HeadResult } from './download/single.js';
+export { EncryptionKey, SSE_B2, SSE_NONE, sseCustomer } from './types/encryption.js';
+export { paginateItems, paginatePages } from './util/paginator.js';
+export type { PageFetcher, PaginatorOptions } from './util/paginator.js';
+export { BucketRetentionMode, BucketType, CorsOperation } from './types/bucket.js';
+export { Capability } from './types/auth.js';
+export { EncryptionAlgorithm, EncryptionMode } from './types/encryption.js';
+export { EventType } from './types/notifications.js';
+export { FileAction, MetadataDirective } from './types/file.js';
+export { LegalHoldValue, RetentionMode } from './types/lock.js';
+export type * from './types/index.js';
+export { accountId, applicationKeyId, bucketId, fileId, keyId, largeFileId, } from './types/ids.js';
+export { VERSION } from './version.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACxF,OAAO,EACL,MAAM,EACN,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,QAAQ,EAAE,KAAK,mBAAmB,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAA;AAEtF,YAAY,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAE3D,OAAO,EACL,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,eAAe,GACrB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EACL,OAAO,EACP,qBAAqB,EACrB,iBAAiB,EACjB,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,6BAA6B,EAC7B,WAAW,EACX,YAAY,EACZ,aAAa,GACd,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACzD,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAEzE,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAC5D,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAC7F,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAE5E,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpE,YAAY,EACV,aAAa,EACb,WAAW,EACX,YAAY,EACZ,qBAAqB,GACtB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,QAAQ,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AACrE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEnD,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAKpF,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAClE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAOxE,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAClF,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAC3E,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AACpD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAC/D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAE/D,mBAAmB,kBAAkB,CAAA;AAQrC,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,QAAQ,EACR,MAAM,EACN,KAAK,EACL,WAAW,GACZ,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Backblaze B2 Cloud Storage SDK for TypeScript/JavaScript.
+ *
+ * The root module re-exports the high-level facade ({@link B2Client}, {@link Bucket},
+ * {@link B2Object}), error types, auth backends, streaming utilities, HTTP transport,
+ * and all request/response type definitions. Most applications only need this import.
+ *
+ * @packageDocumentation
+ */
+export { B2Client, type B2ClientOptions, type CapabilityCheckResult } from './client.js';
+export { Bucket, type DeleteAllDeleteEvent, type DeleteAllErrorEvent, type DeleteAllEvent, type DeleteAllSkipEvent, type DeleteError, type DeleteManyResult, type DeleteTarget, } from './bucket.js';
+export { B2Object, type DownloadCallOptions, type HeadCallOptions } from './object.js';
+export type { UploadWriteHandle } from './upload/stream.js';
+export { RawClient, type RawClientOptions, type DownloadFileOptions, type SseCDownloadKey, } from './raw/index.js';
+export { B2Error, ExpiredAuthTokenError, BadAuthTokenError, ServiceUnavailableError, RequestTimeoutError, TooManyRequestsError, CapExceededError, AccessDeniedError, FileNotPresentError, DuplicateBucketNameError, BadRequestError, BadUploadUrlError, ChecksumMismatchError, B2InsufficientCapabilityError, B2SsrfError, NetworkError, classifyError, } from './errors/index.js';
+export { InMemoryAccountInfo } from './auth/in-memory.js';
+export type { AccountInfo, UploadUrlEntry } from './auth/account-info.js';
+export { IncrementalSha1, sha1Hex } from './streams/hash.js';
+export { toContentSource, BlobSource, BufferSource, StreamSource } from './streams/source.js';
+export type { ContentSource } from './streams/source.js';
+export type { ProgressEvent, ProgressListener } from './streams/progress.js';
+export { FetchTransport, RetryTransport } from './http/transport.js';
+export type { HttpTransport, HttpRequest, HttpResponse, RetryTransportOptions, } from './http/transport.js';
+export { UrlGuard, deriveAllowedSuffixes } from './http/url-guard.js';
+export type { RetryOptions } from './http/retry.js';
+export type { DownloadResult, HeadResult } from './download/single.js';
+export { EncryptionKey, SSE_B2, SSE_NONE, sseCustomer } from './types/encryption.js';
+export { paginateItems, paginatePages } from './util/paginator.js';
+export type { PageFetcher, PaginatorOptions } from './util/paginator.js';
+export { BucketRetentionMode, BucketType, CorsOperation } from './types/bucket.js';
+export { Capability } from './types/auth.js';
+export { EncryptionAlgorithm, EncryptionMode } from './types/encryption.js';
+export { EventType } from './types/notifications.js';
+export { FileAction, MetadataDirective } from './types/file.js';
+export { LegalHoldValue, RetentionMode } from './types/lock.js';
+export type * from './types/index.js';
+export { accountId, applicationKeyId, bucketId, fileId, keyId, largeFileId, } from './types/ids.js';
+export { VERSION } from './version.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACxF,OAAO,EACL,MAAM,EACN,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,QAAQ,EAAE,KAAK,mBAAmB,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAA;AAEtF,YAAY,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAE3D,OAAO,EACL,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,eAAe,GACrB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EACL,OAAO,EACP,qBAAqB,EACrB,iBAAiB,EACjB,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,6BAA6B,EAC7B,WAAW,EACX,YAAY,EACZ,aAAa,GACd,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACzD,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAEzE,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAC5D,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAC7F,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAE5E,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpE,YAAY,EACV,aAAa,EACb,WAAW,EACX,YAAY,EACZ,qBAAqB,GACtB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,QAAQ,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AACrE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEnD,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAKpF,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAClE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAOxE,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAClF,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAC3E,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AACpD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAC/D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAE/D,mBAAmB,kBAAkB,CAAA;AAQrC,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,QAAQ,EACR,MAAM,EACN,KAAK,EACL,WAAW,GACZ,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -0,0 +1,78 @@
+import { B2Client } from "./client.js";
+import { Bucket } from "./bucket.js";
+import { B2Object } from "./object.js";
+import { RawClient } from "./raw/index.js";
+import { AccessDeniedError, B2Error, B2InsufficientCapabilityError, B2SsrfError, BadAuthTokenError, BadRequestError, BadUploadUrlError, CapExceededError, ChecksumMismatchError, DuplicateBucketNameError, ExpiredAuthTokenError, FileNotPresentError, NetworkError, RequestTimeoutError, ServiceUnavailableError, TooManyRequestsError, classifyError } from "./errors/index.js";
+import { InMemoryAccountInfo } from "./auth/in-memory.js";
+import { IncrementalSha1, sha1Hex } from "./streams/hash.js";
+import { BlobSource, BufferSource, StreamSource, toContentSource } from "./streams/source.js";
+import { FetchTransport, RetryTransport } from "./http/transport.js";
+import { UrlGuard, deriveAllowedSuffixes } from "./http/url-guard.js";
+import { EncryptionAlgorithm, EncryptionKey, EncryptionMode, SSE_B2, SSE_NONE, sseCustomer } from "./types/encryption.js";
+import { paginateItems, paginatePages } from "./util/paginator.js";
+import { BucketRetentionMode, BucketType, CorsOperation } from "./types/bucket.js";
+import { Capability } from "./types/auth.js";
+import { EventType } from "./types/notifications.js";
+import { FileAction, MetadataDirective } from "./types/file.js";
+import { LegalHoldValue, RetentionMode } from "./types/lock.js";
+import { accountId, applicationKeyId, bucketId, fileId, keyId, largeFileId } from "./types/ids.js";
+import { VERSION } from "./version.js";
+export {
+  AccessDeniedError,
+  B2Client,
+  B2Error,
+  B2InsufficientCapabilityError,
+  B2Object,
+  B2SsrfError,
+  BadAuthTokenError,
+  BadRequestError,
+  BadUploadUrlError,
+  BlobSource,
+  Bucket,
+  BucketRetentionMode,
+  BucketType,
+  BufferSource,
+  CapExceededError,
+  Capability,
+  ChecksumMismatchError,
+  CorsOperation,
+  DuplicateBucketNameError,
+  EncryptionAlgorithm,
+  EncryptionKey,
+  EncryptionMode,
+  EventType,
+  ExpiredAuthTokenError,
+  FetchTransport,
+  FileAction,
+  FileNotPresentError,
+  InMemoryAccountInfo,
+  IncrementalSha1,
+  LegalHoldValue,
+  MetadataDirective,
+  NetworkError,
+  RawClient,
+  RequestTimeoutError,
+  RetentionMode,
+  RetryTransport,
+  SSE_B2,
+  SSE_NONE,
+  ServiceUnavailableError,
+  StreamSource,
+  TooManyRequestsError,
+  UrlGuard,
+  VERSION,
+  accountId,
+  applicationKeyId,
+  bucketId,
+  classifyError,
+  deriveAllowedSuffixes,
+  fileId,
+  keyId,
+  largeFileId,
+  paginateItems,
+  paginatePages,
+  sha1Hex,
+  sseCustomer,
+  toContentSource
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;"}

package/dist/notifications/index.cjs

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const webhook = require("./webhook.cjs");
+exports.B2_WEBHOOK_SIGNATURE_HEADER = webhook.B2_WEBHOOK_SIGNATURE_HEADER;
+exports.requireValidWebhook = webhook.requireValidWebhook;
+exports.verifyWebhookSignature = webhook.verifyWebhookSignature;
+//# sourceMappingURL=index.cjs.map

package/dist/notifications/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;"}

package/dist/notifications/index.d.cts

@@ -0,0 +1,3 @@
+export { B2_WEBHOOK_SIGNATURE_HEADER, requireValidWebhook, verifyWebhookSignature, } from './webhook.js';
+export type { VerifyWebhookOptions, VerifyWebhookResult, WebhookEvent, WebhookPayload, } from './webhook.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/notifications/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/notifications/index.js"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,cAAc,GACf,MAAM,cAAc,CAAA"}

package/dist/notifications/index.d.ts

@@ -0,0 +1,3 @@
+export { B2_WEBHOOK_SIGNATURE_HEADER, requireValidWebhook, verifyWebhookSignature, } from './webhook.js';
+export type { VerifyWebhookOptions, VerifyWebhookResult, WebhookEvent, WebhookPayload, } from './webhook.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/notifications/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/notifications/index.js"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,cAAc,GACf,MAAM,cAAc,CAAA"}

package/dist/notifications/index.js

@@ -0,0 +1,7 @@
+import { B2_WEBHOOK_SIGNATURE_HEADER, requireValidWebhook, verifyWebhookSignature } from "./webhook.js";
+export {
+  B2_WEBHOOK_SIGNATURE_HEADER,
+  requireValidWebhook,
+  verifyWebhookSignature
+};
+//# sourceMappingURL=index.js.map

package/dist/notifications/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/dist/notifications/webhook.cjs

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const textCodec = require("../util/text-codec.cjs");
+const B2_WEBHOOK_SIGNATURE_HEADER = "x-bz-event-notification-signature";
+const SIGNATURE_VERSION_PREFIX = "v1=";
+function timingSafeEqual(a, b) {
+  if (a.byteLength !== b.byteLength) return false;
+  let diff = 0;
+  for (let i = 0; i < a.byteLength; i++) {
+    diff |= a[i] ^ b[i];
+  }
+  return diff === 0;
+}
+function hexToBytes(hex) {
+  if (hex.length % 2 !== 0) return null;
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.byteLength; i++) {
+    const byte = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    if (Number.isNaN(byte)) return null;
+    out[i] = byte;
+  }
+  return out;
+}
+function pickSignature(raw) {
+  if (raw === void 0) return null;
+  if (Array.isArray(raw)) {
+    for (const v of raw) {
+      if (typeof v === "string" && v.length > 0) return v;
+    }
+    return null;
+  }
+  return typeof raw === "string" && raw.length > 0 ? raw : null;
+}
+function bytes(s) {
+  return textCodec.utf8Encoder.encode(s);
+}
+function bodyBytes(body) {
+  return typeof body === "string" ? bytes(body) : body;
+}
+async function hmacSha256(secret, body) {
+  const secretBytes = bytes(secret);
+  const key = await globalThis.crypto.subtle.importKey(
+    "raw",
+    secretBytes.buffer.slice(
+      secretBytes.byteOffset,
+      secretBytes.byteOffset + secretBytes.byteLength
+    ),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await globalThis.crypto.subtle.sign(
+    "HMAC",
+    key,
+    body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength)
+  );
+  return new Uint8Array(sig);
+}
+function tryParse(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function looksLikePayload(value) {
+  return typeof value === "object" && value !== null && Array.isArray(value.events);
+}
+async function verifyWebhookSignature(opts) {
+  if (typeof opts.secret !== "string" || opts.secret.length === 0) {
+    return { valid: false, payload: null, reason: "missing signing secret" };
+  }
+  const signature = pickSignature(opts.signature);
+  if (signature === null) {
+    return { valid: false, payload: null, reason: "missing signature header" };
+  }
+  if (!signature.startsWith(SIGNATURE_VERSION_PREFIX)) {
+    return { valid: false, payload: null, reason: "unsupported signature version" };
+  }
+  const claimed = hexToBytes(signature.slice(SIGNATURE_VERSION_PREFIX.length).toLowerCase());
+  if (claimed === null) {
+    return { valid: false, payload: null, reason: "bad signature format" };
+  }
+  const raw = bodyBytes(opts.body);
+  const expected = await hmacSha256(opts.secret, raw);
+  if (!timingSafeEqual(claimed, expected)) {
+    return { valid: false, payload: null, reason: "signature mismatch" };
+  }
+  const decoded = typeof opts.body === "string" ? opts.body : textCodec.utf8Decoder.decode(raw);
+  const parsed = tryParse(decoded);
+  if (!looksLikePayload(parsed)) {
+    return { valid: false, payload: null, reason: "invalid payload shape" };
+  }
+  return { valid: true, payload: parsed, reason: null };
+}
+async function requireValidWebhook(opts) {
+  const result = await verifyWebhookSignature(opts);
+  if (!result.valid || result.payload === null) {
+    throw new Error(`B2 webhook verification failed: ${result.reason ?? "unknown"}`);
+  }
+  return result.payload;
+}
+exports.B2_WEBHOOK_SIGNATURE_HEADER = B2_WEBHOOK_SIGNATURE_HEADER;
+exports.requireValidWebhook = requireValidWebhook;
+exports.verifyWebhookSignature = verifyWebhookSignature;
+//# sourceMappingURL=webhook.cjs.map

package/dist/notifications/webhook.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.cjs","sources":["../../src/notifications/webhook.ts"],"sourcesContent":["import type { EventType } from '../types/notifications.ts'\nimport { utf8Decoder, utf8Encoder } from '../util/text-codec.ts'\n\n/**\n * The HTTP header B2 attaches to every event-notification webhook delivery.\n * The value is a versioned HMAC-SHA256 signature of the raw request body:\n * `v1=<lowercase-hex>`.\n *\n * The lowercase form matches Node's `req.headers` normalisation and most\n * server-framework conventions. Producers must compare case-insensitively.\n */\nexport const B2_WEBHOOK_SIGNATURE_HEADER = 'x-bz-event-notification-signature'\n\n/** Current B2 event-notification signature scheme prefix. */\nconst SIGNATURE_VERSION_PREFIX = 'v1='\n\n/**\n * A single event entry inside a B2 webhook payload.\n *\n * The `events` array on the parsed body contains zero or more of these. Most\n * deliveries hold a single event, but B2 may coalesce multiple events from the\n * same bucket into one delivery for efficiency, so callers should iterate.\n *\n * @see https://www.backblaze.com/apidocs/event-notifications-overview\n */\nexport interface WebhookEvent {\n  /** Account that owns the bucket the event fired on. */\n  readonly accountId: string\n  /** Bucket ID the event fired on. */\n  readonly bucketId: string\n  /** Bucket name at the moment the event fired. */\n  readonly bucketName: string\n  /** Globally unique event identifier (useful for idempotency on the receiver). */\n  readonly eventId: string\n  /** Event time in UNIX milliseconds (UTC). */\n  readonly eventTimestamp: number\n  /** Specific event type, e.g. `'b2:ObjectCreated:Upload'`. */\n  readonly eventType: EventType\n  /** Schema version of the event payload. Currently `1`. */\n  readonly eventVersion: number\n  /** Name of the `EventNotificationRule` on the bucket that matched. */\n  readonly matchedRuleName: string\n  /** B2 file name of the affected object. */\n  readonly objectName: string\n  /** Affected object's size in bytes, when present (absent for some delete events). */\n  readonly objectSize?: number\n  /** Specific file version ID, when applicable. */\n  readonly objectVersionId?: string\n}\n\n/**\n * The complete JSON body B2 POSTs to a webhook endpoint after signature\n * verification succeeds. See {@link verifyWebhookSignature}.\n */\nexport interface WebhookPayload {\n  /** One or more event entries. Always non-empty on real deliveries. */\n  readonly events: readonly WebhookEvent[]\n}\n\n/**\n * Options for {@link verifyWebhookSignature} and {@link requireValidWebhook}.\n */\nexport interface VerifyWebhookOptions {\n  /**\n   * The raw request body B2 sent. MUST be the exact bytes received: any\n   * JSON re-serialisation or whitespace normalisation will break the HMAC.\n   *\n   * Pass a `Uint8Array` whenever the surrounding framework gives you raw\n   * bytes (e.g. `req.rawBody` in fastify, `req.arrayBuffer()` in Hono /\n   * Workers). The string overload is provided for convenience when a\n   * framework already decoded the body as UTF-8.\n   */\n  readonly body: string | Uint8Array\n  /**\n   * Value of the {@link B2_WEBHOOK_SIGNATURE_HEADER} header.\n   *\n   * Accepts a single string or an array (Node's `req.headers` returns\n   * `string | string[] | undefined`). When an array is supplied, the first\n   * non-empty element is used: B2 only ever sends one value, and rejecting\n   * the multi-value case prevents callers from accidentally trusting a\n   * spoofed second header injected by a buggy reverse proxy.\n   */\n  readonly signature: string | readonly string[] | undefined\n  /**\n   * The signing secret from `EventNotificationRule.targetConfiguration.hmacSha256SigningSecret`.\n   *\n   * This is the exact string B2 returned in the `b2_set_bucket_notification_rules`\n   * response. Do NOT base64-decode or otherwise transform it.\n   */\n  readonly secret: string\n}\n\n/**\n * Outcome of {@link verifyWebhookSignature}.\n *\n * The verifier never throws; instead it returns a discriminated result so\n * callers can branch on `valid` and log `reason` without try/catch noise.\n * Use {@link requireValidWebhook} when an exception-based control flow is\n * more convenient.\n */\nexport interface VerifyWebhookResult {\n  /** `true` only when the HMAC matched and the body parsed as a valid payload. */\n  readonly valid: boolean\n  /** Parsed payload when {@link valid} is `true`; otherwise `null`. */\n  readonly payload: WebhookPayload | null\n  /** Short reason describing why verification failed, or `null` on success. */\n  readonly reason: string | null\n}\n\n/**\n * Constant-time comparison of two equal-length byte sequences.\n *\n * Web Crypto exposes no native timing-safe compare, so we do the standard\n * XOR-and-OR pattern ourselves. The early-out on length mismatch is fine\n * here because the signature length is publicly fixed (32 bytes for\n * HMAC-SHA256), so a length-mismatch branch leaks nothing about the secret.\n *\n * @param a - First byte sequence.\n * @param b - Second byte sequence.\n *\n * @returns `true` if the byte sequences are byte-for-byte equal.\n */\nfunction timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean {\n  if (a.byteLength !== b.byteLength) return false\n  let diff = 0\n  for (let i = 0; i < a.byteLength; i++) {\n    // Non-null asserted: `a` and `b` have the same length and `i` is in range.\n    diff |= (a[i] as number) ^ (b[i] as number)\n  }\n  return diff === 0\n}\n\n/**\n * Decode a lowercase hex string into bytes. Returns `null` on any malformed\n * input (odd length, non-hex characters). We don't surface a thrown error\n * because all malformed signatures should land in the same\n * `reason: 'bad signature format'` bucket on the verifier's caller,\n * regardless of which specific malformation triggered it.\n *\n * @param hex - The lowercase hex string to decode.\n *\n * @returns The decoded bytes, or `null` if the input was not valid hex.\n */\nfunction hexToBytes(hex: string): Uint8Array | null {\n  if (hex.length % 2 !== 0) return null\n  const out = new Uint8Array(hex.length / 2)\n  for (let i = 0; i < out.byteLength; i++) {\n    const byte = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16)\n    if (Number.isNaN(byte)) return null\n    out[i] = byte\n  }\n  return out\n}\n\n/**\n * Pick the single signature string from {@link VerifyWebhookOptions.signature}.\n * Returns `null` if absent, empty, or supplied as an empty array.\n *\n * @param raw - The signature value as supplied by the caller.\n *\n * @returns The chosen signature string, or `null` if no candidate was usable.\n */\nfunction pickSignature(raw: VerifyWebhookOptions['signature']): string | null {\n  if (raw === undefined) return null\n  if (Array.isArray(raw)) {\n    for (const v of raw) {\n      if (typeof v === 'string' && v.length > 0) return v\n    }\n    return null\n  }\n  return typeof raw === 'string' && raw.length > 0 ? raw : null\n}\n\n/**\n * Encode a UTF-8 string into bytes using a shared encoder.\n *\n * @param s - The string to encode.\n *\n * @returns The UTF-8 encoded bytes.\n */\nfunction bytes(s: string): Uint8Array {\n  return utf8Encoder.encode(s)\n}\n\n/**\n * Normalise the body parameter to a `Uint8Array` view of its raw bytes.\n *\n * Strings are UTF-8 encoded. `Uint8Array` inputs pass through untouched.\n *\n * @param body - The raw request body as supplied by the caller.\n *\n * @returns The body as a byte sequence ready for HMAC computation.\n */\nfunction bodyBytes(body: string | Uint8Array): Uint8Array {\n  return typeof body === 'string' ? bytes(body) : body\n}\n\n/**\n * Compute the HMAC-SHA256 of `body` under `secret` using the isomorphic Web\n * Crypto API. Works in Node 22+, browsers, Bun, Deno, and Cloudflare Workers\n * without any platform-specific code.\n *\n * @param secret - The HMAC signing secret.\n * @param body - The bytes to sign.\n *\n * @returns The 32-byte HMAC-SHA256 digest.\n */\nasync function hmacSha256(secret: string, body: Uint8Array): Promise<Uint8Array> {\n  // The explicit `slice(byteOffset, byteOffset + byteLength)` defends against\n  // a Uint8Array view that points at a subset of a larger buffer. Casting to\n  // `ArrayBuffer` is needed because TS 5.7+ types Uint8Array's buffer as\n  // `ArrayBufferLike`, which includes `SharedArrayBuffer`. Web Crypto's\n  // signatures only accept the plain `ArrayBuffer` variant.\n  const secretBytes = bytes(secret)\n  const key = await globalThis.crypto.subtle.importKey(\n    'raw',\n    secretBytes.buffer.slice(\n      secretBytes.byteOffset,\n      secretBytes.byteOffset + secretBytes.byteLength,\n    ) as ArrayBuffer,\n    { name: 'HMAC', hash: 'SHA-256' },\n    false,\n    ['sign'],\n  )\n  const sig = await globalThis.crypto.subtle.sign(\n    'HMAC',\n    key,\n    body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength) as ArrayBuffer,\n  )\n  return new Uint8Array(sig)\n}\n\n/**\n * Best-effort JSON parse that returns `null` on failure. We accept partial\n * structural mismatches (no `events` array etc.) at the caller's discretion.\n *\n * @param raw - The decoded request body string.\n *\n * @returns The parsed payload, or `null` if `raw` is not valid JSON.\n */\nfunction tryParse(raw: string): unknown {\n  try {\n    return JSON.parse(raw) as unknown\n  } catch {\n    return null\n  }\n}\n\n/**\n * Narrow `value` to {@link WebhookPayload}. Currently only checks that\n * `events` is an array; per-event validation is the caller's responsibility\n * since B2 may add new optional fields and we don't want to reject deliveries\n * that include them.\n *\n * @param value - The parsed JSON value to validate.\n *\n * @returns `true` if the value matches the {@link WebhookPayload} shape.\n */\nfunction looksLikePayload(value: unknown): value is WebhookPayload {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    Array.isArray((value as { events?: unknown }).events)\n  )\n}\n\n/**\n * Verify the HMAC-SHA256 signature B2 attaches to event-notification webhooks\n * and parse the body on success.\n *\n * Never throws: returns a discriminated {@link VerifyWebhookResult}. Use this\n * when you want a single, explicit place to branch on `valid` and log the\n * `reason` on rejection.\n *\n * @param opts - The body, signature header, and signing secret. See {@link VerifyWebhookOptions}.\n *\n * @returns Verification result with optional parsed payload and failure reason.\n *\n * @example\n * ```ts\n * import { verifyWebhookSignature, B2_WEBHOOK_SIGNATURE_HEADER } from '@backblaze-labs/b2-sdk/notifications'\n *\n * app.post('/webhook', async (req, res) => {\n *   const raw = await readRawBody(req) // raw bytes, NOT json\n *   const result = await verifyWebhookSignature({\n *     body: raw,\n *     signature: req.headers[B2_WEBHOOK_SIGNATURE_HEADER],\n *     secret: process.env.B2_WEBHOOK_SECRET,\n *   })\n *   if (!result.valid) return res.status(401).send(result.reason)\n *   for (const event of result.payload.events) handleEvent(event)\n *   res.status(204).end()\n * })\n * ```\n *\n */\nexport async function verifyWebhookSignature(\n  opts: VerifyWebhookOptions,\n): Promise<VerifyWebhookResult> {\n  if (typeof opts.secret !== 'string' || opts.secret.length === 0) {\n    return { valid: false, payload: null, reason: 'missing signing secret' }\n  }\n\n  const signature = pickSignature(opts.signature)\n  if (signature === null) {\n    return { valid: false, payload: null, reason: 'missing signature header' }\n  }\n\n  if (!signature.startsWith(SIGNATURE_VERSION_PREFIX)) {\n    return { valid: false, payload: null, reason: 'unsupported signature version' }\n  }\n\n  const claimed = hexToBytes(signature.slice(SIGNATURE_VERSION_PREFIX.length).toLowerCase())\n  if (claimed === null) {\n    return { valid: false, payload: null, reason: 'bad signature format' }\n  }\n\n  const raw = bodyBytes(opts.body)\n  const expected = await hmacSha256(opts.secret, raw)\n\n  if (!timingSafeEqual(claimed, expected)) {\n    return { valid: false, payload: null, reason: 'signature mismatch' }\n  }\n\n  const decoded = typeof opts.body === 'string' ? opts.body : utf8Decoder.decode(raw)\n  const parsed = tryParse(decoded)\n  if (!looksLikePayload(parsed)) {\n    return { valid: false, payload: null, reason: 'invalid payload shape' }\n  }\n\n  return { valid: true, payload: parsed, reason: null }\n}\n\n/**\n * Throwing wrapper around {@link verifyWebhookSignature}. Returns the parsed\n * payload on success; throws an `Error` whose message is the verifier's\n * `reason` string on any failure.\n *\n * Useful when you want the verification to integrate with your framework's\n * existing error-handling middleware rather than handling the result inline.\n *\n * @param opts - The body, signature header, and signing secret. See {@link VerifyWebhookOptions}.\n *\n * @returns The parsed webhook payload.\n *\n * @throws When verification fails for any reason.\n */\nexport async function requireValidWebhook(opts: VerifyWebhookOptions): Promise<WebhookPayload> {\n  const result = await verifyWebhookSignature(opts)\n  if (!result.valid || result.payload === null) {\n    throw new Error(`B2 webhook verification failed: ${result.reason ?? 'unknown'}`)\n  }\n  return result.payload\n}\n"],"names":["utf8Encoder","utf8Decoder"],"mappings":";;;AAWO,MAAM,8BAA8B;AAG3C,MAAM,2BAA2B;AA4GjC,SAAS,gBAAgB,GAAe,GAAwB;AAC9D,MAAI,EAAE,eAAe,EAAE,WAAY,QAAO;AAC1C,MAAI,OAAO;AACX,WAAS,IAAI,GAAG,IAAI,EAAE,YAAY,KAAK;AAErC,YAAS,EAAE,CAAC,IAAgB,EAAE,CAAC;AAAA,EACjC;AACA,SAAO,SAAS;AAClB;AAaA,SAAS,WAAW,KAAgC;AAClD,MAAI,IAAI,SAAS,MAAM,EAAG,QAAO;AACjC,QAAM,MAAM,IAAI,WAAW,IAAI,SAAS,CAAC;AACzC,WAAS,IAAI,GAAG,IAAI,IAAI,YAAY,KAAK;AACvC,UAAM,OAAO,OAAO,SAAS,IAAI,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE;AAC5D,QAAI,OAAO,MAAM,IAAI,EAAG,QAAO;AAC/B,QAAI,CAAC,IAAI;AAAA,EACX;AACA,SAAO;AACT;AAUA,SAAS,cAAc,KAAuD;AAC5E,MAAI,QAAQ,OAAW,QAAO;AAC9B,MAAI,MAAM,QAAQ,GAAG,GAAG;AACtB,eAAW,KAAK,KAAK;AACnB,UAAI,OAAO,MAAM,YAAY,EAAE,SAAS,EAAG,QAAO;AAAA,IACpD;AACA,WAAO;AAAA,EACT;AACA,SAAO,OAAO,QAAQ,YAAY,IAAI,SAAS,IAAI,MAAM;AAC3D;AASA,SAAS,MAAM,GAAuB;AACpC,SAAOA,UAAAA,YAAY,OAAO,CAAC;AAC7B;AAWA,SAAS,UAAU,MAAuC;AACxD,SAAO,OAAO,SAAS,WAAW,MAAM,IAAI,IAAI;AAClD;AAYA,eAAe,WAAW,QAAgB,MAAuC;AAM/E,QAAM,cAAc,MAAM,MAAM;AAChC,QAAM,MAAM,MAAM,WAAW,OAAO,OAAO;AAAA,IACzC;AAAA,IACA,YAAY,OAAO;AAAA,MACjB,YAAY;AAAA,MACZ,YAAY,aAAa,YAAY;AAAA,IAAA;AAAA,IAEvC,EAAE,MAAM,QAAQ,MAAM,UAAA;AAAA,IACtB;AAAA,IACA,CAAC,MAAM;AAAA,EAAA;AAET,QAAM,MAAM,MAAM,WAAW,OAAO,OAAO;AAAA,IACzC;AAAA,IACA;AAAA,IACA,KAAK,OAAO,MAAM,KAAK,YAAY,KAAK,aAAa,KAAK,UAAU;AAAA,EAAA;AAEtE,SAAO,IAAI,WAAW,GAAG;AAC3B;AAUA,SAAS,SAAS,KAAsB;AACtC,MAAI;AACF,WAAO,KAAK,MAAM,GAAG;AAAA,EACvB,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAYA,SAAS,iBAAiB,OAAyC;AACjE,SACE,OAAO,UAAU,YACjB,UAAU,QACV,MAAM,QAAS,MAA+B,MAAM;AAExD;AAgCA,eAAsB,uBACpB,MAC8B;AAC9B,MAAI,OAAO,KAAK,WAAW,YAAY,KAAK,OAAO,WAAW,GAAG;AAC/D,WAAO,EAAE,OAAO,OAAO,SAAS,MAAM,QAAQ,yBAAA;AAAA,EAChD;AAEA,QAAM,YAAY,cAAc,KAAK,SAAS;AAC9C,MAAI,cAAc,MAAM;AACtB,WAAO,EAAE,OAAO,OAAO,SAAS,MAAM,QAAQ,2BAAA;AAAA,EAChD;AAEA,MAAI,CAAC,UAAU,WAAW,wBAAwB,GAAG;AACnD,WAAO,EAAE,OAAO,OAAO,SAAS,MAAM,QAAQ,gCAAA;AAAA,EAChD;AAEA,QAAM,UAAU,WAAW,UAAU,MAAM,yBAAyB,MAAM,EAAE,aAAa;AACzF,MAAI,YAAY,MAAM;AACpB,WAAO,EAAE,OAAO,OAAO,SAAS,MAAM,QAAQ,uBAAA;AAAA,EAChD;AAEA,QAAM,MAAM,UAAU,KAAK,IAAI;AAC/B,QAAM,WAAW,MAAM,WAAW,KAAK,QAAQ,GAAG;AAElD,MAAI,CAAC,gBAAgB,SAAS,QAAQ,GAAG;AACvC,WAAO,EAAE,OAAO,OAAO,SAAS,MAAM,QAAQ,qBAAA;AAAA,EAChD;AAEA,QAAM,UAAU,OAAO,KAAK,SAAS,WAAW,KAAK,OAAOC,UAAAA,YAAY,OAAO,GAAG;AAClF,QAAM,SAAS,SAAS,OAAO;AAC/B,MAAI,CAAC,iBAAiB,MAAM,GAAG;AAC7B,WAAO,EAAE,OAAO,OAAO,SAAS,MAAM,QAAQ,wBAAA;AAAA,EAChD;AAEA,SAAO,EAAE,OAAO,MAAM,SAAS,QAAQ,QAAQ,KAAA;AACjD;AAgBA,eAAsB,oBAAoB,MAAqD;AAC7F,QAAM,SAAS,MAAM,uBAAuB,IAAI;AAChD,MAAI,CAAC,OAAO,SAAS,OAAO,YAAY,MAAM;AAC5C,UAAM,IAAI,MAAM,mCAAmC,OAAO,UAAU,SAAS,EAAE;AAAA,EACjF;AACA,SAAO,OAAO;AAChB;;;;"}

package/dist/notifications/webhook.d.cts

@@ -0,0 +1,146 @@
+import { EventType } from '../types/notifications.js';
+/**
+ * The HTTP header B2 attaches to every event-notification webhook delivery.
+ * The value is a versioned HMAC-SHA256 signature of the raw request body:
+ * `v1=<lowercase-hex>`.
+ *
+ * The lowercase form matches Node's `req.headers` normalisation and most
+ * server-framework conventions. Producers must compare case-insensitively.
+ */
+export declare const B2_WEBHOOK_SIGNATURE_HEADER = "x-bz-event-notification-signature";
+/**
+ * A single event entry inside a B2 webhook payload.
+ *
+ * The `events` array on the parsed body contains zero or more of these. Most
+ * deliveries hold a single event, but B2 may coalesce multiple events from the
+ * same bucket into one delivery for efficiency, so callers should iterate.
+ *
+ * @see https://www.backblaze.com/apidocs/event-notifications-overview
+ */
+export interface WebhookEvent {
+    /** Account that owns the bucket the event fired on. */
+    readonly accountId: string;
+    /** Bucket ID the event fired on. */
+    readonly bucketId: string;
+    /** Bucket name at the moment the event fired. */
+    readonly bucketName: string;
+    /** Globally unique event identifier (useful for idempotency on the receiver). */
+    readonly eventId: string;
+    /** Event time in UNIX milliseconds (UTC). */
+    readonly eventTimestamp: number;
+    /** Specific event type, e.g. `'b2:ObjectCreated:Upload'`. */
+    readonly eventType: EventType;
+    /** Schema version of the event payload. Currently `1`. */
+    readonly eventVersion: number;
+    /** Name of the `EventNotificationRule` on the bucket that matched. */
+    readonly matchedRuleName: string;
+    /** B2 file name of the affected object. */
+    readonly objectName: string;
+    /** Affected object's size in bytes, when present (absent for some delete events). */
+    readonly objectSize?: number;
+    /** Specific file version ID, when applicable. */
+    readonly objectVersionId?: string;
+}
+/**
+ * The complete JSON body B2 POSTs to a webhook endpoint after signature
+ * verification succeeds. See {@link verifyWebhookSignature}.
+ */
+export interface WebhookPayload {
+    /** One or more event entries. Always non-empty on real deliveries. */
+    readonly events: readonly WebhookEvent[];
+}
+/**
+ * Options for {@link verifyWebhookSignature} and {@link requireValidWebhook}.
+ */
+export interface VerifyWebhookOptions {
+    /**
+     * The raw request body B2 sent. MUST be the exact bytes received: any
+     * JSON re-serialisation or whitespace normalisation will break the HMAC.
+     *
+     * Pass a `Uint8Array` whenever the surrounding framework gives you raw
+     * bytes (e.g. `req.rawBody` in fastify, `req.arrayBuffer()` in Hono /
+     * Workers). The string overload is provided for convenience when a
+     * framework already decoded the body as UTF-8.
+     */
+    readonly body: string | Uint8Array;
+    /**
+     * Value of the {@link B2_WEBHOOK_SIGNATURE_HEADER} header.
+     *
+     * Accepts a single string or an array (Node's `req.headers` returns
+     * `string | string[] | undefined`). When an array is supplied, the first
+     * non-empty element is used: B2 only ever sends one value, and rejecting
+     * the multi-value case prevents callers from accidentally trusting a
+     * spoofed second header injected by a buggy reverse proxy.
+     */
+    readonly signature: string | readonly string[] | undefined;
+    /**
+     * The signing secret from `EventNotificationRule.targetConfiguration.hmacSha256SigningSecret`.
+     *
+     * This is the exact string B2 returned in the `b2_set_bucket_notification_rules`
+     * response. Do NOT base64-decode or otherwise transform it.
+     */
+    readonly secret: string;
+}
+/**
+ * Outcome of {@link verifyWebhookSignature}.
+ *
+ * The verifier never throws; instead it returns a discriminated result so
+ * callers can branch on `valid` and log `reason` without try/catch noise.
+ * Use {@link requireValidWebhook} when an exception-based control flow is
+ * more convenient.
+ */
+export interface VerifyWebhookResult {
+    /** `true` only when the HMAC matched and the body parsed as a valid payload. */
+    readonly valid: boolean;
+    /** Parsed payload when {@link valid} is `true`; otherwise `null`. */
+    readonly payload: WebhookPayload | null;
+    /** Short reason describing why verification failed, or `null` on success. */
+    readonly reason: string | null;
+}
+/**
+ * Verify the HMAC-SHA256 signature B2 attaches to event-notification webhooks
+ * and parse the body on success.
+ *
+ * Never throws: returns a discriminated {@link VerifyWebhookResult}. Use this
+ * when you want a single, explicit place to branch on `valid` and log the
+ * `reason` on rejection.
+ *
+ * @param opts - The body, signature header, and signing secret. See {@link VerifyWebhookOptions}.
+ *
+ * @returns Verification result with optional parsed payload and failure reason.
+ *
+ * @example
+ * ```ts
+ * import { verifyWebhookSignature, B2_WEBHOOK_SIGNATURE_HEADER } from '@backblaze-labs/b2-sdk/notifications'
+ *
+ * app.post('/webhook', async (req, res) => {
+ *   const raw = await readRawBody(req) // raw bytes, NOT json
+ *   const result = await verifyWebhookSignature({
+ *     body: raw,
+ *     signature: req.headers[B2_WEBHOOK_SIGNATURE_HEADER],
+ *     secret: process.env.B2_WEBHOOK_SECRET,
+ *   })
+ *   if (!result.valid) return res.status(401).send(result.reason)
+ *   for (const event of result.payload.events) handleEvent(event)
+ *   res.status(204).end()
+ * })
+ * ```
+ *
+ */
+export declare function verifyWebhookSignature(opts: VerifyWebhookOptions): Promise<VerifyWebhookResult>;
+/**
+ * Throwing wrapper around {@link verifyWebhookSignature}. Returns the parsed
+ * payload on success; throws an `Error` whose message is the verifier's
+ * `reason` string on any failure.
+ *
+ * Useful when you want the verification to integrate with your framework's
+ * existing error-handling middleware rather than handling the result inline.
+ *
+ * @param opts - The body, signature header, and signing secret. See {@link VerifyWebhookOptions}.
+ *
+ * @returns The parsed webhook payload.
+ *
+ * @throws When verification fails for any reason.
+ */
+export declare function requireValidWebhook(opts: VerifyWebhookOptions): Promise<WebhookPayload>;
+//# sourceMappingURL=webhook.d.ts.map

package/dist/notifications/webhook.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../src/notifications/webhook.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAG1D;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,sCAAsC,CAAA;AAK9E;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,2CAA2C;IAC3C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,iDAAiD;IACjD,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;IAClC;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IAC1D;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAAA;IACvC,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AA+JD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,mBAAmB,CAAC,CAiC9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAM7F"}