@backblaze-labs/b2-sdk 0.1.0

package/dist/notifications/webhook.d.ts

@@ -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.ts.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"}

package/dist/notifications/webhook.js

@@ -0,0 +1,106 @@
+import { utf8Decoder, utf8Encoder } from "../util/text-codec.js";
+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 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 : 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;
+}
+export {
+  B2_WEBHOOK_SIGNATURE_HEADER,
+  requireValidWebhook,
+  verifyWebhookSignature
+};
+//# sourceMappingURL=webhook.js.map

package/dist/notifications/webhook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.js","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":[],"mappings":"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"}

package/dist/object.cjs

@@ -0,0 +1,212 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const parallel = require("./download/parallel.cjs");
+const single$1 = require("./download/single.cjs");
+const large = require("./upload/large.cjs");
+const single = require("./upload/single.cjs");
+const stream = require("./upload/stream.cjs");
+class B2Object {
+  /** The file name (path) within the bucket. */
+  fileName;
+  client;
+  bucket;
+  /**
+   * @param client - The parent B2Client instance.
+   * @param bucket - The parent Bucket this object belongs to.
+   * @param fileName - The file path within the bucket.
+   *
+   * @internal
+   */
+  constructor(client, bucket, fileName) {
+    this.client = client;
+    this.bucket = bucket;
+    this.fileName = fileName;
+  }
+  /**
+   * Uploads data to this file name. Automatically uses multipart upload for large files.
+   * @param options - Upload configuration including data source and optional settings.
+   *
+   * @returns Metadata for the uploaded file version.
+   */
+  async upload(options) {
+    const recommendedPartSize = this.client.accountInfo.getRecommendedPartSize();
+    const isLarge = options.source.size > recommendedPartSize;
+    if (isLarge) {
+      return large.uploadLargeFile(this.client.raw, this.client.accountInfo, {
+        bucketId: this.bucket.id,
+        fileName: this.fileName,
+        ...options
+      });
+    }
+    const { resume: _resume, resumeFileId: _resumeFileId, ...smallOptions } = options;
+    return single.uploadSmallFile(this.client.raw, this.client.accountInfo, {
+      bucketId: this.bucket.id,
+      fileName: this.fileName,
+      ...smallOptions
+    });
+  }
+  /**
+   * Downloads this file by name. Pass `method: 'HEAD'` to fetch only the
+   * response headers (file metadata) without streaming the body.
+   * @param options - Optional method, range, SSE-C decryption, response-header overrides, and abort signal.
+   *
+   * @returns The download result with response headers and body stream.
+   */
+  async download(options) {
+    return single$1.downloadByName(this.client.raw, this.client.accountInfo, {
+      bucketName: this.bucket.name,
+      fileName: this.fileName,
+      ...options
+    });
+  }
+  /**
+   * Fetches response headers for this file via HTTP HEAD. Returns a
+   * body-less result so callers never have to drain the (logically
+   * empty) HEAD body themselves.
+   *
+   * @param options - Optional range, SSE-C decryption, response-header
+   *   overrides, and abort signal. Same shape as {@link B2Object.download}'s
+   *   options minus `method` (always HEAD) and `onProgress` (no body).
+   *
+   * @returns Parsed download headers (content type, SHA-1, file info, etc.).
+   */
+  async head(options) {
+    return single$1.headByName(this.client.raw, this.client.accountInfo, {
+      bucketName: this.bucket.name,
+      fileName: this.fileName,
+      ...options
+    });
+  }
+  /**
+   * Downloads a specific version of this file by ID. Pass `method: 'HEAD'`
+   * to fetch only the response headers (file metadata) without streaming the body.
+   * @param fileId - The file version ID to download.
+   * @param options - Optional method, range, SSE-C decryption, response-header overrides, and abort signal.
+   *
+   * @returns The download result with response headers and body stream.
+   */
+  async downloadById(fileId, options) {
+    return single$1.downloadById(this.client.raw, this.client.accountInfo, {
+      fileId,
+      ...options
+    });
+  }
+  /**
+   * Fetches response headers for a specific version of this file by ID
+   * via HTTP HEAD. Returns a body-less result so callers never have to
+   * drain the (logically empty) HEAD body themselves.
+   *
+   * @param fileId - The file version ID to inspect.
+   * @param options - Optional range, SSE-C decryption, response-header
+   *   overrides, and abort signal.
+   *
+   * @returns Parsed download headers.
+   */
+  async headById(fileId, options) {
+    return single$1.headById(this.client.raw, this.client.accountInfo, {
+      fileId,
+      ...options
+    });
+  }
+  /**
+   * Creates a parallel-download ReadableStream that fetches the file in concurrent ranged chunks.
+   * @param fileId - The file version ID to download.
+   * @param totalSize - Total file size in bytes (needed to compute range boundaries).
+   * @param options - Concurrency, range size, and abort signal.
+   *
+   * @returns A Web ReadableStream of file data in sequential order.
+   */
+  createReadStream(fileId, totalSize, options) {
+    return parallel.createParallelDownloadStream(this.client.raw, this.client.accountInfo, {
+      fileId,
+      totalSize,
+      ...options
+    });
+  }
+  /**
+   * Creates a Web `WritableStream` that uploads streamed data into this file
+   * using the multipart protocol. Pipe a `ReadableStream<Uint8Array>` into the
+   * returned `writable` and await `done` to get the final {@link FileVersion}.
+   *
+   * Note: streaming uploads do not support resume because the size and per-part
+   * hashes are not known in advance. Use {@link upload} with a buffered source
+   * when resume is required.
+   *
+   * @param options - Streaming upload parameters (part size, concurrency, encryption).
+   *
+   * @returns A handle with the writable sink and a completion promise.
+   */
+  createWriteStream(options) {
+    return stream.createWriteStream(this.client.raw, this.client.accountInfo, {
+      bucketId: this.bucket.id,
+      fileName: this.fileName,
+      ...options ?? {}
+    });
+  }
+  /**
+   * Retrieves metadata for a specific file version.
+   * @param fileId - The file version ID to look up.
+   *
+   * @returns The file version metadata.
+   */
+  async getFileInfo(fileId) {
+    return this.client.raw.getFileInfo(
+      this.client.accountInfo.getApiUrl(),
+      this.client.accountInfo.getAuthToken(),
+      { fileId }
+    );
+  }
+  /**
+   * Hides this file by creating a hide marker at this file name.
+   *
+   * @returns Metadata for the newly created hide marker.
+   */
+  async hide() {
+    return this.bucket.hideFile(this.fileName);
+  }
+  /**
+   * Permanently deletes a specific version of this file.
+   * @param fileId - The unique identifier of the file version to delete.
+   */
+  async deleteVersion(fileId) {
+    await this.bucket.deleteFileVersion(this.fileName, fileId);
+  }
+  /**
+   * Sets or updates the Object Lock retention policy on a specific file
+   * version of this file.
+   *
+   * The bucket must have Object Lock enabled (`fileLockEnabled: true` at
+   * creation time). Governance-mode retention can be shortened or removed
+   * by passing `bypassGovernance: true` together with an application key
+   * that carries the `bypassGovernance` capability; compliance-mode
+   * retention cannot be shortened by anyone until the
+   * `retainUntilTimestamp` elapses.
+   *
+   * @param fileId - The file version to apply the policy to.
+   * @param retention - The retention policy to apply.
+   * @param options - Optional flag for shortening governance-mode retention.
+   *
+   * @returns Metadata for the updated file version.
+   */
+  async setRetention(fileId, retention, options) {
+    return this.bucket.updateFileRetention(this.fileName, fileId, retention, options);
+  }
+  /**
+   * Toggles the legal hold flag on a specific file version of this file.
+   *
+   * Legal hold is independent of retention: a file can be on legal hold
+   * without any retention policy, and vice versa. The bucket must have
+   * Object Lock enabled, and any caller must hold the `writeFileLegalHolds`
+   * capability.
+   *
+   * @param fileId - The file version to apply the flag to.
+   * @param legalHold - `'on'` to apply the hold, `'off'` to remove it.
+   *
+   * @returns Metadata for the updated file version.
+   */
+  async setLegalHold(fileId, legalHold) {
+    return this.bucket.updateFileLegalHold(this.fileName, fileId, legalHold);
+  }
+}
+exports.B2Object = B2Object;
+//# sourceMappingURL=object.cjs.map

package/dist/object.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"object.cjs","sources":["../src/object.ts"],"sourcesContent":["import type { Bucket } from './bucket.ts'\nimport type { B2Client } from './client.ts'\nimport { createParallelDownloadStream } from './download/parallel.ts'\nimport { type DownloadResult, downloadByName } from './download/single.ts'\nimport { type HeadResult, downloadById, headById, headByName } from './download/single.ts'\nimport type { SseCDownloadKey } from './raw/index.ts'\nimport type { ProgressListener } from './streams/progress.ts'\nimport type { ContentSource } from './streams/source.ts'\nimport type { EncryptionSetting } from './types/encryption.ts'\nimport type { FileVersion } from './types/file.ts'\nimport type { FileId, LargeFileId } from './types/ids.ts'\nimport type { FileRetentionValue, LegalHoldValue } from './types/lock.ts'\nimport { uploadLargeFile } from './upload/large.ts'\nimport { uploadSmallFile } from './upload/single.ts'\nimport { type UploadWriteHandle, createWriteStream } from './upload/stream.ts'\n\n/** Options accepted by {@link B2Object.download} and {@link B2Object.downloadById}. */\nexport interface DownloadCallOptions {\n  /**\n   * HTTP method. Defaults to `'GET'`. Use `'HEAD'` to fetch only\n   * response headers. Prefer the dedicated {@link B2Object.head} /\n   * {@link Bucket.head} method over this option — those return a\n   * body-less result so callers never have to remember to drain the\n   * empty body of a HEAD response.\n   */\n  readonly method?: 'GET' | 'HEAD'\n  /** HTTP Range header value (e.g., `\"bytes=0-999\"`). */\n  readonly range?: string\n  /** SSE-C decryption parameters, required if the file was uploaded with SSE-C. */\n  readonly serverSideEncryption?: SseCDownloadKey\n  /** Override the response `Content-Disposition` header. */\n  readonly b2ContentDisposition?: string\n  /** Override the response `Content-Language` header. */\n  readonly b2ContentLanguage?: string\n  /** Override the response `Content-Encoding` header. */\n  readonly b2ContentEncoding?: string\n  /** Override the response `Content-Type` header. */\n  readonly b2ContentType?: string\n  /** Override the response `Cache-Control` header. */\n  readonly b2CacheControl?: string\n  /** Override the response `Expires` header. */\n  readonly b2Expires?: string\n  /** Abort signal for cancelling the download. */\n  readonly signal?: AbortSignal\n  /**\n   * Callback invoked as the response body is consumed.\n   *\n   * Progress is byte-driven, not request-driven: the callback fires per\n   * chunk as the caller reads the returned `body` stream, and the final\n   * `partsCompleted: 1` event only fires once the stream is read to\n   * completion. Downloads that are dropped or aborted partway through\n   * will NOT emit a `completePart()` event.\n   */\n  readonly onProgress?: ProgressListener\n}\n\n/**\n * Options accepted by {@link B2Object.head} / {@link Bucket.head}.\n * Same shape as {@link DownloadCallOptions} minus `method` (always\n * HEAD) and `onProgress` (no body to track).\n */\nexport type HeadCallOptions = Omit<DownloadCallOptions, 'method' | 'onProgress'>\n\n/**\n * Handle to a specific file (by name) within a B2 bucket.\n *\n * Provides file-scoped upload, download, and management operations.\n * Obtained via {@link Bucket.file}.\n *\n * @example\n * ```ts\n * const obj = bucket.file('photos/2026/sunset.jpg')\n * await obj.upload({ source: new BufferSource(data) })\n * const result = await obj.download()\n * ```\n */\nexport class B2Object {\n  /** The file name (path) within the bucket. */\n  readonly fileName: string\n  private readonly client: B2Client\n  private readonly bucket: Bucket\n\n  /**\n   * @param client - The parent B2Client instance.\n   * @param bucket - The parent Bucket this object belongs to.\n   * @param fileName - The file path within the bucket.\n   *\n   * @internal\n   */\n  constructor(client: B2Client, bucket: Bucket, fileName: string) {\n    this.client = client\n    this.bucket = bucket\n    this.fileName = fileName\n  }\n\n  /**\n   * Uploads data to this file name. Automatically uses multipart upload for large files.\n   * @param options - Upload configuration including data source and optional settings.\n   *\n   * @returns Metadata for the uploaded file version.\n   */\n  async upload(options: {\n    /** Data source to upload. */\n    source: ContentSource\n    /** MIME type. Defaults to auto-detection by B2. */\n    contentType?: string\n    /** Custom key-value metadata stored with the file. */\n    fileInfo?: Record<string, string>\n    /** Server-side encryption settings. */\n    serverSideEncryption?: EncryptionSetting\n    /** File retention policy (requires file lock). */\n    fileRetention?: FileRetentionValue\n    /** Legal hold status. */\n    legalHold?: LegalHoldValue\n    /** Last-modified timestamp in milliseconds since epoch. */\n    lastModifiedMillis?: number\n    /** Part size override for multipart uploads, in bytes. */\n    partSize?: number\n    /** Number of concurrent part uploads for large files. */\n    concurrency?: number\n    /** Callback invoked with upload progress events. */\n    onProgress?: ProgressListener\n    /** Abort signal for cancelling the upload. */\n    signal?: AbortSignal\n    /**\n     * Resume an unfinished multipart upload for this file name when one\n     * exists. Only meaningful on the large-file path. Ignored on the\n     * small-file path.\n     */\n    resume?: boolean\n    /**\n     * Resume into a specific large-file ID, bypassing discovery.\n     * Overrides the `resume` discovery path.\n     */\n    resumeFileId?: LargeFileId\n  }): Promise<FileVersion> {\n    const recommendedPartSize = this.client.accountInfo.getRecommendedPartSize()\n    const isLarge = options.source.size > recommendedPartSize\n\n    if (isLarge) {\n      return uploadLargeFile(this.client.raw, this.client.accountInfo, {\n        bucketId: this.bucket.id,\n        fileName: this.fileName,\n        ...options,\n      })\n    }\n\n    // Small-file path doesn't accept resume options.\n    const { resume: _resume, resumeFileId: _resumeFileId, ...smallOptions } = options\n    return uploadSmallFile(this.client.raw, this.client.accountInfo, {\n      bucketId: this.bucket.id,\n      fileName: this.fileName,\n      ...smallOptions,\n    })\n  }\n\n  /**\n   * Downloads this file by name. Pass `method: 'HEAD'` to fetch only the\n   * response headers (file metadata) without streaming the body.\n   * @param options - Optional method, range, SSE-C decryption, response-header overrides, and abort signal.\n   *\n   * @returns The download result with response headers and body stream.\n   */\n  async download(options?: DownloadCallOptions): Promise<DownloadResult> {\n    return downloadByName(this.client.raw, this.client.accountInfo, {\n      bucketName: this.bucket.name,\n      fileName: this.fileName,\n      ...options,\n    })\n  }\n\n  /**\n   * Fetches response headers for this file via HTTP HEAD. Returns a\n   * body-less result so callers never have to drain the (logically\n   * empty) HEAD body themselves.\n   *\n   * @param options - Optional range, SSE-C decryption, response-header\n   *   overrides, and abort signal. Same shape as {@link B2Object.download}'s\n   *   options minus `method` (always HEAD) and `onProgress` (no body).\n   *\n   * @returns Parsed download headers (content type, SHA-1, file info, etc.).\n   */\n  async head(options?: HeadCallOptions): Promise<HeadResult> {\n    return headByName(this.client.raw, this.client.accountInfo, {\n      bucketName: this.bucket.name,\n      fileName: this.fileName,\n      ...options,\n    })\n  }\n\n  /**\n   * Downloads a specific version of this file by ID. Pass `method: 'HEAD'`\n   * to fetch only the response headers (file metadata) without streaming the body.\n   * @param fileId - The file version ID to download.\n   * @param options - Optional method, range, SSE-C decryption, response-header overrides, and abort signal.\n   *\n   * @returns The download result with response headers and body stream.\n   */\n  async downloadById(fileId: FileId, options?: DownloadCallOptions): Promise<DownloadResult> {\n    return downloadById(this.client.raw, this.client.accountInfo, {\n      fileId,\n      ...options,\n    })\n  }\n\n  /**\n   * Fetches response headers for a specific version of this file by ID\n   * via HTTP HEAD. Returns a body-less result so callers never have to\n   * drain the (logically empty) HEAD body themselves.\n   *\n   * @param fileId - The file version ID to inspect.\n   * @param options - Optional range, SSE-C decryption, response-header\n   *   overrides, and abort signal.\n   *\n   * @returns Parsed download headers.\n   */\n  async headById(fileId: FileId, options?: HeadCallOptions): Promise<HeadResult> {\n    return headById(this.client.raw, this.client.accountInfo, {\n      fileId,\n      ...options,\n    })\n  }\n\n  /**\n   * Creates a parallel-download ReadableStream that fetches the file in concurrent ranged chunks.\n   * @param fileId - The file version ID to download.\n   * @param totalSize - Total file size in bytes (needed to compute range boundaries).\n   * @param options - Concurrency, range size, and abort signal.\n   *\n   * @returns A Web ReadableStream of file data in sequential order.\n   */\n  createReadStream(\n    fileId: FileId,\n    totalSize: number,\n    options?: {\n      /** Size of each ranged GET request in bytes. Defaults to 8 MB. */\n      rangeSize?: number\n      /** Number of concurrent range requests. Defaults to 4. */\n      concurrency?: number\n      /** Abort signal for cancelling the download. */\n      signal?: AbortSignal\n    },\n  ): ReadableStream<Uint8Array> {\n    return createParallelDownloadStream(this.client.raw, this.client.accountInfo, {\n      fileId,\n      totalSize,\n      ...options,\n    })\n  }\n\n  /**\n   * Creates a Web `WritableStream` that uploads streamed data into this file\n   * using the multipart protocol. Pipe a `ReadableStream<Uint8Array>` into the\n   * returned `writable` and await `done` to get the final {@link FileVersion}.\n   *\n   * Note: streaming uploads do not support resume because the size and per-part\n   * hashes are not known in advance. Use {@link upload} with a buffered source\n   * when resume is required.\n   *\n   * @param options - Streaming upload parameters (part size, concurrency, encryption).\n   *\n   * @returns A handle with the writable sink and a completion promise.\n   */\n  createWriteStream(options?: {\n    /** MIME type. Defaults to `b2/x-auto`. */\n    contentType?: string\n    /** Custom key-value metadata stored with the file. */\n    fileInfo?: Record<string, string>\n    /** Server-side encryption applied to each part. */\n    serverSideEncryption?: EncryptionSetting\n    /** Target part size in bytes. Defaults to the account's recommended part size. */\n    partSize?: number\n    /** Maximum number of parts uploaded in parallel. Defaults to 4. */\n    concurrency?: number\n    /** Callback invoked with upload progress events. */\n    onProgress?: ProgressListener\n    /** Abort signal that cancels the upload and the unfinished large file. */\n    signal?: AbortSignal\n  }): UploadWriteHandle {\n    return createWriteStream(this.client.raw, this.client.accountInfo, {\n      bucketId: this.bucket.id,\n      fileName: this.fileName,\n      ...(options ?? {}),\n    })\n  }\n\n  /**\n   * Retrieves metadata for a specific file version.\n   * @param fileId - The file version ID to look up.\n   *\n   * @returns The file version metadata.\n   */\n  async getFileInfo(fileId: FileId): Promise<FileVersion> {\n    return this.client.raw.getFileInfo(\n      this.client.accountInfo.getApiUrl(),\n      this.client.accountInfo.getAuthToken(),\n      { fileId },\n    )\n  }\n\n  /**\n   * Hides this file by creating a hide marker at this file name.\n   *\n   * @returns Metadata for the newly created hide marker.\n   */\n  async hide(): Promise<FileVersion> {\n    return this.bucket.hideFile(this.fileName)\n  }\n\n  /**\n   * Permanently deletes a specific version of this file.\n   * @param fileId - The unique identifier of the file version to delete.\n   */\n  async deleteVersion(fileId: FileId): Promise<void> {\n    await this.bucket.deleteFileVersion(this.fileName, fileId)\n  }\n\n  /**\n   * Sets or updates the Object Lock retention policy on a specific file\n   * version of this file.\n   *\n   * The bucket must have Object Lock enabled (`fileLockEnabled: true` at\n   * creation time). Governance-mode retention can be shortened or removed\n   * by passing `bypassGovernance: true` together with an application key\n   * that carries the `bypassGovernance` capability; compliance-mode\n   * retention cannot be shortened by anyone until the\n   * `retainUntilTimestamp` elapses.\n   *\n   * @param fileId - The file version to apply the policy to.\n   * @param retention - The retention policy to apply.\n   * @param options - Optional flag for shortening governance-mode retention.\n   *\n   * @returns Metadata for the updated file version.\n   */\n  async setRetention(\n    fileId: FileId,\n    retention: FileRetentionValue,\n    options?: { bypassGovernance?: boolean },\n  ) {\n    return this.bucket.updateFileRetention(this.fileName, fileId, retention, options)\n  }\n\n  /**\n   * Toggles the legal hold flag on a specific file version of this file.\n   *\n   * Legal hold is independent of retention: a file can be on legal hold\n   * without any retention policy, and vice versa. The bucket must have\n   * Object Lock enabled, and any caller must hold the `writeFileLegalHolds`\n   * capability.\n   *\n   * @param fileId - The file version to apply the flag to.\n   * @param legalHold - `'on'` to apply the hold, `'off'` to remove it.\n   *\n   * @returns Metadata for the updated file version.\n   */\n  async setLegalHold(fileId: FileId, legalHold: LegalHoldValue) {\n    return this.bucket.updateFileLegalHold(this.fileName, fileId, legalHold)\n  }\n}\n"],"names":["uploadLargeFile","uploadSmallFile","downloadByName","headByName","downloadById","headById","createParallelDownloadStream","createWriteStream"],"mappings":"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"}