@docknetwork/wallet-sdk-core 1.5.14 → 1.7.6

package/src/did-provider.ts

@@ -1,7 +1,18 @@
-import {IWallet} from './types';
+/**
+ * @module did-provider
+ * @description DID (Decentralized Identifier) management functionality for the Truvera Wallet SDK.
+ * This module provides functions for creating, importing, exporting, and managing DIDs.
+ */
+
+import {IWallet, IDIDProvider} from './types';
+export type {IDIDProvider};
 import {didServiceRPC} from '@docknetwork/wallet-sdk-wasm/src/services/dids/index';
 import assert from 'assert';
 
+/**
+ * Internal function to import a DID from an encrypted wallet JSON
+ * @private
+ */
 export async function importDID({
   wallet,
   encryptedJSONWallet,
@@ -30,15 +41,12 @@ export async function importDID({
     });
 
     for (const doc of docs) {
-      const existingDocs = await wallet.query({
-        id: doc.id,
-      });
+      const existingDoc = await wallet.getDocumentById(doc.id);
 
-      if (existingDocs.length === 0) {
+      if (!existingDoc) {
         await wallet.addDocument(doc);
       } else if (
-        existingDocs.length > 0 &&
-        existingDocs[0].type === 'DIDResolutionResponse'
+        existingDoc.type === 'DIDResolutionResponse'
       ) {
         throw new Error('DID already exists in wallet');
       }
@@ -54,14 +62,15 @@ export async function importDID({
   }
 }
 
+/**
+ * Internal function to edit a DID document's name
+ * @private
+ */
 async function editDID({wallet, id, name}){
   if (typeof id === 'string' && id.length > 0) {
-    const docs = await wallet.query({
-      id,
-    });
-    if (docs.length === 1) {
-      const doc = docs[0];
-      await wallet.update({
+    const doc = await wallet.getDocumentById(id);
+    if (doc) {
+      await wallet.updateDocument({
         ...doc,
         name,
       });
@@ -71,19 +80,27 @@ async function editDID({wallet, id, name}){
   }
 };
 
+/**
+ * Internal function to delete a DID from the wallet
+ * @private
+ */
 async function deleteDID({wallet, id}){
   if (typeof id === 'string' && id.length > 0) {
-    return await wallet.remove(id);
+    return await wallet.removeDocument(id);
   } else {
     throw Error('Document ID is not set');
   }
 }
 
+/**
+ * Internal function to export a DID and its correlated documents
+ * @private
+ */
 async function exportDID({wallet, id, password }){
   const existingDoc = await wallet.getDocumentById(id);
   if (existingDoc) {
     const allCorrelationDocuments = (
-      await wallet.resolveCorrelations(id)
+      await wallet.getDocumentCorrelations(id)
     ).filter(doc => doc && doc?.id !== existingDoc.id);
     const documentsToExport = [existingDoc, ...allCorrelationDocuments];
 
@@ -99,6 +116,10 @@ async function exportDID({wallet, id, password }){
   throw new Error('DID Document not found');
 }
 
+/**
+ * Internal function to create a DID document from a keypair document
+ * @private
+ */
 export const createDIDKeyDocument = async (
   keypairDoc: any,
   didDocParams: any = {},
@@ -126,6 +147,10 @@ export const createDIDKeyDocument = async (
   };
 };
 
+/**
+ * Internal function to create a new DID:key with an associated keypair
+ * @private
+ */
 export async function createDIDKey({wallet, name, derivePath=undefined, type=undefined}) {
   assert(!!wallet, 'wallet is required');
   assert(!!name, 'name is required');
@@ -146,10 +171,8 @@ export async function createDIDKey({wallet, name, derivePath=undefined, type=und
 }
 
 /**
- * Get DIDs list
- *
- * @param param0
- * @returns
+ * Internal function to retrieve all DIDs stored in the wallet
+ * @private
  */
 export async function getAll({wallet}) {
   assert(!!wallet, 'wallet is required');
@@ -157,12 +180,20 @@ export async function getAll({wallet}) {
   return dids;
 }
 
+/**
+ * Internal function to get the default DID from the wallet
+ * @private
+ */
 export async function getDefaultDID({wallet}) {
   assert(!!wallet, 'wallet is required');
   const allDids = await getAll({ wallet });
   return allDids[0]?.didDocument.id;
 }
 
+/**
+ * Internal function to retrieve all keypairs associated with DIDs
+ * @private
+ */
 export async function getDIDKeyPairs({wallet}) {
   assert(!!wallet, 'wallet is required');
   const didDocs = await getAll({wallet});
@@ -174,6 +205,7 @@ export async function getDIDKeyPairs({wallet}) {
   return keyPairs;
 }
 
+
 export async function ensureDID({wallet}) {
   assert(!!wallet, 'wallet is required');
   const dids = await getAll({wallet});
@@ -182,49 +214,166 @@ export async function ensureDID({wallet}) {
   }
 }
 
-export interface IDIDProvider {
-  importDID(params: {
-    encryptedJSONWallet: any;
-    password: string;
-  }): Promise<void>;
-  createDIDKey(params: {name: string, derivePath?:string, type?: string}): Promise<any>;
-  editDID(params: {id: string; name: string}): Promise<void>;
-  deleteDID(params: {id: string;}): Promise<void>;
-  exportDID(params: {id: string; password: string}): Promise<void>;
-  getAll(): Promise<any>;
-  getDIDKeyPairs(): Promise<any>;
-  ensureDID(): Promise<any>;
-  getDefaultDID(): Promise<string>;
-}
 
+/**
+ * Creates a DID provider instance bound to a wallet
+ * @param {Object} params - Provider configuration
+ * @param {IWallet} params.wallet - The wallet instance to bind the provider to
+ * @returns {IDIDProvider} A DID provider instance with all DID management methods
+ * @see {@link IDIDProvider} - The interface defining all available DID provider methods
+ * @example
+ * import { createDIDProvider } from '@docknetwork/wallet-sdk-core';
+ *
+ * const didProvider = createDIDProvider({wallet});
+ *
+ * // Create a new DID
+ * const {keyDoc, didDocumentResolution} = await didProvider.createDIDKey({
+ *   name: 'My DID'
+ * });
+ *
+ * // Get all DIDs
+ * const allDIDs = await didProvider.getAll();
+ *
+ * // Export a DID
+ * const exportedDID = await didProvider.exportDID({
+ *   id: didDocumentResolution.id,
+ *   password: 'mypassword'
+ * });
+ */
 export function createDIDProvider({wallet}): IDIDProvider {
-  return {
+  const provider = {
+    /**
+     * Imports a DID from an encrypted wallet JSON
+     * @memberof IDIDProvider
+     * @param {Object} params - Import parameters
+     * @param {any} params.encryptedJSONWallet - The encrypted wallet JSON containing the DID
+     * @param {string} params.password - Password to decrypt the wallet
+     * @returns {Promise<any[]>} Array of imported documents
+     * @throws {Error} If password is incorrect or DID already exists in wallet
+     * @example
+     * const importedDocs = await didProvider.importDID({
+     *   encryptedJSONWallet: encryptedBackup,
+     *   password: 'mypassword'
+     * });
+     */
     async importDID({encryptedJSONWallet, password}) {
       return importDID({wallet, encryptedJSONWallet, password});
     },
+    /**
+     * Creates a new DID:key with an associated keypair
+     * @memberof IDIDProvider
+     * @param {Object} params - Creation parameters
+     * @param {string} params.name - The name for the new DID
+     * @param {string} [params.derivePath] - Optional derivation path for the keypair
+     * @param {string} [params.type] - Optional key type specification
+     * @returns {Promise<{keyDoc: any, didDocumentResolution: any}>} The created keypair and DID document
+     * @throws {Error} If name is not provided
+     * @example
+     * const {keyDoc, didDocumentResolution} = await didProvider.createDIDKey({
+     *   name: 'My Identity DID',
+     *   derivePath: "m/44'/60'/0'/0/0"
+     * });
+     */
     async createDIDKey({name, derivePath, type}) {
       return createDIDKey({wallet, name, derivePath, type});
     },
+    /**
+     * Edits a DID document's name
+     * @memberof IDIDProvider
+     * @param {Object} params - Edit parameters
+     * @param {string} params.id - The ID of the DID document to edit
+     * @param {string} params.name - The new name for the DID
+     * @returns {Promise<void>}
+     * @throws {Error} If document ID is not set or document not found
+     * @example
+     * await didProvider.editDID({
+     *   id: 'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK',
+     *   name: 'Updated DID Name'
+     * });
+     */
     async editDID(params) {
       return editDID({wallet, ...params});
     },
+    /**
+     * Deletes a DID from the wallet
+     * @memberof IDIDProvider
+     * @param {Object} params - Delete parameters
+     * @param {string} params.id - The ID of the DID document to delete
+     * @returns {Promise<void>}
+     * @throws {Error} If document ID is not set
+     * @example
+     * await didProvider.deleteDID({
+     *   id: 'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK'
+     * });
+     */
     async deleteDID(params) {
       return deleteDID({wallet, ...params});
     },
+    /**
+     * Exports a DID and its correlated documents as an encrypted JSON
+     * @memberof IDIDProvider
+     * @param {Object} params - Export parameters
+     * @param {string} params.id - The ID of the DID document to export
+     * @param {string} params.password - Password for encryption
+     * @returns {Promise<any>} Encrypted wallet JSON containing the DID and correlations
+     * @throws {Error} If DID document or keypair not found
+     * @example
+     * const exportedDID = await didProvider.exportDID({
+     *   id: 'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK',
+     *   password: 'mypassword'
+     * });
+     */
     async exportDID(params) {
       return exportDID({wallet, ...params});
     },
+    /**
+     * Retrieves all DIDs stored in the wallet
+     * @memberof IDIDProvider
+     * @returns {Promise<any[]>} Array of DID resolution response documents
+     * @example
+     * const allDIDs = await didProvider.getAll();
+     * console.log(`Found ${allDIDs.length} DIDs in wallet`);
+     */
     async getAll() {
       return getAll({wallet});
     },
+    /**
+     * Retrieves all keypairs associated with DIDs in the wallet
+     * @memberof IDIDProvider
+     * @returns {Promise<any[]>} Array of keypair documents
+     * @example
+     * const keyPairs = await didProvider.getDIDKeyPairs();
+     * console.log(`Found ${keyPairs.length} DID keypairs`);
+     */
     async getDIDKeyPairs() {
       return getDIDKeyPairs({wallet});
     },
+    /**
+     * Ensures at least one DID exists in the wallet, creating a default if none exist
+     * @memberof IDIDProvider
+     * @returns {Promise<{keyDoc: any, didDocumentResolution: any}|void>} The created DID if one was created, undefined otherwise
+     * @example
+     * // Ensure wallet has at least one DID
+     * await didProvider.ensureDID();
+     */
     async ensureDID() {
       return ensureDID({wallet});
     },
+    /**
+     * Gets the default DID from the wallet (first DID if exists)
+     * @memberof IDIDProvider
+     * @returns {Promise<string|undefined>} The default DID identifier or undefined if no DIDs exist
+     * @example
+     * const defaultDID = await didProvider.getDefaultDID();
+     * if (defaultDID) {
+     *   console.log(`Default DID: ${defaultDID}`);
+     * }
+     */
     async getDefaultDID() {
       return getDefaultDID({wallet});
     }
   };
+
+
+  return provider;
 }

package/src/message-provider.ts

@@ -1,23 +1,22 @@
+/**
+ * @module message-provider
+ * @description DIDComm message management functionality for the Truvera Wallet SDK.
+ * This module provides functions for sending, receiving, and processing DIDComm messages.
+ */
+
 import {logger} from '@docknetwork/wallet-sdk-data-store/src/logger';
 import {IDIDProvider} from './did-provider';
 import {WalletDocumentTypes, captureException} from './helpers';
-import {IWallet} from './types';
+import {IWallet, IMessageProvider} from './types';
+export type {IMessageProvider};
 import {relayService as defaultRelayService} from '@docknetwork/wallet-sdk-wasm/src/services/relay-service';
 
 const FETCH_MESSAGE_LIMIT = 10;
 
-export interface IMessageProvider {
-  sendMessage: (message: any) => Promise<any>;
-  fetchMessages: () => Promise<void>;
-  processDIDCommMessages: () => Promise<void>;
-  startAutoFetch: (timeout?: number) => () => void;
-  addMessageListener: (handler: () => void) => () => void;
-  waitForMessage: () => Promise<any>;
-  markMessageAsRead: (messageId: string) => Promise<void>;
-  clearCache: () => Promise<void>;
-  processMessageRecurrentJob: () => Promise<void>;
-}
-
+/**
+ * Internal function to retrieve key pair documents for a DID
+ * @private
+ */
 async function getKeyPairDocs(didProvider: IDIDProvider, did?: string) {
   try {
     const keyPairDocs = await didProvider.getDIDKeyPairs();
@@ -30,6 +29,37 @@ async function getKeyPairDocs(didProvider: IDIDProvider, did?: string) {
   }
 }
 
+/**
+ * Creates a message provider instance bound to a wallet and DID provider
+ * @param {Object} params - Provider configuration
+ * @param {IWallet} params.wallet - The wallet instance to use for message storage
+ * @param {IDIDProvider} params.didProvider - The DID provider instance to use for key management
+ * @param {any} [params.relayService] - Optional relay service implementation (defaults to built-in service)
+ * @returns {IMessageProvider} A message provider instance with all DIDComm message management methods
+ * @see {@link IMessageProvider} - The interface defining all available message provider methods
+ * @example
+ * import { createMessageProvider } from '@docknetwork/wallet-sdk-core';
+ *
+ * const messageProvider = createMessageProvider({
+ *   wallet,
+ *   didProvider
+ * });
+ *
+ * // Send a message
+ * await messageProvider.sendMessage({
+ *   did: 'did:key:sender123',
+ *   recipientDid: 'did:key:recipient456',
+ *   message: { hello: 'world' }
+ * });
+ *
+ * // Start auto-fetching messages
+ * const stopAutoFetch = messageProvider.startAutoFetch(5000);
+ *
+ * // Add message listener
+ * const removeListener = messageProvider.addMessageListener((message) => {
+ *   console.log('Received message:', message);
+ * });
+ */
 export function createMessageProvider({
   wallet,
   didProvider,
@@ -38,7 +68,7 @@ export function createMessageProvider({
   wallet: IWallet;
   didProvider: IDIDProvider;
   relayService?: any;
-}) {
+}): IMessageProvider {
   async function markMessageAsRead(messageId: string) {
     try {
       const message = await wallet.getDocumentById(messageId);
@@ -213,6 +243,8 @@ export function createMessageProvider({
   }
 
   let listenerIntervalId = null;
+  let processMessageTimeoutId = null;
+  let stopped = false;
 
   const processMessageInterval = 3000;
 
@@ -220,43 +252,68 @@ export function createMessageProvider({
     try {
       await processDIDCommMessages();
     } finally {
-      setTimeout(processMessageRecurrentJob, processMessageInterval);
+      if (!stopped) {
+        processMessageTimeoutId = setTimeout(processMessageRecurrentJob, processMessageInterval);
+      }
+    }
+  }
+
+  function stop() {
+    stopped = true;
+    if (listenerIntervalId) {
+      clearInterval(listenerIntervalId);
+      listenerIntervalId = null;
+    }
+    if (processMessageTimeoutId) {
+      clearTimeout(processMessageTimeoutId);
+      processMessageTimeoutId = null;
     }
   }
 
   return {
+    /**
+     * Sends a DIDComm message to a recipient
+     * @memberof IMessageProvider
+     * @param {Object} params - Message parameters
+     * @param {string} [params.from] - Sender DID identifier
+     * @param {string} [params.to] - Recipient DID identifier
+     * @param {any} [params.message] - Message payload to send
+     * @param {string} [params.type] - DIDComm message type
+     * @param {string} [params.did] - @deprecated Use 'from' instead - Sender DID identifier
+     * @param {string} [params.recipientDid] - @deprecated Use 'to' instead - Recipient DID identifier
+     * @param {any} [params.body] - @deprecated Use 'message' instead - Message payload to send
+     * @returns {Promise<any>} Result of sending the message
+     * @throws {Error} If sender DID not found or message sending fails
+     * @example
+     * await messageProvider.sendMessage({
+     *   from: 'did:key:sender123',
+     *   to: 'did:key:recipient456',
+     *   message: { hello: 'world' },
+     *   type: 'basic-message'
+     * });
+     *
+     */
     async sendMessage({
-      did,
-      recipientDid,
-      message,
-      // didcomm message parameters
+      // Recommended parameters
       from,
       to,
-      body,
+      message,
       type,
+      // Deprecated parameters
+      did,
+      recipientDid,
+      body,
     }) {
-      // TODO: rename relay service parameters to make it easier to understand
-      if (from) {
-        did = from;
-      }
-
-      if (to) {
-        recipientDid = to;
-      }
-
-      if (!message && body) {
-        message = body;
-      }
 
       try {
-        const keyPairDoc = await getKeyPairDocs(didProvider, did);
+        const keyPairDoc = await getKeyPairDocs(didProvider, from || did);
         if (!keyPairDoc) {
           throw new Error(`${did} not found in didDocs`);
         }
         return await relayService.sendMessage({
           keyPairDoc,
-          message,
-          recipientDid,
+          message: message || body,
+          recipientDid: to || recipientDid,
           type,
         });
       } catch (error) {
@@ -264,6 +321,14 @@ export function createMessageProvider({
         throw new Error(`Failed to send message: ${error.message}`);
       }
     },
+    /**
+     * Waits for the next incoming message
+     * @memberof IMessageProvider
+     * @returns {Promise<any>} Promise that resolves with the next received message
+     * @example
+     * const nextMessage = await messageProvider.waitForMessage();
+     * console.log('Received message:', nextMessage);
+     */
     waitForMessage() {
       return new Promise((resolve: any) => {
         let removeListener = addMessageListener(async message => {
@@ -272,15 +337,41 @@ export function createMessageProvider({
         });
       });
     },
+    /**
+     * Starts automatic message fetching at regular intervals
+     * @memberof IMessageProvider
+     * @param {number} [timeout=2000] - Interval in milliseconds between fetch operations
+     * @returns {Function} Function to stop the auto-fetch process
+     * @example
+     * const stopAutoFetch = messageProvider.startAutoFetch(5000);
+     * // Later, stop auto-fetching
+     * stopAutoFetch();
+     */
     startAutoFetch(timeout = 2000) {
       clearInterval(listenerIntervalId);
+      stopped = false;
       listenerIntervalId = setInterval(async () => {
-        await fetchMessages();
-        await processDIDCommMessages();
+        try {
+          await fetchMessages();
+          await processDIDCommMessages();
+        } catch (err) {
+          logger.debug(`Auto-fetch error: ${err.message}`);
+        }
       }, timeout);
 
-      return () => clearInterval(listenerIntervalId);
+      return () => {
+        clearInterval(listenerIntervalId);
+        listenerIntervalId = null;
+      };
     },
+    /**
+     * Clears all cached messages from the wallet
+     * @memberof IMessageProvider
+     * @returns {Promise<void>}
+     * @example
+     * await messageProvider.clearCache();
+     * console.log('All messages cleared');
+     */
     clearCache: async () => {
       return Promise.all(
         (
@@ -291,10 +382,58 @@ export function createMessageProvider({
         }),
       );
     },
+    /**
+     * Fetches new messages from the relay service
+     * @memberof IMessageProvider
+     * @returns {Promise<void>}
+     * @throws {Error} If message fetching fails
+     * @example
+     * await messageProvider.fetchMessages();
+     * console.log('Messages fetched successfully');
+     */
     fetchMessages,
+    /**
+     * Adds a listener for when messages are decrypted
+     * @memberof IMessageProvider
+     * @param {Function} handler - Callback function to handle decrypted messages
+     * @returns {Function} Function to remove the listener
+     * @example
+     * const removeListener = messageProvider.addMessageListener((message) => {
+     *   console.log('New message received:', message);
+     * });
+     * // Later, remove the listener
+     * removeListener();
+     */
     addMessageListener,
+    /**
+     * Processes stored DIDComm messages and decrypts them
+     * @memberof IMessageProvider
+     * @returns {Promise<void>}
+     * @throws {Error} If message processing fails
+     * @example
+     * await messageProvider.processDIDCommMessages();
+     * console.log('Messages processed successfully');
+     */
     processDIDCommMessages,
+    /**
+     * Starts the recurrent message processing job
+     * @memberof IMessageProvider
+     * @returns {Promise<void>}
+     * @example
+     * await messageProvider.processMessageRecurrentJob();
+     */
     processMessageRecurrentJob,
+    /**
+     * Marks a message as read and removes it from storage
+     * @memberof IMessageProvider
+     * @param {string} messageId - The ID of the message to mark as read
+     * @returns {Promise<void>}
+     * @throws {Error} If message is not found or not a DIDComm message
+     * @example
+     * await messageProvider.markMessageAsRead('message-id-123');
+     * console.log('Message marked as read');
+     */
     markMessageAsRead,
+    stop,
   } as any;
 }

package/src/qr-handlers/builtin/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Built-in QR Code Handlers
+ *
+ * This module provides pre-built handlers for common protocols used in
+ * decentralized identity wallets. These handlers can be used directly or
+ * extended for custom behavior.
+ *
+ * ## Available Handlers
+ *
+ * - **OID4VCHandler**: OpenID for Verifiable Credentials (OID4VC)
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { OID4VCHandler } from '@docknetwork/wallet-sdk-core/src/qr-handlers/builtin';
+ *
+ * const handler = new OID4VCHandler({
+ *   onImportCredential: async (uri) => {
+ *     // Your credential import logic
+ *     return { success: true };
+ *   },
+ * });
+ *
+ * processor.registerHandler(handler);
+ * ```
+ *
+ * @module qr-handlers/builtin
+ */
+
+export * from './oid4vc-handler';