@bopen-io/wallet-toolbox 1.7.18 → 1.7.19

package/out/src/storage/remoting/StorageMobile.d.ts

@@ -0,0 +1,292 @@
+import { AbortActionArgs, AbortActionResult, InternalizeActionArgs, ListActionsResult, ListCertificatesResult, ListOutputsResult, RelinquishCertificateArgs, RelinquishOutputArgs, WalletInterface, Validation } from '@bsv/sdk';
+import { AuthId, FindCertificatesArgs, FindOutputBasketsArgs, FindOutputsArgs, FindProvenTxReqsArgs, ProcessSyncChunkResult, RequestSyncChunkArgs, StorageCreateActionResult, StorageInternalizeActionResult, StorageProcessActionArgs, StorageProcessActionResults, SyncChunk, UpdateProvenTxReqWithNewProvenTxArgs, UpdateProvenTxReqWithNewProvenTxResult, WalletStorageProvider } from '../../sdk/WalletStorage.interfaces';
+import { WalletServices } from '../../sdk/WalletServices.interfaces';
+import { TableSettings } from '../schema/tables/TableSettings';
+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: Validation.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: Validation.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: Validation.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: Validation.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=StorageMobile.d.ts.map

package/out/src/storage/remoting/StorageMobile.d.ts.map

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