@bsv/sdk 2.0.13 → 2.0.14

package/dist/types/src/storage/StorageUploader.d.ts

@@ -1,6 +1,13 @@
 import { WalletInterface } from '../wallet/Wallet.interfaces.js';
+/** Default UHRP storage providers used when the caller passes no host list. */
+export declare const DEFAULT_UHRP_SERVERS: string[];
 export interface UploaderConfig {
-    storageURL: string;
+    /** Legacy single-host URL. Mutually exclusive with `storageURLs`. */
+    storageURL?: string;
+    /** Explicit provider list. Takes precedence over `storageURL`. */
+    storageURLs?: string[];
+    /** Minimum replicas to store the file on. Defaults to 1. */
+    resilienceLevel?: number;
     wallet: WalletInterface;
 }
 export interface UploadableFile {
@@ -10,94 +17,126 @@ export interface UploadableFile {
 export interface UploadFileResult {
     published: boolean;
     uhrpURL: string;
+    /** Providers that successfully hosted the file. */
+    hostedBy: string[];
 }
 export interface FindFileData {
     name: string;
     size: string;
     mimeType: string;
     expiryTime: number;
+    /** Providers that reported this UHRP URL. Omitted in single-host mode. */
+    hostedBy?: string[];
+}
+export interface RenewPerHostResult {
+    host: string;
+    status: 'success' | 'error';
+    prevExpiryTime?: number;
+    newExpiryTime?: number;
+    amount?: number;
+    error?: string;
 }
 export interface RenewFileResult {
     status: string;
     prevExpiryTime?: number;
     newExpiryTime?: number;
+    /** Total satoshis paid across every host that renewed. */
     amount?: number;
+    /** Per-host outcomes. Omitted in single-host mode. */
+    results?: RenewPerHostResult[];
+}
+export interface HostScopeOptions {
+    /** Restrict the operation to this subset of configured providers. */
+    hostedBy?: string[];
+}
+export interface EstimateCostResult {
+    /** Cheapest-first quotes from configured providers. */
+    quotes: Array<{
+        host: string;
+        amount: number;
+    }>;
+    resilienceLevel: number;
+    /** Sum of the cheapest `resilienceLevel` amounts (or all collected, if below threshold). */
+    totalForResilience: number;
+    /** False when `publishFile` would throw without uploading. */
+    meetsResilienceThreshold: boolean;
 }
 /**
- * The StorageUploader class provides client-side methods for:
- * - Uploading files with a specified retention period
- * - Finding file metadata by UHRP URL
- * - Listing all user uploads
- * - Renewing an existing advertisement's expiry time
+ * Thrown by `renewFile` when successful renewals fall below the resilience
+ * threshold. Per-host outcomes are attached so callers can reconcile which
+ * providers were billed.
+ */
+export declare class RenewResiliencyError extends Error {
+    readonly results: RenewPerHostResult[];
+    readonly requiredSuccesses: number;
+    readonly successCount: number;
+    constructor(message: string, results: RenewPerHostResult[], requiredSuccesses: number, successCount: number);
+}
+/**
+ * Client for publishing, finding, listing, and renewing UHRP-hosted files
+ * across one or more storage providers.
  */
 export declare class StorageUploader {
     private readonly authFetch;
+    private readonly hosts;
+    private readonly resilienceLevel;
+    /** Primary host used for non-upload operations. */
     private readonly baseURL;
-    /**
-     * Creates a new StorageUploader instance.
-     * @param {UploaderConfig} config - An object containing the storage server's URL and a wallet interface
-     */
     constructor(config: UploaderConfig);
+    /** Returns `null` when the provider is unreachable or errors out. */
+    private getQuote;
+    /** Drives the authenticated `/upload` route; `AuthFetch` handles the 402 payment flow. */
+    private getUploadURL;
+    private putFile;
     /**
-     * Requests information from the server to upload a file (including presigned URL and headers).
-     * @private
-     * @param {number} fileSize - The size of the file, in bytes
-     * @param {number} retentionPeriod - The desired hosting time, in minutes
-     * @returns {Promise<{ uploadURL: string; requiredHeaders: Record<string, string>; amount?: number }>}
-     * @throws {Error} If the server returns a non-OK response or an error status
+     * Collects quotes in parallel batches, shrinking each batch to only the
+     * remaining quotes still needed so we never over-query once the quote
+     * budget is satisfied.
      */
-    private getUploadInfo;
+    private collectQuotes;
     /**
-     * Performs the actual file upload (HTTP PUT) to the presigned URL returned by the server.
-     * @private
-     * @param {string} uploadURL - The presigned URL where the file is to be uploaded
-     * @param {UploadableFile} file - The file to upload, including its raw data and MIME type
-     * @param {Record<string, string>} requiredHeaders - Additional headers required by the server (e.g. content-length)
-     * @returns {Promise<UploadFileResult>} An object indicating whether publishing was successful and the resulting UHRP URL
-     * @throws {Error} If the server returns a non-OK response
+     * Queries the unauthenticated `/quote` endpoint on up to `2 * resilienceLevel`
+     * providers and returns the cheapest-first quote list plus the aggregate
+     * cost `publishFile` would pay. No provider is billed.
      */
-    private uploadFile;
+    estimateCost(params: {
+        fileSize: number;
+        retentionPeriod: number;
+    }): Promise<EstimateCostResult>;
     /**
-     * Publishes a file to the storage server with the specified retention period.
-     *
-     * This will:
-     * 1. Request an upload URL from the server.
-     * 2. Perform an HTTP PUT to upload the file’s raw bytes.
-     * 3. Return a UHRP URL referencing the file once published.
-     *
-     * @param {Object} params
-     * @param {UploadableFile} params.file - The file data + type
-     * @param {number} params.retentionPeriod - Number of minutes to host the file
-     * @returns {Promise<UploadFileResult>} An object with the file's UHRP URL
-     * @throws {Error} If the server or upload step returns a non-OK response
+     * Publishes a file across the cheapest configured providers, falling
+     * through to the next-cheapest quote if a paid upload fails. Throws when
+     * the resilience threshold cannot be met.
      */
     publishFile(params: {
         file: UploadableFile;
         retentionPeriod: number;
     }): Promise<UploadFileResult>;
+    private findFileAtHost;
+    private renewFileAtHost;
+    /** Intersects `hostedBy` with the configured host set; throws when empty. */
+    private resolveTargets;
     /**
-     * Retrieves metadata for a file matching the given UHRP URL from the `/find` route.
-     * @param {string} uhrpUrl - The UHRP URL, e.g. "uhrp://abcd..."
-     * @returns {Promise<FindFileData>} An object with file name, size, MIME type, and expiry time
-     * @throws {Error} If the server or the route returns an error
+     * Fans `/find` out across configured hosts (UHRP storage is host-local,
+     * so any one host may not know the file) and returns the record with the
+     * longest remaining expiry. Single-host configurations preserve the
+     * legacy error-message contract verbatim.
      */
-    findFile(uhrpUrl: string): Promise<FindFileData>;
+    findFile(uhrpUrl: string, options?: HostScopeOptions): Promise<FindFileData>;
     /**
-     * Lists all advertisements belonging to the user from the `/list` route.
-     * @returns {Promise<any>} The array of uploads returned by the server
-     * @throws {Error} If the server or the route returns an error
+     * Unions `/list` output across configured hosts, merging duplicate UHRP
+     * URLs by the longest expiry observed. One failing host does not hide
+     * the rest. Single-host configurations preserve the legacy error contract.
      */
-    listUploads(): Promise<any>;
+    listUploads(options?: HostScopeOptions): Promise<any>;
+    private listUploadsAtHost;
     /**
-     * Renews the hosting time for an existing file advertisement identified by uhrpUrl.
-     * Calls the `/renew` route to add `additionalMinutes` to the GCS customTime
-     * and re-mint the advertisement token on-chain.
-     *
-     * @param {string} uhrpUrl - The UHRP URL of the file (e.g., "uhrp://abcd1234...")
-     * @param {number} additionalMinutes - The number of minutes to extend
-     * @returns {Promise<RenewFileResult>} An object with the new and previous expiry times, plus any cost
-     * @throws {Error} If the request fails or the server returns an error
+     * Fans `/renew` out across every configured host (each provider owns its
+     * own advertisement, so a single-host renewal would degrade resilience
+     * over time). Hosts that do not carry the file are not billed. Throws
+     * {@link RenewResiliencyError} when successful renewals fall below the
+     * resilience threshold.
      */
-    renewFile(uhrpUrl: string, additionalMinutes: number): Promise<RenewFileResult>;
+    renewFile(uhrpUrl: string, additionalMinutes: number, options?: HostScopeOptions): Promise<RenewFileResult>;
 }
 //# sourceMappingURL=StorageUploader.d.ts.map

package/dist/types/src/storage/StorageUploader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StorageUploader.d.ts","sourceRoot":"","sources":["../../../../src/storage/StorageUploader.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAA;AAGhE,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,eAAe,CAAA;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,GAAG,MAAM,EAAE,CAAA;IAC3B,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,OAAO,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;GAMG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAEhC;;;OAGG;gBACU,MAAM,EAAE,cAAc;IAKnC;;;;;;;OAOG;YACW,aAAa;IAmC3B;;;;;;;;OAQG;YACW,UAAU;IA0BxB;;;;;;;;;;;;;OAaG;IACU,WAAW,CAAE,MAAM,EAAE;QAChC,IAAI,EAAE,cAAc,CAAA;QACpB,eAAe,EAAE,MAAM,CAAA;KACxB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAS7B;;;;;OAKG;IACU,QAAQ,CAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IA0B9D;;;;OAIG;IACU,WAAW,IAAK,OAAO,CAAC,GAAG,CAAC;IAkBzC;;;;;;;;;OASG;IACU,SAAS,CAAE,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;CAmC9F"}
+{"version":3,"file":"StorageUploader.d.ts","sourceRoot":"","sources":["../../../../src/storage/StorageUploader.ts"],"names":[],"mappings":"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"}

package/dist/types/src/storage/index.d.ts

@@ -1,4 +1,4 @@
 export * as StorageUtils from './StorageUtils.js';
-export { StorageUploader } from './StorageUploader.js';
+export { StorageUploader, DEFAULT_UHRP_SERVERS, RenewResiliencyError } from './StorageUploader.js';
 export { StorageDownloader } from './StorageDownloader.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/src/storage/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAEjD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAEtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAEjD,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAElG,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA"}

package/dist/types/src/wallet/WERR_REVIEW_ACTIONS.d.ts

@@ -1,7 +1,7 @@
 import { AtomicBEEF, OutpointString, ReviewActionResult, SendWithResult, TXIDHexString } from './Wallet.interfaces.js';
 /**
  * When a `createAction` or `signAction` is completed in undelayed mode (`acceptDelayedBroadcast`: false),
- * any unsucccessful result will return the results by way of this exception to ensure attention is
+ * any unsuccessful result will return the results by way of this exception to ensure attention is
  * paid to processing errors.
  */
 export declare class WERR_REVIEW_ACTIONS extends Error {
@@ -13,7 +13,7 @@ export declare class WERR_REVIEW_ACTIONS extends Error {
     code: number;
     isError: boolean;
     /**
-     * All parameters correspond to their comparable `createAction` or `signSction` results
+     * All parameters correspond to their comparable `createAction` or `signAction` results
      * with the exception of `reviewActionResults`;
      * which contains more details, particularly for double spend results.
      */

package/dist/types/src/wallet/Wallet.interfaces.d.ts

@@ -254,10 +254,10 @@ export interface SendWithResult {
 }
 /**
  * Indicates status of a new Action following a `createAction` or `signAction` in immediate mode:
- * When `acceptDelayedBroadcast` is falses.
+ * When `acceptDelayedBroadcast` is false.
  *
  * 'success': The action has been broadcast and accepted by the bitcoin processing network.
- * 'doulbeSpend': The action has been confirmed to double spend one or more inputs, and by the "first-seen-rule" is the loosing transaction.
+ * 'doubleSpend': The action has been confirmed to double spend one or more inputs, and by the "first-seen-rule" is the losing transaction.
  * 'invalidTx': The action was rejected by the processing network as an invalid bitcoin transaction.
  * 'serviceError': The broadcast services are currently unable to reach the bitcoin network. The action is now queued for delayed retries.
  */