@bsv/wallet-toolbox-client/out/src/storage/remoting/StorageClient.d.ts

Client only Wallet Storage

import { AbortActionArgs, AbortActionResult, InternalizeActionArgs, ListActionsResult, ListCertificatesResult, ListOutputsResult, RelinquishCertificateArgs, RelinquishOutputArgs, WalletInterface } from '@bsv/sdk';
import { AuthId, FindCertificatesArgs, FindOutputBasketsArgs, FindOutputsArgs, FindProvenTxReqsArgs, ProcessSyncChunkResult, RequestSyncChunkArgs, StorageCreateActionResult, StorageInternalizeActionResult, StorageProcessActionArgs, StorageProcessActionResults, SyncChunk, UpdateProvenTxReqWithNewProvenTxArgs, UpdateProvenTxReqWithNewProvenTxResult, WalletStorageProvider } from '../../sdk/WalletStorage.interfaces';
import { TableSettings } from '../schema/tables/TableSettings';
import { WalletServices } from '../../sdk/WalletServices.interfaces';
import { ValidCreateActionArgs, ValidListActionsArgs, ValidListCertificatesArgs, ValidListOutputsArgs } from '../../sdk/validationHelpers';
import { TableUser } from '../schema/tables/TableUser';
import { TableSyncState } from '../schema/tables/TableSyncState';
import { TableCertificateX } from '../schema/tables/TableCertificate';
import { TableOutputBasket } from '../schema/tables/TableOutputBasket';
import { TableOutput } from '../schema/tables/TableOutput';
import { TableProvenTxReq } from '../schema/tables/TableProvenTxReq';
import { EntityTimeStamp } from '../../sdk/types';
/**
 * `StorageClient` implements the `WalletStorageProvider` interface which allows it to
 * serve as a BRC-100 wallet's active storage.
 *
 * Internally, it uses JSON-RPC over HTTPS to make requests of a remote server.
 * Typically this server uses the `StorageServer` class to implement the service.
 *
 * The `AuthFetch` component is used to secure and authenticate the requests to the remote server.
 *
 * `AuthFetch` is initialized with a BRC-100 wallet which establishes the identity of
 * the party making requests of the remote service.
 *
 * For details of the API implemented, follow the "See also" link for the `WalletStorageProvider` interface.
 */
export declare class StorageClient implements WalletStorageProvider {
    readonly endpointUrl: string;
    private readonly authClient;
    private nextId;
    settings?: TableSettings;
    constructor(wallet: WalletInterface, endpointUrl: string);
    /**
     * The `StorageClient` implements the `WalletStorageProvider` interface.
     * It does not implement the lower level `StorageProvider` interface.
     *
     * @returns false
     */
    isStorageProvider(): boolean;
    /**
     * Make a JSON-RPC call to the remote server.
     * @param method The WalletStorage method name to call.
     * @param params The array of parameters to pass to the method in order.
     */
    private rpcCall;
    /**
     * @returns true once storage `TableSettings` have been retreived from remote storage.
     */
    isAvailable(): boolean;
    /**
     * @returns remote storage `TableSettings` if they have been retreived by `makeAvailable`.
     * @throws WERR_INVALID_OPERATION if `makeAvailable` has not yet been called.
     */
    getSettings(): TableSettings;
    /**
     * Must be called prior to making use of storage.
     * Retreives `TableSettings` from remote storage provider.
     * @returns remote storage `TableSettings`
     */
    makeAvailable(): Promise<TableSettings>;
    /**
     * Called to cleanup resources when no further use of this object will occur.
     */
    destroy(): Promise<void>;
    /**
     * Requests schema migration to latest.
     * Typically remote storage will ignore this request.
     * @param storageName Unique human readable name for remote storage if it does not yet exist.
     * @param storageIdentityKey Unique identity key for remote storage if it does not yet exist.
     * @returns current schema migration identifier
     */
    migrate(storageName: string, storageIdentityKey: string): Promise<string>;
    /**
     * Remote storage does not offer `Services` to remote clients.
     * @throws WERR_INVALID_OPERATION
     */
    getServices(): WalletServices;
    /**
     * Ignored. Remote storage cannot share `Services` with remote clients.
     */
    setServices(v: WalletServices): void;
    /**
     * Storage level processing for wallet `internalizeAction`.
     * Updates internalized outputs in remote storage.
     * Triggers proof validation of containing transaction.
     * @param auth Identifies client by identity key and the storage identity key of their currently active storage.
     * This must match the `AuthFetch` identity securing the remote conneciton.
     * @param args Original wallet `internalizeAction` arguments.
     * @returns `internalizeAction` results
     */
    internalizeAction(auth: AuthId, args: InternalizeActionArgs): Promise<StorageInternalizeActionResult>;
    /**
     * Storage level processing for wallet `createAction`.
     * @param auth Identifies client by identity key and the storage identity key of their currently active storage.
     * This must match the `AuthFetch` identity securing the remote conneciton.
     * @param args Validated extension of original wallet `createAction` arguments.
     * @returns `StorageCreateActionResults` supporting additional wallet processing to yield `createAction` results.
     */
    createAction(auth: AuthId, args: ValidCreateActionArgs): Promise<StorageCreateActionResult>;
    /**
     * Storage level processing for wallet `createAction` and `signAction`.
     *
     * Handles remaining storage tasks once a fully signed transaction has been completed. This is common to both `createAction` and `signAction`.
     *
     * @param auth Identifies client by identity key and the storage identity key of their currently active storage.
     * This must match the `AuthFetch` identity securing the remote conneciton.
     * @param args `StorageProcessActionArgs` convey completed signed transaction to storage.
     * @returns `StorageProcessActionResults` supporting final wallet processing to yield `createAction` or `signAction` results.
     */
    processAction(auth: AuthId, args: StorageProcessActionArgs): Promise<StorageProcessActionResults>;
    /**
     * Aborts an action by `reference` string.
     * @param auth Identifies client by identity key and the storage identity key of their currently active storage.
     * This must match the `AuthFetch` identity securing the remote conneciton.
     * @param args original wallet `abortAction` args.
     * @returns `abortAction` result.
     */
    abortAction(auth: AuthId, args: AbortActionArgs): Promise<AbortActionResult>;
    /**
     * Used to both find and initialize a new user by identity key.
     * It is up to the remote storage whether to allow creation of new users by this method.
     * @param identityKey of the user.
     * @returns `TableUser` for the user and whether a new user was created.
     */
    findOrInsertUser(identityKey: any): Promise<{
        user: TableUser;
        isNew: boolean;
    }>;
    /**
     * Used to both find and insert a `TableSyncState` record for the user to track wallet data replication across storage providers.
     * @param auth Identifies client by identity key and the storage identity key of their currently active storage.
     * This must match the `AuthFetch` identity securing the remote conneciton.
     * @param storageName the name of the remote storage being sync'd
     * @param storageIdentityKey the identity key of the remote storage being sync'd
     * @returns `TableSyncState` and whether a new record was created.
     */
    findOrInsertSyncStateAuth(auth: AuthId, storageIdentityKey: string, storageName: string): Promise<{
        syncState: TableSyncState;
        isNew: boolean;
    }>;
    /**
     * Inserts a new certificate with fields and keyring into remote storage.
     * @param auth Identifies client by identity key and the storage identity key of their currently active storage.
     * This must match the `AuthFetch` identity securing the remote conneciton.
     * @param certificate the certificate to insert.
     * @returns record Id of the inserted `TableCertificate` record.
     */
    insertCertificateAuth(auth: AuthId, certificate: TableCertificateX): Promise<number>;
    /**
     * Storage level processing for wallet `listActions`.
     * @param auth Identifies client by identity key and the storage identity key of their currently active storage.
     * This must match the `AuthFetch` identity securing the remote conneciton.
     * @param args Validated extension of original wallet `listActions` arguments.
     * @returns `listActions` results.
     */
    listActions(auth: AuthId, vargs: ValidListActionsArgs): Promise<ListActionsResult>;
    /**
     * Storage level processing for wallet `listOutputs`.
     * @param auth Identifies client by identity key and the storage identity key of their currently active storage.
     * This must match the `AuthFetch` identity securing the remote conneciton.
     * @param args Validated extension of original wallet `listOutputs` arguments.
     * @returns `listOutputs` results.
     */
    listOutputs(auth: AuthId, vargs: ValidListOutputsArgs): Promise<ListOutputsResult>;
    /**
     * Storage level processing for wallet `listCertificates`.
     * @param auth Identifies client by identity key and the storage identity key of their currently active storage.
     * This must match the `AuthFetch` identity securing the remote conneciton.
     * @param args Validated extension of original wallet `listCertificates` arguments.
     * @returns `listCertificates` results.
     */
    listCertificates(auth: AuthId, vargs: ValidListCertificatesArgs): Promise<ListCertificatesResult>;
    /**
     * Find user certificates, optionally with fields.
     *
     * This certificate retrieval method supports internal wallet operations.
     * Field values are stored and retrieved encrypted.
     *
     * @param auth Identifies client by identity key and the storage identity key of their currently active storage.
     * This must match the `AuthFetch` identity securing the remote conneciton.
     * @param args `FindCertificatesArgs` determines which certificates to retrieve and whether to include fields.
     * @returns array of certificates matching args.
     */
    findCertificatesAuth(auth: AuthId, args: FindCertificatesArgs): Promise<TableCertificateX[]>;
    /**
     * Find output baskets.
     *
     * This retrieval method supports internal wallet operations.
     *
     * @param auth Identifies client by identity key and the storage identity key of their currently active storage.
     * This must match the `AuthFetch` identity securing the remote conneciton.
     * @param args `FindOutputBasketsArgs` determines which baskets to retrieve.
     * @returns array of output baskets matching args.
     */
    findOutputBasketsAuth(auth: AuthId, args: FindOutputBasketsArgs): Promise<TableOutputBasket[]>;
    /**
     * Find outputs.
     *
     * This retrieval method supports internal wallet operations.
     *
     * @param auth Identifies client by identity key and the storage identity key of their currently active storage.
     * This must match the `AuthFetch` identity securing the remote conneciton.
     * @param args `FindOutputsArgs` determines which outputs to retrieve.
     * @returns array of outputs matching args.
     */
    findOutputsAuth(auth: AuthId, args: FindOutputsArgs): Promise<TableOutput[]>;
    /**
     * Find requests for transaction proofs.
     *
     * This retrieval method supports internal wallet operations.
     *
     * @param auth Identifies client by identity key and the storage identity key of their currently active storage.
     * This must match the `AuthFetch` identity securing the remote conneciton.
     * @param args `FindProvenTxReqsArgs` determines which proof requests to retrieve.
     * @returns array of proof requests matching args.
     */
    findProvenTxReqs(args: FindProvenTxReqsArgs): Promise<TableProvenTxReq[]>;
    /**
     * Relinquish a certificate.
     *
     * For storage supporting replication records must be kept of deletions. Therefore certificates are marked as deleted
     * when relinquished, and no longer returned by `listCertificates`, but are still retained by storage.
     *
     * @param auth Identifies client by identity key and the storage identity key of their currently active storage.
     * This must match the `AuthFetch` identity securing the remote conneciton.
     * @param args original wallet `relinquishCertificate` args.
     */
    relinquishCertificate(auth: AuthId, args: RelinquishCertificateArgs): Promise<number>;
    /**
     * Relinquish an output.
     *
     * Relinquishing an output removes the output from whatever basket was tracking it.
     *
     * @param auth Identifies client by identity key and the storage identity key of their currently active storage.
     * This must match the `AuthFetch` identity securing the remote conneciton.
     * @param args original wallet `relinquishOutput` args.
     */
    relinquishOutput(auth: AuthId, args: RelinquishOutputArgs): Promise<number>;
    /**
     * Process a "chunk" of replication data for the user.
     *
     * The normal data flow is for the active storage to push backups as a sequence of data chunks to backup storage providers.
     *
     * @param args a copy of the replication request args that initiated the sequence of data chunks.
     * @param chunk the current data chunk to process.
     * @returns whether processing is done, counts of inserts and udpates, and related progress tracking properties.
     */
    processSyncChunk(args: RequestSyncChunkArgs, chunk: SyncChunk): Promise<ProcessSyncChunkResult>;
    /**
     * Request a "chunk" of replication data for a specific user and storage provider.
     *
     * The normal data flow is for the active storage to push backups as a sequence of data chunks to backup storage providers.
     * Also supports recovery where non-active storage can attempt to merge available data prior to becoming active.
     *
     * @param args that identify the non-active storage which will receive replication data and constrains the replication process.
     * @returns the next "chunk" of replication data
     */
    getSyncChunk(args: RequestSyncChunkArgs): Promise<SyncChunk>;
    /**
     * Handles the data received when a new transaction proof is found in response to an outstanding request for proof data:
     *
     *   - Creates a new `TableProvenTx` record.
     *   - Notifies all user transaction records of the new status.
     *   - Updates the proof request record to 'completed' status which enables delayed deletion.
     *
     * @param args proof request and new transaction proof data
     * @returns results of updates
     */
    updateProvenTxReqWithNewProvenTx(args: UpdateProvenTxReqWithNewProvenTxArgs): Promise<UpdateProvenTxReqWithNewProvenTxResult>;
    /**
     * Ensures up-to-date wallet data replication to all configured backup storage providers,
     * then promotes one of the configured backups to active,
     * demoting the current active to new backup.
     *
     * @param auth Identifies client by identity key and the storage identity key of their currently active storage.
     * This must match the `AuthFetch` identity securing the remote conneciton.
     * @param newActiveStorageIdentityKey which must be a currently configured backup storage provider.
     */
    setActive(auth: AuthId, newActiveStorageIdentityKey: string): Promise<number>;
    validateDate(date: Date | string | number): Date;
    /**
     * Helper to force uniform behavior across database engines.
     * Use to process all individual records with time stamps retreived from database.
     */
    validateEntity<T extends EntityTimeStamp>(entity: T, dateFields?: string[]): T;
    /**
     * Helper to force uniform behavior across database engines.
     * Use to process all arrays of records with time stamps retreived from database.
     * @returns input `entities` array with contained values validated.
     */
    validateEntities<T extends EntityTimeStamp>(entities: T[], dateFields?: string[]): T[];
}
//# sourceMappingURL=StorageClient.d.ts.map