@bsv/sdk 1.7.0 → 1.7.2

package/docs/reference/identity.md

@@ -130,8 +130,8 @@ IdentityClient lets you discover who others are, and let the world know who you
 export class IdentityClient {
     constructor(wallet?: WalletInterface, private readonly options = DEFAULT_IDENTITY_CLIENT_OPTIONS, private readonly originator?: OriginatorDomainNameStringUnder250Bytes) 
     async publiclyRevealAttributes(certificate: WalletCertificate, fieldsToReveal: CertificateFieldNameUnder50Bytes[]): Promise<BroadcastResponse | BroadcastFailure> 
-    async resolveByIdentityKey(args: DiscoverByIdentityKeyArgs): Promise<DisplayableIdentity[]> 
-    async resolveByAttributes(args: DiscoverByAttributesArgs): Promise<DisplayableIdentity[]> 
+    async resolveByIdentityKey(args: DiscoverByIdentityKeyArgs, overrideWithContacts = true): Promise<DisplayableIdentity[]> 
+    async resolveByAttributes(args: DiscoverByAttributesArgs, overrideWithContacts = true): Promise<DisplayableIdentity[]> 
     public async getContacts(identityKey?: PubKeyHex, forceRefresh = false): Promise<Contact[]> 
     public async saveContact(contact: DisplayableIdentity, metadata?: Record<string, any>): Promise<void> 
     public async removeContact(identityKey: PubKeyHex): Promise<void> 
@@ -228,7 +228,7 @@ Argument Details
 Resolves displayable identity certificates by specific identity attributes, issued by a trusted entity.
 
 ```ts
-async resolveByAttributes(args: DiscoverByAttributesArgs): Promise<DisplayableIdentity[]> 
+async resolveByAttributes(args: DiscoverByAttributesArgs, overrideWithContacts = true): Promise<DisplayableIdentity[]> 
 ```
 See also: [DiscoverByAttributesArgs](./wallet.md#interface-discoverbyattributesargs), [DisplayableIdentity](./identity.md#interface-displayableidentity)
 
@@ -240,13 +240,15 @@ Argument Details
 
 + **args**
   + Attributes and optional parameters used to discover certificates.
++ **overrideWithContacts**
+  + Whether to override the results with personal contacts if available.
 
 #### Method resolveByIdentityKey
 
 Resolves displayable identity certificates, issued to a given identity key by a trusted certifier.
 
 ```ts
-async resolveByIdentityKey(args: DiscoverByIdentityKeyArgs): Promise<DisplayableIdentity[]> 
+async resolveByIdentityKey(args: DiscoverByIdentityKeyArgs, overrideWithContacts = true): Promise<DisplayableIdentity[]> 
 ```
 See also: [DiscoverByIdentityKeyArgs](./wallet.md#interface-discoverbyidentitykeyargs), [DisplayableIdentity](./identity.md#interface-displayableidentity)
 
@@ -258,6 +260,8 @@ Argument Details
 
 + **args**
   + Arguments for requesting the discovery based on the identity key.
++ **overrideWithContacts**
+  + Whether to override the results with personal contacts if available.
 
 #### Method saveContact
 

package/docs/reference/overlay-tools.md

@@ -100,6 +100,7 @@ export interface LookupResolverConfig {
     slapTrackers?: string[];
     hostOverrides?: Record<string, string[]>;
     additionalHosts?: Record<string, string[]>;
+    cache?: CacheOptions;
 }
 ```
 
@@ -113,6 +114,14 @@ Map of lookup service names to arrays of hosts to use in addition to resolving v
 additionalHosts?: Record<string, string[]>
 ```
 
+#### Property cache
+
+Optional cache tuning.
+
+```ts
+cache?: CacheOptions
+```
+
 #### Property facilitator
 
 The facilitator used to make requests to Overlay Services hosts.
@@ -327,7 +336,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ---
 ### Class: LookupResolver
 
-Represents an SHIP transaction broadcaster.
+Represents a Lookup Resolver.
 
 ```ts
 export default class LookupResolver {

package/docs/reference/storage.md

@@ -354,7 +354,7 @@ getURLForFile = (file: Uint8Array | number[]): string => {
 }
 ```
 
-See also: [getURLForHash](./storage.md#variable-geturlforhash)
+See also: [SHA256](./primitives.md#class-sha256), [getURLForHash](./storage.md#variable-geturlforhash)
 
 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.7.0",
+  "version": "1.7.2",
   "type": "module",
   "description": "BSV Blockchain Software Development Kit",
   "main": "dist/cjs/mod.js",

package/src/identity/IdentityClient.ts

@@ -116,11 +116,21 @@ export class IdentityClient {
   * Resolves displayable identity certificates, issued to a given identity key by a trusted certifier.
   *
   * @param {DiscoverByIdentityKeyArgs} args - Arguments for requesting the discovery based on the identity key.
+  * @param {boolean} [overrideWithContacts=true] - Whether to override the results with personal contacts if available.
   * @returns {Promise<DisplayableIdentity[]>} The promise resolves to displayable identities.
   */
   async resolveByIdentityKey (
-    args: DiscoverByIdentityKeyArgs
+    args: DiscoverByIdentityKeyArgs,
+    overrideWithContacts = true
   ): Promise<DisplayableIdentity[]> {
+    if (overrideWithContacts) {
+      // Override results with personal contacts if available
+      const contacts = await this.contactsManager.getContacts(args.identityKey)
+      if (contacts.length > 0) {
+        return contacts
+      }
+    }
+
     const { certificates } = await this.wallet.discoverByIdentityKey(args, this.originator)
     return certificates.map(cert => {
       return IdentityClient.parseIdentity(cert)
@@ -131,15 +141,31 @@ export class IdentityClient {
    * Resolves displayable identity certificates by specific identity attributes, issued by a trusted entity.
    *
    * @param {DiscoverByAttributesArgs} args - Attributes and optional parameters used to discover certificates.
+   * @param {boolean} [overrideWithContacts=true] - Whether to override the results with personal contacts if available.
    * @returns {Promise<DisplayableIdentity[]>} The promise resolves to displayable identities.
    */
   async resolveByAttributes (
-    args: DiscoverByAttributesArgs
+    args: DiscoverByAttributesArgs,
+    overrideWithContacts = true
   ): Promise<DisplayableIdentity[]> {
-    const { certificates } = await this.wallet.discoverByAttributes(args, this.originator)
-    return certificates.map(cert => {
-      return IdentityClient.parseIdentity(cert)
-    })
+    // Run both queries in parallel for better performance
+    const [contacts, certificatesResult] = await Promise.all([
+      overrideWithContacts ? this.contactsManager.getContacts() : Promise.resolve([]),
+      this.wallet.discoverByAttributes(args, this.originator)
+    ])
+
+    // Fast lookup by identityKey
+    const contactByKey = new Map<PubKeyHex, Contact>(
+      contacts.map(contact => [contact.identityKey, contact] as const)
+    )
+
+    // Guard if certificates might be absent
+    const certs = certificatesResult?.certificates ?? []
+
+    // Parse certificates and substitute with contacts where available
+    return certs.map(cert =>
+      contactByKey.get(cert.subject) ?? IdentityClient.parseIdentity(cert)
+    )
   }
 
   /**

package/src/identity/__tests/IdentityClient.test.ts

@@ -226,6 +226,43 @@ describe('IdentityClient', () => {
         badgeClickURL: 'https://socialcert.net'
       })
     })
+
+    it('should prioritize contacts over discovered identities for same identity key', async () => {
+      const contact = {
+        name: 'Alice Smith (Personal Contact)',
+        identityKey: 'alice-identity-key',
+        avatarURL: 'alice-avatar.png',
+        abbreviatedKey: 'alice-i...',
+        badgeIconURL: '',
+        badgeLabel: '',
+        badgeClickURL: ''
+      }
+
+      const discoveredCertificate = {
+        type: KNOWN_IDENTITY_TYPES.xCert,
+        subject: 'alice-identity-key',
+        decryptedFields: {
+          userName: 'Alice Public',
+          profilePhoto: 'public-photo.png'
+        },
+        certifierInfo: {
+          name: 'CertifierX',
+          iconUrl: 'certifier-icon.png'
+        }
+      }
+
+      // Mock ContactsManager to return contact for the specific identity key
+      const mockContactsManager = identityClient['contactsManager']
+      mockContactsManager.getContacts = jest.fn().mockResolvedValue([contact])
+      walletMock.discoverByIdentityKey = jest.fn().mockResolvedValue({ certificates: [discoveredCertificate] })
+
+      const identities = await identityClient.resolveByIdentityKey({ identityKey: 'alice-identity-key' })
+
+      expect(identities).toHaveLength(1)
+      expect(identities[0].name).toBe('Alice Smith (Personal Contact)') // Contact should be returned, not discovered identity
+      // Wallet method should not be called when contact is found
+      expect(walletMock.discoverByIdentityKey).not.toHaveBeenCalled()
+    })
   })
 
   it('should throw if createAction returns no tx', async () => {
@@ -256,34 +293,124 @@ describe('IdentityClient', () => {
   })
 
   describe('resolveByAttributes', () => {
-    it('should return parsed identities from discovered certificates', async () => {
+    beforeEach(() => {
+      // Mock both getContacts and discoverByAttributes
+      walletMock.discoverByAttributes = jest.fn().mockResolvedValue({ certificates: [] })
+      identityClient.getContacts = jest.fn().mockResolvedValue([])
+    })
+
+    it('should return parsed identities from discovered certificates only', async () => {
       const dummyCertificate = {
         type: KNOWN_IDENTITY_TYPES.emailCert,
-        subject: 'emailSubject1234',
+        subject: 'alice-identity-key',
         decryptedFields: {
-          email: 'alice@example.com',
-          profilePhoto: 'ignored' // not used for email type
+          identityKey: 'alice-identity-key',
+          email: 'alice@example.com'
         },
         certifierInfo: {
-          name: 'EmailCertifier',
-          iconUrl: 'emailIconUrl'
+          name: 'Email Certifier',
+          iconUrl: 'certifier-icon.png',
+          publicKey: 'certifier-public-key',
+          website: 'https://certifier.example.com'
         }
       }
-      // Mock discoverByAttributes to return a certificate list.
+
       walletMock.discoverByAttributes = jest.fn().mockResolvedValue({ certificates: [dummyCertificate] })
 
       const identities = await identityClient.resolveByAttributes({ attributes: { email: 'alice@example.com' } })
-      expect(walletMock.discoverByAttributes).toHaveBeenCalledWith({ attributes: { email: 'alice@example.com' } }, undefined)
       expect(identities).toHaveLength(1)
-      expect(identities[0]).toEqual({
-        name: 'alice@example.com',
-        avatarURL: 'XUTZxep7BBghAJbSBwTjNfmcsDdRFs5EaGEgkESGSgjJVYgMEizu',
-        abbreviatedKey: 'emailSubje...',
-        identityKey: 'emailSubject1234',
-        badgeLabel: 'Email certified by EmailCertifier',
-        badgeIconURL: 'emailIconUrl',
-        badgeClickURL: 'https://socialcert.net'
-      })
+      expect(identities[0].name).toBe('alice@example.com')
+    })
+
+    it('should prioritize contacts over discovered identities for same identity key', async () => {
+      const contact = {
+        name: 'Alice Smith (Personal)',
+        identityKey: 'alice-identity-key',
+        avatarURL: 'alice-avatar.png',
+        abbreviatedKey: 'alice-i...',
+        badgeIconURL: '',
+        badgeLabel: '',
+        badgeClickURL: ''
+      }
+
+      const discoveredCertificate = {
+        type: KNOWN_IDENTITY_TYPES.emailCert,
+        subject: 'alice-identity-key',
+        decryptedFields: {
+          email: 'alice@example.com'
+        },
+        certifierInfo: {
+          name: 'Email Certifier',
+          iconUrl: 'certifier-icon.png',
+          publicKey: 'certifier-public-key',
+          website: 'https://certifier.example.com'
+        }
+      }
+
+      // Mock the ContactsManager's getContacts method instead of the IdentityClient method
+      const mockContactsManager = identityClient['contactsManager']
+      mockContactsManager.getContacts = jest.fn().mockResolvedValue([contact])
+      walletMock.discoverByAttributes = jest.fn().mockResolvedValue({ certificates: [discoveredCertificate] })
+
+      const identities = await identityClient.resolveByAttributes({ attributes: { name: 'Alice' } })
+
+      expect(identities).toHaveLength(1)
+      expect(identities[0].name).toBe('Alice Smith (Personal)') // Contact should be returned, not discovered identity
+    })
+
+    it('should return empty array for empty search terms', async () => {
+      const contacts = [
+        {
+          name: 'Alice Smith',
+          identityKey: 'alice-key',
+          avatarURL: '', abbreviatedKey: 'alice-i...', badgeIconURL: '', badgeLabel: '', badgeClickURL: ''
+        }
+      ]
+
+      const mockContactsManager = identityClient['contactsManager']
+      mockContactsManager.getContacts = jest.fn().mockResolvedValue(contacts)
+
+      const identities = await identityClient.resolveByAttributes({ attributes: { name: '', email: '   ' } })
+
+      expect(identities).toHaveLength(0)
+    })
+
+    it('should return only discovered identities when overrideWithContacts is false', async () => {
+      const contacts = [
+        {
+          name: 'Alice Smith (Personal)',
+          identityKey: 'alice-key',
+          avatarURL: '', abbreviatedKey: 'alice-i...', badgeIconURL: '', badgeLabel: '', badgeClickURL: ''
+        }
+      ]
+
+      const discoveredCertificate = {
+        type: KNOWN_IDENTITY_TYPES.emailCert,
+        subject: 'alice-key', // Same key as contact but should not be filtered out
+        decryptedFields: {
+          email: 'alice@example.com'
+        },
+        certifierInfo: {
+          name: 'Email Certifier',
+          iconUrl: 'certifier-icon.png',
+          publicKey: 'certifier-public-key',
+          website: 'https://certifier.example.com'
+        }
+      }
+
+      const mockContactsManager = identityClient['contactsManager']
+      mockContactsManager.getContacts = jest.fn().mockResolvedValue(contacts)
+      walletMock.discoverByAttributes = jest.fn().mockResolvedValue({ certificates: [discoveredCertificate] })
+
+      // With overrideWithContacts = false, should ignore contacts entirely
+      const identities = await identityClient.resolveByAttributes(
+        { attributes: { name: 'Alice' } },
+        false
+      )
+
+      expect(identities).toHaveLength(1)
+      expect(identities[0].name).toBe('alice@example.com') // Should be discovered identity, not contact
+      expect(mockContactsManager.getContacts).not.toHaveBeenCalled() // Should not fetch contacts
     })
   })
 
@@ -434,14 +561,14 @@ describe('IdentityClient', () => {
           customInstructions: JSON.stringify({ keyID: 'existingKeyID' })
         }
 
-        ; (walletMock.listOutputs as jest.Mock).mockResolvedValueOnce({
-          outputs: [existingOutput],
-          BEEF: [1, 2, 3]
-        })
+          ; (walletMock.listOutputs as jest.Mock).mockResolvedValueOnce({
+            outputs: [existingOutput],
+            BEEF: [1, 2, 3]
+          })
 
-        ; (walletMock.decrypt as jest.Mock).mockResolvedValue({
-          plaintext: new TextEncoder().encode(JSON.stringify(mockContact))
-        })
+          ; (walletMock.decrypt as jest.Mock).mockResolvedValue({
+            plaintext: new TextEncoder().encode(JSON.stringify(mockContact))
+          })
 
         const updatedContact = { ...mockContact, name: 'Alice Updated' }
         await identityClient.saveContact(updatedContact)
@@ -489,14 +616,14 @@ describe('IdentityClient', () => {
           customInstructions: JSON.stringify({ keyID: 'mockKeyID' })
         }
 
-        ; (walletMock.listOutputs as jest.Mock).mockResolvedValue({
-          outputs: [mockOutput],
-          BEEF: [1, 2, 3]
-        })
+          ; (walletMock.listOutputs as jest.Mock).mockResolvedValue({
+            outputs: [mockOutput],
+            BEEF: [1, 2, 3]
+          })
 
-        ; (walletMock.decrypt as jest.Mock).mockResolvedValue({
-          plaintext: new TextEncoder().encode(JSON.stringify(mockContact))
-        })
+          ; (walletMock.decrypt as jest.Mock).mockResolvedValue({
+            plaintext: new TextEncoder().encode(JSON.stringify(mockContact))
+          })
 
         const result = await identityClient.getContacts()
 
@@ -523,11 +650,11 @@ describe('IdentityClient', () => {
         })
         await identityClient.saveContact(mockContact)
 
-        // Mock empty result for force refresh
-        ; (walletMock.listOutputs as jest.Mock).mockResolvedValue({
-          outputs: [],
-          BEEF: []
-        })
+          // Mock empty result for force refresh
+          ; (walletMock.listOutputs as jest.Mock).mockResolvedValue({
+            outputs: [],
+            BEEF: []
+          })
 
         const result = await identityClient.getContacts(undefined, true)
 
@@ -542,7 +669,7 @@ describe('IdentityClient', () => {
           BEEF: []
         })
         await identityClient.saveContact(mockContact)
-        
+
         const otherContact = { ...mockContact, identityKey: 'different-key', name: 'Bob' }
         await identityClient.saveContact(otherContact)
 
@@ -575,7 +702,7 @@ describe('IdentityClient', () => {
           BEEF: []
         })
         await identityClient.saveContact(mockContact)
-        
+
         const otherContact = { ...mockContact, identityKey: 'other-key', name: 'Bob' }
         await identityClient.saveContact(otherContact)
 
@@ -585,14 +712,14 @@ describe('IdentityClient', () => {
           customInstructions: JSON.stringify({ keyID: 'mockKeyID' })
         }
 
-        ; (walletMock.listOutputs as jest.Mock).mockResolvedValue({
-          outputs: [mockOutput],
-          BEEF: [1, 2, 3]
-        })
+          ; (walletMock.listOutputs as jest.Mock).mockResolvedValue({
+            outputs: [mockOutput],
+            BEEF: [1, 2, 3]
+          })
 
-        ; (walletMock.decrypt as jest.Mock).mockResolvedValue({
-          plaintext: new TextEncoder().encode(JSON.stringify(mockContact))
-        })
+          ; (walletMock.decrypt as jest.Mock).mockResolvedValue({
+            plaintext: new TextEncoder().encode(JSON.stringify(mockContact))
+          })
 
         await identityClient.removeContact(mockContact.identityKey)