@bsv/sdk 1.4.18 → 1.4.20

package/docs/kvstore.md

@@ -14,7 +14,7 @@ Allows setting, getting, and removing key-value pairs, with optional encryption.
 
 ```ts
 export default class LocalKVStore {
-    constructor(wallet: WalletInterface = new WalletClient(), context = "kvstore-default", encrypt = true, originator?: string) 
+    constructor(wallet: WalletInterface = new WalletClient(), context = "kvstore default", encrypt = true, originator?: string) 
     async get(key: string, defaultValue: string | undefined = undefined): Promise<string | undefined> 
     async set(key: string, value: string): Promise<OutpointString> 
     async remove(key: string): Promise<string[]> 
@@ -28,7 +28,7 @@ See also: [OutpointString](./wallet.md#type-outpointstring), [WalletClient](./wa
 Creates an instance of the localKVStore.
 
 ```ts
-constructor(wallet: WalletInterface = new WalletClient(), context = "kvstore-default", encrypt = true, originator?: string) 
+constructor(wallet: WalletInterface = new WalletClient(), context = "kvstore default", encrypt = true, originator?: string) 
 ```
 See also: [WalletClient](./wallet.md#class-walletclient), [WalletInterface](./wallet.md#interface-walletinterface), [encrypt](./messages.md#variable-encrypt)
 
@@ -37,7 +37,7 @@ Argument Details
 + **wallet**
   + The wallet interface to use. Defaults to a new WalletClient instance.
 + **context**
-  + The context (basket) for namespacing keys. Defaults to 'kvstore-default'.
+  + The context (basket) for namespacing keys. Defaults to 'kvstore default'.
 + **encrypt**
   + Whether to encrypt values. Defaults to true.
 + **originator**

package/docs/storage.md

@@ -8,6 +8,8 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 | --- |
 | [DownloadResult](#interface-downloadresult) |
 | [DownloaderConfig](#interface-downloaderconfig) |
+| [FindFileData](#interface-findfiledata) |
+| [RenewFileResult](#interface-renewfileresult) |
 | [UploadFileResult](#interface-uploadfileresult) |
 | [UploadableFile](#interface-uploadablefile) |
 | [UploaderConfig](#interface-uploaderconfig) |
@@ -38,6 +40,34 @@ export interface DownloaderConfig {
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
+---
+### Interface: FindFileData
+
+```ts
+export interface FindFileData {
+    name: string;
+    size: string;
+    mimeType: string;
+    expiryTime: number;
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Interface: RenewFileResult
+
+```ts
+export interface RenewFileResult {
+    status: string;
+    prevExpiryTime?: number;
+    newExpiryTime?: number;
+    amount?: number;
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
 ---
 ### Interface: UploadFileResult
 
@@ -107,6 +137,12 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ---
 ### Class: StorageUploader
 
+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
+
 ```ts
 export class StorageUploader {
     constructor(config: UploaderConfig) 
@@ -114,10 +150,65 @@ export class StorageUploader {
         file: UploadableFile;
         retentionPeriod: number;
     }): Promise<UploadFileResult> 
+    public async findFile(uhrpUrl: string): Promise<FindFileData> 
+    public async listUploads(): Promise<any> 
+    public async renewFile(uhrpUrl: string, additionalMinutes: number): Promise<RenewFileResult> 
 }
 ```
 
-See also: [UploadFileResult](./storage.md#interface-uploadfileresult), [UploadableFile](./storage.md#interface-uploadablefile), [UploaderConfig](./storage.md#interface-uploaderconfig)
+See also: [FindFileData](./storage.md#interface-findfiledata), [RenewFileResult](./storage.md#interface-renewfileresult), [UploadFileResult](./storage.md#interface-uploadfileresult), [UploadableFile](./storage.md#interface-uploadablefile), [UploaderConfig](./storage.md#interface-uploaderconfig)
+
+#### Constructor
+
+Creates a new StorageUploader instance.
+
+```ts
+constructor(config: UploaderConfig) 
+```
+See also: [UploaderConfig](./storage.md#interface-uploaderconfig)
+
+Argument Details
+
++ **config**
+  + An object containing the storage server's URL and a wallet interface
+
+#### Method findFile
+
+Retrieves metadata for a file matching the given UHRP URL from the `/find` route.
+
+```ts
+public async findFile(uhrpUrl: string): Promise<FindFileData> 
+```
+See also: [FindFileData](./storage.md#interface-findfiledata)
+
+Returns
+
+An object with file name, size, MIME type, and expiry time
+
+Argument Details
+
++ **uhrpUrl**
+  + The UHRP URL, e.g. "uhrp://abcd..."
+
+Throws
+
+If the server or the route returns an error
+
+#### Method listUploads
+
+Lists all advertisements belonging to the user from the `/list` route.
+
+```ts
+public async listUploads(): Promise<any> 
+```
+
+Returns
+
+The array of uploads returned by the server
+
+Throws
+
+If the server or the route returns an error
 
 #### Method publishFile
 
@@ -138,18 +229,37 @@ See also: [UploadFileResult](./storage.md#interface-uploadfileresult), [Uploadab
 
 Returns
 
-An object indicating whether the file was published successfully and the resulting UHRP URL.
+An object with the file's UHRP URL
+
+Throws
+
+If the server or upload step returns a non-OK response
+
+#### Method renewFile
+
+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.
+
+```ts
+public async renewFile(uhrpUrl: string, additionalMinutes: number): Promise<RenewFileResult> 
+```
+See also: [RenewFileResult](./storage.md#interface-renewfileresult)
+
+Returns
+
+An object with the new and previous expiry times, plus any cost
 
 Argument Details
 
-+ **params.file**
-  + An object describing the file’s data (number[] array of bytes) and mime type.
-+ **params.retentionPeriod**
-  + Number of minutes to keep the file hosted.
++ **uhrpUrl**
+  + The UHRP URL of the file (e.g., "uhrp://abcd1234...")
++ **additionalMinutes**
+  + The number of minutes to extend
 
 Throws
 
-If either the upload info request or the subsequent file upload request fails (non-OK HTTP status).
+If the request fails or the server returns an error
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "1.4.18",
+  "version": "1.4.20",
   "type": "module",
   "description": "BSV Blockchain Software Development Kit",
   "main": "dist/cjs/mod.js",

package/src/storage/StorageUploader.ts

@@ -17,15 +17,48 @@ export interface UploadFileResult {
   uhrpURL: string
 }
 
+export interface FindFileData {
+  name: string
+  size: string
+  mimeType: string
+  expiryTime: number
+}
+
+export interface RenewFileResult {
+  status: string
+  prevExpiryTime?: number
+  newExpiryTime?: number
+  amount?: number
+}
+
+/**
+ * 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
+ */
 export class StorageUploader {
   private readonly authFetch: AuthFetch
   private readonly baseURL: string
 
+  /**
+   * Creates a new StorageUploader instance.
+   * @param {UploaderConfig} config - An object containing the storage server's URL and a wallet interface
+   */
   constructor (config: UploaderConfig) {
     this.baseURL = config.storageURL
     this.authFetch = new AuthFetch(config.wallet)
   }
 
+  /**
+   * 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
+   */
   private async getUploadInfo (
     fileSize: number,
     retentionPeriod: number
@@ -61,6 +94,15 @@ export class StorageUploader {
     }
   }
 
+  /**
+   * 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
+   */
   private async uploadFile (
     uploadURL: string,
     file: UploadableFile,
@@ -88,20 +130,19 @@ export class StorageUploader {
   }
 
   /**
-     * 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 params.file - An object describing the file’s data (number[] array of bytes) and mime type.
-     * @param params.retentionPeriod - Number of minutes to keep the file hosted.
-     *
-     * @returns An object indicating whether the file was published successfully and the resulting UHRP URL.
-     *
-     * @throws If either the upload info request or the subsequent file upload request fails (non-OK HTTP status).
-     */
+   * 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
+   */
   public async publishFile (params: {
     file: UploadableFile
     retentionPeriod: number
@@ -112,4 +153,105 @@ export class StorageUploader {
     const { uploadURL, requiredHeaders } = await this.getUploadInfo(fileSize, retentionPeriod)
     return await this.uploadFile(uploadURL, file, requiredHeaders)
   }
+
+  /**
+   * 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
+   */
+  public async findFile (uhrpUrl: string): Promise<FindFileData> {
+    const url = new URL(`${this.baseURL}/find`)
+    url.searchParams.set('uhrpUrl', uhrpUrl)
+
+    const response = await this.authFetch.fetch(url.toString(), {
+      method: 'GET'
+    })
+    if (!response.ok) {
+      throw new Error(`findFile request failed: HTTP ${response.status}`)
+    }
+
+    const data = await response.json() as {
+      status: string
+      data: { name: string, size: string, mimeType: string, expiryTime: number }
+      code?: string
+      description?: string
+    }
+
+    if (data.status === 'error') {
+      const errCode = data.code ?? 'unknown-code'
+      const errDesc = data.description ?? 'no-description'
+      throw new Error(`findFile returned an error: ${errCode} - ${errDesc}`)
+    }
+    return data.data
+  }
+
+  /**
+   * 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
+   */
+  public async listUploads (): Promise<any> {
+    const url = `${this.baseURL}/list`
+    const response = await this.authFetch.fetch(url, {
+      method: 'GET'
+    })
+    if (!response.ok) {
+      throw new Error(`listUploads request failed: HTTP ${response.status}`)
+    }
+
+    const data = await response.json()
+    if (data.status === 'error') {
+      const errCode = data.code as string ?? 'unknown-code'
+      const errDesc = data.description as string ?? 'no-description'
+      throw new Error(`listUploads returned an error: ${errCode} - ${errDesc}`)
+    }
+    return data.uploads
+  }
+
+  /**
+   * 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
+   */
+  public async renewFile (uhrpUrl: string, additionalMinutes: number): Promise<RenewFileResult> {
+    const url = `${this.baseURL}/renew`
+    const body = { uhrpUrl, additionalMinutes }
+
+    const response = await this.authFetch.fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body)
+    })
+    if (!response.ok) {
+      throw new Error(`renewFile request failed: HTTP ${response.status}`)
+    }
+
+    const data = await response.json() as {
+      status: string
+      prevExpiryTime?: number
+      newExpiryTime?: number
+      amount?: number
+      code?: string
+      description?: string
+    }
+
+    if (data.status === 'error') {
+      const errCode = data.code ?? 'unknown-code'
+      const errDesc = data.description ?? 'no-description'
+      throw new Error(`renewFile returned an error: ${errCode} - ${errDesc}`)
+    }
+
+    return {
+      status: data.status,
+      prevExpiryTime: data.prevExpiryTime,
+      newExpiryTime: data.newExpiryTime,
+      amount: data.amount
+    }
+  }
 }

package/src/storage/__test/StorageUploader.test.ts

@@ -2,7 +2,9 @@ import { StorageUploader } from '../StorageUploader.js'
 import * as StorageUtils from '../StorageUtils.js'
 import WalletClient from '../../wallet/WalletClient.js'
 
-// A helper for converting a string to a number[] of UTF-8 bytes
+/**
+ * A helper for converting a string to a number[] of UTF-8 bytes
+ */
 function stringToUtf8Array(str: string): number[] {
   return Array.from(new TextEncoder().encode(str))
 }
@@ -10,16 +12,24 @@ function stringToUtf8Array(str: string): number[] {
 describe('StorageUploader Tests', () => {
   let uploader: StorageUploader
   let walletClient: WalletClient
+
+  // We'll have TWO spies:
+  let authFetchSpy: jest.SpiedFunction<typeof global.fetch>
   let globalFetchSpy: jest.SpiedFunction<typeof global.fetch>
 
   beforeEach(() => {
     walletClient = new WalletClient('json-api', 'non-admin.com')
-
     uploader = new StorageUploader({
       storageURL: 'https://example.test.system',
       wallet: walletClient
     })
 
+    // 1) Spy on the "authFetch.fetch" calls for /find, /list, /renew
+    authFetchSpy = jest
+      .spyOn(uploader['authFetch'], 'fetch')
+      .mockResolvedValue(new Response(null, { status: 200 }))
+
+    // 2) Spy on the global "fetch" calls for file upload (uploadFile)
     globalFetchSpy = jest
       .spyOn(global, 'fetch')
       .mockResolvedValue(new Response(null, { status: 200 }))
@@ -34,47 +44,156 @@ describe('StorageUploader Tests', () => {
 
     // Mock out getUploadInfo so we can control the returned upload/public URLs
     jest.spyOn(uploader as any, 'getUploadInfo').mockResolvedValue({
-      uploadURL: 'https://example-upload.com/put',
+      uploadURL: 'https://example-upload.com/put'
     })
 
     const result = await uploader.publishFile({
-      file: {
-        data,
-        type: 'text/plain'
-      },
+      file: { data, type: 'text/plain' },
       retentionPeriod: 7
     })
 
-    // We expect exactly one PUT request
+    // This direct upload uses global.fetch, not authFetch
     expect(globalFetchSpy).toHaveBeenCalledTimes(1)
+
     // Check the result
     expect(StorageUtils.isValidURL(result.uhrpURL)).toBe(true)
     expect(result.published).toBe(true)
 
     const url = StorageUtils.getHashFromURL(result.uhrpURL)
-    const firstFour = url.slice(0, 4).map(b => b.toString(16).padStart(2, '0')).join('')
+    const firstFour = url.slice(0, 4)
+      .map(b => b.toString(16).padStart(2, '0'))
+      .join('')
     expect(firstFour).toHaveLength(8)
   })
 
   it('should throw if the upload fails with HTTP 500', async () => {
-    // Force the fetch to fail
+    // Force the direct upload (global fetch) to fail
     globalFetchSpy.mockResolvedValueOnce(new Response(null, { status: 500 }))
 
     // Also mock getUploadInfo
     jest.spyOn(uploader as any, 'getUploadInfo').mockResolvedValue({
-      uploadURL: 'https://example-upload.com/put',
+      uploadURL: 'https://example-upload.com/put'
     })
 
     const failingData = stringToUtf8Array('failing data')
 
     await expect(
       uploader.publishFile({
-        file: {
-          data: failingData,
-          type: 'text/plain'
-        },
+        file: { data: failingData, type: 'text/plain' },
         retentionPeriod: 30
       })
     ).rejects.toThrow('File upload failed: HTTP 500')
   })
+
+  it('should find a file and return metadata', async () => {
+    // This route goes through authFetch, not global fetch
+    authFetchSpy.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          status: 'success',
+          data: {
+            name: 'cdn/abc123',
+            size: '1024',
+            mimeType: 'text/plain',
+            expiryTime: 123456
+          }
+        }),
+        { status: 200 }
+      )
+    )
+
+    const fileData = await uploader.findFile('uhrp://some-hash')
+    expect(authFetchSpy).toHaveBeenCalledTimes(1)
+    expect(fileData.name).toBe('cdn/abc123')
+    expect(fileData.size).toBe('1024')
+    expect(fileData.mimeType).toBe('text/plain')
+    expect(fileData.expiryTime).toBe(123456)
+  })
+
+  it('should throw an error if findFile returns an error status', async () => {
+    authFetchSpy.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({ status: 'error', code: 'ERR_NOT_FOUND', description: 'File not found' }),
+        { status: 200 }
+      )
+    )
+
+    await expect(uploader.findFile('uhrp://unknown-hash'))
+      .rejects
+      .toThrow('findFile returned an error: ERR_NOT_FOUND - File not found')
+  })
+
+  it('should list user uploads successfully', async () => {
+    // /list uses authFetch
+    const mockUploads = [
+      { uhrpUrl: 'uhrp://hash1', expiryTime: 111111 },
+      { uhrpUrl: 'uhrp://hash2', expiryTime: 222222 }
+    ]
+    authFetchSpy.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({ status: 'success', uploads: mockUploads }),
+        { status: 200 }
+      )
+    )
+
+    const result = await uploader.listUploads()
+    expect(authFetchSpy).toHaveBeenCalledTimes(1)
+    expect(result).toEqual(mockUploads)
+  })
+
+  it('should throw an error if listUploads returns an error', async () => {
+    authFetchSpy.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({ status: 'error', code: 'ERR_INTERNAL', description: 'Something broke' }),
+        { status: 200 }
+      )
+    )
+
+    await expect(uploader.listUploads()).rejects.toThrow(
+      'listUploads returned an error: ERR_INTERNAL - Something broke'
+    )
+  })
+
+  it('should renew a file and return the new expiry info', async () => {
+    // /renew uses authFetch
+    authFetchSpy.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          status: 'success',
+          prevExpiryTime: 123,
+          newExpiryTime: 456,
+          amount: 99
+        }),
+        { status: 200 }
+      )
+    )
+
+    const renewal = await uploader.renewFile('uhrp://some-hash', 30)
+    expect(authFetchSpy).toHaveBeenCalledTimes(1)
+    expect(renewal.status).toBe('success')
+    expect(renewal.prevExpiryTime).toBe(123)
+    expect(renewal.newExpiryTime).toBe(456)
+    expect(renewal.amount).toBe(99)
+  })
+
+  it('should throw an error if renewFile returns error status JSON', async () => {
+    authFetchSpy.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({ status: 'error', code: 'ERR_CANT_RENEW', description: 'Failed to renew' }),
+        { status: 200 }
+      )
+    )
+
+    await expect(uploader.renewFile('uhrp://some-other-hash', 15))
+      .rejects
+      .toThrow('renewFile returned an error: ERR_CANT_RENEW - Failed to renew')
+  })
+
+  it('should throw if renewFile request fails with non-200 status', async () => {
+    authFetchSpy.mockResolvedValueOnce(new Response(null, { status: 404 }))
+
+    await expect(uploader.renewFile('uhrp://ghost', 10))
+      .rejects
+      .toThrow('renewFile request failed: HTTP 404')
+  })
 })

package/src/wallet/substrates/index.ts

@@ -5,3 +5,4 @@ export * from './WalletWireCalls.js'
 export { default as WalletWireTransceiver } from './WalletWireTransceiver.js'
 export { default as WalletWireProcessor } from './WalletWireProcessor.js'
 export { default as HTTPWalletWire } from './HTTPWalletWire.js'
+export { default as HTTPWalletJSON } from './HTTPWalletJSON.js'