@backblaze-labs/b2-sdk 0.1.0 → 0.3.0

package/dist/partner/endpoint-url.cjs

@@ -0,0 +1,108 @@
+const require_errors_index = require("../errors/index.cjs");
+const require_url_guard = require("../http/url-guard.cjs");
+const require_transport = require("../http/transport.cjs");
+//#region src/partner/endpoint-url.ts
+function isLoopbackHost(hostname) {
+	const host = hostname.toLowerCase();
+	if (host === "[::1]" || host === "::1") return true;
+	const parts = host.split(".");
+	return parts.length === 4 && parts[0] === "127" && parts.every((part) => /^\d+$/.test(part) && Number(part) <= 255);
+}
+function hostAllowedBySuffixes(hostname, allowedSuffixes) {
+	return allowedSuffixes.some((suffix) => require_url_guard.hostMatchesAllowedSuffix(hostname, suffix));
+}
+/**
+* Resolves endpoint host suffixes from fresh/cached Partner authorization or a locked transport guard.
+*
+* @param transport - Transport whose URL guard may already be locked.
+* @param authorizedSuffixes - Suffixes derived from validated Partner authorization.
+* @param messages - Surface-specific failure messages.
+*
+* @returns The suffixes safe for credential-bearing endpoint requests.
+*
+* @throws B2PartnerAuthorizationError if no locked guard or authorized suffixes exist.
+*
+* @internal
+*/
+function endpointAllowedSuffixes(transport, authorizedSuffixes, messages) {
+	if (authorizedSuffixes.length > 0) return authorizedSuffixes;
+	const guard = require_transport.getTransportUrlGuard(transport);
+	if (guard === void 0) throw new require_errors_index.B2PartnerAuthorizationError(messages.missingGuard);
+	const suffixes = guard.getAllowedSuffixes();
+	if (suffixes.length === 0) throw new require_errors_index.B2PartnerAuthorizationError(messages.unlockedGuard);
+	return suffixes;
+}
+/**
+* Validates a Partner-derived endpoint URL before a Partner token is sent to it.
+*
+* @param rawUrl - Endpoint URL from Partner authorization or cache.
+* @param fieldName - Authorize-response field being validated.
+* @param allowedSuffixes - Host suffix allow-list derived from the trusted realm.
+*
+* @returns The original URL when it is safe to use.
+*
+* @throws B2PartnerAuthorizationError if the URL is malformed or unsafe.
+*
+* @internal
+*/
+function validatePartnerEndpointUrl(rawUrl, fieldName, allowedSuffixes) {
+	let url;
+	try {
+		url = new URL(rawUrl);
+	} catch {
+		throw new require_errors_index.B2PartnerAuthorizationError(`Partner authorize response included malformed ${fieldName}`);
+	}
+	const host = url.hostname.toLowerCase();
+	const isAllowedLoopbackHttp = url.protocol === "http:" && isLoopbackHost(host) && hostAllowedBySuffixes(host, allowedSuffixes);
+	if (url.protocol !== "https:" && !isAllowedLoopbackHttp) throw new require_errors_index.B2PartnerAuthorizationError(`Partner authorize response ${fieldName} must use HTTPS`);
+	if (url.username !== "" || url.password !== "") throw new require_errors_index.B2PartnerAuthorizationError(`Partner authorize response ${fieldName} must not include userinfo`);
+	if (url.search !== "" || url.hash !== "") throw new require_errors_index.B2PartnerAuthorizationError(`Partner authorize response ${fieldName} must not include query or fragment`);
+	if (isAllowedLoopbackHttp) return rawUrl;
+	const guard = new require_url_guard.UrlGuard();
+	guard.setAllowedSuffixes(allowedSuffixes);
+	try {
+		guard.check(rawUrl);
+	} catch (err) {
+		throw new require_errors_index.B2PartnerAuthorizationError(err instanceof Error ? `Partner authorize response included unsafe ${fieldName}: ${err.message}` : `Partner authorize response included unsafe ${fieldName}`);
+	}
+	return rawUrl;
+}
+/**
+* Appends query parameters using the SDK's B2 URL encoding semantics.
+*
+* @param url - Base URL without query string.
+* @param query - Query keys and string/number values to append.
+*
+* @returns URL with encoded query parameters, or the original URL for an empty query.
+*
+* @internal
+*/
+function withQueryString(url, query) {
+	const queryString = Object.entries(query).map(([key, value]) => `${key}=${encodeURIComponent(String(value))}`).join("&");
+	return queryString.length === 0 ? url : `${url}?${queryString}`;
+}
+/**
+* Forces non-idempotent mutation calls to opt out of automatic request replay.
+*
+* @param options - Caller-provided request options.
+*
+* @returns Request options with `retry.maxRetries` set to zero.
+*
+* @internal
+*/
+function nonRetryingMutationRequestOptions(options) {
+	return {
+		...options?.signal !== void 0 ? { signal: options.signal } : {},
+		retry: {
+			...options?.retry ?? {},
+			maxRetries: 0
+		}
+	};
+}
+//#endregion
+exports.endpointAllowedSuffixes = endpointAllowedSuffixes;
+exports.nonRetryingMutationRequestOptions = nonRetryingMutationRequestOptions;
+exports.validatePartnerEndpointUrl = validatePartnerEndpointUrl;
+exports.withQueryString = withQueryString;
+
+//# sourceMappingURL=endpoint-url.cjs.map

package/dist/partner/endpoint-url.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint-url.cjs","names":[],"sources":["../../src/partner/endpoint-url.ts"],"sourcesContent":["import { B2PartnerAuthorizationError } from '../errors/index.ts'\nimport type { RetryOptions } from '../http/retry.ts'\nimport { getTransportUrlGuard, type HttpTransport } from '../http/transport.ts'\nimport { hostMatchesAllowedSuffix, UrlGuard } from '../http/url-guard.ts'\n\n/** Partner authorize endpoint URL field names that are validated before token use. */\nexport type PartnerEndpointUrlField = 'groupsApiUrl' | 'backupApiUrl'\n\n/** Message copy for resolving endpoint suffixes from an authorized or guarded transport. */\nexport interface EndpointAllowedSuffixMessages {\n  /** Error message when no validated suffixes and no URL guard are available. */\n  readonly missingGuard: string\n  /** Error message when a URL guard exists but has not been locked to suffixes. */\n  readonly unlockedGuard: string\n}\n\n/** Query-string scalar value supported by Partner and Backup endpoint helpers. */\nexport type QueryValue = string | number\n/** Query-string parameter map supported by Partner and Backup endpoint helpers. */\nexport type QueryParams = Readonly<Record<string, QueryValue>>\n\n/** Shared request options shape for non-idempotent Partner and Backup mutations. */\nexport interface MutationRequestOptions {\n  /** Abort signal for cancelling the request. */\n  readonly signal?: AbortSignal\n  /** Per-request retry override. */\n  readonly retry?: Partial<RetryOptions>\n}\n\nfunction isLoopbackHost(hostname: string): boolean {\n  const host = hostname.toLowerCase()\n  if (host === '[::1]' || host === '::1') return true\n\n  const parts = host.split('.')\n  return (\n    parts.length === 4 &&\n    parts[0] === '127' &&\n    parts.every((part) => /^\\d+$/.test(part) && Number(part) <= 255)\n  )\n}\n\nfunction hostAllowedBySuffixes(hostname: string, allowedSuffixes: readonly string[]): boolean {\n  return allowedSuffixes.some((suffix) => hostMatchesAllowedSuffix(hostname, suffix))\n}\n\n/**\n * Resolves endpoint host suffixes from fresh/cached Partner authorization or a locked transport guard.\n *\n * @param transport - Transport whose URL guard may already be locked.\n * @param authorizedSuffixes - Suffixes derived from validated Partner authorization.\n * @param messages - Surface-specific failure messages.\n *\n * @returns The suffixes safe for credential-bearing endpoint requests.\n *\n * @throws B2PartnerAuthorizationError if no locked guard or authorized suffixes exist.\n *\n * @internal\n */\nexport function endpointAllowedSuffixes(\n  transport: HttpTransport,\n  authorizedSuffixes: readonly string[],\n  messages: EndpointAllowedSuffixMessages,\n): readonly string[] {\n  if (authorizedSuffixes.length > 0) return authorizedSuffixes\n\n  const guard = getTransportUrlGuard(transport)\n  if (guard === undefined) {\n    throw new B2PartnerAuthorizationError(messages.missingGuard)\n  }\n\n  const suffixes = guard.getAllowedSuffixes()\n  if (suffixes.length === 0) {\n    throw new B2PartnerAuthorizationError(messages.unlockedGuard)\n  }\n\n  return suffixes\n}\n\n/**\n * Validates a Partner-derived endpoint URL before a Partner token is sent to it.\n *\n * @param rawUrl - Endpoint URL from Partner authorization or cache.\n * @param fieldName - Authorize-response field being validated.\n * @param allowedSuffixes - Host suffix allow-list derived from the trusted realm.\n *\n * @returns The original URL when it is safe to use.\n *\n * @throws B2PartnerAuthorizationError if the URL is malformed or unsafe.\n *\n * @internal\n */\nexport function validatePartnerEndpointUrl(\n  rawUrl: string,\n  fieldName: PartnerEndpointUrlField,\n  allowedSuffixes: readonly string[],\n): string {\n  let url: URL\n  try {\n    url = new URL(rawUrl)\n  } catch {\n    throw new B2PartnerAuthorizationError(\n      `Partner authorize response included malformed ${fieldName}`,\n    )\n  }\n\n  const host = url.hostname.toLowerCase()\n  const isAllowedLoopbackHttp =\n    url.protocol === 'http:' && isLoopbackHost(host) && hostAllowedBySuffixes(host, allowedSuffixes)\n\n  if (url.protocol !== 'https:' && !isAllowedLoopbackHttp) {\n    throw new B2PartnerAuthorizationError(`Partner authorize response ${fieldName} must use HTTPS`)\n  }\n  if (url.username !== '' || url.password !== '') {\n    throw new B2PartnerAuthorizationError(\n      `Partner authorize response ${fieldName} must not include userinfo`,\n    )\n  }\n  if (url.search !== '' || url.hash !== '') {\n    throw new B2PartnerAuthorizationError(\n      `Partner authorize response ${fieldName} must not include query or fragment`,\n    )\n  }\n\n  if (isAllowedLoopbackHttp) return rawUrl\n\n  const guard = new UrlGuard()\n  guard.setAllowedSuffixes(allowedSuffixes)\n  try {\n    guard.check(rawUrl)\n  } catch (err) {\n    throw new B2PartnerAuthorizationError(\n      err instanceof Error\n        ? `Partner authorize response included unsafe ${fieldName}: ${err.message}`\n        : `Partner authorize response included unsafe ${fieldName}`,\n    )\n  }\n\n  return rawUrl\n}\n\n/**\n * Appends query parameters using the SDK's B2 URL encoding semantics.\n *\n * @param url - Base URL without query string.\n * @param query - Query keys and string/number values to append.\n *\n * @returns URL with encoded query parameters, or the original URL for an empty query.\n *\n * @internal\n */\nexport function withQueryString(url: string, query: QueryParams): string {\n  // Match the storage raw client's encodeURIComponent query semantics: spaces\n  // are `%20`, not form-style `+`.\n  const queryString = Object.entries(query)\n    .map(([key, value]) => `${key}=${encodeURIComponent(String(value))}`)\n    .join('&')\n  return queryString.length === 0 ? url : `${url}?${queryString}`\n}\n\n/**\n * Forces non-idempotent mutation calls to opt out of automatic request replay.\n *\n * @param options - Caller-provided request options.\n *\n * @returns Request options with `retry.maxRetries` set to zero.\n *\n * @internal\n */\nexport function nonRetryingMutationRequestOptions(\n  options: MutationRequestOptions | undefined,\n): MutationRequestOptions {\n  return {\n    ...(options?.signal !== undefined ? { signal: options.signal } : {}),\n    retry: { ...(options?.retry ?? {}), maxRetries: 0 },\n  }\n}\n"],"mappings":";;;;AA6BA,SAAS,eAAe,UAA2B;CACjD,MAAM,OAAO,SAAS,YAAY;CAClC,IAAI,SAAS,WAAW,SAAS,OAAO,OAAO;CAE/C,MAAM,QAAQ,KAAK,MAAM,GAAG;CAC5B,OACE,MAAM,WAAW,KACjB,MAAM,OAAO,SACb,MAAM,OAAO,SAAS,QAAQ,KAAK,IAAI,KAAK,OAAO,IAAI,KAAK,GAAG;AAEnE;AAEA,SAAS,sBAAsB,UAAkB,iBAA6C;CAC5F,OAAO,gBAAgB,MAAM,WAAW,kBAAA,yBAAyB,UAAU,MAAM,CAAC;AACpF;;;;;;;;;;;;;;AAeA,SAAgB,wBACd,WACA,oBACA,UACmB;CACnB,IAAI,mBAAmB,SAAS,GAAG,OAAO;CAE1C,MAAM,QAAQ,kBAAA,qBAAqB,SAAS;CAC5C,IAAI,UAAU,KAAA,GACZ,MAAM,IAAI,qBAAA,4BAA4B,SAAS,YAAY;CAG7D,MAAM,WAAW,MAAM,mBAAmB;CAC1C,IAAI,SAAS,WAAW,GACtB,MAAM,IAAI,qBAAA,4BAA4B,SAAS,aAAa;CAG9D,OAAO;AACT;;;;;;;;;;;;;;AAeA,SAAgB,2BACd,QACA,WACA,iBACQ;CACR,IAAI;CACJ,IAAI;EACF,MAAM,IAAI,IAAI,MAAM;CACtB,QAAQ;EACN,MAAM,IAAI,qBAAA,4BACR,iDAAiD,WACnD;CACF;CAEA,MAAM,OAAO,IAAI,SAAS,YAAY;CACtC,MAAM,wBACJ,IAAI,aAAa,WAAW,eAAe,IAAI,KAAK,sBAAsB,MAAM,eAAe;CAEjG,IAAI,IAAI,aAAa,YAAY,CAAC,uBAChC,MAAM,IAAI,qBAAA,4BAA4B,8BAA8B,UAAU,gBAAgB;CAEhG,IAAI,IAAI,aAAa,MAAM,IAAI,aAAa,IAC1C,MAAM,IAAI,qBAAA,4BACR,8BAA8B,UAAU,2BAC1C;CAEF,IAAI,IAAI,WAAW,MAAM,IAAI,SAAS,IACpC,MAAM,IAAI,qBAAA,4BACR,8BAA8B,UAAU,oCAC1C;CAGF,IAAI,uBAAuB,OAAO;CAElC,MAAM,QAAQ,IAAI,kBAAA,SAAS;CAC3B,MAAM,mBAAmB,eAAe;CACxC,IAAI;EACF,MAAM,MAAM,MAAM;CACpB,SAAS,KAAK;EACZ,MAAM,IAAI,qBAAA,4BACR,eAAe,QACX,8CAA8C,UAAU,IAAI,IAAI,YAChE,8CAA8C,WACpD;CACF;CAEA,OAAO;AACT;;;;;;;;;;;AAYA,SAAgB,gBAAgB,KAAa,OAA4B;CAGvE,MAAM,cAAc,OAAO,QAAQ,KAAK,CAAC,CACtC,KAAK,CAAC,KAAK,WAAW,GAAG,IAAI,GAAG,mBAAmB,OAAO,KAAK,CAAC,GAAG,CAAC,CACpE,KAAK,GAAG;CACX,OAAO,YAAY,WAAW,IAAI,MAAM,GAAG,IAAI,GAAG;AACpD;;;;;;;;;;AAWA,SAAgB,kCACd,SACwB;CACxB,OAAO;EACL,GAAI,SAAS,WAAW,KAAA,IAAY,EAAE,QAAQ,QAAQ,OAAO,IAAI,CAAC;EAClE,OAAO;GAAE,GAAI,SAAS,SAAS,CAAC;GAAI,YAAY;EAAE;CACpD;AACF"}

package/dist/partner/endpoint-url.d.cts

@@ -0,0 +1,72 @@
+import { RetryOptions } from '../http/retry.js';
+import { HttpTransport } from '../http/transport.js';
+/** Partner authorize endpoint URL field names that are validated before token use. */
+export type PartnerEndpointUrlField = 'groupsApiUrl' | 'backupApiUrl';
+/** Message copy for resolving endpoint suffixes from an authorized or guarded transport. */
+export interface EndpointAllowedSuffixMessages {
+    /** Error message when no validated suffixes and no URL guard are available. */
+    readonly missingGuard: string;
+    /** Error message when a URL guard exists but has not been locked to suffixes. */
+    readonly unlockedGuard: string;
+}
+/** Query-string scalar value supported by Partner and Backup endpoint helpers. */
+export type QueryValue = string | number;
+/** Query-string parameter map supported by Partner and Backup endpoint helpers. */
+export type QueryParams = Readonly<Record<string, QueryValue>>;
+/** Shared request options shape for non-idempotent Partner and Backup mutations. */
+export interface MutationRequestOptions {
+    /** Abort signal for cancelling the request. */
+    readonly signal?: AbortSignal;
+    /** Per-request retry override. */
+    readonly retry?: Partial<RetryOptions>;
+}
+/**
+ * Resolves endpoint host suffixes from fresh/cached Partner authorization or a locked transport guard.
+ *
+ * @param transport - Transport whose URL guard may already be locked.
+ * @param authorizedSuffixes - Suffixes derived from validated Partner authorization.
+ * @param messages - Surface-specific failure messages.
+ *
+ * @returns The suffixes safe for credential-bearing endpoint requests.
+ *
+ * @throws B2PartnerAuthorizationError if no locked guard or authorized suffixes exist.
+ *
+ * @internal
+ */
+export declare function endpointAllowedSuffixes(transport: HttpTransport, authorizedSuffixes: readonly string[], messages: EndpointAllowedSuffixMessages): readonly string[];
+/**
+ * Validates a Partner-derived endpoint URL before a Partner token is sent to it.
+ *
+ * @param rawUrl - Endpoint URL from Partner authorization or cache.
+ * @param fieldName - Authorize-response field being validated.
+ * @param allowedSuffixes - Host suffix allow-list derived from the trusted realm.
+ *
+ * @returns The original URL when it is safe to use.
+ *
+ * @throws B2PartnerAuthorizationError if the URL is malformed or unsafe.
+ *
+ * @internal
+ */
+export declare function validatePartnerEndpointUrl(rawUrl: string, fieldName: PartnerEndpointUrlField, allowedSuffixes: readonly string[]): string;
+/**
+ * Appends query parameters using the SDK's B2 URL encoding semantics.
+ *
+ * @param url - Base URL without query string.
+ * @param query - Query keys and string/number values to append.
+ *
+ * @returns URL with encoded query parameters, or the original URL for an empty query.
+ *
+ * @internal
+ */
+export declare function withQueryString(url: string, query: QueryParams): string;
+/**
+ * Forces non-idempotent mutation calls to opt out of automatic request replay.
+ *
+ * @param options - Caller-provided request options.
+ *
+ * @returns Request options with `retry.maxRetries` set to zero.
+ *
+ * @internal
+ */
+export declare function nonRetryingMutationRequestOptions(options: MutationRequestOptions | undefined): MutationRequestOptions;
+//# sourceMappingURL=endpoint-url.d.ts.map

package/dist/partner/endpoint-url.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint-url.d.ts","sourceRoot":"","sources":["../../src/partner/endpoint-url.js"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAG/E,sFAAsF;AACtF,MAAM,MAAM,uBAAuB,GAAG,cAAc,GAAG,cAAc,CAAA;AAErE,4FAA4F;AAC5F,MAAM,WAAW,6BAA6B;IAC5C,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAC/B;AAED,kFAAkF;AAClF,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAA;AACxC,mFAAmF;AACnF,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAA;AAE9D,oFAAoF;AACpF,MAAM,WAAW,sBAAsB;IACrC,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B,kCAAkC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;CACvC;AAkBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,aAAa,EACxB,kBAAkB,EAAE,SAAS,MAAM,EAAE,EACrC,QAAQ,EAAE,6BAA6B,GACtC,SAAS,MAAM,EAAE,CAcnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,uBAAuB,EAClC,eAAe,EAAE,SAAS,MAAM,EAAE,GACjC,MAAM,CA2CR;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,MAAM,CAOvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,sBAAsB,GAAG,SAAS,GAC1C,sBAAsB,CAKxB"}

package/dist/partner/endpoint-url.d.ts

@@ -0,0 +1,72 @@
+import { RetryOptions } from '../http/retry.js';
+import { HttpTransport } from '../http/transport.js';
+/** Partner authorize endpoint URL field names that are validated before token use. */
+export type PartnerEndpointUrlField = 'groupsApiUrl' | 'backupApiUrl';
+/** Message copy for resolving endpoint suffixes from an authorized or guarded transport. */
+export interface EndpointAllowedSuffixMessages {
+    /** Error message when no validated suffixes and no URL guard are available. */
+    readonly missingGuard: string;
+    /** Error message when a URL guard exists but has not been locked to suffixes. */
+    readonly unlockedGuard: string;
+}
+/** Query-string scalar value supported by Partner and Backup endpoint helpers. */
+export type QueryValue = string | number;
+/** Query-string parameter map supported by Partner and Backup endpoint helpers. */
+export type QueryParams = Readonly<Record<string, QueryValue>>;
+/** Shared request options shape for non-idempotent Partner and Backup mutations. */
+export interface MutationRequestOptions {
+    /** Abort signal for cancelling the request. */
+    readonly signal?: AbortSignal;
+    /** Per-request retry override. */
+    readonly retry?: Partial<RetryOptions>;
+}
+/**
+ * Resolves endpoint host suffixes from fresh/cached Partner authorization or a locked transport guard.
+ *
+ * @param transport - Transport whose URL guard may already be locked.
+ * @param authorizedSuffixes - Suffixes derived from validated Partner authorization.
+ * @param messages - Surface-specific failure messages.
+ *
+ * @returns The suffixes safe for credential-bearing endpoint requests.
+ *
+ * @throws B2PartnerAuthorizationError if no locked guard or authorized suffixes exist.
+ *
+ * @internal
+ */
+export declare function endpointAllowedSuffixes(transport: HttpTransport, authorizedSuffixes: readonly string[], messages: EndpointAllowedSuffixMessages): readonly string[];
+/**
+ * Validates a Partner-derived endpoint URL before a Partner token is sent to it.
+ *
+ * @param rawUrl - Endpoint URL from Partner authorization or cache.
+ * @param fieldName - Authorize-response field being validated.
+ * @param allowedSuffixes - Host suffix allow-list derived from the trusted realm.
+ *
+ * @returns The original URL when it is safe to use.
+ *
+ * @throws B2PartnerAuthorizationError if the URL is malformed or unsafe.
+ *
+ * @internal
+ */
+export declare function validatePartnerEndpointUrl(rawUrl: string, fieldName: PartnerEndpointUrlField, allowedSuffixes: readonly string[]): string;
+/**
+ * Appends query parameters using the SDK's B2 URL encoding semantics.
+ *
+ * @param url - Base URL without query string.
+ * @param query - Query keys and string/number values to append.
+ *
+ * @returns URL with encoded query parameters, or the original URL for an empty query.
+ *
+ * @internal
+ */
+export declare function withQueryString(url: string, query: QueryParams): string;
+/**
+ * Forces non-idempotent mutation calls to opt out of automatic request replay.
+ *
+ * @param options - Caller-provided request options.
+ *
+ * @returns Request options with `retry.maxRetries` set to zero.
+ *
+ * @internal
+ */
+export declare function nonRetryingMutationRequestOptions(options: MutationRequestOptions | undefined): MutationRequestOptions;
+//# sourceMappingURL=endpoint-url.d.ts.map

package/dist/partner/endpoint-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint-url.d.ts","sourceRoot":"","sources":["../../src/partner/endpoint-url.js"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAG/E,sFAAsF;AACtF,MAAM,MAAM,uBAAuB,GAAG,cAAc,GAAG,cAAc,CAAA;AAErE,4FAA4F;AAC5F,MAAM,WAAW,6BAA6B;IAC5C,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAC/B;AAED,kFAAkF;AAClF,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAA;AACxC,mFAAmF;AACnF,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAA;AAE9D,oFAAoF;AACpF,MAAM,WAAW,sBAAsB;IACrC,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B,kCAAkC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;CACvC;AAkBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,aAAa,EACxB,kBAAkB,EAAE,SAAS,MAAM,EAAE,EACrC,QAAQ,EAAE,6BAA6B,GACtC,SAAS,MAAM,EAAE,CAcnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,uBAAuB,EAClC,eAAe,EAAE,SAAS,MAAM,EAAE,GACjC,MAAM,CA2CR;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,MAAM,CAOvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,sBAAsB,GAAG,SAAS,GAC1C,sBAAsB,CAKxB"}

package/dist/partner/endpoint-url.js

@@ -0,0 +1,105 @@
+import { B2PartnerAuthorizationError } from "../errors/index.js";
+import { UrlGuard, hostMatchesAllowedSuffix } from "../http/url-guard.js";
+import { getTransportUrlGuard } from "../http/transport.js";
+//#region src/partner/endpoint-url.ts
+function isLoopbackHost(hostname) {
+	const host = hostname.toLowerCase();
+	if (host === "[::1]" || host === "::1") return true;
+	const parts = host.split(".");
+	return parts.length === 4 && parts[0] === "127" && parts.every((part) => /^\d+$/.test(part) && Number(part) <= 255);
+}
+function hostAllowedBySuffixes(hostname, allowedSuffixes) {
+	return allowedSuffixes.some((suffix) => hostMatchesAllowedSuffix(hostname, suffix));
+}
+/**
+* Resolves endpoint host suffixes from fresh/cached Partner authorization or a locked transport guard.
+*
+* @param transport - Transport whose URL guard may already be locked.
+* @param authorizedSuffixes - Suffixes derived from validated Partner authorization.
+* @param messages - Surface-specific failure messages.
+*
+* @returns The suffixes safe for credential-bearing endpoint requests.
+*
+* @throws B2PartnerAuthorizationError if no locked guard or authorized suffixes exist.
+*
+* @internal
+*/
+function endpointAllowedSuffixes(transport, authorizedSuffixes, messages) {
+	if (authorizedSuffixes.length > 0) return authorizedSuffixes;
+	const guard = getTransportUrlGuard(transport);
+	if (guard === void 0) throw new B2PartnerAuthorizationError(messages.missingGuard);
+	const suffixes = guard.getAllowedSuffixes();
+	if (suffixes.length === 0) throw new B2PartnerAuthorizationError(messages.unlockedGuard);
+	return suffixes;
+}
+/**
+* Validates a Partner-derived endpoint URL before a Partner token is sent to it.
+*
+* @param rawUrl - Endpoint URL from Partner authorization or cache.
+* @param fieldName - Authorize-response field being validated.
+* @param allowedSuffixes - Host suffix allow-list derived from the trusted realm.
+*
+* @returns The original URL when it is safe to use.
+*
+* @throws B2PartnerAuthorizationError if the URL is malformed or unsafe.
+*
+* @internal
+*/
+function validatePartnerEndpointUrl(rawUrl, fieldName, allowedSuffixes) {
+	let url;
+	try {
+		url = new URL(rawUrl);
+	} catch {
+		throw new B2PartnerAuthorizationError(`Partner authorize response included malformed ${fieldName}`);
+	}
+	const host = url.hostname.toLowerCase();
+	const isAllowedLoopbackHttp = url.protocol === "http:" && isLoopbackHost(host) && hostAllowedBySuffixes(host, allowedSuffixes);
+	if (url.protocol !== "https:" && !isAllowedLoopbackHttp) throw new B2PartnerAuthorizationError(`Partner authorize response ${fieldName} must use HTTPS`);
+	if (url.username !== "" || url.password !== "") throw new B2PartnerAuthorizationError(`Partner authorize response ${fieldName} must not include userinfo`);
+	if (url.search !== "" || url.hash !== "") throw new B2PartnerAuthorizationError(`Partner authorize response ${fieldName} must not include query or fragment`);
+	if (isAllowedLoopbackHttp) return rawUrl;
+	const guard = new UrlGuard();
+	guard.setAllowedSuffixes(allowedSuffixes);
+	try {
+		guard.check(rawUrl);
+	} catch (err) {
+		throw new B2PartnerAuthorizationError(err instanceof Error ? `Partner authorize response included unsafe ${fieldName}: ${err.message}` : `Partner authorize response included unsafe ${fieldName}`);
+	}
+	return rawUrl;
+}
+/**
+* Appends query parameters using the SDK's B2 URL encoding semantics.
+*
+* @param url - Base URL without query string.
+* @param query - Query keys and string/number values to append.
+*
+* @returns URL with encoded query parameters, or the original URL for an empty query.
+*
+* @internal
+*/
+function withQueryString(url, query) {
+	const queryString = Object.entries(query).map(([key, value]) => `${key}=${encodeURIComponent(String(value))}`).join("&");
+	return queryString.length === 0 ? url : `${url}?${queryString}`;
+}
+/**
+* Forces non-idempotent mutation calls to opt out of automatic request replay.
+*
+* @param options - Caller-provided request options.
+*
+* @returns Request options with `retry.maxRetries` set to zero.
+*
+* @internal
+*/
+function nonRetryingMutationRequestOptions(options) {
+	return {
+		...options?.signal !== void 0 ? { signal: options.signal } : {},
+		retry: {
+			...options?.retry ?? {},
+			maxRetries: 0
+		}
+	};
+}
+//#endregion
+export { endpointAllowedSuffixes, nonRetryingMutationRequestOptions, validatePartnerEndpointUrl, withQueryString };
+
+//# sourceMappingURL=endpoint-url.js.map

package/dist/partner/endpoint-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint-url.js","names":[],"sources":["../../src/partner/endpoint-url.ts"],"sourcesContent":["import { B2PartnerAuthorizationError } from '../errors/index.ts'\nimport type { RetryOptions } from '../http/retry.ts'\nimport { getTransportUrlGuard, type HttpTransport } from '../http/transport.ts'\nimport { hostMatchesAllowedSuffix, UrlGuard } from '../http/url-guard.ts'\n\n/** Partner authorize endpoint URL field names that are validated before token use. */\nexport type PartnerEndpointUrlField = 'groupsApiUrl' | 'backupApiUrl'\n\n/** Message copy for resolving endpoint suffixes from an authorized or guarded transport. */\nexport interface EndpointAllowedSuffixMessages {\n  /** Error message when no validated suffixes and no URL guard are available. */\n  readonly missingGuard: string\n  /** Error message when a URL guard exists but has not been locked to suffixes. */\n  readonly unlockedGuard: string\n}\n\n/** Query-string scalar value supported by Partner and Backup endpoint helpers. */\nexport type QueryValue = string | number\n/** Query-string parameter map supported by Partner and Backup endpoint helpers. */\nexport type QueryParams = Readonly<Record<string, QueryValue>>\n\n/** Shared request options shape for non-idempotent Partner and Backup mutations. */\nexport interface MutationRequestOptions {\n  /** Abort signal for cancelling the request. */\n  readonly signal?: AbortSignal\n  /** Per-request retry override. */\n  readonly retry?: Partial<RetryOptions>\n}\n\nfunction isLoopbackHost(hostname: string): boolean {\n  const host = hostname.toLowerCase()\n  if (host === '[::1]' || host === '::1') return true\n\n  const parts = host.split('.')\n  return (\n    parts.length === 4 &&\n    parts[0] === '127' &&\n    parts.every((part) => /^\\d+$/.test(part) && Number(part) <= 255)\n  )\n}\n\nfunction hostAllowedBySuffixes(hostname: string, allowedSuffixes: readonly string[]): boolean {\n  return allowedSuffixes.some((suffix) => hostMatchesAllowedSuffix(hostname, suffix))\n}\n\n/**\n * Resolves endpoint host suffixes from fresh/cached Partner authorization or a locked transport guard.\n *\n * @param transport - Transport whose URL guard may already be locked.\n * @param authorizedSuffixes - Suffixes derived from validated Partner authorization.\n * @param messages - Surface-specific failure messages.\n *\n * @returns The suffixes safe for credential-bearing endpoint requests.\n *\n * @throws B2PartnerAuthorizationError if no locked guard or authorized suffixes exist.\n *\n * @internal\n */\nexport function endpointAllowedSuffixes(\n  transport: HttpTransport,\n  authorizedSuffixes: readonly string[],\n  messages: EndpointAllowedSuffixMessages,\n): readonly string[] {\n  if (authorizedSuffixes.length > 0) return authorizedSuffixes\n\n  const guard = getTransportUrlGuard(transport)\n  if (guard === undefined) {\n    throw new B2PartnerAuthorizationError(messages.missingGuard)\n  }\n\n  const suffixes = guard.getAllowedSuffixes()\n  if (suffixes.length === 0) {\n    throw new B2PartnerAuthorizationError(messages.unlockedGuard)\n  }\n\n  return suffixes\n}\n\n/**\n * Validates a Partner-derived endpoint URL before a Partner token is sent to it.\n *\n * @param rawUrl - Endpoint URL from Partner authorization or cache.\n * @param fieldName - Authorize-response field being validated.\n * @param allowedSuffixes - Host suffix allow-list derived from the trusted realm.\n *\n * @returns The original URL when it is safe to use.\n *\n * @throws B2PartnerAuthorizationError if the URL is malformed or unsafe.\n *\n * @internal\n */\nexport function validatePartnerEndpointUrl(\n  rawUrl: string,\n  fieldName: PartnerEndpointUrlField,\n  allowedSuffixes: readonly string[],\n): string {\n  let url: URL\n  try {\n    url = new URL(rawUrl)\n  } catch {\n    throw new B2PartnerAuthorizationError(\n      `Partner authorize response included malformed ${fieldName}`,\n    )\n  }\n\n  const host = url.hostname.toLowerCase()\n  const isAllowedLoopbackHttp =\n    url.protocol === 'http:' && isLoopbackHost(host) && hostAllowedBySuffixes(host, allowedSuffixes)\n\n  if (url.protocol !== 'https:' && !isAllowedLoopbackHttp) {\n    throw new B2PartnerAuthorizationError(`Partner authorize response ${fieldName} must use HTTPS`)\n  }\n  if (url.username !== '' || url.password !== '') {\n    throw new B2PartnerAuthorizationError(\n      `Partner authorize response ${fieldName} must not include userinfo`,\n    )\n  }\n  if (url.search !== '' || url.hash !== '') {\n    throw new B2PartnerAuthorizationError(\n      `Partner authorize response ${fieldName} must not include query or fragment`,\n    )\n  }\n\n  if (isAllowedLoopbackHttp) return rawUrl\n\n  const guard = new UrlGuard()\n  guard.setAllowedSuffixes(allowedSuffixes)\n  try {\n    guard.check(rawUrl)\n  } catch (err) {\n    throw new B2PartnerAuthorizationError(\n      err instanceof Error\n        ? `Partner authorize response included unsafe ${fieldName}: ${err.message}`\n        : `Partner authorize response included unsafe ${fieldName}`,\n    )\n  }\n\n  return rawUrl\n}\n\n/**\n * Appends query parameters using the SDK's B2 URL encoding semantics.\n *\n * @param url - Base URL without query string.\n * @param query - Query keys and string/number values to append.\n *\n * @returns URL with encoded query parameters, or the original URL for an empty query.\n *\n * @internal\n */\nexport function withQueryString(url: string, query: QueryParams): string {\n  // Match the storage raw client's encodeURIComponent query semantics: spaces\n  // are `%20`, not form-style `+`.\n  const queryString = Object.entries(query)\n    .map(([key, value]) => `${key}=${encodeURIComponent(String(value))}`)\n    .join('&')\n  return queryString.length === 0 ? url : `${url}?${queryString}`\n}\n\n/**\n * Forces non-idempotent mutation calls to opt out of automatic request replay.\n *\n * @param options - Caller-provided request options.\n *\n * @returns Request options with `retry.maxRetries` set to zero.\n *\n * @internal\n */\nexport function nonRetryingMutationRequestOptions(\n  options: MutationRequestOptions | undefined,\n): MutationRequestOptions {\n  return {\n    ...(options?.signal !== undefined ? { signal: options.signal } : {}),\n    retry: { ...(options?.retry ?? {}), maxRetries: 0 },\n  }\n}\n"],"mappings":";;;;AA6BA,SAAS,eAAe,UAA2B;CACjD,MAAM,OAAO,SAAS,YAAY;CAClC,IAAI,SAAS,WAAW,SAAS,OAAO,OAAO;CAE/C,MAAM,QAAQ,KAAK,MAAM,GAAG;CAC5B,OACE,MAAM,WAAW,KACjB,MAAM,OAAO,SACb,MAAM,OAAO,SAAS,QAAQ,KAAK,IAAI,KAAK,OAAO,IAAI,KAAK,GAAG;AAEnE;AAEA,SAAS,sBAAsB,UAAkB,iBAA6C;CAC5F,OAAO,gBAAgB,MAAM,WAAW,yBAAyB,UAAU,MAAM,CAAC;AACpF;;;;;;;;;;;;;;AAeA,SAAgB,wBACd,WACA,oBACA,UACmB;CACnB,IAAI,mBAAmB,SAAS,GAAG,OAAO;CAE1C,MAAM,QAAQ,qBAAqB,SAAS;CAC5C,IAAI,UAAU,KAAA,GACZ,MAAM,IAAI,4BAA4B,SAAS,YAAY;CAG7D,MAAM,WAAW,MAAM,mBAAmB;CAC1C,IAAI,SAAS,WAAW,GACtB,MAAM,IAAI,4BAA4B,SAAS,aAAa;CAG9D,OAAO;AACT;;;;;;;;;;;;;;AAeA,SAAgB,2BACd,QACA,WACA,iBACQ;CACR,IAAI;CACJ,IAAI;EACF,MAAM,IAAI,IAAI,MAAM;CACtB,QAAQ;EACN,MAAM,IAAI,4BACR,iDAAiD,WACnD;CACF;CAEA,MAAM,OAAO,IAAI,SAAS,YAAY;CACtC,MAAM,wBACJ,IAAI,aAAa,WAAW,eAAe,IAAI,KAAK,sBAAsB,MAAM,eAAe;CAEjG,IAAI,IAAI,aAAa,YAAY,CAAC,uBAChC,MAAM,IAAI,4BAA4B,8BAA8B,UAAU,gBAAgB;CAEhG,IAAI,IAAI,aAAa,MAAM,IAAI,aAAa,IAC1C,MAAM,IAAI,4BACR,8BAA8B,UAAU,2BAC1C;CAEF,IAAI,IAAI,WAAW,MAAM,IAAI,SAAS,IACpC,MAAM,IAAI,4BACR,8BAA8B,UAAU,oCAC1C;CAGF,IAAI,uBAAuB,OAAO;CAElC,MAAM,QAAQ,IAAI,SAAS;CAC3B,MAAM,mBAAmB,eAAe;CACxC,IAAI;EACF,MAAM,MAAM,MAAM;CACpB,SAAS,KAAK;EACZ,MAAM,IAAI,4BACR,eAAe,QACX,8CAA8C,UAAU,IAAI,IAAI,YAChE,8CAA8C,WACpD;CACF;CAEA,OAAO;AACT;;;;;;;;;;;AAYA,SAAgB,gBAAgB,KAAa,OAA4B;CAGvE,MAAM,cAAc,OAAO,QAAQ,KAAK,CAAC,CACtC,KAAK,CAAC,KAAK,WAAW,GAAG,IAAI,GAAG,mBAAmB,OAAO,KAAK,CAAC,GAAG,CAAC,CACpE,KAAK,GAAG;CACX,OAAO,YAAY,WAAW,IAAI,MAAM,GAAG,IAAI,GAAG;AACpD;;;;;;;;;;AAWA,SAAgB,kCACd,SACwB;CACxB,OAAO;EACL,GAAI,SAAS,WAAW,KAAA,IAAY,EAAE,QAAQ,QAAQ,OAAO,IAAI,CAAC;EAClE,OAAO;GAAE,GAAI,SAAS,SAAS,CAAC;GAAI,YAAY;EAAE;CACpD;AACF"}

package/dist/partner/in-memory.cjs

@@ -0,0 +1,135 @@
+const require_errors_index = require("../errors/index.cjs");
+const require_redaction_placeholders = require("./redaction-placeholders.cjs");
+const require_auth_clone = require("./auth-clone.cjs");
+const require_redaction = require("./redaction.cjs");
+//#region src/partner/in-memory.ts
+function clonePartnerAuth(auth) {
+	return require_redaction.redactPartnerAuthorizeResponse(require_auth_clone.clonePartnerAuthorizeResponse(auth));
+}
+/**
+* In-memory implementation of {@link PartnerAccountInfo}.
+* Suitable for short-lived processes or tests; state is lost when the process exits.
+*/
+var InMemoryPartnerAccountInfo = class {
+	/** Cached Partner authorization response, or null before authorizePartner() is called. */
+	#auth = null;
+	/**
+	* Store a fresh Partner authorization response, replacing any previous state.
+	*
+	* @param auth - The Partner authorize response to store.
+	*/
+	setAuth(auth) {
+		this.#auth = clonePartnerAuth(auth);
+	}
+	/**
+	* Return the current Partner authorization response, or null if not authorized.
+	*
+	* @returns The cached Partner authorization response, or null if not yet authorized.
+	*/
+	getAuth() {
+		return this.#auth;
+	}
+	/** Discard all cached Partner authorization state. */
+	clear() {
+		this.#auth = null;
+	}
+	/**
+	* Current Partner/Backup authorization token.
+	*
+	* @returns The current Partner token.
+	*
+	* @throws B2PartnerAuthorizationError if not yet authorized.
+	*/
+	getPartnerToken() {
+		return this.requireAuth().authorizationToken;
+	}
+	/**
+	* Base URL for Partner API calls.
+	*
+	* @returns The base URL for Partner API calls.
+	*
+	* @throws B2PartnerAuthorizationError if not yet authorized.
+	*/
+	getGroupsApiUrl() {
+		return this.requireAuth().apiInfo.groupsApi?.groupsApiUrl ?? null;
+	}
+	/**
+	* Base URL for Computer Backup API calls, or null when the suite is unavailable.
+	*
+	* @returns The Computer Backup API URL, or null.
+	*
+	* @throws B2PartnerAuthorizationError if not yet authorized.
+	*/
+	getBackupApiUrl() {
+		return this.requireAuth().backupApiUrl ?? null;
+	}
+	/**
+	* The authorized partner administrator account ID.
+	*
+	* @returns The authorized account identifier.
+	*
+	* @throws B2PartnerAuthorizationError if not yet authorized.
+	*/
+	getAccountId() {
+		return this.requireAuth().accountId;
+	}
+	/**
+	* Capabilities granted for Partner API calls.
+	*
+	* @returns The Partner API capabilities.
+	*
+	* @throws B2PartnerAuthorizationError if not yet authorized.
+	*/
+	getGroupsCapabilities() {
+		return this.requireAuth().apiInfo.groupsApi?.capabilities ?? null;
+	}
+	/**
+	* Capabilities granted for Computer Backup API calls, or null when the suite is unavailable.
+	*
+	* @returns The Computer Backup API capabilities, or null.
+	*
+	* @throws B2PartnerAuthorizationError if not yet authorized.
+	*/
+	getBackupCapabilities() {
+		return this.requireAuth().backupCapabilities ?? null;
+	}
+	/**
+	* Hides the Partner token from `JSON.stringify(accountInfo)`.
+	*
+	* @returns Redacted Partner auth state, or null when not authorized.
+	*/
+	toJSON() {
+		return { auth: this.#auth === null ? null : require_redaction.partnerAuthorizeResponseToRedactedJson(this.#auth) };
+	}
+	/**
+	* Hides the Partner token from default stringification.
+	*
+	* @returns A short opaque label for this account info store.
+	*/
+	toString() {
+		return this.#auth === null ? "[InMemoryPartnerAccountInfo unauthorized]" : `[InMemoryPartnerAccountInfo ${require_redaction_placeholders.PARTNER_TOKEN_REDACTED}]`;
+	}
+	/**
+	* Hides the Partner token from Node's `util.inspect`.
+	*
+	* @returns A short opaque label for this account info store.
+	*/
+	[Symbol.for("nodejs.util.inspect.custom")]() {
+		return this.toString();
+	}
+	/**
+	* Retrieve the cached auth response or throw if not yet authorized.
+	*
+	* @returns The cached authorization response.
+	*
+	* @throws B2PartnerAuthorizationError if authorizePartner() has not been called.
+	*/
+	requireAuth() {
+		if (!this.#auth) throw new require_errors_index.B2PartnerAuthorizationError("Not authorized. Call authorizePartner() first.");
+		return this.#auth;
+	}
+};
+//#endregion
+exports.InMemoryPartnerAccountInfo = InMemoryPartnerAccountInfo;
+
+//# sourceMappingURL=in-memory.cjs.map

package/dist/partner/in-memory.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory.cjs","names":["#auth"],"sources":["../../src/partner/in-memory.ts"],"sourcesContent":["import { B2PartnerAuthorizationError } from '../errors/index.ts'\nimport type { AccountId, PartnerToken } from '../types/ids.ts'\nimport type { PartnerAuthorizeResponse, PartnerCapability } from '../types/partner.ts'\nimport type { PartnerAccountInfo } from './account-info.ts'\nimport { clonePartnerAuthorizeResponse } from './auth-clone.ts'\nimport {\n  PARTNER_TOKEN_REDACTED,\n  partnerAuthorizeResponseToRedactedJson,\n  type RedactedPartnerAuthorizeResponseJson,\n  redactPartnerAuthorizeResponse,\n} from './redaction.ts'\n\n/** Redacted JSON diagnostic shape emitted by {@link InMemoryPartnerAccountInfo.toJSON}. */\nexport interface InMemoryPartnerAccountInfoJson {\n  /** Redacted cached authorization state, or null before authorization. */\n  readonly auth: RedactedPartnerAuthorizeResponseJson | null\n}\n\nfunction clonePartnerAuth(auth: PartnerAuthorizeResponse): PartnerAuthorizeResponse {\n  return redactPartnerAuthorizeResponse(clonePartnerAuthorizeResponse(auth))\n}\n\n/**\n * In-memory implementation of {@link PartnerAccountInfo}.\n * Suitable for short-lived processes or tests; state is lost when the process exits.\n */\nexport class InMemoryPartnerAccountInfo implements PartnerAccountInfo {\n  /** Cached Partner authorization response, or null before authorizePartner() is called. */\n  #auth: PartnerAuthorizeResponse | null = null\n\n  /**\n   * Store a fresh Partner authorization response, replacing any previous state.\n   *\n   * @param auth - The Partner authorize response to store.\n   */\n  setAuth(auth: PartnerAuthorizeResponse): void {\n    this.#auth = clonePartnerAuth(auth)\n  }\n\n  /**\n   * Return the current Partner authorization response, or null if not authorized.\n   *\n   * @returns The cached Partner authorization response, or null if not yet authorized.\n   */\n  getAuth(): PartnerAuthorizeResponse | null {\n    return this.#auth\n  }\n\n  /** Discard all cached Partner authorization state. */\n  clear(): void {\n    this.#auth = null\n  }\n\n  /**\n   * Current Partner/Backup authorization token.\n   *\n   * @returns The current Partner token.\n   *\n   * @throws B2PartnerAuthorizationError if not yet authorized.\n   */\n  getPartnerToken(): PartnerToken {\n    return this.requireAuth().authorizationToken\n  }\n\n  /**\n   * Base URL for Partner API calls.\n   *\n   * @returns The base URL for Partner API calls.\n   *\n   * @throws B2PartnerAuthorizationError if not yet authorized.\n   */\n  getGroupsApiUrl(): string | null {\n    return this.requireAuth().apiInfo.groupsApi?.groupsApiUrl ?? null\n  }\n\n  /**\n   * Base URL for Computer Backup API calls, or null when the suite is unavailable.\n   *\n   * @returns The Computer Backup API URL, or null.\n   *\n   * @throws B2PartnerAuthorizationError if not yet authorized.\n   */\n  getBackupApiUrl(): string | null {\n    return this.requireAuth().backupApiUrl ?? null\n  }\n\n  /**\n   * The authorized partner administrator account ID.\n   *\n   * @returns The authorized account identifier.\n   *\n   * @throws B2PartnerAuthorizationError if not yet authorized.\n   */\n  getAccountId(): AccountId {\n    return this.requireAuth().accountId\n  }\n\n  /**\n   * Capabilities granted for Partner API calls.\n   *\n   * @returns The Partner API capabilities.\n   *\n   * @throws B2PartnerAuthorizationError if not yet authorized.\n   */\n  getGroupsCapabilities(): readonly PartnerCapability[] | null {\n    return this.requireAuth().apiInfo.groupsApi?.capabilities ?? null\n  }\n\n  /**\n   * Capabilities granted for Computer Backup API calls, or null when the suite is unavailable.\n   *\n   * @returns The Computer Backup API capabilities, or null.\n   *\n   * @throws B2PartnerAuthorizationError if not yet authorized.\n   */\n  getBackupCapabilities(): readonly PartnerCapability[] | null {\n    return this.requireAuth().backupCapabilities ?? null\n  }\n\n  /**\n   * Hides the Partner token from `JSON.stringify(accountInfo)`.\n   *\n   * @returns Redacted Partner auth state, or null when not authorized.\n   */\n  toJSON(): InMemoryPartnerAccountInfoJson {\n    return {\n      auth: this.#auth === null ? null : partnerAuthorizeResponseToRedactedJson(this.#auth),\n    }\n  }\n\n  /**\n   * Hides the Partner token from default stringification.\n   *\n   * @returns A short opaque label for this account info store.\n   */\n  toString(): string {\n    return this.#auth === null\n      ? '[InMemoryPartnerAccountInfo unauthorized]'\n      : `[InMemoryPartnerAccountInfo ${PARTNER_TOKEN_REDACTED}]`\n  }\n\n  /**\n   * Hides the Partner token from Node's `util.inspect`.\n   *\n   * @returns A short opaque label for this account info store.\n   */\n  [Symbol.for('nodejs.util.inspect.custom')](): string {\n    return this.toString()\n  }\n\n  /**\n   * Retrieve the cached auth response or throw if not yet authorized.\n   *\n   * @returns The cached authorization response.\n   *\n   * @throws B2PartnerAuthorizationError if authorizePartner() has not been called.\n   */\n  private requireAuth(): PartnerAuthorizeResponse {\n    if (!this.#auth) {\n      throw new B2PartnerAuthorizationError('Not authorized. Call authorizePartner() first.')\n    }\n    return this.#auth\n  }\n}\n"],"mappings":";;;;;AAkBA,SAAS,iBAAiB,MAA0D;CAClF,OAAO,kBAAA,+BAA+B,mBAAA,8BAA8B,IAAI,CAAC;AAC3E;;;;;AAMA,IAAa,6BAAb,MAAsE;;CAEpE,QAAyC;;;;;;CAOzC,QAAQ,MAAsC;EAC5C,KAAKA,QAAQ,iBAAiB,IAAI;CACpC;;;;;;CAOA,UAA2C;EACzC,OAAO,KAAKA;CACd;;CAGA,QAAc;EACZ,KAAKA,QAAQ;CACf;;;;;;;;CASA,kBAAgC;EAC9B,OAAO,KAAK,YAAY,CAAC,CAAC;CAC5B;;;;;;;;CASA,kBAAiC;EAC/B,OAAO,KAAK,YAAY,CAAC,CAAC,QAAQ,WAAW,gBAAgB;CAC/D;;;;;;;;CASA,kBAAiC;EAC/B,OAAO,KAAK,YAAY,CAAC,CAAC,gBAAgB;CAC5C;;;;;;;;CASA,eAA0B;EACxB,OAAO,KAAK,YAAY,CAAC,CAAC;CAC5B;;;;;;;;CASA,wBAA6D;EAC3D,OAAO,KAAK,YAAY,CAAC,CAAC,QAAQ,WAAW,gBAAgB;CAC/D;;;;;;;;CASA,wBAA6D;EAC3D,OAAO,KAAK,YAAY,CAAC,CAAC,sBAAsB;CAClD;;;;;;CAOA,SAAyC;EACvC,OAAO,EACL,MAAM,KAAKA,UAAU,OAAO,OAAO,kBAAA,uCAAuC,KAAKA,KAAK,EACtF;CACF;;;;;;CAOA,WAAmB;EACjB,OAAO,KAAKA,UAAU,OAClB,8CACA,+BAA+B,+BAAA,uBAAuB;CAC5D;;;;;;CAOA,CAAC,OAAO,IAAI,4BAA4B,KAAa;EACnD,OAAO,KAAK,SAAS;CACvB;;;;;;;;CASA,cAAgD;EAC9C,IAAI,CAAC,KAAKA,OACR,MAAM,IAAI,qBAAA,4BAA4B,gDAAgD;EAExF,OAAO,KAAKA;CACd;AACF"}

package/dist/partner/in-memory.d.cts

@@ -0,0 +1,99 @@
+import { AccountId, PartnerToken } from '../types/ids.js';
+import { PartnerAuthorizeResponse, PartnerCapability } from '../types/partner.js';
+import { PartnerAccountInfo } from './account-info.js';
+import { RedactedPartnerAuthorizeResponseJson } from './redaction.js';
+/** Redacted JSON diagnostic shape emitted by {@link InMemoryPartnerAccountInfo.toJSON}. */
+export interface InMemoryPartnerAccountInfoJson {
+    /** Redacted cached authorization state, or null before authorization. */
+    readonly auth: RedactedPartnerAuthorizeResponseJson | null;
+}
+/**
+ * In-memory implementation of {@link PartnerAccountInfo}.
+ * Suitable for short-lived processes or tests; state is lost when the process exits.
+ */
+export declare class InMemoryPartnerAccountInfo implements PartnerAccountInfo {
+    #private;
+    /**
+     * Store a fresh Partner authorization response, replacing any previous state.
+     *
+     * @param auth - The Partner authorize response to store.
+     */
+    setAuth(auth: PartnerAuthorizeResponse): void;
+    /**
+     * Return the current Partner authorization response, or null if not authorized.
+     *
+     * @returns The cached Partner authorization response, or null if not yet authorized.
+     */
+    getAuth(): PartnerAuthorizeResponse | null;
+    /** Discard all cached Partner authorization state. */
+    clear(): void;
+    /**
+     * Current Partner/Backup authorization token.
+     *
+     * @returns The current Partner token.
+     *
+     * @throws B2PartnerAuthorizationError if not yet authorized.
+     */
+    getPartnerToken(): PartnerToken;
+    /**
+     * Base URL for Partner API calls.
+     *
+     * @returns The base URL for Partner API calls.
+     *
+     * @throws B2PartnerAuthorizationError if not yet authorized.
+     */
+    getGroupsApiUrl(): string | null;
+    /**
+     * Base URL for Computer Backup API calls, or null when the suite is unavailable.
+     *
+     * @returns The Computer Backup API URL, or null.
+     *
+     * @throws B2PartnerAuthorizationError if not yet authorized.
+     */
+    getBackupApiUrl(): string | null;
+    /**
+     * The authorized partner administrator account ID.
+     *
+     * @returns The authorized account identifier.
+     *
+     * @throws B2PartnerAuthorizationError if not yet authorized.
+     */
+    getAccountId(): AccountId;
+    /**
+     * Capabilities granted for Partner API calls.
+     *
+     * @returns The Partner API capabilities.
+     *
+     * @throws B2PartnerAuthorizationError if not yet authorized.
+     */
+    getGroupsCapabilities(): readonly PartnerCapability[] | null;
+    /**
+     * Capabilities granted for Computer Backup API calls, or null when the suite is unavailable.
+     *
+     * @returns The Computer Backup API capabilities, or null.
+     *
+     * @throws B2PartnerAuthorizationError if not yet authorized.
+     */
+    getBackupCapabilities(): readonly PartnerCapability[] | null;
+    /**
+     * Hides the Partner token from `JSON.stringify(accountInfo)`.
+     *
+     * @returns Redacted Partner auth state, or null when not authorized.
+     */
+    toJSON(): InMemoryPartnerAccountInfoJson;
+    /**
+     * Hides the Partner token from default stringification.
+     *
+     * @returns A short opaque label for this account info store.
+     */
+    toString(): string;
+    /**
+     * Retrieve the cached auth response or throw if not yet authorized.
+     *
+     * @returns The cached authorization response.
+     *
+     * @throws B2PartnerAuthorizationError if authorizePartner() has not been called.
+     */
+    private requireAuth;
+}
+//# sourceMappingURL=in-memory.d.ts.map

package/dist/partner/in-memory.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory.d.ts","sourceRoot":"","sources":["../../src/partner/in-memory.js"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC9D,OAAO,KAAK,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACtF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAE3D,OAAO,EAGL,KAAK,oCAAoC,EAE1C,MAAM,gBAAgB,CAAA;AAEvB,2FAA2F;AAC3F,MAAM,WAAW,8BAA8B;IAC7C,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,oCAAoC,GAAG,IAAI,CAAA;CAC3D;AAMD;;;GAGG;AACH,qBAAa,0BAA2B,YAAW,kBAAkB;;IAInE;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,wBAAwB,GAAG,IAAI;IAI7C;;;;OAIG;IACH,OAAO,IAAI,wBAAwB,GAAG,IAAI;IAI1C,sDAAsD;IACtD,KAAK,IAAI,IAAI;IAIb;;;;;;OAMG;IACH,eAAe,IAAI,YAAY;IAI/B;;;;;;OAMG;IACH,eAAe,IAAI,MAAM,GAAG,IAAI;IAIhC;;;;;;OAMG;IACH,eAAe,IAAI,MAAM,GAAG,IAAI;IAIhC;;;;;;OAMG;IACH,YAAY,IAAI,SAAS;IAIzB;;;;;;OAMG;IACH,qBAAqB,IAAI,SAAS,iBAAiB,EAAE,GAAG,IAAI;IAI5D;;;;;;OAMG;IACH,qBAAqB,IAAI,SAAS,iBAAiB,EAAE,GAAG,IAAI;IAI5D;;;;OAIG;IACH,MAAM,IAAI,8BAA8B;IAMxC;;;;OAIG;IACH,QAAQ,IAAI,MAAM;IAelB;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;CAMpB"}