@backblaze-labs/b2-sdk 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,222 @@
+import { AccountInfo } from './auth/account-info.js';
+import { Bucket } from './bucket.js';
+import { RetryOptions } from './http/retry.js';
+import { HttpTransport } from './http/transport.js';
+import { UrlGuard } from './http/url-guard.js';
+import { RawClient } from './raw/index.js';
+import { AuthorizeAccountResponse, Capability } from './types/auth.js';
+import { BucketInfo, BucketType, CorsRule, LifecycleRule, BucketRetentionPolicy } from './types/bucket.js';
+import { EncryptionSetting } from './types/encryption.js';
+import { ApplicationKeyId, BucketId } from './types/ids.js';
+import { ApplicationKey, FullApplicationKey, ListKeysResponse } from './types/key.js';
+import { ReplicationConfiguration } from './types/replication.js';
+import { PaginatorOptions } from './util/paginator.js';
+/** Result of {@link B2Client.hasCapabilities}. */
+export interface CapabilityCheckResult {
+    /** `true` when the key carries every requested capability. */
+    readonly ok: boolean;
+    /** Capabilities the call requested that the current key does not hold. Empty when `ok` is `true`. */
+    readonly missing: readonly Capability[];
+}
+/** Configuration options for creating a {@link B2Client}. */
+export interface B2ClientOptions {
+    /** The application key ID from the B2 dashboard or `b2_create_key`. */
+    readonly applicationKeyId: string;
+    /** The application key secret. */
+    readonly applicationKey: string;
+    /** B2 realm to authenticate against. Defaults to `"production"`. */
+    readonly realm?: string;
+    /** Storage backend for authorization state. Defaults to {@link InMemoryAccountInfo}. */
+    readonly accountInfo?: AccountInfo;
+    /** Custom HTTP transport. Defaults to {@link FetchTransport}. Wrapped by {@link RetryTransport}. */
+    readonly transport?: HttpTransport;
+    /** Override retry behavior (max retries, backoff, jitter). */
+    readonly retry?: Partial<RetryOptions>;
+    /** Custom user-agent string prepended to the SDK default. */
+    readonly userAgent?: string;
+    /**
+     * Override the SSRF allow-list. By default the SDK locks the
+     * {@link FetchTransport} to host suffixes derived from the realm's authorize
+     * response (e.g. `backblazeb2.com`, `backblaze.com`) so a compromised B2
+     * endpoint cannot redirect the SDK to internal services. Pass an explicit
+     * list to add hosts (e.g. when testing against a self-hosted proxy) or set
+     * to an empty array to disable the guard entirely (not recommended).
+     *
+     * Only consulted when {@link B2ClientOptions.transport} is unset; a custom
+     * transport is the user's responsibility to harden.
+     */
+    readonly allowedHostSuffixes?: readonly string[];
+}
+/**
+ * High-level B2 client providing ergonomic access to buckets, files, and keys.
+ *
+ * @example
+ * ```ts
+ * const client = new B2Client({
+ *   applicationKeyId: process.env.B2_APPLICATION_KEY_ID,
+ *   applicationKey: process.env.B2_APPLICATION_KEY,
+ * })
+ * await client.authorize()
+ * const buckets = await client.listBuckets()
+ * ```
+ */
+export declare class B2Client {
+    /** Low-level client for direct B2 API calls. */
+    readonly raw: RawClient;
+    /** Authorization state storage (tokens, URLs, capabilities). */
+    readonly accountInfo: AccountInfo;
+    /**
+     * SSRF allow-list applied by the default {@link FetchTransport}. `null` when
+     * a custom transport was supplied — in that case the SDK does not own the
+     * guard. Locked down by {@link B2Client.authorize}.
+     */
+    readonly urlGuard: UrlGuard | null;
+    private readonly applicationKeyId;
+    private readonly applicationKey;
+    private readonly realmUrl;
+    private readonly userAllowedSuffixes;
+    /**
+     * Creates a new B2Client. Call {@link authorize} before making API requests.
+     * @param options - Configuration including credentials, realm, and transport settings.
+     */
+    constructor(options: B2ClientOptions);
+    /**
+     * Authenticates with B2 and stores the authorization state. Must be called before other methods.
+     *
+     * @returns The authorization response containing tokens, URLs, and capabilities.
+     */
+    authorize(): Promise<AuthorizeAccountResponse>;
+    /**
+     * Refresh credentials after a 401. Returns the fresh auth token so
+     * {@link RetryTransport} can rewrite the in-flight request's
+     * Authorization header before retrying.
+     *
+     * @returns The fresh authorization token.
+     */
+    private reauthorize;
+    /**
+     * Creates a new B2 bucket.
+     * @param options - Bucket configuration including name, type, and optional settings.
+     *
+     * @returns A {@link Bucket} handle for the newly created bucket.
+     */
+    createBucket(options: {
+        /** Globally unique bucket name (6-50 chars, letters, digits, hyphens). */
+        bucketName: string;
+        /** Access level: `"allPrivate"` or `"allPublic"`. */
+        bucketType: BucketType;
+        /** Custom key-value metadata stored with the bucket. */
+        bucketInfo?: Record<string, string>;
+        /** CORS rules for browser-based access. */
+        corsRules?: CorsRule[];
+        /** Default server-side encryption for new files. */
+        defaultServerSideEncryption?: EncryptionSetting;
+        /** Default retention policy for new files (requires file lock). */
+        defaultRetention?: BucketRetentionPolicy;
+        /** Enable file lock (Object Lock) on the bucket. Cannot be disabled once set. */
+        fileLockEnabled?: boolean;
+        /** Lifecycle rules for automatic file deletion or hiding. */
+        lifecycleRules?: LifecycleRule[];
+        /** Cross-region replication configuration. */
+        replicationConfiguration?: ReplicationConfiguration;
+    }): Promise<Bucket>;
+    /**
+     * Lists buckets in the account, optionally filtered by ID, name, or type.
+     * @param options - Optional filters for bucket ID, name, or type.
+     *
+     * @returns An array of {@link Bucket} handles.
+     */
+    listBuckets(options?: {
+        /** Filter to a specific bucket by ID. */
+        bucketId?: BucketId;
+        /** Filter to a specific bucket by name. */
+        bucketName?: string;
+        /** Filter by bucket types (e.g., `["allPrivate"]`). */
+        bucketTypes?: BucketType[];
+    }): Promise<Bucket[]>;
+    /**
+     * Looks up a single bucket by name.
+     * @param bucketName - The name of the bucket to find.
+     *
+     * @returns The {@link Bucket} handle, or `null` if not found.
+     */
+    getBucket(bucketName: string): Promise<Bucket | null>;
+    /**
+     * Permanently deletes a bucket. The bucket must be empty.
+     * @param id - The unique identifier of the bucket to delete.
+     *
+     * @returns The deleted bucket metadata.
+     */
+    deleteBucket(id: BucketId): Promise<BucketInfo>;
+    /**
+     * Creates a new application key with the specified capabilities.
+     * @param options - Key configuration including capabilities, name, and optional restrictions.
+     *
+     * @returns The full key including the secret (only returned at creation time).
+     */
+    createKey(options: {
+        /** Capabilities to grant (e.g., `["readFiles", "writeFiles"]`). */
+        capabilities: Capability[];
+        /** Human-readable name for the key. */
+        keyName: string;
+        /** Key expiration in seconds from now. Omit for non-expiring keys. */
+        validDurationInSeconds?: number;
+        /** Restrict the key to a single bucket. */
+        bucketId?: BucketId;
+        /** Restrict the key to files with this name prefix. */
+        namePrefix?: string;
+    }): Promise<FullApplicationKey>;
+    /**
+     * Lists application keys in the account.
+     * @param options - Optional pagination settings.
+     *
+     * @returns A page of application keys with an optional continuation token.
+     */
+    listKeys(options?: {
+        /**
+         * Maximum number of keys to return per request. Forwarded to the
+         * raw API's `maxKeyCount` parameter.
+         */
+        pageSize?: number;
+        /** Start listing after this key ID (for pagination). */
+        startApplicationKeyId?: ApplicationKeyId;
+    }): Promise<ListKeysResponse>;
+    /**
+     * Async iterator that yields every application key on the account,
+     * automatically handling pagination via `listKeys`.
+     *
+     * @param options - Pagination + abort options. `pageSize` is forwarded
+     *   to `maxKeyCount`; the default is 1000.
+     *
+     * @returns An async iterable of {@link ApplicationKey} entries.
+     *
+     * @example
+     * ```ts
+     * for await (const key of client.paginateKeys()) {
+     *   console.log(key.keyName, key.capabilities)
+     * }
+     * ```
+     */
+    paginateKeys(options?: PaginatorOptions): AsyncIterableIterator<ApplicationKey>;
+    /**
+     * Permanently deletes an application key.
+     * @param applicationKeyId - The unique identifier of the key to delete.
+     *
+     * @returns The deleted application key metadata.
+     */
+    deleteKey(applicationKeyId: ApplicationKeyId): Promise<ApplicationKey>;
+    /**
+     * Checks whether the authorized application key carries every capability in
+     * `needed`. Returns the missing capabilities so callers can fail fast with a
+     * clear error instead of a generic 401/403 from the server.
+     *
+     * @param needed - The capabilities required by the planned operation.
+     *
+     * @returns An object with `ok: true` when every needed capability is
+     *   present, otherwise `{ ok: false, missing: [...] }`.
+     *
+     * @throws If {@link authorize} has not been called yet.
+     */
+    hasCapabilities(needed: readonly Capability[]): CapabilityCheckResult;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -0,0 +1,230 @@
+import { InMemoryAccountInfo } from "./auth/in-memory.js";
+import { getRealmUrl } from "./auth/realms.js";
+import { Bucket } from "./bucket.js";
+import { FetchTransport, RetryTransport } from "./http/transport.js";
+import { UrlGuard, deriveAllowedSuffixes } from "./http/url-guard.js";
+import { RawClient } from "./raw/index.js";
+import { accountId } from "./types/ids.js";
+import { DEFAULT_PAGE_SIZE } from "./util/defaults.js";
+import { paginateItems } from "./util/paginator.js";
+class B2Client {
+  /** Low-level client for direct B2 API calls. */
+  raw;
+  /** Authorization state storage (tokens, URLs, capabilities). */
+  accountInfo;
+  /**
+   * SSRF allow-list applied by the default {@link FetchTransport}. `null` when
+   * a custom transport was supplied — in that case the SDK does not own the
+   * guard. Locked down by {@link B2Client.authorize}.
+   */
+  urlGuard;
+  applicationKeyId;
+  applicationKey;
+  realmUrl;
+  userAllowedSuffixes;
+  /**
+   * Creates a new B2Client. Call {@link authorize} before making API requests.
+   * @param options - Configuration including credentials, realm, and transport settings.
+   */
+  constructor(options) {
+    this.applicationKeyId = options.applicationKeyId;
+    this.applicationKey = options.applicationKey;
+    this.realmUrl = getRealmUrl(options.realm ?? "production");
+    this.accountInfo = options.accountInfo ?? new InMemoryAccountInfo();
+    this.userAllowedSuffixes = options.allowedHostSuffixes;
+    let baseTransport;
+    if (options.transport !== void 0) {
+      baseTransport = options.transport;
+      this.urlGuard = null;
+    } else {
+      const urlGuard = new UrlGuard();
+      baseTransport = new FetchTransport({
+        urlGuard,
+        ...options.userAgent !== void 0 ? { userAgent: options.userAgent } : {}
+      });
+      this.urlGuard = urlGuard;
+    }
+    const retryTransport = new RetryTransport({
+      transport: baseTransport,
+      ...options.retry !== void 0 ? { retry: options.retry } : {},
+      onReauth: () => this.reauthorize()
+    });
+    this.raw = new RawClient({ transport: retryTransport });
+  }
+  /**
+   * Authenticates with B2 and stores the authorization state. Must be called before other methods.
+   *
+   * @returns The authorization response containing tokens, URLs, and capabilities.
+   */
+  async authorize() {
+    const auth = await this.raw.authorizeAccount(
+      this.applicationKeyId,
+      this.applicationKey,
+      this.realmUrl
+    );
+    this.accountInfo.setAuth(auth);
+    if (this.urlGuard !== null) {
+      const derived = deriveAllowedSuffixes(auth.apiInfo.storageApi);
+      const merged = this.userAllowedSuffixes !== void 0 ? Array.from(/* @__PURE__ */ new Set([...derived, ...this.userAllowedSuffixes])) : derived;
+      this.urlGuard.setAllowedSuffixes(merged);
+    }
+    return auth;
+  }
+  /**
+   * Refresh credentials after a 401. Returns the fresh auth token so
+   * {@link RetryTransport} can rewrite the in-flight request's
+   * Authorization header before retrying.
+   *
+   * @returns The fresh authorization token.
+   */
+  async reauthorize() {
+    this.accountInfo.clear();
+    const auth = await this.authorize();
+    return auth.authorizationToken;
+  }
+  /**
+   * Creates a new B2 bucket.
+   * @param options - Bucket configuration including name, type, and optional settings.
+   *
+   * @returns A {@link Bucket} handle for the newly created bucket.
+   */
+  async createBucket(options) {
+    const request = {
+      accountId: accountId(this.accountInfo.getAccountId()),
+      ...options
+    };
+    const info = await this.raw.createBucket(
+      this.accountInfo.getApiUrl(),
+      this.accountInfo.getAuthToken(),
+      request
+    );
+    return new Bucket(this, info);
+  }
+  /**
+   * Lists buckets in the account, optionally filtered by ID, name, or type.
+   * @param options - Optional filters for bucket ID, name, or type.
+   *
+   * @returns An array of {@link Bucket} handles.
+   */
+  async listBuckets(options) {
+    const resp = await this.raw.listBuckets(
+      this.accountInfo.getApiUrl(),
+      this.accountInfo.getAuthToken(),
+      {
+        accountId: accountId(this.accountInfo.getAccountId()),
+        ...options
+      }
+    );
+    return resp.buckets.map((info) => new Bucket(this, info));
+  }
+  /**
+   * Looks up a single bucket by name.
+   * @param bucketName - The name of the bucket to find.
+   *
+   * @returns The {@link Bucket} handle, or `null` if not found.
+   */
+  async getBucket(bucketName) {
+    const buckets = await this.listBuckets({ bucketName });
+    return buckets[0] ?? null;
+  }
+  /**
+   * Permanently deletes a bucket. The bucket must be empty.
+   * @param id - The unique identifier of the bucket to delete.
+   *
+   * @returns The deleted bucket metadata.
+   */
+  async deleteBucket(id) {
+    return this.raw.deleteBucket(this.accountInfo.getApiUrl(), this.accountInfo.getAuthToken(), {
+      accountId: accountId(this.accountInfo.getAccountId()),
+      bucketId: id
+    });
+  }
+  /**
+   * Creates a new application key with the specified capabilities.
+   * @param options - Key configuration including capabilities, name, and optional restrictions.
+   *
+   * @returns The full key including the secret (only returned at creation time).
+   */
+  async createKey(options) {
+    return this.raw.createKey(this.accountInfo.getApiUrl(), this.accountInfo.getAuthToken(), {
+      accountId: accountId(this.accountInfo.getAccountId()),
+      ...options
+    });
+  }
+  /**
+   * Lists application keys in the account.
+   * @param options - Optional pagination settings.
+   *
+   * @returns A page of application keys with an optional continuation token.
+   */
+  async listKeys(options) {
+    return this.raw.listKeys(this.accountInfo.getApiUrl(), this.accountInfo.getAuthToken(), {
+      accountId: accountId(this.accountInfo.getAccountId()),
+      ...options?.pageSize !== void 0 ? { maxKeyCount: options.pageSize } : {},
+      ...options?.startApplicationKeyId !== void 0 ? { startApplicationKeyId: options.startApplicationKeyId } : {}
+    });
+  }
+  /**
+   * Async iterator that yields every application key on the account,
+   * automatically handling pagination via `listKeys`.
+   *
+   * @param options - Pagination + abort options. `pageSize` is forwarded
+   *   to `maxKeyCount`; the default is 1000.
+   *
+   * @returns An async iterable of {@link ApplicationKey} entries.
+   *
+   * @example
+   * ```ts
+   * for await (const key of client.paginateKeys()) {
+   *   console.log(key.keyName, key.capabilities)
+   * }
+   * ```
+   */
+  paginateKeys(options) {
+    return paginateItems(
+      async (cursor) => {
+        const resp = await this.listKeys({
+          pageSize: options?.pageSize ?? DEFAULT_PAGE_SIZE,
+          ...cursor !== void 0 ? { startApplicationKeyId: cursor } : {}
+        });
+        return { page: resp, nextCursor: resp.nextApplicationKeyId ?? void 0 };
+      },
+      (page) => page.keys,
+      options?.signal
+    );
+  }
+  /**
+   * Permanently deletes an application key.
+   * @param applicationKeyId - The unique identifier of the key to delete.
+   *
+   * @returns The deleted application key metadata.
+   */
+  async deleteKey(applicationKeyId) {
+    return this.raw.deleteKey(this.accountInfo.getApiUrl(), this.accountInfo.getAuthToken(), {
+      applicationKeyId
+    });
+  }
+  /**
+   * Checks whether the authorized application key carries every capability in
+   * `needed`. Returns the missing capabilities so callers can fail fast with a
+   * clear error instead of a generic 401/403 from the server.
+   *
+   * @param needed - The capabilities required by the planned operation.
+   *
+   * @returns An object with `ok: true` when every needed capability is
+   *   present, otherwise `{ ok: false, missing: [...] }`.
+   *
+   * @throws If {@link authorize} has not been called yet.
+   */
+  hasCapabilities(needed) {
+    const auth = this.accountInfo.getAuth();
+    if (!auth) throw new Error("Not authorized. Call authorize() first.");
+    const available = new Set(auth.apiInfo.storageApi.allowed.capabilities);
+    const missing = needed.filter((cap) => !available.has(cap));
+    return { ok: missing.length === 0, missing };
+  }
+}
+export {
+  B2Client
+};
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sources":["../src/client.ts"],"sourcesContent":["import type { AccountInfo } from './auth/account-info.ts'\nimport { InMemoryAccountInfo } from './auth/in-memory.ts'\nimport { getRealmUrl } from './auth/realms.ts'\nimport { Bucket } from './bucket.ts'\nimport type { RetryOptions } from './http/retry.ts'\nimport type { HttpTransport } from './http/transport.ts'\nimport { FetchTransport, RetryTransport } from './http/transport.ts'\nimport { UrlGuard, deriveAllowedSuffixes } from './http/url-guard.ts'\nimport { RawClient } from './raw/index.ts'\nimport type { AuthorizeAccountResponse, Capability } from './types/auth.ts'\nimport type {\n  BucketInfo,\n  BucketType,\n  CorsRule,\n  CreateBucketRequest,\n  LifecycleRule,\n} from './types/bucket.ts'\nimport type { BucketRetentionPolicy } from './types/bucket.ts'\nimport type { EncryptionSetting } from './types/encryption.ts'\nimport type { ApplicationKeyId, BucketId } from './types/ids.ts'\nimport { accountId } from './types/ids.ts'\nimport type { ApplicationKey, FullApplicationKey, ListKeysResponse } from './types/key.ts'\nimport type { ReplicationConfiguration } from './types/replication.ts'\nimport { DEFAULT_PAGE_SIZE } from './util/defaults.ts'\nimport { type PaginatorOptions, paginateItems } from './util/paginator.ts'\n\n/** Result of {@link B2Client.hasCapabilities}. */\nexport interface CapabilityCheckResult {\n  /** `true` when the key carries every requested capability. */\n  readonly ok: boolean\n  /** Capabilities the call requested that the current key does not hold. Empty when `ok` is `true`. */\n  readonly missing: readonly Capability[]\n}\n\n/** Configuration options for creating a {@link B2Client}. */\nexport interface B2ClientOptions {\n  /** The application key ID from the B2 dashboard or `b2_create_key`. */\n  readonly applicationKeyId: string\n  /** The application key secret. */\n  readonly applicationKey: string\n  /** B2 realm to authenticate against. Defaults to `\"production\"`. */\n  readonly realm?: string\n  /** Storage backend for authorization state. Defaults to {@link InMemoryAccountInfo}. */\n  readonly accountInfo?: AccountInfo\n  /** Custom HTTP transport. Defaults to {@link FetchTransport}. Wrapped by {@link RetryTransport}. */\n  readonly transport?: HttpTransport\n  /** Override retry behavior (max retries, backoff, jitter). */\n  readonly retry?: Partial<RetryOptions>\n  /** Custom user-agent string prepended to the SDK default. */\n  readonly userAgent?: string\n  /**\n   * Override the SSRF allow-list. By default the SDK locks the\n   * {@link FetchTransport} to host suffixes derived from the realm's authorize\n   * response (e.g. `backblazeb2.com`, `backblaze.com`) so a compromised B2\n   * endpoint cannot redirect the SDK to internal services. Pass an explicit\n   * list to add hosts (e.g. when testing against a self-hosted proxy) or set\n   * to an empty array to disable the guard entirely (not recommended).\n   *\n   * Only consulted when {@link B2ClientOptions.transport} is unset; a custom\n   * transport is the user's responsibility to harden.\n   */\n  readonly allowedHostSuffixes?: readonly string[]\n}\n\n/**\n * High-level B2 client providing ergonomic access to buckets, files, and keys.\n *\n * @example\n * ```ts\n * const client = new B2Client({\n *   applicationKeyId: process.env.B2_APPLICATION_KEY_ID,\n *   applicationKey: process.env.B2_APPLICATION_KEY,\n * })\n * await client.authorize()\n * const buckets = await client.listBuckets()\n * ```\n */\nexport class B2Client {\n  /** Low-level client for direct B2 API calls. */\n  readonly raw: RawClient\n  /** Authorization state storage (tokens, URLs, capabilities). */\n  readonly accountInfo: AccountInfo\n  /**\n   * SSRF allow-list applied by the default {@link FetchTransport}. `null` when\n   * a custom transport was supplied — in that case the SDK does not own the\n   * guard. Locked down by {@link B2Client.authorize}.\n   */\n  readonly urlGuard: UrlGuard | null\n  private readonly applicationKeyId: string\n  private readonly applicationKey: string\n  private readonly realmUrl: string\n  private readonly userAllowedSuffixes: readonly string[] | undefined\n\n  /**\n   * Creates a new B2Client. Call {@link authorize} before making API requests.\n   * @param options - Configuration including credentials, realm, and transport settings.\n   */\n  constructor(options: B2ClientOptions) {\n    this.applicationKeyId = options.applicationKeyId\n    this.applicationKey = options.applicationKey\n    this.realmUrl = getRealmUrl(options.realm ?? 'production')\n    this.accountInfo = options.accountInfo ?? new InMemoryAccountInfo()\n    this.userAllowedSuffixes = options.allowedHostSuffixes\n\n    let baseTransport: HttpTransport\n    if (options.transport !== undefined) {\n      baseTransport = options.transport\n      this.urlGuard = null\n    } else {\n      const urlGuard = new UrlGuard()\n      baseTransport = new FetchTransport({\n        urlGuard,\n        ...(options.userAgent !== undefined ? { userAgent: options.userAgent } : {}),\n      })\n      this.urlGuard = urlGuard\n    }\n\n    const retryTransport = new RetryTransport({\n      transport: baseTransport,\n      ...(options.retry !== undefined ? { retry: options.retry } : {}),\n      onReauth: () => this.reauthorize(),\n    })\n\n    this.raw = new RawClient({ transport: retryTransport })\n  }\n\n  /**\n   * Authenticates with B2 and stores the authorization state. Must be called before other methods.\n   *\n   * @returns The authorization response containing tokens, URLs, and capabilities.\n   */\n  async authorize(): Promise<AuthorizeAccountResponse> {\n    const auth = await this.raw.authorizeAccount(\n      this.applicationKeyId,\n      this.applicationKey,\n      this.realmUrl,\n    )\n    this.accountInfo.setAuth(auth)\n    // Lock the SSRF guard to the realm's hosts (plus any user additions).\n    // No-op when the caller supplied a custom transport: their threat model.\n    if (this.urlGuard !== null) {\n      const derived = deriveAllowedSuffixes(auth.apiInfo.storageApi)\n      const merged =\n        this.userAllowedSuffixes !== undefined\n          ? Array.from(new Set([...derived, ...this.userAllowedSuffixes]))\n          : derived\n      this.urlGuard.setAllowedSuffixes(merged)\n    }\n    return auth\n  }\n\n  /**\n   * Refresh credentials after a 401. Returns the fresh auth token so\n   * {@link RetryTransport} can rewrite the in-flight request's\n   * Authorization header before retrying.\n   *\n   * @returns The fresh authorization token.\n   */\n  private async reauthorize(): Promise<string> {\n    this.accountInfo.clear()\n    const auth = await this.authorize()\n    return auth.authorizationToken\n  }\n\n  /**\n   * Creates a new B2 bucket.\n   * @param options - Bucket configuration including name, type, and optional settings.\n   *\n   * @returns A {@link Bucket} handle for the newly created bucket.\n   */\n  async createBucket(options: {\n    /** Globally unique bucket name (6-50 chars, letters, digits, hyphens). */\n    bucketName: string\n    /** Access level: `\"allPrivate\"` or `\"allPublic\"`. */\n    bucketType: BucketType\n    /** Custom key-value metadata stored with the bucket. */\n    bucketInfo?: Record<string, string>\n    /** CORS rules for browser-based access. */\n    corsRules?: CorsRule[]\n    /** Default server-side encryption for new files. */\n    defaultServerSideEncryption?: EncryptionSetting\n    /** Default retention policy for new files (requires file lock). */\n    defaultRetention?: BucketRetentionPolicy\n    /** Enable file lock (Object Lock) on the bucket. Cannot be disabled once set. */\n    fileLockEnabled?: boolean\n    /** Lifecycle rules for automatic file deletion or hiding. */\n    lifecycleRules?: LifecycleRule[]\n    /** Cross-region replication configuration. */\n    replicationConfiguration?: ReplicationConfiguration\n  }): Promise<Bucket> {\n    const request: CreateBucketRequest = {\n      accountId: accountId(this.accountInfo.getAccountId()),\n      ...options,\n    }\n    const info = await this.raw.createBucket(\n      this.accountInfo.getApiUrl(),\n      this.accountInfo.getAuthToken(),\n      request,\n    )\n    return new Bucket(this, info)\n  }\n\n  /**\n   * Lists buckets in the account, optionally filtered by ID, name, or type.\n   * @param options - Optional filters for bucket ID, name, or type.\n   *\n   * @returns An array of {@link Bucket} handles.\n   */\n  async listBuckets(options?: {\n    /** Filter to a specific bucket by ID. */\n    bucketId?: BucketId\n    /** Filter to a specific bucket by name. */\n    bucketName?: string\n    /** Filter by bucket types (e.g., `[\"allPrivate\"]`). */\n    bucketTypes?: BucketType[]\n  }): Promise<Bucket[]> {\n    const resp = await this.raw.listBuckets(\n      this.accountInfo.getApiUrl(),\n      this.accountInfo.getAuthToken(),\n      {\n        accountId: accountId(this.accountInfo.getAccountId()),\n        ...options,\n      },\n    )\n    return resp.buckets.map((info) => new Bucket(this, info))\n  }\n\n  /**\n   * Looks up a single bucket by name.\n   * @param bucketName - The name of the bucket to find.\n   *\n   * @returns The {@link Bucket} handle, or `null` if not found.\n   */\n  async getBucket(bucketName: string): Promise<Bucket | null> {\n    const buckets = await this.listBuckets({ bucketName })\n    return buckets[0] ?? null\n  }\n\n  /**\n   * Permanently deletes a bucket. The bucket must be empty.\n   * @param id - The unique identifier of the bucket to delete.\n   *\n   * @returns The deleted bucket metadata.\n   */\n  async deleteBucket(id: BucketId): Promise<BucketInfo> {\n    return this.raw.deleteBucket(this.accountInfo.getApiUrl(), this.accountInfo.getAuthToken(), {\n      accountId: accountId(this.accountInfo.getAccountId()),\n      bucketId: id,\n    })\n  }\n\n  /**\n   * Creates a new application key with the specified capabilities.\n   * @param options - Key configuration including capabilities, name, and optional restrictions.\n   *\n   * @returns The full key including the secret (only returned at creation time).\n   */\n  async createKey(options: {\n    /** Capabilities to grant (e.g., `[\"readFiles\", \"writeFiles\"]`). */\n    capabilities: Capability[]\n    /** Human-readable name for the key. */\n    keyName: string\n    /** Key expiration in seconds from now. Omit for non-expiring keys. */\n    validDurationInSeconds?: number\n    /** Restrict the key to a single bucket. */\n    bucketId?: BucketId\n    /** Restrict the key to files with this name prefix. */\n    namePrefix?: string\n  }): Promise<FullApplicationKey> {\n    return this.raw.createKey(this.accountInfo.getApiUrl(), this.accountInfo.getAuthToken(), {\n      accountId: accountId(this.accountInfo.getAccountId()),\n      ...options,\n    })\n  }\n\n  /**\n   * Lists application keys in the account.\n   * @param options - Optional pagination settings.\n   *\n   * @returns A page of application keys with an optional continuation token.\n   */\n  async listKeys(options?: {\n    /**\n     * Maximum number of keys to return per request. Forwarded to the\n     * raw API's `maxKeyCount` parameter.\n     */\n    pageSize?: number\n    /** Start listing after this key ID (for pagination). */\n    startApplicationKeyId?: ApplicationKeyId\n  }): Promise<ListKeysResponse> {\n    return this.raw.listKeys(this.accountInfo.getApiUrl(), this.accountInfo.getAuthToken(), {\n      accountId: accountId(this.accountInfo.getAccountId()),\n      ...(options?.pageSize !== undefined ? { maxKeyCount: options.pageSize } : {}),\n      ...(options?.startApplicationKeyId !== undefined\n        ? { startApplicationKeyId: options.startApplicationKeyId }\n        : {}),\n    })\n  }\n\n  /**\n   * Async iterator that yields every application key on the account,\n   * automatically handling pagination via `listKeys`.\n   *\n   * @param options - Pagination + abort options. `pageSize` is forwarded\n   *   to `maxKeyCount`; the default is 1000.\n   *\n   * @returns An async iterable of {@link ApplicationKey} entries.\n   *\n   * @example\n   * ```ts\n   * for await (const key of client.paginateKeys()) {\n   *   console.log(key.keyName, key.capabilities)\n   * }\n   * ```\n   */\n  paginateKeys(options?: PaginatorOptions): AsyncIterableIterator<ApplicationKey> {\n    return paginateItems(\n      async (cursor: ApplicationKeyId | undefined) => {\n        const resp = await this.listKeys({\n          pageSize: options?.pageSize ?? DEFAULT_PAGE_SIZE,\n          ...(cursor !== undefined ? { startApplicationKeyId: cursor } : {}),\n        })\n        return { page: resp, nextCursor: resp.nextApplicationKeyId ?? undefined }\n      },\n      (page) => page.keys,\n      options?.signal,\n    )\n  }\n\n  /**\n   * Permanently deletes an application key.\n   * @param applicationKeyId - The unique identifier of the key to delete.\n   *\n   * @returns The deleted application key metadata.\n   */\n  async deleteKey(applicationKeyId: ApplicationKeyId): Promise<ApplicationKey> {\n    return this.raw.deleteKey(this.accountInfo.getApiUrl(), this.accountInfo.getAuthToken(), {\n      applicationKeyId,\n    })\n  }\n\n  /**\n   * Checks whether the authorized application key carries every capability in\n   * `needed`. Returns the missing capabilities so callers can fail fast with a\n   * clear error instead of a generic 401/403 from the server.\n   *\n   * @param needed - The capabilities required by the planned operation.\n   *\n   * @returns An object with `ok: true` when every needed capability is\n   *   present, otherwise `{ ok: false, missing: [...] }`.\n   *\n   * @throws If {@link authorize} has not been called yet.\n   */\n  hasCapabilities(needed: readonly Capability[]): CapabilityCheckResult {\n    const auth = this.accountInfo.getAuth()\n    if (!auth) throw new Error('Not authorized. Call authorize() first.')\n    const available = new Set<string>(auth.apiInfo.storageApi.allowed.capabilities)\n    const missing = needed.filter((cap) => !available.has(cap as string))\n    return { ok: missing.length === 0, missing }\n  }\n}\n"],"names":[],"mappings":";;;;;;;;;AA6EO,MAAM,SAAS;AAAA;AAAA,EAEX;AAAA;AAAA,EAEA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA;AAAA,EACQ;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMjB,YAAY,SAA0B;AACpC,SAAK,mBAAmB,QAAQ;AAChC,SAAK,iBAAiB,QAAQ;AAC9B,SAAK,WAAW,YAAY,QAAQ,SAAS,YAAY;AACzD,SAAK,cAAc,QAAQ,eAAe,IAAI,oBAAA;AAC9C,SAAK,sBAAsB,QAAQ;AAEnC,QAAI;AACJ,QAAI,QAAQ,cAAc,QAAW;AACnC,sBAAgB,QAAQ;AACxB,WAAK,WAAW;AAAA,IAClB,OAAO;AACL,YAAM,WAAW,IAAI,SAAA;AACrB,sBAAgB,IAAI,eAAe;AAAA,QACjC;AAAA,QACA,GAAI,QAAQ,cAAc,SAAY,EAAE,WAAW,QAAQ,cAAc,CAAA;AAAA,MAAC,CAC3E;AACD,WAAK,WAAW;AAAA,IAClB;AAEA,UAAM,iBAAiB,IAAI,eAAe;AAAA,MACxC,WAAW;AAAA,MACX,GAAI,QAAQ,UAAU,SAAY,EAAE,OAAO,QAAQ,MAAA,IAAU,CAAA;AAAA,MAC7D,UAAU,MAAM,KAAK,YAAA;AAAA,IAAY,CAClC;AAED,SAAK,MAAM,IAAI,UAAU,EAAE,WAAW,gBAAgB;AAAA,EACxD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,YAA+C;AACnD,UAAM,OAAO,MAAM,KAAK,IAAI;AAAA,MAC1B,KAAK;AAAA,MACL,KAAK;AAAA,MACL,KAAK;AAAA,IAAA;AAEP,SAAK,YAAY,QAAQ,IAAI;AAG7B,QAAI,KAAK,aAAa,MAAM;AAC1B,YAAM,UAAU,sBAAsB,KAAK,QAAQ,UAAU;AAC7D,YAAM,SACJ,KAAK,wBAAwB,SACzB,MAAM,KAAK,oBAAI,IAAI,CAAC,GAAG,SAAS,GAAG,KAAK,mBAAmB,CAAC,CAAC,IAC7D;AACN,WAAK,SAAS,mBAAmB,MAAM;AAAA,IACzC;AACA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAc,cAA+B;AAC3C,SAAK,YAAY,MAAA;AACjB,UAAM,OAAO,MAAM,KAAK,UAAA;AACxB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,aAAa,SAmBC;AAClB,UAAM,UAA+B;AAAA,MACnC,WAAW,UAAU,KAAK,YAAY,cAAc;AAAA,MACpD,GAAG;AAAA,IAAA;AAEL,UAAM,OAAO,MAAM,KAAK,IAAI;AAAA,MAC1B,KAAK,YAAY,UAAA;AAAA,MACjB,KAAK,YAAY,aAAA;AAAA,MACjB;AAAA,IAAA;AAEF,WAAO,IAAI,OAAO,MAAM,IAAI;AAAA,EAC9B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,YAAY,SAOI;AACpB,UAAM,OAAO,MAAM,KAAK,IAAI;AAAA,MAC1B,KAAK,YAAY,UAAA;AAAA,MACjB,KAAK,YAAY,aAAA;AAAA,MACjB;AAAA,QACE,WAAW,UAAU,KAAK,YAAY,cAAc;AAAA,QACpD,GAAG;AAAA,MAAA;AAAA,IACL;AAEF,WAAO,KAAK,QAAQ,IAAI,CAAC,SAAS,IAAI,OAAO,MAAM,IAAI,CAAC;AAAA,EAC1D;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,UAAU,YAA4C;AAC1D,UAAM,UAAU,MAAM,KAAK,YAAY,EAAE,YAAY;AACrD,WAAO,QAAQ,CAAC,KAAK;AAAA,EACvB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,aAAa,IAAmC;AACpD,WAAO,KAAK,IAAI,aAAa,KAAK,YAAY,aAAa,KAAK,YAAY,gBAAgB;AAAA,MAC1F,WAAW,UAAU,KAAK,YAAY,cAAc;AAAA,MACpD,UAAU;AAAA,IAAA,CACX;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,UAAU,SAWgB;AAC9B,WAAO,KAAK,IAAI,UAAU,KAAK,YAAY,aAAa,KAAK,YAAY,gBAAgB;AAAA,MACvF,WAAW,UAAU,KAAK,YAAY,cAAc;AAAA,MACpD,GAAG;AAAA,IAAA,CACJ;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,SAAS,SAQe;AAC5B,WAAO,KAAK,IAAI,SAAS,KAAK,YAAY,aAAa,KAAK,YAAY,gBAAgB;AAAA,MACtF,WAAW,UAAU,KAAK,YAAY,cAAc;AAAA,MACpD,GAAI,SAAS,aAAa,SAAY,EAAE,aAAa,QAAQ,SAAA,IAAa,CAAA;AAAA,MAC1E,GAAI,SAAS,0BAA0B,SACnC,EAAE,uBAAuB,QAAQ,0BACjC,CAAA;AAAA,IAAC,CACN;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBA,aAAa,SAAmE;AAC9E,WAAO;AAAA,MACL,OAAO,WAAyC;AAC9C,cAAM,OAAO,MAAM,KAAK,SAAS;AAAA,UAC/B,UAAU,SAAS,YAAY;AAAA,UAC/B,GAAI,WAAW,SAAY,EAAE,uBAAuB,OAAA,IAAW,CAAA;AAAA,QAAC,CACjE;AACD,eAAO,EAAE,MAAM,MAAM,YAAY,KAAK,wBAAwB,OAAA;AAAA,MAChE;AAAA,MACA,CAAC,SAAS,KAAK;AAAA,MACf,SAAS;AAAA,IAAA;AAAA,EAEb;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,UAAU,kBAA6D;AAC3E,WAAO,KAAK,IAAI,UAAU,KAAK,YAAY,aAAa,KAAK,YAAY,gBAAgB;AAAA,MACvF;AAAA,IAAA,CACD;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAcA,gBAAgB,QAAsD;AACpE,UAAM,OAAO,KAAK,YAAY,QAAA;AAC9B,QAAI,CAAC,KAAM,OAAM,IAAI,MAAM,yCAAyC;AACpE,UAAM,YAAY,IAAI,IAAY,KAAK,QAAQ,WAAW,QAAQ,YAAY;AAC9E,UAAM,UAAU,OAAO,OAAO,CAAC,QAAQ,CAAC,UAAU,IAAI,GAAa,CAAC;AACpE,WAAO,EAAE,IAAI,QAAQ,WAAW,GAAG,QAAA;AAAA,EACrC;AACF;"}

package/dist/copy/large.cjs

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const ids = require("../types/ids.cjs");
+const cancel = require("../upload/cancel.cjs");
+const concurrency = require("../upload/concurrency.cjs");
+const defaults = require("../util/defaults.cjs");
+const planRanges = require("../util/plan-ranges.cjs");
+async function copyLargeFile(raw, accountInfo, options) {
+  const recommendedPartSize = accountInfo.getRecommendedPartSize();
+  const minPartSize = accountInfo.getAbsoluteMinimumPartSize();
+  const partSize = Math.max(options.partSize ?? recommendedPartSize, minPartSize);
+  const concurrency$1 = options.concurrency ?? defaults.DEFAULT_TRANSFER_CONCURRENCY;
+  const sourceInfo = await raw.getFileInfo(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {
+    fileId: options.sourceFileId
+  });
+  const totalSize = sourceInfo.contentLength;
+  if (totalSize <= partSize) {
+    return raw.copyFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {
+      sourceFileId: options.sourceFileId,
+      fileName: options.fileName,
+      ...options.destinationBucketId !== void 0 ? { destinationBucketId: options.destinationBucketId } : {},
+      ...options.contentType !== void 0 ? { contentType: options.contentType } : {},
+      ...options.fileInfo !== void 0 ? { fileInfo: options.fileInfo } : {},
+      ...options.destinationServerSideEncryption !== void 0 ? { destinationServerSideEncryption: options.destinationServerSideEncryption } : {},
+      ...options.sourceServerSideEncryption !== void 0 ? { sourceServerSideEncryption: options.sourceServerSideEncryption } : {}
+    });
+  }
+  const destBucketId = options.destinationBucketId ?? sourceInfo.bucketId;
+  const startResp = await raw.startLargeFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {
+    bucketId: destBucketId,
+    fileName: options.fileName,
+    contentType: options.contentType ?? sourceInfo.contentType ?? defaults.DEFAULT_CONTENT_TYPE,
+    fileInfo: options.fileInfo ?? {},
+    ...options.destinationServerSideEncryption !== void 0 ? { serverSideEncryption: options.destinationServerSideEncryption } : {}
+  });
+  const largeFileId = startResp.fileId;
+  const ranges = planRanges.planRanges(totalSize, partSize);
+  const partSha1s = new Array(ranges.length);
+  const sem = new concurrency.Semaphore(concurrency$1);
+  try {
+    options.signal?.throwIfAborted();
+    await Promise.all(
+      ranges.map(async (range) => {
+        await sem.acquire();
+        try {
+          options.signal?.throwIfAborted();
+          const resp = await raw.copyPart(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {
+            sourceFileId: options.sourceFileId,
+            // `startLargeFile` returns `LargeFileId`; `copyPart` takes the
+            // same value typed as `FileId`. Re-brand via the factory.
+            largeFileId: ids.fileId(largeFileId),
+            partNumber: range.partNumber,
+            range: planRanges.byteRangeHeader(range.start, range.end),
+            ...options.sourceServerSideEncryption !== void 0 ? { sourceServerSideEncryption: options.sourceServerSideEncryption } : {},
+            ...options.destinationServerSideEncryption !== void 0 ? { destinationServerSideEncryption: options.destinationServerSideEncryption } : {}
+          });
+          partSha1s[range.partNumber - 1] = resp.contentSha1;
+        } finally {
+          sem.release();
+        }
+      })
+    );
+    options.signal?.throwIfAborted();
+    return await raw.finishLargeFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {
+      fileId: largeFileId,
+      partSha1Array: partSha1s
+    });
+  } catch (err) {
+    await cancel.cancelLargeFileBestEffort(raw, accountInfo, largeFileId);
+    throw err;
+  }
+}
+exports.copyLargeFile = copyLargeFile;
+//# sourceMappingURL=large.cjs.map

package/dist/copy/large.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"large.cjs","sources":["../../src/copy/large.ts"],"sourcesContent":["import type { AccountInfo } from '../auth/account-info.ts'\nimport type { RawClient } from '../raw/index.ts'\nimport type { EncryptionSetting } from '../types/encryption.ts'\nimport type { FileVersion } from '../types/file.ts'\nimport { type BucketId, type FileId, fileId as fileIdOf } from '../types/ids.ts'\nimport { cancelLargeFileBestEffort } from '../upload/cancel.ts'\nimport { Semaphore } from '../upload/concurrency.ts'\nimport { DEFAULT_CONTENT_TYPE, DEFAULT_TRANSFER_CONCURRENCY } from '../util/defaults.ts'\nimport { byteRangeHeader, planRanges } from '../util/plan-ranges.ts'\n\n/** Options for a server-side multipart copy. */\nexport interface CopyLargeFileOptions {\n  /** ID of the source file version to copy. */\n  readonly sourceFileId: FileId\n  /** Destination file name in the target bucket. */\n  readonly fileName: string\n  /** Target bucket. Defaults to the source's bucket. */\n  readonly destinationBucketId?: BucketId\n  /** Size of each part in bytes. Defaults to the account's recommended part size. */\n  readonly partSize?: number\n  /**\n   * Maximum number of parts copied in parallel. Defaults to\n   * {@link DEFAULT_TRANSFER_CONCURRENCY}.\n   */\n  readonly concurrency?: number\n  /** MIME type for the destination file. Defaults to `b2/x-auto`. */\n  readonly contentType?: string\n  /** Custom file info merged into the destination. */\n  readonly fileInfo?: Record<string, string>\n  /** Server-side encryption applied to the destination. */\n  readonly destinationServerSideEncryption?: EncryptionSetting\n  /** SSE-C settings used to read the source if it was uploaded with SSE-C. */\n  readonly sourceServerSideEncryption?: EncryptionSetting\n  /**\n   * Optional abort signal. Checked before dispatching each part and\n   * between parts; an aborted signal cancels remaining parts and rolls\n   * back the unfinished large file via best-effort `cancelLargeFile`.\n   *\n   * Aborting does NOT roll back parts already accepted by B2; those\n   * exist on the unfinished large file until the cancel call completes\n   * or B2's lifecycle expires the in-progress upload (24 hours).\n   */\n  readonly signal?: AbortSignal\n}\n\n/**\n * Performs a server-side copy of a file using the multipart `b2_copy_part` protocol.\n * The source bytes never traverse the client; B2 copies each range internally.\n *\n * Falls back to a single `copyFile` call when the source fits in one part.\n *\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state (used to resolve API URL, recommended part size).\n * @param options - Copy parameters including source, destination, and concurrency.\n *\n * @returns The resulting destination {@link FileVersion}.\n */\nexport async function copyLargeFile(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  options: CopyLargeFileOptions,\n): Promise<FileVersion> {\n  const recommendedPartSize = accountInfo.getRecommendedPartSize()\n  const minPartSize = accountInfo.getAbsoluteMinimumPartSize()\n  const partSize = Math.max(options.partSize ?? recommendedPartSize, minPartSize)\n  const concurrency = options.concurrency ?? DEFAULT_TRANSFER_CONCURRENCY\n\n  // Discover the source size via getFileInfo.\n  const sourceInfo = await raw.getFileInfo(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {\n    fileId: options.sourceFileId,\n  })\n  const totalSize = sourceInfo.contentLength\n\n  // Below the part threshold, take the single-call fast path.\n  if (totalSize <= partSize) {\n    return raw.copyFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {\n      sourceFileId: options.sourceFileId,\n      fileName: options.fileName,\n      ...(options.destinationBucketId !== undefined\n        ? { destinationBucketId: options.destinationBucketId }\n        : {}),\n      ...(options.contentType !== undefined ? { contentType: options.contentType } : {}),\n      ...(options.fileInfo !== undefined ? { fileInfo: options.fileInfo } : {}),\n      ...(options.destinationServerSideEncryption !== undefined\n        ? { destinationServerSideEncryption: options.destinationServerSideEncryption }\n        : {}),\n      ...(options.sourceServerSideEncryption !== undefined\n        ? { sourceServerSideEncryption: options.sourceServerSideEncryption }\n        : {}),\n    })\n  }\n\n  // Resolve destination bucket (defaults to source's bucket). Both operands\n  // are already typed `BucketId`, so no cast is needed.\n  const destBucketId = options.destinationBucketId ?? sourceInfo.bucketId\n\n  // Start the multipart file.\n  const startResp = await raw.startLargeFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {\n    bucketId: destBucketId,\n    fileName: options.fileName,\n    contentType: options.contentType ?? sourceInfo.contentType ?? DEFAULT_CONTENT_TYPE,\n    fileInfo: options.fileInfo ?? {},\n    ...(options.destinationServerSideEncryption !== undefined\n      ? { serverSideEncryption: options.destinationServerSideEncryption }\n      : {}),\n  })\n  const largeFileId = startResp.fileId\n\n  const ranges = planRanges(totalSize, partSize)\n  const partSha1s: string[] = new Array(ranges.length)\n  const sem = new Semaphore(concurrency)\n\n  try {\n    options.signal?.throwIfAborted()\n    await Promise.all(\n      ranges.map(async (range) => {\n        await sem.acquire()\n        try {\n          // Re-check the abort flag after every queue handoff so the\n          // first cancelled task short-circuits the remaining parts.\n          options.signal?.throwIfAborted()\n          const resp = await raw.copyPart(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {\n            sourceFileId: options.sourceFileId,\n            // `startLargeFile` returns `LargeFileId`; `copyPart` takes the\n            // same value typed as `FileId`. Re-brand via the factory.\n            largeFileId: fileIdOf(largeFileId),\n            partNumber: range.partNumber,\n            range: byteRangeHeader(range.start, range.end),\n            ...(options.sourceServerSideEncryption !== undefined\n              ? { sourceServerSideEncryption: options.sourceServerSideEncryption }\n              : {}),\n            ...(options.destinationServerSideEncryption !== undefined\n              ? { destinationServerSideEncryption: options.destinationServerSideEncryption }\n              : {}),\n          })\n          partSha1s[range.partNumber - 1] = resp.contentSha1\n        } finally {\n          sem.release()\n        }\n      }),\n    )\n\n    options.signal?.throwIfAborted()\n    return await raw.finishLargeFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {\n      fileId: largeFileId,\n      partSha1Array: partSha1s,\n    })\n  } catch (err) {\n    await cancelLargeFileBestEffort(raw, accountInfo, largeFileId)\n    throw err\n  }\n}\n"],"names":["concurrency","DEFAULT_TRANSFER_CONCURRENCY","DEFAULT_CONTENT_TYPE","planRanges","Semaphore","fileIdOf","byteRangeHeader","cancelLargeFileBestEffort"],"mappings":";;;;;;;AAyDA,eAAsB,cACpB,KACA,aACA,SACsB;AACtB,QAAM,sBAAsB,YAAY,uBAAA;AACxC,QAAM,cAAc,YAAY,2BAAA;AAChC,QAAM,WAAW,KAAK,IAAI,QAAQ,YAAY,qBAAqB,WAAW;AAC9E,QAAMA,gBAAc,QAAQ,eAAeC,SAAAA;AAG3C,QAAM,aAAa,MAAM,IAAI,YAAY,YAAY,UAAA,GAAa,YAAY,gBAAgB;AAAA,IAC5F,QAAQ,QAAQ;AAAA,EAAA,CACjB;AACD,QAAM,YAAY,WAAW;AAG7B,MAAI,aAAa,UAAU;AACzB,WAAO,IAAI,SAAS,YAAY,aAAa,YAAY,gBAAgB;AAAA,MACvE,cAAc,QAAQ;AAAA,MACtB,UAAU,QAAQ;AAAA,MAClB,GAAI,QAAQ,wBAAwB,SAChC,EAAE,qBAAqB,QAAQ,oBAAA,IAC/B,CAAA;AAAA,MACJ,GAAI,QAAQ,gBAAgB,SAAY,EAAE,aAAa,QAAQ,YAAA,IAAgB,CAAA;AAAA,MAC/E,GAAI,QAAQ,aAAa,SAAY,EAAE,UAAU,QAAQ,SAAA,IAAa,CAAA;AAAA,MACtE,GAAI,QAAQ,oCAAoC,SAC5C,EAAE,iCAAiC,QAAQ,gCAAA,IAC3C,CAAA;AAAA,MACJ,GAAI,QAAQ,+BAA+B,SACvC,EAAE,4BAA4B,QAAQ,+BACtC,CAAA;AAAA,IAAC,CACN;AAAA,EACH;AAIA,QAAM,eAAe,QAAQ,uBAAuB,WAAW;AAG/D,QAAM,YAAY,MAAM,IAAI,eAAe,YAAY,UAAA,GAAa,YAAY,gBAAgB;AAAA,IAC9F,UAAU;AAAA,IACV,UAAU,QAAQ;AAAA,IAClB,aAAa,QAAQ,eAAe,WAAW,eAAeC,SAAAA;AAAAA,IAC9D,UAAU,QAAQ,YAAY,CAAA;AAAA,IAC9B,GAAI,QAAQ,oCAAoC,SAC5C,EAAE,sBAAsB,QAAQ,oCAChC,CAAA;AAAA,EAAC,CACN;AACD,QAAM,cAAc,UAAU;AAE9B,QAAM,SAASC,WAAAA,WAAW,WAAW,QAAQ;AAC7C,QAAM,YAAsB,IAAI,MAAM,OAAO,MAAM;AACnD,QAAM,MAAM,IAAIC,YAAAA,UAAUJ,aAAW;AAErC,MAAI;AACF,YAAQ,QAAQ,eAAA;AAChB,UAAM,QAAQ;AAAA,MACZ,OAAO,IAAI,OAAO,UAAU;AAC1B,cAAM,IAAI,QAAA;AACV,YAAI;AAGF,kBAAQ,QAAQ,eAAA;AAChB,gBAAM,OAAO,MAAM,IAAI,SAAS,YAAY,UAAA,GAAa,YAAY,gBAAgB;AAAA,YACnF,cAAc,QAAQ;AAAA;AAAA;AAAA,YAGtB,aAAaK,IAAAA,OAAS,WAAW;AAAA,YACjC,YAAY,MAAM;AAAA,YAClB,OAAOC,WAAAA,gBAAgB,MAAM,OAAO,MAAM,GAAG;AAAA,YAC7C,GAAI,QAAQ,+BAA+B,SACvC,EAAE,4BAA4B,QAAQ,2BAAA,IACtC,CAAA;AAAA,YACJ,GAAI,QAAQ,oCAAoC,SAC5C,EAAE,iCAAiC,QAAQ,oCAC3C,CAAA;AAAA,UAAC,CACN;AACD,oBAAU,MAAM,aAAa,CAAC,IAAI,KAAK;AAAA,QACzC,UAAA;AACE,cAAI,QAAA;AAAA,QACN;AAAA,MACF,CAAC;AAAA,IAAA;AAGH,YAAQ,QAAQ,eAAA;AAChB,WAAO,MAAM,IAAI,gBAAgB,YAAY,aAAa,YAAY,gBAAgB;AAAA,MACpF,QAAQ;AAAA,MACR,eAAe;AAAA,IAAA,CAChB;AAAA,EACH,SAAS,KAAK;AACZ,UAAMC,iCAA0B,KAAK,aAAa,WAAW;AAC7D,UAAM;AAAA,EACR;AACF;;"}

package/dist/copy/large.d.cts

@@ -0,0 +1,53 @@
+import { AccountInfo } from '../auth/account-info.js';
+import { RawClient } from '../raw/index.js';
+import { EncryptionSetting } from '../types/encryption.js';
+import { FileVersion } from '../types/file.js';
+import { BucketId, FileId } from '../types/ids.js';
+/** Options for a server-side multipart copy. */
+export interface CopyLargeFileOptions {
+    /** ID of the source file version to copy. */
+    readonly sourceFileId: FileId;
+    /** Destination file name in the target bucket. */
+    readonly fileName: string;
+    /** Target bucket. Defaults to the source's bucket. */
+    readonly destinationBucketId?: BucketId;
+    /** Size of each part in bytes. Defaults to the account's recommended part size. */
+    readonly partSize?: number;
+    /**
+     * Maximum number of parts copied in parallel. Defaults to
+     * {@link DEFAULT_TRANSFER_CONCURRENCY}.
+     */
+    readonly concurrency?: number;
+    /** MIME type for the destination file. Defaults to `b2/x-auto`. */
+    readonly contentType?: string;
+    /** Custom file info merged into the destination. */
+    readonly fileInfo?: Record<string, string>;
+    /** Server-side encryption applied to the destination. */
+    readonly destinationServerSideEncryption?: EncryptionSetting;
+    /** SSE-C settings used to read the source if it was uploaded with SSE-C. */
+    readonly sourceServerSideEncryption?: EncryptionSetting;
+    /**
+     * Optional abort signal. Checked before dispatching each part and
+     * between parts; an aborted signal cancels remaining parts and rolls
+     * back the unfinished large file via best-effort `cancelLargeFile`.
+     *
+     * Aborting does NOT roll back parts already accepted by B2; those
+     * exist on the unfinished large file until the cancel call completes
+     * or B2's lifecycle expires the in-progress upload (24 hours).
+     */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Performs a server-side copy of a file using the multipart `b2_copy_part` protocol.
+ * The source bytes never traverse the client; B2 copies each range internally.
+ *
+ * Falls back to a single `copyFile` call when the source fits in one part.
+ *
+ * @param raw - Low-level B2 API client.
+ * @param accountInfo - Authorized account state (used to resolve API URL, recommended part size).
+ * @param options - Copy parameters including source, destination, and concurrency.
+ *
+ * @returns The resulting destination {@link FileVersion}.
+ */
+export declare function copyLargeFile(raw: RawClient, accountInfo: AccountInfo, options: CopyLargeFileOptions): Promise<FileVersion>;
+//# sourceMappingURL=large.d.ts.map

package/dist/copy/large.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"large.d.ts","sourceRoot":"","sources":["../../src/copy/large.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAsB,MAAM,iBAAiB,CAAA;AAMhF,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACnC,6CAA6C;IAC7C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,sDAAsD;IACtD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,QAAQ,CAAA;IACvC,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC1C,yDAAyD;IACzD,QAAQ,CAAC,+BAA+B,CAAC,EAAE,iBAAiB,CAAA;IAC5D,4EAA4E;IAC5E,QAAQ,CAAC,0BAA0B,CAAC,EAAE,iBAAiB,CAAA;IACvD;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,SAAS,EACd,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,WAAW,CAAC,CA0FtB"}