@backblaze-labs/b2-sdk 0.1.0

package/dist/auth/file.js

@@ -0,0 +1,210 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { InMemoryAccountInfo } from "./in-memory.js";
+class FileAccountInfo {
+  /**
+   * Constructs a `FileAccountInfo` bound to a JSON file on disk. The file is
+   * created on the first `setAuth` write; reading it back happens via
+   * {@link load}.
+   *
+   * @param path - Absolute path to the JSON file that backs this account info.
+   */
+  constructor(path) {
+    this.path = path;
+  }
+  inner = new InMemoryAccountInfo();
+  writeQueue = Promise.resolve();
+  /**
+   * Reads the JSON file at the configured path and populates in-memory state.
+   * If the file is missing or contains invalid JSON, leaves state empty and
+   * returns silently (a re-auth is expected next).
+   *
+   * @returns A promise that resolves when load is complete.
+   */
+  async load() {
+    try {
+      const text = await readFile(this.path, "utf8");
+      const parsed = JSON.parse(text);
+      this.inner.setAuth(parsed);
+    } catch {
+    }
+  }
+  /**
+   * Persists the current auth response to the file. Atomically queues writes
+   * so concurrent updates serialize.
+   *
+   * @returns A promise that resolves when the write completes.
+   */
+  flush() {
+    const auth = this.inner.getAuth();
+    const next = this.writeQueue.then(async () => {
+      if (auth === null) {
+        try {
+          await writeFile(this.path, "", "utf8");
+        } catch {
+        }
+        return;
+      }
+      await mkdir(dirname(this.path), { recursive: true });
+      await writeFile(this.path, JSON.stringify(auth), "utf8");
+    });
+    this.writeQueue = next.catch(() => {
+    });
+    return next;
+  }
+  /**
+   * Stores the given authorization response and triggers an async write to disk.
+   *
+   * @param auth - The authorize-account response to persist.
+   */
+  setAuth(auth) {
+    this.inner.setAuth(auth);
+    void this.flush();
+  }
+  /**
+   * Returns the currently cached authorization response, or `null` if none.
+   *
+   * @returns The cached authorization response, or `null` if not authorized.
+   */
+  getAuth() {
+    return this.inner.getAuth();
+  }
+  /** Discards in-memory state and clears the on-disk file. */
+  clear() {
+    this.inner.clear();
+    void this.flush();
+  }
+  /**
+   * Returns the cached B2 API URL.
+   *
+   * @returns The base URL for B2 API calls.
+   */
+  getApiUrl() {
+    return this.inner.getApiUrl();
+  }
+  /**
+   * Returns the cached file-download URL.
+   *
+   * @returns The base URL for file downloads.
+   */
+  getDownloadUrl() {
+    return this.inner.getDownloadUrl();
+  }
+  /**
+   * Returns the cached session authorization token.
+   *
+   * @returns The current authorization token.
+   */
+  getAuthToken() {
+    return this.inner.getAuthToken();
+  }
+  /**
+   * Returns the cached account identifier.
+   *
+   * @returns The authorized account ID.
+   */
+  getAccountId() {
+    return this.inner.getAccountId();
+  }
+  /**
+   * Returns the server-recommended part size for multipart uploads.
+   *
+   * @returns The recommended part size in bytes.
+   */
+  getRecommendedPartSize() {
+    return this.inner.getRecommendedPartSize();
+  }
+  /**
+   * Returns the server-enforced minimum part size for multipart uploads.
+   *
+   * @returns The absolute minimum part size in bytes.
+   */
+  getAbsoluteMinimumPartSize() {
+    return this.inner.getAbsoluteMinimumPartSize();
+  }
+  /**
+   * Returns the cached S3-compatible API URL.
+   *
+   * @returns The base URL for the S3-compatible API.
+   */
+  getS3ApiUrl() {
+    return this.inner.getS3ApiUrl();
+  }
+  /**
+   * Returns the bucket the key is restricted to, if any.
+   *
+   * @returns The restricted bucket ID, or `null` if the key is unrestricted.
+   */
+  getAllowedBucketId() {
+    return this.inner.getAllowedBucketId();
+  }
+  /**
+   * Takes an upload URL from the in-memory pool for the given bucket.
+   *
+   * @param bucketId - Bucket to check out an upload URL for.
+   *
+   * @returns A reusable upload URL entry, or `null` if none are pooled.
+   */
+  checkoutUploadUrl(bucketId) {
+    return this.inner.checkoutUploadUrl(bucketId);
+  }
+  /**
+   * Returns a still-valid upload URL to the pool for reuse.
+   *
+   * @param bucketId - Bucket the upload URL belongs to.
+   * @param entry - Upload URL entry to return.
+   */
+  returnUploadUrl(bucketId, entry) {
+    this.inner.returnUploadUrl(bucketId, entry);
+  }
+  /**
+   * Removes an upload URL from the pool after an upload error.
+   *
+   * @param bucketId - Bucket the failed upload URL belongs to.
+   * @param entry - Upload URL entry to evict.
+   */
+  evictUploadUrl(bucketId, entry) {
+    this.inner.evictUploadUrl(bucketId, entry);
+  }
+  /**
+   * Takes a large-file part upload URL from the in-memory pool.
+   *
+   * @param fileId - Large file to check out a part upload URL for.
+   *
+   * @returns A reusable part upload URL entry, or `null` if none are pooled.
+   */
+  checkoutPartUploadUrl(fileId) {
+    return this.inner.checkoutPartUploadUrl(fileId);
+  }
+  /**
+   * Returns a still-valid part upload URL to the pool for reuse.
+   *
+   * @param fileId - Large file the part upload URL belongs to.
+   * @param entry - Part upload URL entry to return.
+   */
+  returnPartUploadUrl(fileId, entry) {
+    this.inner.returnPartUploadUrl(fileId, entry);
+  }
+  /**
+   * Removes a part upload URL from the pool after an error.
+   *
+   * @param fileId - Large file the failed part upload URL belongs to.
+   * @param entry - Part upload URL entry to evict.
+   */
+  evictPartUploadUrl(fileId, entry) {
+    this.inner.evictPartUploadUrl(fileId, entry);
+  }
+  /**
+   * Awaits any pending disk writes. Call before process exit to ensure the
+   * latest state is persisted.
+   *
+   * @returns A promise that resolves once all queued writes are flushed.
+   */
+  async flushed() {
+    await this.writeQueue;
+  }
+}
+export {
+  FileAccountInfo
+};
+//# sourceMappingURL=file.js.map

package/dist/auth/file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.js","sources":["../../src/auth/file.ts"],"sourcesContent":["import { mkdir, readFile, writeFile } from 'node:fs/promises'\nimport { dirname } from 'node:path'\nimport type { AuthorizeAccountResponse } from '../types/auth.ts'\nimport type { BucketId } from '../types/ids.ts'\nimport type { AccountInfo, UploadUrlEntry } from './account-info.ts'\nimport { InMemoryAccountInfo } from './in-memory.ts'\n\n/**\n * Node-only {@link AccountInfo} backend that persists the authorization\n * response to a JSON file. Upload URL pools remain in memory because URLs are\n * short-lived and shouldn't be shared across processes.\n *\n * On instantiation, call {@link FileAccountInfo.load} to populate state from\n * disk (or start fresh if the file is missing or corrupt). The authorization\n * response is written back to disk on every {@link setAuth} or {@link clear}\n * call so a process restart can resume without re-authorizing.\n *\n * This module imports `node:fs/promises`; do not load it in browser bundles.\n */\nexport class FileAccountInfo implements AccountInfo {\n  private readonly inner = new InMemoryAccountInfo()\n  private writeQueue: Promise<void> = Promise.resolve()\n\n  /**\n   * Constructs a `FileAccountInfo` bound to a JSON file on disk. The file is\n   * created on the first `setAuth` write; reading it back happens via\n   * {@link load}.\n   *\n   * @param path - Absolute path to the JSON file that backs this account info.\n   */\n  constructor(public readonly path: string) {}\n\n  /**\n   * Reads the JSON file at the configured path and populates in-memory state.\n   * If the file is missing or contains invalid JSON, leaves state empty and\n   * returns silently (a re-auth is expected next).\n   *\n   * @returns A promise that resolves when load is complete.\n   */\n  async load(): Promise<void> {\n    try {\n      const text = await readFile(this.path, 'utf8')\n      const parsed = JSON.parse(text) as AuthorizeAccountResponse\n      this.inner.setAuth(parsed)\n    } catch {\n      // Missing file, invalid JSON, or permission denied: start empty.\n    }\n  }\n\n  /**\n   * Persists the current auth response to the file. Atomically queues writes\n   * so concurrent updates serialize.\n   *\n   * @returns A promise that resolves when the write completes.\n   */\n  private flush(): Promise<void> {\n    const auth = this.inner.getAuth()\n    const next = this.writeQueue.then(async () => {\n      if (auth === null) {\n        try {\n          await writeFile(this.path, '', 'utf8')\n        } catch {\n          // Best-effort\n        }\n        return\n      }\n      await mkdir(dirname(this.path), { recursive: true })\n      await writeFile(this.path, JSON.stringify(auth), 'utf8')\n    })\n    this.writeQueue = next.catch(() => {})\n    return next\n  }\n\n  /**\n   * Stores the given authorization response and triggers an async write to disk.\n   *\n   * @param auth - The authorize-account response to persist.\n   */\n  setAuth(auth: AuthorizeAccountResponse): void {\n    this.inner.setAuth(auth)\n    void this.flush()\n  }\n\n  /**\n   * Returns the currently cached authorization response, or `null` if none.\n   *\n   * @returns The cached authorization response, or `null` if not authorized.\n   */\n  getAuth(): AuthorizeAccountResponse | null {\n    return this.inner.getAuth()\n  }\n\n  /** Discards in-memory state and clears the on-disk file. */\n  clear(): void {\n    this.inner.clear()\n    void this.flush()\n  }\n\n  /**\n   * Returns the cached B2 API URL.\n   *\n   * @returns The base URL for B2 API calls.\n   */\n  getApiUrl(): string {\n    return this.inner.getApiUrl()\n  }\n\n  /**\n   * Returns the cached file-download URL.\n   *\n   * @returns The base URL for file downloads.\n   */\n  getDownloadUrl(): string {\n    return this.inner.getDownloadUrl()\n  }\n\n  /**\n   * Returns the cached session authorization token.\n   *\n   * @returns The current authorization token.\n   */\n  getAuthToken(): string {\n    return this.inner.getAuthToken()\n  }\n\n  /**\n   * Returns the cached account identifier.\n   *\n   * @returns The authorized account ID.\n   */\n  getAccountId(): string {\n    return this.inner.getAccountId()\n  }\n\n  /**\n   * Returns the server-recommended part size for multipart uploads.\n   *\n   * @returns The recommended part size in bytes.\n   */\n  getRecommendedPartSize(): number {\n    return this.inner.getRecommendedPartSize()\n  }\n\n  /**\n   * Returns the server-enforced minimum part size for multipart uploads.\n   *\n   * @returns The absolute minimum part size in bytes.\n   */\n  getAbsoluteMinimumPartSize(): number {\n    return this.inner.getAbsoluteMinimumPartSize()\n  }\n\n  /**\n   * Returns the cached S3-compatible API URL.\n   *\n   * @returns The base URL for the S3-compatible API.\n   */\n  getS3ApiUrl(): string {\n    return this.inner.getS3ApiUrl()\n  }\n\n  /**\n   * Returns the bucket the key is restricted to, if any.\n   *\n   * @returns The restricted bucket ID, or `null` if the key is unrestricted.\n   */\n  getAllowedBucketId(): BucketId | null {\n    return this.inner.getAllowedBucketId()\n  }\n\n  /**\n   * Takes an upload URL from the in-memory pool for the given bucket.\n   *\n   * @param bucketId - Bucket to check out an upload URL for.\n   *\n   * @returns A reusable upload URL entry, or `null` if none are pooled.\n   */\n  checkoutUploadUrl(bucketId: BucketId): UploadUrlEntry | null {\n    return this.inner.checkoutUploadUrl(bucketId)\n  }\n\n  /**\n   * Returns a still-valid upload URL to the pool for reuse.\n   *\n   * @param bucketId - Bucket the upload URL belongs to.\n   * @param entry - Upload URL entry to return.\n   */\n  returnUploadUrl(bucketId: BucketId, entry: UploadUrlEntry): void {\n    this.inner.returnUploadUrl(bucketId, entry)\n  }\n\n  /**\n   * Removes an upload URL from the pool after an upload error.\n   *\n   * @param bucketId - Bucket the failed upload URL belongs to.\n   * @param entry - Upload URL entry to evict.\n   */\n  evictUploadUrl(bucketId: BucketId, entry: UploadUrlEntry): void {\n    this.inner.evictUploadUrl(bucketId, entry)\n  }\n\n  /**\n   * Takes a large-file part upload URL from the in-memory pool.\n   *\n   * @param fileId - Large file to check out a part upload URL for.\n   *\n   * @returns A reusable part upload URL entry, or `null` if none are pooled.\n   */\n  checkoutPartUploadUrl(fileId: string): UploadUrlEntry | null {\n    return this.inner.checkoutPartUploadUrl(fileId)\n  }\n\n  /**\n   * Returns a still-valid part upload URL to the pool for reuse.\n   *\n   * @param fileId - Large file the part upload URL belongs to.\n   * @param entry - Part upload URL entry to return.\n   */\n  returnPartUploadUrl(fileId: string, entry: UploadUrlEntry): void {\n    this.inner.returnPartUploadUrl(fileId, entry)\n  }\n\n  /**\n   * Removes a part upload URL from the pool after an error.\n   *\n   * @param fileId - Large file the failed part upload URL belongs to.\n   * @param entry - Part upload URL entry to evict.\n   */\n  evictPartUploadUrl(fileId: string, entry: UploadUrlEntry): void {\n    this.inner.evictPartUploadUrl(fileId, entry)\n  }\n\n  /**\n   * Awaits any pending disk writes. Call before process exit to ensure the\n   * latest state is persisted.\n   *\n   * @returns A promise that resolves once all queued writes are flushed.\n   */\n  async flushed(): Promise<void> {\n    await this.writeQueue\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/auth/in-memory.cjs

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const uploadUrlPool = require("./upload-url-pool.cjs");
+class InMemoryAccountInfo {
+  /** Cached authorization response, or null before authorize() is called. */
+  auth = null;
+  /** Pool of reusable small-file upload URLs, keyed by bucket ID. */
+  uploadUrls = new uploadUrlPool.UploadUrlPool();
+  /** Pool of reusable large-file part upload URLs, keyed by file ID. */
+  partUploadUrls = new uploadUrlPool.UploadUrlPool();
+  /**
+   * Store a fresh authorization response, replacing any previous state.
+   *
+   * @param auth - The authorize account response to store.
+   */
+  setAuth(auth) {
+    this.auth = auth;
+    this.uploadUrls.clear();
+    this.partUploadUrls.clear();
+  }
+  /**
+   * Return the current authorization response, or null if not authorized.
+   *
+   * @returns The cached authorization response, or null if not yet authorized.
+   */
+  getAuth() {
+    return this.auth;
+  }
+  /** Discard all cached authorization state and upload URLs. */
+  clear() {
+    this.auth = null;
+    this.uploadUrls.clear();
+    this.partUploadUrls.clear();
+  }
+  /**
+   * Base URL for B2 API calls.
+   *
+   * @returns The base URL for B2 API calls.
+   *
+   * @throws Error if not yet authorized.
+   */
+  getApiUrl() {
+    return this.requireAuth().apiInfo.storageApi.apiUrl;
+  }
+  /**
+   * Base URL for file downloads.
+   *
+   * @returns The base URL for file downloads.
+   *
+   * @throws Error if not yet authorized.
+   */
+  getDownloadUrl() {
+    return this.requireAuth().apiInfo.storageApi.downloadUrl;
+  }
+  /**
+   * Current authorization token.
+   *
+   * @returns The current authorization token.
+   *
+   * @throws Error if not yet authorized.
+   */
+  getAuthToken() {
+    return this.requireAuth().authorizationToken;
+  }
+  /**
+   * The authorized account ID.
+   *
+   * @returns The authorized account identifier.
+   *
+   * @throws Error if not yet authorized.
+   */
+  getAccountId() {
+    return this.requireAuth().accountId;
+  }
+  /**
+   * Server-recommended part size for large file uploads, in bytes.
+   *
+   * @returns The server-recommended part size in bytes.
+   *
+   * @throws Error if not yet authorized.
+   */
+  getRecommendedPartSize() {
+    return this.requireAuth().apiInfo.storageApi.recommendedPartSize;
+  }
+  /**
+   * Smallest allowed part size for large file uploads, in bytes.
+   *
+   * @returns The smallest allowed part size in bytes.
+   *
+   * @throws Error if not yet authorized.
+   */
+  getAbsoluteMinimumPartSize() {
+    return this.requireAuth().apiInfo.storageApi.absoluteMinimumPartSize;
+  }
+  /**
+   * Base URL for the S3-compatible API.
+   *
+   * @returns The base URL for the S3-compatible API.
+   *
+   * @throws Error if not yet authorized.
+   */
+  getS3ApiUrl() {
+    return this.requireAuth().apiInfo.storageApi.s3ApiUrl;
+  }
+  /**
+   * Bucket ID the key is restricted to, or null if unrestricted.
+   *
+   * @returns The restricted bucket identifier, or null if the key is unrestricted.
+   *
+   * @throws Error if not yet authorized.
+   */
+  getAllowedBucketId() {
+    return this.requireAuth().apiInfo.storageApi.allowed.bucketId ?? null;
+  }
+  /**
+   * Take an upload URL from the pool for the given bucket, or null if none available.
+   *
+   * @param bucketId - The bucket to check out an upload URL for.
+   *
+   * @returns A reusable upload URL entry, or null if none are available.
+   */
+  checkoutUploadUrl(bucketId) {
+    return this.uploadUrls.checkout(bucketId);
+  }
+  /**
+   * Return a still-valid upload URL to the pool for reuse.
+   *
+   * @param bucketId - The bucket the upload URL belongs to.
+   * @param entry - The upload URL entry to return to the pool.
+   */
+  returnUploadUrl(bucketId, entry) {
+    this.uploadUrls.checkin(bucketId, entry);
+  }
+  /**
+   * Remove an upload URL from the pool after an upload error.
+   *
+   * @param bucketId - The bucket the failed upload URL belongs to.
+   * @param entry - The upload URL entry to remove from the pool.
+   */
+  evictUploadUrl(bucketId, entry) {
+    this.uploadUrls.evict(bucketId, entry);
+  }
+  /**
+   * Take a large-file part upload URL from the pool, or null if none available.
+   *
+   * @param fileId - The large file to check out a part upload URL for.
+   *
+   * @returns A reusable part upload URL entry, or null if none are available.
+   */
+  checkoutPartUploadUrl(fileId) {
+    return this.partUploadUrls.checkout(fileId);
+  }
+  /**
+   * Return a still-valid part upload URL to the pool for reuse.
+   *
+   * @param fileId - The large file the part upload URL belongs to.
+   * @param entry - The part upload URL entry to return to the pool.
+   */
+  returnPartUploadUrl(fileId, entry) {
+    this.partUploadUrls.checkin(fileId, entry);
+  }
+  /**
+   * Remove a part upload URL from the pool after an error.
+   *
+   * @param fileId - The large file the failed part upload URL belongs to.
+   * @param entry - The part upload URL entry to remove from the pool.
+   */
+  evictPartUploadUrl(fileId, entry) {
+    this.partUploadUrls.evict(fileId, entry);
+  }
+  /**
+   * Retrieve the cached auth response or throw if not yet authorized.
+   *
+   * @returns The cached authorization response.
+   *
+   * @throws Error if authorize() has not been called.
+   */
+  requireAuth() {
+    if (!this.auth) throw new Error("Not authorized. Call authorize() first.");
+    return this.auth;
+  }
+}
+exports.InMemoryAccountInfo = InMemoryAccountInfo;
+//# sourceMappingURL=in-memory.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory.cjs","sources":["../../src/auth/in-memory.ts"],"sourcesContent":["import type { AuthorizeAccountResponse } from '../types/auth.ts'\nimport type { BucketId } from '../types/ids.ts'\nimport type { AccountInfo, UploadUrlEntry } from './account-info.ts'\nimport { UploadUrlPool } from './upload-url-pool.ts'\n\n/**\n * In-memory implementation of {@link AccountInfo}.\n * Stores the authorization response and upload URL pools in plain object fields.\n * Suitable for short-lived processes or tests; state is lost when the process exits.\n */\nexport class InMemoryAccountInfo implements AccountInfo {\n  /** Cached authorization response, or null before authorize() is called. */\n  private auth: AuthorizeAccountResponse | null = null\n  /** Pool of reusable small-file upload URLs, keyed by bucket ID. */\n  private readonly uploadUrls = new UploadUrlPool()\n  /** Pool of reusable large-file part upload URLs, keyed by file ID. */\n  private readonly partUploadUrls = new UploadUrlPool()\n\n  /**\n   * Store a fresh authorization response, replacing any previous state.\n   *\n   * @param auth - The authorize account response to store.\n   */\n  setAuth(auth: AuthorizeAccountResponse): void {\n    this.auth = auth\n    this.uploadUrls.clear()\n    this.partUploadUrls.clear()\n  }\n\n  /**\n   * Return the current authorization response, or null if not authorized.\n   *\n   * @returns The cached authorization response, or null if not yet authorized.\n   */\n  getAuth(): AuthorizeAccountResponse | null {\n    return this.auth\n  }\n\n  /** Discard all cached authorization state and upload URLs. */\n  clear(): void {\n    this.auth = null\n    this.uploadUrls.clear()\n    this.partUploadUrls.clear()\n  }\n\n  /**\n   * Base URL for B2 API calls.\n   *\n   * @returns The base URL for B2 API calls.\n   *\n   * @throws Error if not yet authorized.\n   */\n  getApiUrl(): string {\n    return this.requireAuth().apiInfo.storageApi.apiUrl\n  }\n\n  /**\n   * Base URL for file downloads.\n   *\n   * @returns The base URL for file downloads.\n   *\n   * @throws Error if not yet authorized.\n   */\n  getDownloadUrl(): string {\n    return this.requireAuth().apiInfo.storageApi.downloadUrl\n  }\n\n  /**\n   * Current authorization token.\n   *\n   * @returns The current authorization token.\n   *\n   * @throws Error if not yet authorized.\n   */\n  getAuthToken(): string {\n    return this.requireAuth().authorizationToken as string\n  }\n\n  /**\n   * The authorized account ID.\n   *\n   * @returns The authorized account identifier.\n   *\n   * @throws Error if not yet authorized.\n   */\n  getAccountId(): string {\n    return this.requireAuth().accountId as string\n  }\n\n  /**\n   * Server-recommended part size for large file uploads, in bytes.\n   *\n   * @returns The server-recommended part size in bytes.\n   *\n   * @throws Error if not yet authorized.\n   */\n  getRecommendedPartSize(): number {\n    return this.requireAuth().apiInfo.storageApi.recommendedPartSize\n  }\n\n  /**\n   * Smallest allowed part size for large file uploads, in bytes.\n   *\n   * @returns The smallest allowed part size in bytes.\n   *\n   * @throws Error if not yet authorized.\n   */\n  getAbsoluteMinimumPartSize(): number {\n    return this.requireAuth().apiInfo.storageApi.absoluteMinimumPartSize\n  }\n\n  /**\n   * Base URL for the S3-compatible API.\n   *\n   * @returns The base URL for the S3-compatible API.\n   *\n   * @throws Error if not yet authorized.\n   */\n  getS3ApiUrl(): string {\n    return this.requireAuth().apiInfo.storageApi.s3ApiUrl\n  }\n\n  /**\n   * Bucket ID the key is restricted to, or null if unrestricted.\n   *\n   * @returns The restricted bucket identifier, or null if the key is unrestricted.\n   *\n   * @throws Error if not yet authorized.\n   */\n  getAllowedBucketId(): BucketId | null {\n    return this.requireAuth().apiInfo.storageApi.allowed.bucketId ?? null\n  }\n\n  /**\n   * Take an upload URL from the pool for the given bucket, or null if none available.\n   *\n   * @param bucketId - The bucket to check out an upload URL for.\n   *\n   * @returns A reusable upload URL entry, or null if none are available.\n   */\n  checkoutUploadUrl(bucketId: BucketId): UploadUrlEntry | null {\n    return this.uploadUrls.checkout(bucketId as string)\n  }\n\n  /**\n   * Return a still-valid upload URL to the pool for reuse.\n   *\n   * @param bucketId - The bucket the upload URL belongs to.\n   * @param entry - The upload URL entry to return to the pool.\n   */\n  returnUploadUrl(bucketId: BucketId, entry: UploadUrlEntry): void {\n    this.uploadUrls.checkin(bucketId as string, entry)\n  }\n\n  /**\n   * Remove an upload URL from the pool after an upload error.\n   *\n   * @param bucketId - The bucket the failed upload URL belongs to.\n   * @param entry - The upload URL entry to remove from the pool.\n   */\n  evictUploadUrl(bucketId: BucketId, entry: UploadUrlEntry): void {\n    this.uploadUrls.evict(bucketId as string, entry)\n  }\n\n  /**\n   * Take a large-file part upload URL from the pool, or null if none available.\n   *\n   * @param fileId - The large file to check out a part upload URL for.\n   *\n   * @returns A reusable part upload URL entry, or null if none are available.\n   */\n  checkoutPartUploadUrl(fileId: string): UploadUrlEntry | null {\n    return this.partUploadUrls.checkout(fileId)\n  }\n\n  /**\n   * Return a still-valid part upload URL to the pool for reuse.\n   *\n   * @param fileId - The large file the part upload URL belongs to.\n   * @param entry - The part upload URL entry to return to the pool.\n   */\n  returnPartUploadUrl(fileId: string, entry: UploadUrlEntry): void {\n    this.partUploadUrls.checkin(fileId, entry)\n  }\n\n  /**\n   * Remove a part upload URL from the pool after an error.\n   *\n   * @param fileId - The large file the failed part upload URL belongs to.\n   * @param entry - The part upload URL entry to remove from the pool.\n   */\n  evictPartUploadUrl(fileId: string, entry: UploadUrlEntry): void {\n    this.partUploadUrls.evict(fileId, entry)\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 Error if authorize() has not been called.\n   */\n  private requireAuth(): AuthorizeAccountResponse {\n    if (!this.auth) throw new Error('Not authorized. Call authorize() first.')\n    return this.auth\n  }\n}\n"],"names":["UploadUrlPool"],"mappings":";;;AAUO,MAAM,oBAA2C;AAAA;AAAA,EAE9C,OAAwC;AAAA;AAAA,EAE/B,aAAa,IAAIA,cAAAA,cAAA;AAAA;AAAA,EAEjB,iBAAiB,IAAIA,cAAAA,cAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOtC,QAAQ,MAAsC;AAC5C,SAAK,OAAO;AACZ,SAAK,WAAW,MAAA;AAChB,SAAK,eAAe,MAAA;AAAA,EACtB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,UAA2C;AACzC,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,QAAc;AACZ,SAAK,OAAO;AACZ,SAAK,WAAW,MAAA;AAChB,SAAK,eAAe,MAAA;AAAA,EACtB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,YAAoB;AAClB,WAAO,KAAK,YAAA,EAAc,QAAQ,WAAW;AAAA,EAC/C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,iBAAyB;AACvB,WAAO,KAAK,YAAA,EAAc,QAAQ,WAAW;AAAA,EAC/C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,eAAuB;AACrB,WAAO,KAAK,cAAc;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,eAAuB;AACrB,WAAO,KAAK,cAAc;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,yBAAiC;AAC/B,WAAO,KAAK,YAAA,EAAc,QAAQ,WAAW;AAAA,EAC/C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,6BAAqC;AACnC,WAAO,KAAK,YAAA,EAAc,QAAQ,WAAW;AAAA,EAC/C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,cAAsB;AACpB,WAAO,KAAK,YAAA,EAAc,QAAQ,WAAW;AAAA,EAC/C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,qBAAsC;AACpC,WAAO,KAAK,cAAc,QAAQ,WAAW,QAAQ,YAAY;AAAA,EACnE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,kBAAkB,UAA2C;AAC3D,WAAO,KAAK,WAAW,SAAS,QAAkB;AAAA,EACpD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,gBAAgB,UAAoB,OAA6B;AAC/D,SAAK,WAAW,QAAQ,UAAoB,KAAK;AAAA,EACnD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,eAAe,UAAoB,OAA6B;AAC9D,SAAK,WAAW,MAAM,UAAoB,KAAK;AAAA,EACjD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,sBAAsB,QAAuC;AAC3D,WAAO,KAAK,eAAe,SAAS,MAAM;AAAA,EAC5C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,oBAAoB,QAAgB,OAA6B;AAC/D,SAAK,eAAe,QAAQ,QAAQ,KAAK;AAAA,EAC3C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,mBAAmB,QAAgB,OAA6B;AAC9D,SAAK,eAAe,MAAM,QAAQ,KAAK;AAAA,EACzC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASQ,cAAwC;AAC9C,QAAI,CAAC,KAAK,KAAM,OAAM,IAAI,MAAM,yCAAyC;AACzE,WAAO,KAAK;AAAA,EACd;AACF;;"}

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

@@ -0,0 +1,147 @@
+import { AuthorizeAccountResponse } from '../types/auth.js';
+import { BucketId } from '../types/ids.js';
+import { AccountInfo, UploadUrlEntry } from './account-info.js';
+/**
+ * In-memory implementation of {@link AccountInfo}.
+ * Stores the authorization response and upload URL pools in plain object fields.
+ * Suitable for short-lived processes or tests; state is lost when the process exits.
+ */
+export declare class InMemoryAccountInfo implements AccountInfo {
+    /** Cached authorization response, or null before authorize() is called. */
+    private auth;
+    /** Pool of reusable small-file upload URLs, keyed by bucket ID. */
+    private readonly uploadUrls;
+    /** Pool of reusable large-file part upload URLs, keyed by file ID. */
+    private readonly partUploadUrls;
+    /**
+     * Store a fresh authorization response, replacing any previous state.
+     *
+     * @param auth - The authorize account response to store.
+     */
+    setAuth(auth: AuthorizeAccountResponse): void;
+    /**
+     * Return the current authorization response, or null if not authorized.
+     *
+     * @returns The cached authorization response, or null if not yet authorized.
+     */
+    getAuth(): AuthorizeAccountResponse | null;
+    /** Discard all cached authorization state and upload URLs. */
+    clear(): void;
+    /**
+     * Base URL for B2 API calls.
+     *
+     * @returns The base URL for B2 API calls.
+     *
+     * @throws Error if not yet authorized.
+     */
+    getApiUrl(): string;
+    /**
+     * Base URL for file downloads.
+     *
+     * @returns The base URL for file downloads.
+     *
+     * @throws Error if not yet authorized.
+     */
+    getDownloadUrl(): string;
+    /**
+     * Current authorization token.
+     *
+     * @returns The current authorization token.
+     *
+     * @throws Error if not yet authorized.
+     */
+    getAuthToken(): string;
+    /**
+     * The authorized account ID.
+     *
+     * @returns The authorized account identifier.
+     *
+     * @throws Error if not yet authorized.
+     */
+    getAccountId(): string;
+    /**
+     * Server-recommended part size for large file uploads, in bytes.
+     *
+     * @returns The server-recommended part size in bytes.
+     *
+     * @throws Error if not yet authorized.
+     */
+    getRecommendedPartSize(): number;
+    /**
+     * Smallest allowed part size for large file uploads, in bytes.
+     *
+     * @returns The smallest allowed part size in bytes.
+     *
+     * @throws Error if not yet authorized.
+     */
+    getAbsoluteMinimumPartSize(): number;
+    /**
+     * Base URL for the S3-compatible API.
+     *
+     * @returns The base URL for the S3-compatible API.
+     *
+     * @throws Error if not yet authorized.
+     */
+    getS3ApiUrl(): string;
+    /**
+     * Bucket ID the key is restricted to, or null if unrestricted.
+     *
+     * @returns The restricted bucket identifier, or null if the key is unrestricted.
+     *
+     * @throws Error if not yet authorized.
+     */
+    getAllowedBucketId(): BucketId | null;
+    /**
+     * Take an upload URL from the pool for the given bucket, or null if none available.
+     *
+     * @param bucketId - The bucket to check out an upload URL for.
+     *
+     * @returns A reusable upload URL entry, or null if none are available.
+     */
+    checkoutUploadUrl(bucketId: BucketId): UploadUrlEntry | null;
+    /**
+     * Return a still-valid upload URL to the pool for reuse.
+     *
+     * @param bucketId - The bucket the upload URL belongs to.
+     * @param entry - The upload URL entry to return to the pool.
+     */
+    returnUploadUrl(bucketId: BucketId, entry: UploadUrlEntry): void;
+    /**
+     * Remove an upload URL from the pool after an upload error.
+     *
+     * @param bucketId - The bucket the failed upload URL belongs to.
+     * @param entry - The upload URL entry to remove from the pool.
+     */
+    evictUploadUrl(bucketId: BucketId, entry: UploadUrlEntry): void;
+    /**
+     * Take a large-file part upload URL from the pool, or null if none available.
+     *
+     * @param fileId - The large file to check out a part upload URL for.
+     *
+     * @returns A reusable part upload URL entry, or null if none are available.
+     */
+    checkoutPartUploadUrl(fileId: string): UploadUrlEntry | null;
+    /**
+     * Return a still-valid part upload URL to the pool for reuse.
+     *
+     * @param fileId - The large file the part upload URL belongs to.
+     * @param entry - The part upload URL entry to return to the pool.
+     */
+    returnPartUploadUrl(fileId: string, entry: UploadUrlEntry): void;
+    /**
+     * Remove a part upload URL from the pool after an error.
+     *
+     * @param fileId - The large file the failed part upload URL belongs to.
+     * @param entry - The part upload URL entry to remove from the pool.
+     */
+    evictPartUploadUrl(fileId: string, entry: UploadUrlEntry): void;
+    /**
+     * Retrieve the cached auth response or throw if not yet authorized.
+     *
+     * @returns The cached authorization response.
+     *
+     * @throws Error if authorize() has not been called.
+     */
+    private requireAuth;
+}
+//# sourceMappingURL=in-memory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory.d.ts","sourceRoot":"","sources":["../../src/auth/in-memory.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAA;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAGpE;;;;GAIG;AACH,qBAAa,mBAAoB,YAAW,WAAW;IACrD,2EAA2E;IAC3E,OAAO,CAAC,IAAI,CAAwC;IACpD,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IACjD,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAsB;IAErD;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,wBAAwB,GAAG,IAAI;IAM7C;;;;OAIG;IACH,OAAO,IAAI,wBAAwB,GAAG,IAAI;IAI1C,8DAA8D;IAC9D,KAAK,IAAI,IAAI;IAMb;;;;;;OAMG;IACH,SAAS,IAAI,MAAM;IAInB;;;;;;OAMG;IACH,cAAc,IAAI,MAAM;IAIxB;;;;;;OAMG;IACH,YAAY,IAAI,MAAM;IAItB;;;;;;OAMG;IACH,YAAY,IAAI,MAAM;IAItB;;;;;;OAMG;IACH,sBAAsB,IAAI,MAAM;IAIhC;;;;;;OAMG;IACH,0BAA0B,IAAI,MAAM;IAIpC;;;;;;OAMG;IACH,WAAW,IAAI,MAAM;IAIrB;;;;;;OAMG;IACH,kBAAkB,IAAI,QAAQ,GAAG,IAAI;IAIrC;;;;;;OAMG;IACH,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,cAAc,GAAG,IAAI;IAI5D;;;;;OAKG;IACH,eAAe,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,GAAG,IAAI;IAIhE;;;;;OAKG;IACH,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,GAAG,IAAI;IAI/D;;;;;;OAMG;IACH,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAI5D;;;;;OAKG;IACH,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,IAAI;IAIhE;;;;;OAKG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,IAAI;IAI/D;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;CAIpB"}