@backblaze-labs/b2-sdk 0.1.0 → 0.3.0

package/dist/backup/client.cjs

@@ -0,0 +1,206 @@
+const require_ids = require("../types/ids.cjs");
+const require_errors_index = require("../errors/index.cjs");
+const require_paginator = require("../util/paginator.cjs");
+const require_redaction_placeholders = require("../partner/redaction-placeholders.cjs");
+const require_auth_core = require("../partner/auth-core.cjs");
+const require_raw = require("./raw.cjs");
+//#region src/backup/client.ts
+var MASTER_KEY_REDACTED = "[redacted Master Application Key]";
+function badListComputersResponse(message) {
+	return new require_errors_index.BadJsonError({
+		status: 400,
+		code: "bad_json",
+		message: `bz_list_computers response did not match documented wire shape: ${message}`
+	});
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function normalizeListComputersResponse(response) {
+	if (!isRecord(response) || Array.isArray(response)) throw badListComputersResponse("expected a JSON object");
+	const resultComputers = response["computers"];
+	if (!Array.isArray(resultComputers)) throw badListComputersResponse("response must include a computers array");
+	const cursor = response["nextComputerId"];
+	if (cursor !== null && typeof cursor !== "string") throw badListComputersResponse("response must include nextComputerId as string or null");
+	return {
+		nextComputerId: cursor === null ? null : require_ids.computerId(cursor),
+		computers: resultComputers
+	};
+}
+/**
+* High-level Computer Backup API client for listing and deleting backup records.
+*
+* The client uses Partner authorization and the `backupApiUrl` returned by
+* `authorizePartner`. The target account must belong to a group with
+* Enterprise Controls enabled, and the caller must be a group admin. Deleting
+* a backup also requires the Enterprise Controls setting that permits admins
+* to delete member backups.
+*
+* @example
+* ```ts
+* const backup = new BackupClient({
+*   masterKeyId: process.env.B2_MASTER_KEY_ID,
+*   masterKey: process.env.B2_MASTER_KEY,
+* })
+* await backup.authorize()
+* for await (const computer of backup.paginateComputers()) {
+*   console.log(computer.computerName)
+* }
+* ```
+*
+* @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.
+*/
+var BackupClient = class {
+	/** Low-level client for direct Computer Backup API calls. */
+	raw;
+	/** Partner authorization state storage (tokens, URLs, capabilities). */
+	partnerAccountInfo;
+	/**
+	* SSRF allow-list applied by the default transport. `null` when
+	* a custom transport was supplied; in that case the SDK does not own the
+	* guard.
+	*/
+	urlGuard;
+	authCore;
+	/**
+	* Creates a new BackupClient. Call {@link authorize} before making API requests
+	* unless `partnerAccountInfo` already contains valid Partner authorization.
+	*
+	* @param options - Configuration including credentials, realm, and transport settings.
+	*/
+	constructor(options) {
+		this.authCore = new require_auth_core.PartnerAuthCore(options);
+		this.partnerAccountInfo = this.authCore.partnerAccountInfo;
+		this.urlGuard = this.authCore.urlGuard;
+		this.raw = new require_raw.BackupRawClient({
+			transport: this.authCore.transport,
+			...this.authCore.cachedEndpointSuffixes !== void 0 ? { authorizedBackupEndpointSuffixes: this.authCore.cachedEndpointSuffixes } : {}
+		});
+	}
+	/**
+	* Authenticates with B2 Partner authorization and stores the authorization state.
+	*
+	* @param options - Optional abort signal.
+	*
+	* @returns The Partner authorization response containing tokens, URLs, and capabilities.
+	*
+	* @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.
+	*/
+	async authorize(options) {
+		const auth = await this.authCore.authorize(options);
+		this.raw.setAuthorizedEndpointSuffixes(this.authCore.activateEndpointSuffixes(auth));
+		return auth;
+	}
+	/**
+	* Lists active Computer Backup records for an account.
+	*
+	* @param options - Optional target account and pagination settings.
+	*
+	* @returns A normalized page of computer backup records with an optional continuation cursor.
+	*
+	* @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.
+	*/
+	async listComputers(options) {
+		const auth = this.ensureBackupAuthorization();
+		const { backupApiUrl, authToken, accountId } = this.backupCoordinates(auth, options?.accountId);
+		return normalizeListComputersResponse(await this.raw.listComputers(backupApiUrl, authToken, {
+			accountId,
+			...options?.startComputerId !== void 0 ? { startComputerId: options.startComputerId } : {},
+			...options?.pageSize !== void 0 ? { maxComputerCount: options.pageSize } : {}
+		}, options?.signal !== void 0 ? { signal: options.signal } : void 0));
+	}
+	/**
+	* Async iterator that yields every active Computer Backup record for an account.
+	*
+	* @param options - Optional target account, page size, and abort signal.
+	*
+	* @returns An async iterable of {@link ComputerBackup} entries.
+	*
+	* @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.
+	*/
+	paginateComputers(options) {
+		return require_paginator.paginateItems(async (cursor) => {
+			const resp = await this.listComputers({
+				...options?.accountId !== void 0 ? { accountId: options.accountId } : {},
+				...options?.pageSize !== void 0 ? { pageSize: options.pageSize } : {},
+				...cursor !== void 0 ? { startComputerId: cursor } : {},
+				...options?.signal !== void 0 ? { signal: options.signal } : {}
+			});
+			return {
+				page: resp,
+				nextCursor: resp.nextComputerId ?? void 0
+			};
+		}, (page) => page.computers, options?.signal);
+	}
+	/**
+	* Deletes a Computer Backup record.
+	*
+	* This destructive mutation is not automatically retried or reauthorized in
+	* place; callers should reconcile backup state before issuing a new delete
+	* after an ambiguous failure.
+	*
+	* @param options - Target account, computer ID, and optional abort signal.
+	*
+	* @returns The deleted computer backup record array.
+	*
+	* @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.
+	*/
+	async deleteComputer(options) {
+		const auth = this.ensureBackupAuthorization();
+		const { backupApiUrl, authToken, accountId } = this.backupCoordinates(auth, options.accountId);
+		return this.raw.deleteComputer(backupApiUrl, authToken, {
+			accountId,
+			computerId: options.computerId
+		}, options.signal !== void 0 ? { signal: options.signal } : void 0);
+	}
+	ensureBackupAuthorization() {
+		const auth = this.partnerAccountInfo.getAuth();
+		if (auth === null) throw new require_errors_index.B2PartnerAuthorizationError("Not authorized. Call BackupClient.authorize() first.");
+		const suffixes = this.authCore.activateEndpointSuffixes(auth);
+		this.raw.setAuthorizedEndpointSuffixes(suffixes);
+		return auth;
+	}
+	backupCoordinates(auth, accountIdOverride) {
+		const backupApiUrl = auth.apiInfo.backupApi?.backupApiUrl;
+		if (backupApiUrl === void 0) throw new require_errors_index.B2PartnerAuthorizationError("Computer Backup API is not available; Partner authorization did not return apiInfo.backupApi.");
+		return {
+			backupApiUrl,
+			authToken: auth.authorizationToken,
+			accountId: accountIdOverride ?? auth.accountId
+		};
+	}
+	/**
+	* Hides credentials and Partner tokens from `JSON.stringify(client)`.
+	*
+	* @returns A redacted diagnostic object.
+	*/
+	toJSON() {
+		return {
+			type: "BackupClient",
+			credentials: MASTER_KEY_REDACTED,
+			authorization: this.partnerAccountInfo.getAuth() === null ? "[unauthorized]" : require_redaction_placeholders.PARTNER_TOKEN_REDACTED,
+			authorized: this.partnerAccountInfo.getAuth() !== null,
+			urlGuardAllowedSuffixes: this.urlGuard?.getAllowedSuffixes() ?? null
+		};
+	}
+	/**
+	* Hides credentials and Partner tokens from default stringification.
+	*
+	* @returns A short redacted label.
+	*/
+	toString() {
+		return `[BackupClient ${MASTER_KEY_REDACTED}]`;
+	}
+	/**
+	* Hides credentials and Partner tokens from Node's `util.inspect`.
+	*
+	* @returns A short redacted label.
+	*/
+	[Symbol.for("nodejs.util.inspect.custom")]() {
+		return this.toString();
+	}
+};
+//#endregion
+exports.BackupClient = BackupClient;
+
+//# sourceMappingURL=client.cjs.map

package/dist/backup/client.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.cjs","names":[],"sources":["../../src/backup/client.ts"],"sourcesContent":["import { B2PartnerAuthorizationError, BadJsonError } from '../errors/index.ts'\nimport type { RetryOptions } from '../http/retry.ts'\nimport type { HttpTransport } from '../http/transport.ts'\nimport type { UrlGuard } from '../http/url-guard.ts'\nimport type { PartnerAccountInfo } from '../partner/account-info.ts'\nimport { PartnerAuthCore } from '../partner/auth-core.ts'\nimport { PARTNER_TOKEN_REDACTED } from '../partner/redaction.ts'\nimport type {\n  ComputerBackup,\n  DeleteComputerResponse,\n  ListComputersResponse,\n  ListComputersResult,\n} from '../types/backup.ts'\nimport { type AccountId, type ComputerId, computerId, type PartnerToken } from '../types/ids.ts'\nimport type { PartnerAuthorizeResponse } from '../types/partner.ts'\nimport { paginateItems } from '../util/paginator.ts'\nimport { BackupRawClient } from './raw.ts'\n\nconst MASTER_KEY_REDACTED = '[redacted Master Application Key]'\n\n/**\n * Configuration options for creating a {@link BackupClient}.\n *\n * @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.\n */\nexport interface BackupClientOptions {\n  /** The Master Application Key ID for the partner administrator account. */\n  readonly masterKeyId: string\n  /** The Master Application Key secret. */\n  readonly masterKey: string\n  /**\n   * B2 realm to authenticate against. Accepts a known realm-map key\n   * (`\"production\"` or `\"staging\"`) or a direct base URL. Custom HTTPS hosts\n   * and loopback IP literal HTTP URLs for local testing are trusted with the\n   * Master Application Key during Partner authorize, so never derive `realm`\n   * from untrusted input. Defaults to `\"production\"`.\n   */\n  readonly realm?: string\n  /**\n   * Shared Partner authorization state. Defaults to\n   * {@link InMemoryPartnerAccountInfo}. Pass the same store to\n   * {@link BackupClient} and Partner clients when both surfaces should reuse\n   * one Partner token. Cached authorization whose endpoints fail this client's\n   * realm policy is ignored locally until `authorize()` replaces it; shared\n   * stores are not cleared during construction.\n   */\n  readonly partnerAccountInfo?: PartnerAccountInfo\n  /** Custom HTTP transport. Defaults to `FetchTransport`. Wrapped by `RetryTransport`. */\n  readonly transport?: HttpTransport\n  /** Override retry behavior (max retries, backoff, and per-attempt timeout). */\n  readonly retry?: Partial<RetryOptions>\n  /** Custom user-agent string prepended to the SDK default. */\n  readonly userAgent?: string\n  /**\n   * Additional SSRF allow-list host suffixes for the default transport.\n   *\n   * Only consulted when {@link BackupClientOptions.transport} is unset; a\n   * custom transport is the user's responsibility to harden.\n   */\n  readonly additionalAllowedHostSuffixes?: readonly string[]\n  /**\n   * Explicitly disable the default SSRF guard after authorize.\n   *\n   * Intended only for controlled simulator/private-proxy tests. Never enable\n   * it for URLs derived from untrusted input or production credentials.\n   */\n  readonly disableSsrfGuard?: boolean\n  /**\n   * Follow same-origin GET/HEAD redirects in the default fetch transport after\n   * checking each target with the SSRF guard. POST redirects remain blocked.\n   * Defaults to true.\n   */\n  readonly followSameOriginRedirects?: boolean\n  /**\n   * Allow direct custom authorize realms for tests or private proxies.\n   * Leave disabled unless the configured host is trusted with the Master\n   * Application Key.\n   */\n  readonly allowCustomAuthorizeRealm?: boolean\n}\n\n/**\n * Options for Partner authorization performed by {@link BackupClient}.\n *\n * @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.\n */\nexport interface BackupAuthorizeOptions {\n  /** Abort signal for cancelling the authorize request. */\n  readonly signal?: AbortSignal\n}\n\n/**\n * Options for listing Computer Backup records.\n *\n * @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.\n */\nexport interface ListComputersOptions {\n  /**\n   * Account whose active computer backups should be listed. Defaults to the\n   * partner administrator account ID from authorization.\n   */\n  readonly accountId?: AccountId\n  /** Computer ID to start listing from for pagination. */\n  readonly startComputerId?: ComputerId\n  /** Maximum computers to return in this page. Forwarded to `maxComputerCount`. */\n  readonly pageSize?: number\n  /** Abort signal for cancelling the request. */\n  readonly signal?: AbortSignal\n}\n\n/**\n * Options for paginating Computer Backup records.\n *\n * @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.\n */\nexport interface PaginateComputersOptions extends Omit<ListComputersOptions, 'startComputerId'> {\n  /**\n   * Aborts the iteration between page fetches. The signal is also forwarded to\n   * each underlying list request.\n   */\n  readonly signal?: AbortSignal\n}\n\n/**\n * Options for deleting a Computer Backup record.\n *\n * @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.\n */\nexport interface DeleteComputerOptions {\n  /**\n   * Account that owns the computer backup. Defaults to the partner\n   * administrator account ID from authorization.\n   */\n  readonly accountId?: AccountId\n  /** Computer ID of the backup to delete. */\n  readonly computerId: ComputerId\n  /** Abort signal for cancelling the request. */\n  readonly signal?: AbortSignal\n}\n\ninterface BackupCoordinates {\n  readonly backupApiUrl: string\n  readonly authToken: PartnerToken\n  readonly accountId: AccountId\n}\n\nfunction badListComputersResponse(message: string): BadJsonError {\n  return new BadJsonError({\n    status: 400,\n    code: 'bad_json',\n    message: `bz_list_computers response did not match documented wire shape: ${message}`,\n  })\n}\n\nfunction isRecord(value: unknown): value is Readonly<Record<string, unknown>> {\n  return typeof value === 'object' && value !== null\n}\n\nfunction normalizeListComputersResponse(response: ListComputersResponse): ListComputersResult {\n  // Archived Backup API docs model bz_list_computers as a single result object\n  // with a pagination cursor and a `computers` array (an empty account returns\n  // an empty `computers` array, not a top-level empty array).\n  if (!isRecord(response) || Array.isArray(response)) {\n    throw badListComputersResponse('expected a JSON object')\n  }\n  const resultComputers = response['computers']\n  if (!Array.isArray(resultComputers)) {\n    throw badListComputersResponse('response must include a computers array')\n  }\n  const cursor = response['nextComputerId']\n  if (cursor !== null && typeof cursor !== 'string') {\n    throw badListComputersResponse('response must include nextComputerId as string or null')\n  }\n\n  return {\n    nextComputerId: cursor === null ? null : computerId(cursor),\n    computers: resultComputers as readonly ComputerBackup[],\n  }\n}\n\n/** Redacted JSON diagnostic shape emitted by {@link BackupClient.toJSON}. */\nexport interface BackupClientJson {\n  /** Object kind for log consumers. */\n  readonly type: 'BackupClient'\n  /** Redacted Master Application Key credential placeholder. */\n  readonly credentials: string\n  /** Redacted Partner token placeholder, or unauthorized state. */\n  readonly authorization: string\n  /** Whether this client currently has Partner authorization state. */\n  readonly authorized: boolean\n  /** Current default URL guard suffixes, or null when a custom transport owns guarding. */\n  readonly urlGuardAllowedSuffixes: readonly string[] | null\n}\n\n/**\n * High-level Computer Backup API client for listing and deleting backup records.\n *\n * The client uses Partner authorization and the `backupApiUrl` returned by\n * `authorizePartner`. The target account must belong to a group with\n * Enterprise Controls enabled, and the caller must be a group admin. Deleting\n * a backup also requires the Enterprise Controls setting that permits admins\n * to delete member backups.\n *\n * @example\n * ```ts\n * const backup = new BackupClient({\n *   masterKeyId: process.env.B2_MASTER_KEY_ID,\n *   masterKey: process.env.B2_MASTER_KEY,\n * })\n * await backup.authorize()\n * for await (const computer of backup.paginateComputers()) {\n *   console.log(computer.computerName)\n * }\n * ```\n *\n * @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.\n */\nexport class BackupClient {\n  /** Low-level client for direct Computer Backup API calls. */\n  readonly raw: BackupRawClient\n  /** Partner authorization state storage (tokens, URLs, capabilities). */\n  readonly partnerAccountInfo: PartnerAccountInfo\n  /**\n   * SSRF allow-list applied by the default transport. `null` when\n   * a custom transport was supplied; in that case the SDK does not own the\n   * guard.\n   */\n  readonly urlGuard: UrlGuard | null\n  private readonly authCore: PartnerAuthCore\n\n  /**\n   * Creates a new BackupClient. Call {@link authorize} before making API requests\n   * unless `partnerAccountInfo` already contains valid Partner authorization.\n   *\n   * @param options - Configuration including credentials, realm, and transport settings.\n   */\n  constructor(options: BackupClientOptions) {\n    this.authCore = new PartnerAuthCore(options)\n    this.partnerAccountInfo = this.authCore.partnerAccountInfo\n    this.urlGuard = this.authCore.urlGuard\n    this.raw = new BackupRawClient({\n      transport: this.authCore.transport,\n      ...(this.authCore.cachedEndpointSuffixes !== undefined\n        ? { authorizedBackupEndpointSuffixes: this.authCore.cachedEndpointSuffixes }\n        : {}),\n    })\n  }\n\n  /**\n   * Authenticates with B2 Partner authorization and stores the authorization state.\n   *\n   * @param options - Optional abort signal.\n   *\n   * @returns The Partner authorization response containing tokens, URLs, and capabilities.\n   *\n   * @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.\n   */\n  async authorize(options?: BackupAuthorizeOptions): Promise<PartnerAuthorizeResponse> {\n    const auth = await this.authCore.authorize(options)\n    this.raw.setAuthorizedEndpointSuffixes(this.authCore.activateEndpointSuffixes(auth))\n    return auth\n  }\n\n  /**\n   * Lists active Computer Backup records for an account.\n   *\n   * @param options - Optional target account and pagination settings.\n   *\n   * @returns A normalized page of computer backup records with an optional continuation cursor.\n   *\n   * @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.\n   */\n  async listComputers(options?: ListComputersOptions): Promise<ListComputersResult> {\n    const auth = this.ensureBackupAuthorization()\n    const { backupApiUrl, authToken, accountId } = this.backupCoordinates(auth, options?.accountId)\n    const response = await this.raw.listComputers(\n      backupApiUrl,\n      authToken,\n      {\n        accountId,\n        ...(options?.startComputerId !== undefined\n          ? { startComputerId: options.startComputerId }\n          : {}),\n        ...(options?.pageSize !== undefined ? { maxComputerCount: options.pageSize } : {}),\n      },\n      options?.signal !== undefined ? { signal: options.signal } : undefined,\n    )\n    return normalizeListComputersResponse(response)\n  }\n\n  /**\n   * Async iterator that yields every active Computer Backup record for an account.\n   *\n   * @param options - Optional target account, page size, and abort signal.\n   *\n   * @returns An async iterable of {@link ComputerBackup} entries.\n   *\n   * @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.\n   */\n  paginateComputers(options?: PaginateComputersOptions): AsyncIterableIterator<ComputerBackup> {\n    return paginateItems(\n      async (cursor: ComputerId | undefined) => {\n        const resp = await this.listComputers({\n          ...(options?.accountId !== undefined ? { accountId: options.accountId } : {}),\n          ...(options?.pageSize !== undefined ? { pageSize: options.pageSize } : {}),\n          ...(cursor !== undefined ? { startComputerId: cursor } : {}),\n          ...(options?.signal !== undefined ? { signal: options.signal } : {}),\n        })\n        return { page: resp, nextCursor: resp.nextComputerId ?? undefined }\n      },\n      (page) => page.computers,\n      options?.signal,\n    )\n  }\n\n  /**\n   * Deletes a Computer Backup record.\n   *\n   * This destructive mutation is not automatically retried or reauthorized in\n   * place; callers should reconcile backup state before issuing a new delete\n   * after an ambiguous failure.\n   *\n   * @param options - Target account, computer ID, and optional abort signal.\n   *\n   * @returns The deleted computer backup record array.\n   *\n   * @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.\n   */\n  async deleteComputer(options: DeleteComputerOptions): Promise<DeleteComputerResponse> {\n    const auth = this.ensureBackupAuthorization()\n    const { backupApiUrl, authToken, accountId } = this.backupCoordinates(auth, options.accountId)\n    return this.raw.deleteComputer(\n      backupApiUrl,\n      authToken,\n      {\n        accountId,\n        computerId: options.computerId,\n      },\n      options.signal !== undefined ? { signal: options.signal } : undefined,\n    )\n  }\n\n  private ensureBackupAuthorization(): PartnerAuthorizeResponse {\n    const auth = this.partnerAccountInfo.getAuth()\n    if (auth === null) {\n      throw new B2PartnerAuthorizationError('Not authorized. Call BackupClient.authorize() first.')\n    }\n    const suffixes = this.authCore.activateEndpointSuffixes(auth)\n    this.raw.setAuthorizedEndpointSuffixes(suffixes)\n    return auth\n  }\n\n  private backupCoordinates(\n    auth: PartnerAuthorizeResponse,\n    accountIdOverride: AccountId | undefined,\n  ): BackupCoordinates {\n    const backupApiUrl = auth.apiInfo.backupApi?.backupApiUrl\n    if (backupApiUrl === undefined) {\n      throw new B2PartnerAuthorizationError(\n        'Computer Backup API is not available; Partner authorization did not return apiInfo.backupApi.',\n      )\n    }\n    return {\n      backupApiUrl,\n      authToken: auth.authorizationToken,\n      accountId: accountIdOverride ?? auth.accountId,\n    }\n  }\n\n  /**\n   * Hides credentials and Partner tokens from `JSON.stringify(client)`.\n   *\n   * @returns A redacted diagnostic object.\n   */\n  toJSON(): BackupClientJson {\n    return {\n      type: 'BackupClient',\n      credentials: MASTER_KEY_REDACTED,\n      authorization:\n        this.partnerAccountInfo.getAuth() === null ? '[unauthorized]' : PARTNER_TOKEN_REDACTED,\n      authorized: this.partnerAccountInfo.getAuth() !== null,\n      urlGuardAllowedSuffixes: this.urlGuard?.getAllowedSuffixes() ?? null,\n    }\n  }\n\n  /**\n   * Hides credentials and Partner tokens from default stringification.\n   *\n   * @returns A short redacted label.\n   */\n  toString(): string {\n    return `[BackupClient ${MASTER_KEY_REDACTED}]`\n  }\n\n  /**\n   * Hides credentials and Partner tokens from Node's `util.inspect`.\n   *\n   * @returns A short redacted label.\n   */\n  [Symbol.for('nodejs.util.inspect.custom')](): string {\n    return this.toString()\n  }\n}\n"],"mappings":"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"}

package/dist/backup/client.d.cts

@@ -0,0 +1,238 @@
+import { RetryOptions } from '../http/retry.js';
+import { HttpTransport } from '../http/transport.js';
+import { UrlGuard } from '../http/url-guard.js';
+import { PartnerAccountInfo } from '../partner/account-info.js';
+import { ComputerBackup, DeleteComputerResponse, ListComputersResult } from '../types/backup.js';
+import { AccountId, ComputerId } from '../types/ids.js';
+import { PartnerAuthorizeResponse } from '../types/partner.js';
+import { BackupRawClient } from './raw.js';
+/**
+ * Configuration options for creating a {@link BackupClient}.
+ *
+ * @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.
+ */
+export interface BackupClientOptions {
+    /** The Master Application Key ID for the partner administrator account. */
+    readonly masterKeyId: string;
+    /** The Master Application Key secret. */
+    readonly masterKey: string;
+    /**
+     * B2 realm to authenticate against. Accepts a known realm-map key
+     * (`"production"` or `"staging"`) or a direct base URL. Custom HTTPS hosts
+     * and loopback IP literal HTTP URLs for local testing are trusted with the
+     * Master Application Key during Partner authorize, so never derive `realm`
+     * from untrusted input. Defaults to `"production"`.
+     */
+    readonly realm?: string;
+    /**
+     * Shared Partner authorization state. Defaults to
+     * {@link InMemoryPartnerAccountInfo}. Pass the same store to
+     * {@link BackupClient} and Partner clients when both surfaces should reuse
+     * one Partner token. Cached authorization whose endpoints fail this client's
+     * realm policy is ignored locally until `authorize()` replaces it; shared
+     * stores are not cleared during construction.
+     */
+    readonly partnerAccountInfo?: PartnerAccountInfo;
+    /** Custom HTTP transport. Defaults to `FetchTransport`. Wrapped by `RetryTransport`. */
+    readonly transport?: HttpTransport;
+    /** Override retry behavior (max retries, backoff, and per-attempt timeout). */
+    readonly retry?: Partial<RetryOptions>;
+    /** Custom user-agent string prepended to the SDK default. */
+    readonly userAgent?: string;
+    /**
+     * Additional SSRF allow-list host suffixes for the default transport.
+     *
+     * Only consulted when {@link BackupClientOptions.transport} is unset; a
+     * custom transport is the user's responsibility to harden.
+     */
+    readonly additionalAllowedHostSuffixes?: readonly string[];
+    /**
+     * Explicitly disable the default SSRF guard after authorize.
+     *
+     * Intended only for controlled simulator/private-proxy tests. Never enable
+     * it for URLs derived from untrusted input or production credentials.
+     */
+    readonly disableSsrfGuard?: boolean;
+    /**
+     * Follow same-origin GET/HEAD redirects in the default fetch transport after
+     * checking each target with the SSRF guard. POST redirects remain blocked.
+     * Defaults to true.
+     */
+    readonly followSameOriginRedirects?: boolean;
+    /**
+     * Allow direct custom authorize realms for tests or private proxies.
+     * Leave disabled unless the configured host is trusted with the Master
+     * Application Key.
+     */
+    readonly allowCustomAuthorizeRealm?: boolean;
+}
+/**
+ * Options for Partner authorization performed by {@link BackupClient}.
+ *
+ * @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.
+ */
+export interface BackupAuthorizeOptions {
+    /** Abort signal for cancelling the authorize request. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Options for listing Computer Backup records.
+ *
+ * @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.
+ */
+export interface ListComputersOptions {
+    /**
+     * Account whose active computer backups should be listed. Defaults to the
+     * partner administrator account ID from authorization.
+     */
+    readonly accountId?: AccountId;
+    /** Computer ID to start listing from for pagination. */
+    readonly startComputerId?: ComputerId;
+    /** Maximum computers to return in this page. Forwarded to `maxComputerCount`. */
+    readonly pageSize?: number;
+    /** Abort signal for cancelling the request. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Options for paginating Computer Backup records.
+ *
+ * @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.
+ */
+export interface PaginateComputersOptions extends Omit<ListComputersOptions, 'startComputerId'> {
+    /**
+     * Aborts the iteration between page fetches. The signal is also forwarded to
+     * each underlying list request.
+     */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Options for deleting a Computer Backup record.
+ *
+ * @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.
+ */
+export interface DeleteComputerOptions {
+    /**
+     * Account that owns the computer backup. Defaults to the partner
+     * administrator account ID from authorization.
+     */
+    readonly accountId?: AccountId;
+    /** Computer ID of the backup to delete. */
+    readonly computerId: ComputerId;
+    /** Abort signal for cancelling the request. */
+    readonly signal?: AbortSignal;
+}
+/** Redacted JSON diagnostic shape emitted by {@link BackupClient.toJSON}. */
+export interface BackupClientJson {
+    /** Object kind for log consumers. */
+    readonly type: 'BackupClient';
+    /** Redacted Master Application Key credential placeholder. */
+    readonly credentials: string;
+    /** Redacted Partner token placeholder, or unauthorized state. */
+    readonly authorization: string;
+    /** Whether this client currently has Partner authorization state. */
+    readonly authorized: boolean;
+    /** Current default URL guard suffixes, or null when a custom transport owns guarding. */
+    readonly urlGuardAllowedSuffixes: readonly string[] | null;
+}
+/**
+ * High-level Computer Backup API client for listing and deleting backup records.
+ *
+ * The client uses Partner authorization and the `backupApiUrl` returned by
+ * `authorizePartner`. The target account must belong to a group with
+ * Enterprise Controls enabled, and the caller must be a group admin. Deleting
+ * a backup also requires the Enterprise Controls setting that permits admins
+ * to delete member backups.
+ *
+ * @example
+ * ```ts
+ * const backup = new BackupClient({
+ *   masterKeyId: process.env.B2_MASTER_KEY_ID,
+ *   masterKey: process.env.B2_MASTER_KEY,
+ * })
+ * await backup.authorize()
+ * for await (const computer of backup.paginateComputers()) {
+ *   console.log(computer.computerName)
+ * }
+ * ```
+ *
+ * @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.
+ */
+export declare class BackupClient {
+    /** Low-level client for direct Computer Backup API calls. */
+    readonly raw: BackupRawClient;
+    /** Partner authorization state storage (tokens, URLs, capabilities). */
+    readonly partnerAccountInfo: PartnerAccountInfo;
+    /**
+     * SSRF allow-list applied by the default transport. `null` when
+     * a custom transport was supplied; in that case the SDK does not own the
+     * guard.
+     */
+    readonly urlGuard: UrlGuard | null;
+    private readonly authCore;
+    /**
+     * Creates a new BackupClient. Call {@link authorize} before making API requests
+     * unless `partnerAccountInfo` already contains valid Partner authorization.
+     *
+     * @param options - Configuration including credentials, realm, and transport settings.
+     */
+    constructor(options: BackupClientOptions);
+    /**
+     * Authenticates with B2 Partner authorization and stores the authorization state.
+     *
+     * @param options - Optional abort signal.
+     *
+     * @returns The Partner authorization response containing tokens, URLs, and capabilities.
+     *
+     * @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.
+     */
+    authorize(options?: BackupAuthorizeOptions): Promise<PartnerAuthorizeResponse>;
+    /**
+     * Lists active Computer Backup records for an account.
+     *
+     * @param options - Optional target account and pagination settings.
+     *
+     * @returns A normalized page of computer backup records with an optional continuation cursor.
+     *
+     * @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.
+     */
+    listComputers(options?: ListComputersOptions): Promise<ListComputersResult>;
+    /**
+     * Async iterator that yields every active Computer Backup record for an account.
+     *
+     * @param options - Optional target account, page size, and abort signal.
+     *
+     * @returns An async iterable of {@link ComputerBackup} entries.
+     *
+     * @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.
+     */
+    paginateComputers(options?: PaginateComputersOptions): AsyncIterableIterator<ComputerBackup>;
+    /**
+     * Deletes a Computer Backup record.
+     *
+     * This destructive mutation is not automatically retried or reauthorized in
+     * place; callers should reconcile backup state before issuing a new delete
+     * after an ambiguous failure.
+     *
+     * @param options - Target account, computer ID, and optional abort signal.
+     *
+     * @returns The deleted computer backup record array.
+     *
+     * @experimental Computer Backup API surface; shape may change as the Backup API docs evolve.
+     */
+    deleteComputer(options: DeleteComputerOptions): Promise<DeleteComputerResponse>;
+    private ensureBackupAuthorization;
+    private backupCoordinates;
+    /**
+     * Hides credentials and Partner tokens from `JSON.stringify(client)`.
+     *
+     * @returns A redacted diagnostic object.
+     */
+    toJSON(): BackupClientJson;
+    /**
+     * Hides credentials and Partner tokens from default stringification.
+     *
+     * @returns A short redacted label.
+     */
+    toString(): string;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/backup/client.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/backup/client.js"],"names":[],"mappings":"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"}