@backblaze-labs/b2-sdk 0.3.0 → 0.4.0

package/dist/raw/encoding.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"encoding.cjs","names":[],"sources":["../../src/raw/encoding.ts"],"sourcesContent":["import { utf8Encoder } from '../util/text-codec.ts'\n\n/**\n * Characters that B2 treats as safe (not percent-encoded) in file names.\n *\n * Per the B2 docs, everything except `a-z A-Z 0-9 - . _ ~ / ! $ & ' ( ) * + , ; = : @`\n * must be percent-encoded using UTF-8 byte values.\n */\nconst SAFE_CHARS = new Set(\n  \"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~!$&'()*+,;=:@/\".split(''),\n)\n\n/**\n * Percent-encodes a file name using the B2-specific encoding rules.\n *\n * Unlike standard `encodeURIComponent`, B2 keeps `/` and several other\n * characters unencoded while encoding all other non-ASCII and special\n * characters as uppercase percent-encoded UTF-8 bytes.\n *\n * @param name - The raw (unencoded) file name.\n *\n * @returns The percent-encoded file name suitable for `X-Bz-File-Name` headers.\n */\nexport function encodeFileName(name: string): string {\n  const encoded: string[] = []\n  for (const char of name) {\n    if (SAFE_CHARS.has(char)) {\n      encoded.push(char)\n    } else {\n      const bytes = utf8Encoder.encode(char)\n      for (const byte of bytes) {\n        encoded.push(`%${byte.toString(16).toUpperCase().padStart(2, '0')}`)\n      }\n    }\n  }\n  return encoded.join('')\n}\n\n/**\n * Decodes a B2 percent-encoded file name back to a plain string.\n *\n * B2 percent-encoding is compatible with standard `decodeURIComponent`,\n * so this is a thin wrapper.\n *\n * @param encoded - The percent-encoded file name from B2.\n *\n * @returns The decoded file name.\n */\nexport function decodeFileName(encoded: string): string {\n  return decodeURIComponent(encoded)\n}\n\n/**\n * Converts a file-info map into `X-Bz-Info-*` HTTP headers.\n *\n * Both keys and values are percent-encoded with {@link encodeFileName}\n * to satisfy B2 header requirements.\n *\n * @param fileInfo - Key/value pairs to attach as custom file info, or `undefined`.\n *\n * @returns A record of header name/value pairs (empty if `fileInfo` is `undefined`).\n */\nexport function buildFileInfoHeaders(\n  fileInfo: Record<string, string> | undefined,\n): Record<string, string> {\n  if (!fileInfo) return {}\n  const headers: Record<string, string> = {}\n  for (const [key, value] of Object.entries(fileInfo)) {\n    headers[`X-Bz-Info-${encodeFileName(key)}`] = encodeFileName(value)\n  }\n  return headers\n}\n\n/**\n * Extracts custom file-info key/value pairs from B2 response headers.\n *\n * Scans for headers prefixed with `x-bz-info-` and decodes both the\n * key suffix and value using {@link decodeFileName}.\n *\n * @param headers - The HTTP response headers from a B2 download or file-info call.\n *\n * @returns A record of decoded file-info key/value pairs.\n */\nexport function parseFileInfoHeaders(headers: Headers): Record<string, string> {\n  const info: Record<string, string> = {}\n  headers.forEach((value, key) => {\n    const lower = key.toLowerCase()\n    if (lower.startsWith('x-bz-info-')) {\n      const infoKey = decodeFileName(lower.slice('x-bz-info-'.length))\n      info[infoKey] = decodeFileName(value)\n    }\n  })\n  return info\n}\n"],"mappings":";;;;;;;;AAQA,IAAM,aAAa,IAAI,IACrB,mFAAmF,MAAM,EAAE,CAC7F;;;;;;;;;;;;AAaA,SAAgB,eAAe,MAAsB;CACnD,MAAM,UAAoB,CAAC;CAC3B,KAAK,MAAM,QAAQ,MACjB,IAAI,WAAW,IAAI,IAAI,GACrB,QAAQ,KAAK,IAAI;MACZ;EACL,MAAM,QAAQ,mBAAA,YAAY,OAAO,IAAI;EACrC,KAAK,MAAM,QAAQ,OACjB,QAAQ,KAAK,IAAI,KAAK,SAAS,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG;CAEvE;CAEF,OAAO,QAAQ,KAAK,EAAE;AACxB;;;;;;;;;;;AAYA,SAAgB,eAAe,SAAyB;CACtD,OAAO,mBAAmB,OAAO;AACnC;;;;;;;;;;;AAYA,SAAgB,qBACd,UACwB;CACxB,IAAI,CAAC,UAAU,OAAO,CAAC;CACvB,MAAM,UAAkC,CAAC;CACzC,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,QAAQ,GAChD,QAAQ,aAAa,eAAe,GAAG,OAAO,eAAe,KAAK;CAEpE,OAAO;AACT;;;;;;;;;;;AAYA,SAAgB,qBAAqB,SAA0C;CAC7E,MAAM,OAA+B,CAAC;CACtC,QAAQ,SAAS,OAAO,QAAQ;EAC9B,MAAM,QAAQ,IAAI,YAAY;EAC9B,IAAI,MAAM,WAAW,YAAY,GAAG;GAClC,MAAM,UAAU,eAAe,MAAM,MAAM,EAAmB,CAAC;GAC/D,KAAK,WAAW,eAAe,KAAK;EACtC;CACF,CAAC;CACD,OAAO;AACT"}
+{"version":3,"file":"encoding.cjs","names":[],"sources":["../../src/raw/encoding.ts"],"sourcesContent":["import { utf8Encoder } from '../util/text-codec.ts'\n\n/**\n * Characters that B2 treats as safe (not percent-encoded) in file names.\n *\n * Per the B2 docs, everything except `a-z A-Z 0-9 - . _ ~ / ! $ & ' ( ) * + , ; = : @`\n * must be percent-encoded using UTF-8 byte values.\n */\nconst SAFE_CHARS = new Set(\n  \"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~!$&'()*+,;=:@/\".split(''),\n)\n\nconst FILE_INFO_VALUE_SAFE_CHARS = new Set(\n  'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~'.split(''),\n)\n\nfunction encodeWithSafeChars(value: string, safeChars: ReadonlySet<string>): string {\n  const encoded: string[] = []\n  for (const char of value) {\n    if (safeChars.has(char)) {\n      encoded.push(char)\n    } else {\n      const bytes = utf8Encoder.encode(char)\n      for (const byte of bytes) {\n        encoded.push(`%${byte.toString(16).toUpperCase().padStart(2, '0')}`)\n      }\n    }\n  }\n  return encoded.join('')\n}\n\n/**\n * Percent-encodes a file name using the B2-specific encoding rules.\n *\n * Unlike standard `encodeURIComponent`, B2 keeps `/` and several other\n * characters unencoded while encoding all other non-ASCII and special\n * characters as uppercase percent-encoded UTF-8 bytes.\n *\n * @param name - The raw (unencoded) file name.\n *\n * @returns The percent-encoded file name suitable for `X-Bz-File-Name` headers.\n */\nexport function encodeFileName(name: string): string {\n  return encodeWithSafeChars(name, SAFE_CHARS)\n}\n\n/**\n * Percent-encodes a file-info value using the stricter B2 metadata value rules.\n *\n * File-info values must be decoded by B2 before storage. Live B2 rejects comma\n * and other RFC punctuation when left raw in these values, so only RFC 3986\n * unreserved characters are passed through.\n *\n * @param value - The raw (unencoded) file-info value.\n *\n * @returns The percent-encoded value suitable for `X-Bz-Info-*` header values.\n */\nfunction encodeFileInfoValue(value: string): string {\n  return encodeWithSafeChars(value, FILE_INFO_VALUE_SAFE_CHARS)\n}\n\n/**\n * Decodes a B2 percent-encoded file name back to a plain string.\n *\n * B2 percent-encoding is compatible with standard `decodeURIComponent`,\n * so this is a thin wrapper.\n *\n * @param encoded - The percent-encoded file name from B2.\n *\n * @returns The decoded file name.\n */\nexport function decodeFileName(encoded: string): string {\n  return decodeURIComponent(encoded)\n}\n\n/**\n * Converts a file-info map into `X-Bz-Info-*` HTTP headers.\n *\n * Keys use B2 file-name encoding. Values use stricter B2 file-info value\n * encoding so punctuation such as commas is percent-encoded before B2 decodes\n * and validates stored metadata.\n *\n * @param fileInfo - Key/value pairs to attach as custom file info, or `undefined`.\n *\n * @returns A record of header name/value pairs (empty if `fileInfo` is `undefined`).\n */\nexport function buildFileInfoHeaders(\n  fileInfo: Record<string, string> | undefined,\n): Record<string, string> {\n  if (!fileInfo) return {}\n  const headers: Record<string, string> = {}\n  for (const [key, value] of Object.entries(fileInfo)) {\n    headers[`X-Bz-Info-${encodeFileName(key)}`] = encodeFileInfoValue(value)\n  }\n  return headers\n}\n\n/**\n * Extracts custom file-info key/value pairs from B2 response headers.\n *\n * Scans for headers prefixed with `x-bz-info-` and decodes both the\n * key suffix and value using {@link decodeFileName}.\n *\n * @param headers - The HTTP response headers from a B2 download or file-info call.\n *\n * @returns A record of decoded file-info key/value pairs.\n */\nexport function parseFileInfoHeaders(headers: Headers): Record<string, string> {\n  const info: Record<string, string> = {}\n  headers.forEach((value, key) => {\n    const lower = key.toLowerCase()\n    if (lower.startsWith('x-bz-info-')) {\n      const infoKey = decodeFileName(lower.slice('x-bz-info-'.length))\n      info[infoKey] = decodeFileName(value)\n    }\n  })\n  return info\n}\n"],"mappings":";;;;;;;;AAQA,IAAM,aAAa,IAAI,IACrB,mFAAmF,MAAM,EAAE,CAC7F;AAEA,IAAM,6BAA6B,IAAI,IACrC,qEAAqE,MAAM,EAAE,CAC/E;AAEA,SAAS,oBAAoB,OAAe,WAAwC;CAClF,MAAM,UAAoB,CAAC;CAC3B,KAAK,MAAM,QAAQ,OACjB,IAAI,UAAU,IAAI,IAAI,GACpB,QAAQ,KAAK,IAAI;MACZ;EACL,MAAM,QAAQ,mBAAA,YAAY,OAAO,IAAI;EACrC,KAAK,MAAM,QAAQ,OACjB,QAAQ,KAAK,IAAI,KAAK,SAAS,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG;CAEvE;CAEF,OAAO,QAAQ,KAAK,EAAE;AACxB;;;;;;;;;;;;AAaA,SAAgB,eAAe,MAAsB;CACnD,OAAO,oBAAoB,MAAM,UAAU;AAC7C;;;;;;;;;;;;AAaA,SAAS,oBAAoB,OAAuB;CAClD,OAAO,oBAAoB,OAAO,0BAA0B;AAC9D;;;;;;;;;;;AAYA,SAAgB,eAAe,SAAyB;CACtD,OAAO,mBAAmB,OAAO;AACnC;;;;;;;;;;;;AAaA,SAAgB,qBACd,UACwB;CACxB,IAAI,CAAC,UAAU,OAAO,CAAC;CACvB,MAAM,UAAkC,CAAC;CACzC,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,QAAQ,GAChD,QAAQ,aAAa,eAAe,GAAG,OAAO,oBAAoB,KAAK;CAEzE,OAAO;AACT;;;;;;;;;;;AAYA,SAAgB,qBAAqB,SAA0C;CAC7E,MAAM,OAA+B,CAAC;CACtC,QAAQ,SAAS,OAAO,QAAQ;EAC9B,MAAM,QAAQ,IAAI,YAAY;EAC9B,IAAI,MAAM,WAAW,YAAY,GAAG;GAClC,MAAM,UAAU,eAAe,MAAM,MAAM,EAAmB,CAAC;GAC/D,KAAK,WAAW,eAAe,KAAK;EACtC;CACF,CAAC;CACD,OAAO;AACT"}

package/dist/raw/encoding.d.cts

@@ -24,8 +24,9 @@ export declare function decodeFileName(encoded: string): string;
 /**
  * Converts a file-info map into `X-Bz-Info-*` HTTP headers.
  *
- * Both keys and values are percent-encoded with {@link encodeFileName}
- * to satisfy B2 header requirements.
+ * Keys use B2 file-name encoding. Values use stricter B2 file-info value
+ * encoding so punctuation such as commas is percent-encoded before B2 decodes
+ * and validates stored metadata.
  *
  * @param fileInfo - Key/value pairs to attach as custom file info, or `undefined`.
  *

package/dist/raw/encoding.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/raw/encoding.js"],"names":[],"mappings":"AAYA;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAanD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAC3C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAU7E"}
+{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/raw/encoding.js"],"names":[],"mappings":"AA+BA;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAiBD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAC3C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAU7E"}

package/dist/raw/encoding.d.ts

@@ -24,8 +24,9 @@ export declare function decodeFileName(encoded: string): string;
 /**
  * Converts a file-info map into `X-Bz-Info-*` HTTP headers.
  *
- * Both keys and values are percent-encoded with {@link encodeFileName}
- * to satisfy B2 header requirements.
+ * Keys use B2 file-name encoding. Values use stricter B2 file-info value
+ * encoding so punctuation such as commas is percent-encoded before B2 decodes
+ * and validates stored metadata.
  *
  * @param fileInfo - Key/value pairs to attach as custom file info, or `undefined`.
  *

package/dist/raw/encoding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/raw/encoding.js"],"names":[],"mappings":"AAYA;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAanD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAC3C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAU7E"}
+{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/raw/encoding.js"],"names":[],"mappings":"AA+BA;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAiBD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAC3C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAU7E"}

package/dist/raw/encoding.js

@@ -7,6 +7,16 @@ import { utf8Encoder } from "../util/text-codec.js";
 * must be percent-encoded using UTF-8 byte values.
 */
 var SAFE_CHARS = new Set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~!$&'()*+,;=:@/".split(""));
+var FILE_INFO_VALUE_SAFE_CHARS = new Set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~".split(""));
+function encodeWithSafeChars(value, safeChars) {
+	const encoded = [];
+	for (const char of value) if (safeChars.has(char)) encoded.push(char);
+	else {
+		const bytes = utf8Encoder.encode(char);
+		for (const byte of bytes) encoded.push(`%${byte.toString(16).toUpperCase().padStart(2, "0")}`);
+	}
+	return encoded.join("");
+}
 /**
 * Percent-encodes a file name using the B2-specific encoding rules.
 *
@@ -19,13 +29,21 @@ var SAFE_CHARS = new Set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01
 * @returns The percent-encoded file name suitable for `X-Bz-File-Name` headers.
 */
 function encodeFileName(name) {
-	const encoded = [];
-	for (const char of name) if (SAFE_CHARS.has(char)) encoded.push(char);
-	else {
-		const bytes = utf8Encoder.encode(char);
-		for (const byte of bytes) encoded.push(`%${byte.toString(16).toUpperCase().padStart(2, "0")}`);
-	}
-	return encoded.join("");
+	return encodeWithSafeChars(name, SAFE_CHARS);
+}
+/**
+* Percent-encodes a file-info value using the stricter B2 metadata value rules.
+*
+* File-info values must be decoded by B2 before storage. Live B2 rejects comma
+* and other RFC punctuation when left raw in these values, so only RFC 3986
+* unreserved characters are passed through.
+*
+* @param value - The raw (unencoded) file-info value.
+*
+* @returns The percent-encoded value suitable for `X-Bz-Info-*` header values.
+*/
+function encodeFileInfoValue(value) {
+	return encodeWithSafeChars(value, FILE_INFO_VALUE_SAFE_CHARS);
 }
 /**
 * Decodes a B2 percent-encoded file name back to a plain string.
@@ -43,8 +61,9 @@ function decodeFileName(encoded) {
 /**
 * Converts a file-info map into `X-Bz-Info-*` HTTP headers.
 *
-* Both keys and values are percent-encoded with {@link encodeFileName}
-* to satisfy B2 header requirements.
+* Keys use B2 file-name encoding. Values use stricter B2 file-info value
+* encoding so punctuation such as commas is percent-encoded before B2 decodes
+* and validates stored metadata.
 *
 * @param fileInfo - Key/value pairs to attach as custom file info, or `undefined`.
 *
@@ -53,7 +72,7 @@ function decodeFileName(encoded) {
 function buildFileInfoHeaders(fileInfo) {
 	if (!fileInfo) return {};
 	const headers = {};
-	for (const [key, value] of Object.entries(fileInfo)) headers[`X-Bz-Info-${encodeFileName(key)}`] = encodeFileName(value);
+	for (const [key, value] of Object.entries(fileInfo)) headers[`X-Bz-Info-${encodeFileName(key)}`] = encodeFileInfoValue(value);
 	return headers;
 }
 /**

package/dist/raw/encoding.js.map

@@ -1 +1 @@
-{"version":3,"file":"encoding.js","names":[],"sources":["../../src/raw/encoding.ts"],"sourcesContent":["import { utf8Encoder } from '../util/text-codec.ts'\n\n/**\n * Characters that B2 treats as safe (not percent-encoded) in file names.\n *\n * Per the B2 docs, everything except `a-z A-Z 0-9 - . _ ~ / ! $ & ' ( ) * + , ; = : @`\n * must be percent-encoded using UTF-8 byte values.\n */\nconst SAFE_CHARS = new Set(\n  \"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~!$&'()*+,;=:@/\".split(''),\n)\n\n/**\n * Percent-encodes a file name using the B2-specific encoding rules.\n *\n * Unlike standard `encodeURIComponent`, B2 keeps `/` and several other\n * characters unencoded while encoding all other non-ASCII and special\n * characters as uppercase percent-encoded UTF-8 bytes.\n *\n * @param name - The raw (unencoded) file name.\n *\n * @returns The percent-encoded file name suitable for `X-Bz-File-Name` headers.\n */\nexport function encodeFileName(name: string): string {\n  const encoded: string[] = []\n  for (const char of name) {\n    if (SAFE_CHARS.has(char)) {\n      encoded.push(char)\n    } else {\n      const bytes = utf8Encoder.encode(char)\n      for (const byte of bytes) {\n        encoded.push(`%${byte.toString(16).toUpperCase().padStart(2, '0')}`)\n      }\n    }\n  }\n  return encoded.join('')\n}\n\n/**\n * Decodes a B2 percent-encoded file name back to a plain string.\n *\n * B2 percent-encoding is compatible with standard `decodeURIComponent`,\n * so this is a thin wrapper.\n *\n * @param encoded - The percent-encoded file name from B2.\n *\n * @returns The decoded file name.\n */\nexport function decodeFileName(encoded: string): string {\n  return decodeURIComponent(encoded)\n}\n\n/**\n * Converts a file-info map into `X-Bz-Info-*` HTTP headers.\n *\n * Both keys and values are percent-encoded with {@link encodeFileName}\n * to satisfy B2 header requirements.\n *\n * @param fileInfo - Key/value pairs to attach as custom file info, or `undefined`.\n *\n * @returns A record of header name/value pairs (empty if `fileInfo` is `undefined`).\n */\nexport function buildFileInfoHeaders(\n  fileInfo: Record<string, string> | undefined,\n): Record<string, string> {\n  if (!fileInfo) return {}\n  const headers: Record<string, string> = {}\n  for (const [key, value] of Object.entries(fileInfo)) {\n    headers[`X-Bz-Info-${encodeFileName(key)}`] = encodeFileName(value)\n  }\n  return headers\n}\n\n/**\n * Extracts custom file-info key/value pairs from B2 response headers.\n *\n * Scans for headers prefixed with `x-bz-info-` and decodes both the\n * key suffix and value using {@link decodeFileName}.\n *\n * @param headers - The HTTP response headers from a B2 download or file-info call.\n *\n * @returns A record of decoded file-info key/value pairs.\n */\nexport function parseFileInfoHeaders(headers: Headers): Record<string, string> {\n  const info: Record<string, string> = {}\n  headers.forEach((value, key) => {\n    const lower = key.toLowerCase()\n    if (lower.startsWith('x-bz-info-')) {\n      const infoKey = decodeFileName(lower.slice('x-bz-info-'.length))\n      info[infoKey] = decodeFileName(value)\n    }\n  })\n  return info\n}\n"],"mappings":";;;;;;;;AAQA,IAAM,aAAa,IAAI,IACrB,mFAAmF,MAAM,EAAE,CAC7F;;;;;;;;;;;;AAaA,SAAgB,eAAe,MAAsB;CACnD,MAAM,UAAoB,CAAC;CAC3B,KAAK,MAAM,QAAQ,MACjB,IAAI,WAAW,IAAI,IAAI,GACrB,QAAQ,KAAK,IAAI;MACZ;EACL,MAAM,QAAQ,YAAY,OAAO,IAAI;EACrC,KAAK,MAAM,QAAQ,OACjB,QAAQ,KAAK,IAAI,KAAK,SAAS,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG;CAEvE;CAEF,OAAO,QAAQ,KAAK,EAAE;AACxB;;;;;;;;;;;AAYA,SAAgB,eAAe,SAAyB;CACtD,OAAO,mBAAmB,OAAO;AACnC;;;;;;;;;;;AAYA,SAAgB,qBACd,UACwB;CACxB,IAAI,CAAC,UAAU,OAAO,CAAC;CACvB,MAAM,UAAkC,CAAC;CACzC,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,QAAQ,GAChD,QAAQ,aAAa,eAAe,GAAG,OAAO,eAAe,KAAK;CAEpE,OAAO;AACT;;;;;;;;;;;AAYA,SAAgB,qBAAqB,SAA0C;CAC7E,MAAM,OAA+B,CAAC;CACtC,QAAQ,SAAS,OAAO,QAAQ;EAC9B,MAAM,QAAQ,IAAI,YAAY;EAC9B,IAAI,MAAM,WAAW,YAAY,GAAG;GAClC,MAAM,UAAU,eAAe,MAAM,MAAM,EAAmB,CAAC;GAC/D,KAAK,WAAW,eAAe,KAAK;EACtC;CACF,CAAC;CACD,OAAO;AACT"}
+{"version":3,"file":"encoding.js","names":[],"sources":["../../src/raw/encoding.ts"],"sourcesContent":["import { utf8Encoder } from '../util/text-codec.ts'\n\n/**\n * Characters that B2 treats as safe (not percent-encoded) in file names.\n *\n * Per the B2 docs, everything except `a-z A-Z 0-9 - . _ ~ / ! $ & ' ( ) * + , ; = : @`\n * must be percent-encoded using UTF-8 byte values.\n */\nconst SAFE_CHARS = new Set(\n  \"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~!$&'()*+,;=:@/\".split(''),\n)\n\nconst FILE_INFO_VALUE_SAFE_CHARS = new Set(\n  'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~'.split(''),\n)\n\nfunction encodeWithSafeChars(value: string, safeChars: ReadonlySet<string>): string {\n  const encoded: string[] = []\n  for (const char of value) {\n    if (safeChars.has(char)) {\n      encoded.push(char)\n    } else {\n      const bytes = utf8Encoder.encode(char)\n      for (const byte of bytes) {\n        encoded.push(`%${byte.toString(16).toUpperCase().padStart(2, '0')}`)\n      }\n    }\n  }\n  return encoded.join('')\n}\n\n/**\n * Percent-encodes a file name using the B2-specific encoding rules.\n *\n * Unlike standard `encodeURIComponent`, B2 keeps `/` and several other\n * characters unencoded while encoding all other non-ASCII and special\n * characters as uppercase percent-encoded UTF-8 bytes.\n *\n * @param name - The raw (unencoded) file name.\n *\n * @returns The percent-encoded file name suitable for `X-Bz-File-Name` headers.\n */\nexport function encodeFileName(name: string): string {\n  return encodeWithSafeChars(name, SAFE_CHARS)\n}\n\n/**\n * Percent-encodes a file-info value using the stricter B2 metadata value rules.\n *\n * File-info values must be decoded by B2 before storage. Live B2 rejects comma\n * and other RFC punctuation when left raw in these values, so only RFC 3986\n * unreserved characters are passed through.\n *\n * @param value - The raw (unencoded) file-info value.\n *\n * @returns The percent-encoded value suitable for `X-Bz-Info-*` header values.\n */\nfunction encodeFileInfoValue(value: string): string {\n  return encodeWithSafeChars(value, FILE_INFO_VALUE_SAFE_CHARS)\n}\n\n/**\n * Decodes a B2 percent-encoded file name back to a plain string.\n *\n * B2 percent-encoding is compatible with standard `decodeURIComponent`,\n * so this is a thin wrapper.\n *\n * @param encoded - The percent-encoded file name from B2.\n *\n * @returns The decoded file name.\n */\nexport function decodeFileName(encoded: string): string {\n  return decodeURIComponent(encoded)\n}\n\n/**\n * Converts a file-info map into `X-Bz-Info-*` HTTP headers.\n *\n * Keys use B2 file-name encoding. Values use stricter B2 file-info value\n * encoding so punctuation such as commas is percent-encoded before B2 decodes\n * and validates stored metadata.\n *\n * @param fileInfo - Key/value pairs to attach as custom file info, or `undefined`.\n *\n * @returns A record of header name/value pairs (empty if `fileInfo` is `undefined`).\n */\nexport function buildFileInfoHeaders(\n  fileInfo: Record<string, string> | undefined,\n): Record<string, string> {\n  if (!fileInfo) return {}\n  const headers: Record<string, string> = {}\n  for (const [key, value] of Object.entries(fileInfo)) {\n    headers[`X-Bz-Info-${encodeFileName(key)}`] = encodeFileInfoValue(value)\n  }\n  return headers\n}\n\n/**\n * Extracts custom file-info key/value pairs from B2 response headers.\n *\n * Scans for headers prefixed with `x-bz-info-` and decodes both the\n * key suffix and value using {@link decodeFileName}.\n *\n * @param headers - The HTTP response headers from a B2 download or file-info call.\n *\n * @returns A record of decoded file-info key/value pairs.\n */\nexport function parseFileInfoHeaders(headers: Headers): Record<string, string> {\n  const info: Record<string, string> = {}\n  headers.forEach((value, key) => {\n    const lower = key.toLowerCase()\n    if (lower.startsWith('x-bz-info-')) {\n      const infoKey = decodeFileName(lower.slice('x-bz-info-'.length))\n      info[infoKey] = decodeFileName(value)\n    }\n  })\n  return info\n}\n"],"mappings":";;;;;;;;AAQA,IAAM,aAAa,IAAI,IACrB,mFAAmF,MAAM,EAAE,CAC7F;AAEA,IAAM,6BAA6B,IAAI,IACrC,qEAAqE,MAAM,EAAE,CAC/E;AAEA,SAAS,oBAAoB,OAAe,WAAwC;CAClF,MAAM,UAAoB,CAAC;CAC3B,KAAK,MAAM,QAAQ,OACjB,IAAI,UAAU,IAAI,IAAI,GACpB,QAAQ,KAAK,IAAI;MACZ;EACL,MAAM,QAAQ,YAAY,OAAO,IAAI;EACrC,KAAK,MAAM,QAAQ,OACjB,QAAQ,KAAK,IAAI,KAAK,SAAS,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG;CAEvE;CAEF,OAAO,QAAQ,KAAK,EAAE;AACxB;;;;;;;;;;;;AAaA,SAAgB,eAAe,MAAsB;CACnD,OAAO,oBAAoB,MAAM,UAAU;AAC7C;;;;;;;;;;;;AAaA,SAAS,oBAAoB,OAAuB;CAClD,OAAO,oBAAoB,OAAO,0BAA0B;AAC9D;;;;;;;;;;;AAYA,SAAgB,eAAe,SAAyB;CACtD,OAAO,mBAAmB,OAAO;AACnC;;;;;;;;;;;;AAaA,SAAgB,qBACd,UACwB;CACxB,IAAI,CAAC,UAAU,OAAO,CAAC;CACvB,MAAM,UAAkC,CAAC;CACzC,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,QAAQ,GAChD,QAAQ,aAAa,eAAe,GAAG,OAAO,oBAAoB,KAAK;CAEzE,OAAO;AACT;;;;;;;;;;;AAYA,SAAgB,qBAAqB,SAA0C;CAC7E,MAAM,OAA+B,CAAC;CACtC,QAAQ,SAAS,OAAO,QAAQ;EAC9B,MAAM,QAAQ,IAAI,YAAY;EAC9B,IAAI,MAAM,WAAW,YAAY,GAAG;GAClC,MAAM,UAAU,eAAe,MAAM,MAAM,EAAmB,CAAC;GAC/D,KAAK,WAAW,eAAe,KAAK;EACtC;CACF,CAAC;CACD,OAAO;AACT"}

package/dist/raw/index.cjs

@@ -3,6 +3,8 @@ const require_errors_index = require("../errors/index.cjs");
 const require_encoding = require("./encoding.cjs");
 const require_encryption = require("../types/encryption.cjs");
 const require_normalize = require("../util/normalize.cjs");
+const require_bucket = require("../types/bucket.cjs");
+const require_bucket_validation = require("../bucket-validation.cjs");
 const require_realms = require("../auth/realms.cjs");
 const require_url = require("./url.cjs");
 //#region src/raw/index.ts
@@ -13,14 +15,13 @@ const require_url = require("./url.cjs");
 * with fully typed request and response objects. No retry logic, no URL pooling,
 * no automatic reauthorization. Use this when you need precise control over
 * individual API calls; for most use cases prefer the high-level `B2Client`.
+* SDK-built B2 native storage API URLs use `/b2api/v4`. JSON endpoints use
+* POST request bodies, including read/list endpoints whose API docs also show
+* GET query examples but document POST JSON compatibility.
 *
 * @packageDocumentation
 */
-var B2_NATIVE_API_V3 = {
-	prefix: "b2api",
-	version: "v3"
-};
-var B2_NATIVE_API_V4 = {
+var B2_NATIVE_API = {
 	prefix: "b2api",
 	version: "v4"
 };
@@ -43,6 +44,21 @@ function assertCustomUploadTimestamp(value) {
 	if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) return;
 	throw new TypeError("customUploadTimestamp must be a non-negative safe integer");
 }
+function assertSafeHttpHeaderValue(name, value) {
+	if (hasHttpHeaderControlByte(value)) throw new TypeError(`${name} must not contain HTTP control characters`);
+}
+function hasHttpHeaderControlByte(value) {
+	for (let i = 0; i < value.length; i += 1) {
+		const code = value.charCodeAt(i);
+		if (code <= 31 || code === 127) return true;
+	}
+	return false;
+}
+function setB2ContentFileInfoHeader(headers, key, optionName, value) {
+	if (!value) return;
+	assertSafeHttpHeaderValue(optionName, value);
+	Object.assign(headers, require_encoding.buildFileInfoHeaders({ [key]: value }));
+}
 function assertRawCustomUploadTimestamp(value) {
 	if (value === void 0 || value === null) return;
 	if (typeof value === "string" && /^\d+$/.test(value)) {
@@ -139,18 +155,21 @@ var RawClient = class {
 	* @param applicationKeyId - The application key ID for authentication.
 	* @param applicationKey - The application key secret.
 	* @param realmUrl - The B2 realm URL to authenticate against.
+	* @param options - Optional request controls.
 	*
 	* @returns The authorization response with API URLs and credentials.
 	*/
-	async authorizeAccount(applicationKeyId, applicationKey, realmUrl = "https://api.backblazeb2.com") {
+	async authorizeAccount(applicationKeyId, applicationKey, realmUrl = "https://api.backblazeb2.com", options) {
 		require_realms.assertSecureRealmUrl(realmUrl);
 		return normalizeAuthorizeAccountResponse(await (await this.transport.send({
 			url: require_url.b2Url(realmUrl, {
-				...B2_NATIVE_API_V4,
+				...B2_NATIVE_API,
 				endpoint: "b2_authorize_account"
 			}),
 			method: "GET",
-			headers: { Authorization: `Basic ${btoa(`${applicationKeyId}:${applicationKey}`)}` }
+			headers: { Authorization: `Basic ${btoa(`${applicationKeyId}:${applicationKey}`)}` },
+			...options?.signal !== void 0 ? { signal: options.signal } : {},
+			...options?.retry !== void 0 ? { retry: options.retry } : {}
 		})).json());
 	}
 	/**
@@ -162,6 +181,7 @@ var RawClient = class {
 	* @returns The created bucket metadata.
 	*/
 	async createBucket(apiUrl, authToken, request) {
+		require_bucket_validation.assertValidBucketConfiguration(request);
 		return this.postJson(apiUrl, authToken, "b2_create_bucket", request);
 	}
 	/**
@@ -195,6 +215,7 @@ var RawClient = class {
 	* @returns The updated bucket metadata.
 	*/
 	async updateBucket(apiUrl, authToken, request) {
+		require_bucket_validation.assertValidBucketConfiguration(request);
 		return this.postJson(apiUrl, authToken, "b2_update_bucket", request);
 	}
 	/**
@@ -222,6 +243,9 @@ var RawClient = class {
 	*/
 	async uploadFile(uploadUrl, headers, body, optionsOrSignal, retry) {
 		const options = normalizeRawRequestOptions(optionsOrSignal, retry);
+		assertSafeHttpHeaderValue("authorization", headers.authorization);
+		assertSafeHttpHeaderValue("contentType", headers.contentType);
+		assertSafeHttpHeaderValue("contentSha1", headers.contentSha1);
 		const reqHeaders = {
 			Authorization: headers.authorization,
 			"X-Bz-File-Name": require_encoding.encodeFileName(headers.fileName),
@@ -235,11 +259,11 @@ var RawClient = class {
 			assertCustomUploadTimestamp(headers.customUploadTimestamp);
 			reqHeaders["X-Bz-Custom-Upload-Timestamp"] = String(headers.customUploadTimestamp);
 		}
-		if (headers.contentDisposition) reqHeaders["X-Bz-Info-b2-content-disposition"] = headers.contentDisposition;
-		if (headers.contentLanguage) reqHeaders["X-Bz-Info-b2-content-language"] = headers.contentLanguage;
-		if (headers.expires) reqHeaders["X-Bz-Info-b2-expires"] = headers.expires;
-		if (headers.cacheControl) reqHeaders["X-Bz-Info-b2-cache-control"] = headers.cacheControl;
-		if (headers.contentEncoding) reqHeaders["X-Bz-Info-b2-content-encoding"] = headers.contentEncoding;
+		setB2ContentFileInfoHeader(reqHeaders, "b2-content-disposition", "contentDisposition", headers.contentDisposition);
+		setB2ContentFileInfoHeader(reqHeaders, "b2-content-language", "contentLanguage", headers.contentLanguage);
+		setB2ContentFileInfoHeader(reqHeaders, "b2-expires", "expires", headers.expires);
+		setB2ContentFileInfoHeader(reqHeaders, "b2-cache-control", "cacheControl", headers.cacheControl);
+		setB2ContentFileInfoHeader(reqHeaders, "b2-content-encoding", "contentEncoding", headers.contentEncoding);
 		applyEncryptionHeaders(reqHeaders, headers.serverSideEncryption);
 		applyRetentionHeaders(reqHeaders, headers.fileRetention);
 		applyLegalHoldHeader(reqHeaders, headers.legalHold);
@@ -257,27 +281,9 @@ var RawClient = class {
 			throw uploadResponseBodyError(err, options?.signal);
 		}
 	}
-	/**
-	* Calls {@link https://www.backblaze.com/apidocs/b2-list-file-names | b2_list_file_names}.
-	* @param apiUrl - The B2 API base URL.
-	* @param authToken - The authorization token.
-	* @param request - The API request parameters.
-	* @param options - Optional request controls such as an abort signal.
-	*
-	* @returns The list of file names and optional continuation token.
-	*/
 	async listFileNames(apiUrl, authToken, request, options) {
 		return require_normalize.normalizeFileVersionListSha1(await this.postJson(apiUrl, authToken, "b2_list_file_names", request, options));
 	}
-	/**
-	* Calls {@link https://www.backblaze.com/apidocs/b2-list-file-versions | b2_list_file_versions}.
-	* @param apiUrl - The B2 API base URL.
-	* @param authToken - The authorization token.
-	* @param request - The API request parameters.
-	* @param options - Optional request controls such as an abort signal.
-	*
-	* @returns The list of file versions and optional continuation token.
-	*/
 	async listFileVersions(apiUrl, authToken, request, options) {
 		return require_normalize.normalizeFileVersionListSha1(await this.postJson(apiUrl, authToken, "b2_list_file_versions", request, options));
 	}
@@ -378,6 +384,8 @@ var RawClient = class {
 	*/
 	async uploadPart(uploadUrl, headers, body, optionsOrSignal, retry) {
 		const options = normalizeRawRequestOptions(optionsOrSignal, retry);
+		assertSafeHttpHeaderValue("authorization", headers.authorization);
+		assertSafeHttpHeaderValue("contentSha1", headers.contentSha1);
 		const reqHeaders = {
 			Authorization: headers.authorization,
 			"X-Bz-Part-Number": String(headers.partNumber),
@@ -411,7 +419,7 @@ var RawClient = class {
 	async finishLargeFile(apiUrl, authToken, request, options) {
 		const response = await this.transport.send({
 			url: require_url.b2Url(apiUrl, {
-				...B2_NATIVE_API_V3,
+				...B2_NATIVE_API,
 				endpoint: "b2_finish_large_file"
 			}),
 			method: "POST",
@@ -482,7 +490,7 @@ var RawClient = class {
 	async downloadFileById(downloadUrl, authToken, fileId, options) {
 		const headers = buildDownloadRequestHeaders(authToken, options);
 		const url = appendDownloadOverrides(`${require_url.b2Url(downloadUrl, {
-			...B2_NATIVE_API_V3,
+			...B2_NATIVE_API,
 			endpoint: "b2_download_file_by_id"
 		})}?fileId=${encodeURIComponent(fileId)}`, options);
 		const response = await this.transport.send({
@@ -542,7 +550,7 @@ var RawClient = class {
 	* @returns The newly created application key with secret.
 	*/
 	async createKey(apiUrl, authToken, request) {
-		return normalizeKeyResponse(await this.postJson(apiUrl, authToken, "b2_create_key", normalizeCreateKeyRequest(request), void 0, B2_NATIVE_API_V4));
+		return normalizeKeyResponse(await this.postJson(apiUrl, authToken, "b2_create_key", normalizeCreateKeyRequest(request)));
 	}
 	/**
 	* Calls {@link https://www.backblaze.com/apidocs/b2-list-keys | b2_list_keys}.
@@ -553,7 +561,7 @@ var RawClient = class {
 	* @returns The list of application keys and optional continuation token.
 	*/
 	async listKeys(apiUrl, authToken, request) {
-		const response = await this.postJson(apiUrl, authToken, "b2_list_keys", request, void 0, B2_NATIVE_API_V4);
+		const response = await this.postJson(apiUrl, authToken, "b2_list_keys", request);
 		return {
 			...response,
 			keys: response.keys.map((key) => normalizeKeyResponse(key))
@@ -568,7 +576,7 @@ var RawClient = class {
 	* @returns The deleted application key metadata.
 	*/
 	async deleteKey(apiUrl, authToken, request) {
-		return normalizeKeyResponse(await this.postJson(apiUrl, authToken, "b2_delete_key", request, void 0, B2_NATIVE_API_V4));
+		return normalizeKeyResponse(await this.postJson(apiUrl, authToken, "b2_delete_key", request));
 	}
 	/**
 	* Calls {@link https://www.backblaze.com/apidocs/b2-update-file-retention | b2_update_file_retention}.
@@ -621,14 +629,13 @@ var RawClient = class {
 	* @param endpoint - The B2 API endpoint name.
 	* @param body - The JSON request body.
 	* @param options - Optional abort and per-request retry settings.
-	* @param urlOptions - B2 endpoint path prefix and version settings.
 	*
 	* @returns The parsed JSON response.
 	*/
-	async postJson(apiUrl, authToken, endpoint, body, options, urlOptions = B2_NATIVE_API_V3) {
+	async postJson(apiUrl, authToken, endpoint, body, options) {
 		return (await this.transport.send({
 			url: require_url.b2Url(apiUrl, {
-				...urlOptions,
+				...B2_NATIVE_API,
 				endpoint
 			}),
 			method: "POST",
@@ -744,7 +751,25 @@ function applyLegalHoldHeader(headers, legalHold) {
 	headers["X-Bz-File-Legal-Hold"] = legalHold;
 }
 //#endregion
+exports.BUCKET_INFO_KEY_MAX_BYTES = require_bucket.BUCKET_INFO_KEY_MAX_BYTES;
+exports.BUCKET_INFO_KEY_MIN_BYTES = require_bucket.BUCKET_INFO_KEY_MIN_BYTES;
+exports.BUCKET_INFO_KEY_PATTERN = require_bucket.BUCKET_INFO_KEY_PATTERN;
+exports.BUCKET_INFO_RESERVED_PREFIX = require_bucket.BUCKET_INFO_RESERVED_PREFIX;
+exports.BUCKET_INFO_VALUES_MAX_BYTES = require_bucket.BUCKET_INFO_VALUES_MAX_BYTES;
+exports.BucketKeyOption = require_bucket.BucketKeyOption;
+exports.CORS_ALLOWED_OPERATIONS = require_bucket.CORS_ALLOWED_OPERATIONS;
+exports.CORS_MAX_AGE_SECONDS_MAX = require_bucket.CORS_MAX_AGE_SECONDS_MAX;
+exports.CORS_RULES_MAX_COUNT = require_bucket.CORS_RULES_MAX_COUNT;
+exports.CORS_RULE_MAX_BYTES = require_bucket.CORS_RULE_MAX_BYTES;
+exports.CORS_RULE_NAME_MAX_LENGTH = require_bucket.CORS_RULE_NAME_MAX_LENGTH;
+exports.CORS_RULE_NAME_MIN_LENGTH = require_bucket.CORS_RULE_NAME_MIN_LENGTH;
+exports.CORS_RULE_NAME_PATTERN = require_bucket.CORS_RULE_NAME_PATTERN;
+exports.CORS_RULE_NAME_RESERVED_PREFIX = require_bucket.CORS_RULE_NAME_RESERVED_PREFIX;
+exports.CorsOperation = require_bucket.CorsOperation;
 exports.RawClient = RawClient;
+exports.assertValidBucketConfiguration = require_bucket_validation.assertValidBucketConfiguration;
+exports.assertValidBucketInfo = require_bucket_validation.assertValidBucketInfo;
+exports.assertValidCorsRules = require_bucket_validation.assertValidCorsRules;
 exports.buildFileInfoHeaders = require_encoding.buildFileInfoHeaders;
 exports.decodeFileName = require_encoding.decodeFileName;
 exports.encodeFileName = require_encoding.encodeFileName;