@bsv/overlay-discovery-services 1.4.0 → 1.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/overlay-discovery-services",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "type": "module",
   "description": "BSV Blockchain Overlay Services Engine",
   "main": "dist/cjs/mod.js",
@@ -62,9 +62,9 @@
     "typescript": "^5.2.2"
   },
   "dependencies": {
-    "@bsv/overlay": "^0.4.0",
-    "@bsv/sdk": "^1.6.8",
-    "@bsv/wallet-toolbox-client": "^1.5.0",
+    "@bsv/overlay": "^0.4.4",
+    "@bsv/sdk": "^1.6.19",
+    "@bsv/wallet-toolbox-client": "^1.5.18",
     "mongodb": "^6.11.0"
   }
 }

package/src/SHIP/SHIPLookupService.ts

@@ -13,9 +13,9 @@ import SHIPLookupDocs from './SHIPLookup.docs.js'
 export class SHIPLookupService implements LookupService {
   admissionMode: AdmissionMode = 'locking-script'
   spendNotificationMode: SpendNotificationMode = 'none'
-  constructor(public storage: SHIPStorage) { }
+  constructor (public storage: SHIPStorage) { }
 
-  async outputAdmittedByTopic(payload: OutputAdmittedByTopic): Promise<void> {
+  async outputAdmittedByTopic (payload: OutputAdmittedByTopic): Promise<void> {
     if (payload.mode !== 'locking-script') throw new Error('Invalid payload')
     const { topic, lockingScript, txid, outputIndex } = payload
     if (topic !== 'tm_ship') return
@@ -28,7 +28,7 @@ export class SHIPLookupService implements LookupService {
     await this.storage.storeSHIPRecord(txid, outputIndex, identityKey, domain, topicSupported)
   }
 
-  async outputSpent(payload: OutputSpent): Promise<void> {
+  async outputSpent (payload: OutputSpent): Promise<void> {
     if (payload.mode !== 'none') throw new Error('Invalid payload')
     const { topic, txid, outputIndex } = payload
     if (topic !== 'tm_ship') return
@@ -39,7 +39,7 @@ export class SHIPLookupService implements LookupService {
     await this.storage.deleteSHIPRecord(txid, outputIndex)
   }
 
-  async lookup(question: LookupQuestion): Promise<LookupFormula> {
+  async lookup (question: LookupQuestion): Promise<LookupFormula> {
     if (question.query === undefined || question.query === null) {
       throw new Error('A valid query must be provided!')
     }
@@ -47,29 +47,69 @@ export class SHIPLookupService implements LookupService {
       throw new Error('Lookup service not supported!')
     }
 
+    // Handle legacy "findAll" string query
     if (question.query === 'findAll') {
       return await this.storage.findAll()
     }
 
-    // Validate lookup query
-    const { domain, topics, identityKey } = question.query as SHIPQuery
-    if (typeof domain !== 'string' && typeof domain !== 'undefined') {
-      throw new Error('query.domain must be a string if provided')
-    }
-    if (!Array.isArray(topics) && typeof topics !== 'undefined') {
-      throw new Error('query.topics must be an array of strings if provided')
-    }
-    if (typeof identityKey !== 'string' && typeof identityKey !== 'undefined') {
-      throw new Error('query.identityKey must be a string if provided')
+    // Handle object-based query
+    if (typeof question.query === 'object') {
+      const query = question.query as SHIPQuery
+
+      // Handle new findAll mode with pagination
+      if (query.findAll) {
+        const { limit, skip, sortOrder } = query
+
+        // Validate pagination parameters
+        if (typeof limit !== 'undefined' && (typeof limit !== 'number' || limit < 0)) {
+          throw new Error('query.limit must be a positive number if provided')
+        }
+        if (typeof skip !== 'undefined' && (typeof skip !== 'number' || skip < 0)) {
+          throw new Error('query.skip must be a non-negative number if provided')
+        }
+        if (typeof sortOrder !== 'undefined' && sortOrder !== 'asc' && sortOrder !== 'desc') {
+          throw new Error('query.sortOrder must be "asc" or "desc" if provided')
+        }
+
+        return await this.storage.findAll(limit, skip, sortOrder)
+      }
+
+      // Handle specific query with domain, topics, identityKey
+      const { domain, topics, identityKey, limit, skip, sortOrder } = query
+
+      // Validate query parameters
+      if (typeof domain !== 'string' && typeof domain !== 'undefined') {
+        throw new Error('query.domain must be a string if provided')
+      }
+      if (!Array.isArray(topics) && typeof topics !== 'undefined') {
+        throw new Error('query.topics must be an array of strings if provided')
+      }
+      if (typeof identityKey !== 'string' && typeof identityKey !== 'undefined') {
+        throw new Error('query.identityKey must be a string if provided')
+      }
+
+      // Validate pagination parameters
+      if (typeof limit !== 'undefined' && (typeof limit !== 'number' || limit < 0)) {
+        throw new Error('query.limit must be a positive number if provided')
+      }
+      if (typeof skip !== 'undefined' && (typeof skip !== 'number' || skip < 0)) {
+        throw new Error('query.skip must be a non-negative number if provided')
+      }
+      if (typeof sortOrder !== 'undefined' && sortOrder !== 'asc' && sortOrder !== 'desc') {
+        throw new Error('query.sortOrder must be "asc" or "desc" if provided')
+      }
+
+      return await this.storage.findRecord({ domain, topics, identityKey, limit, skip, sortOrder })
     }
-    return await this.storage.findRecord({ domain, topics, identityKey })
+
+    throw new Error('Invalid query format. Query must be "findAll" string or an object with valid parameters.')
   }
 
-  async getDocumentation(): Promise<string> {
+  async getDocumentation (): Promise<string> {
     return SHIPLookupDocs
   }
 
-  async getMetaData(): Promise<{
+  async getMetaData (): Promise<{
     name: string
     shortDescription: string
     iconURL?: string

package/src/SHIP/SHIPStorage.ts

@@ -11,14 +11,14 @@ export class SHIPStorage {
    * Constructs a new SHIPStorage instance
    * @param {Db} db - connected mongo database instance
    */
-  constructor(private readonly db: Db) {
+  constructor (private readonly db: Db) {
     this.shipRecords = db.collection<SHIPRecord>('shipRecords')
   }
 
   /**
    * Ensures the necessary indexes are created for the collections.
    */
-  async ensureIndexes(): Promise<void> {
+  async ensureIndexes (): Promise<void> {
     await this.shipRecords.createIndex({ domain: 1, topic: 1 })
   }
 
@@ -30,7 +30,7 @@ export class SHIPStorage {
    * @param {string} domain domain name
    * @param {string} topic topic name
    */
-  async storeSHIPRecord(txid: string, outputIndex: number, identityKey: string, domain: string, topic: string): Promise<void> {
+  async storeSHIPRecord (txid: string, outputIndex: number, identityKey: string, domain: string, topic: string): Promise<void> {
     await this.shipRecords.insertOne({
       txid,
       outputIndex,
@@ -46,16 +46,16 @@ export class SHIPStorage {
    * @param {string} txid transaction id
    * @param {number} outputIndex index of the UTXO
    */
-  async deleteSHIPRecord(txid: string, outputIndex: number): Promise<void> {
+  async deleteSHIPRecord (txid: string, outputIndex: number): Promise<void> {
     await this.shipRecords.deleteOne({ txid, outputIndex })
   }
 
   /**
    * Finds SHIP records based on a given query object.
-   * @param {Object} query The query object which may contain properties for domain, topics, and/or identityKey.
+   * @param {Object} query The query object which may contain properties for domain, topics, identityKey, limit, and skip.
    * @returns {Promise<UTXOReference[]>} Returns matching UTXO references.
    */
-  async findRecord(query: SHIPQuery): Promise<UTXOReference[]> {
+  async findRecord (query: SHIPQuery): Promise<UTXOReference[]> {
     const mongoQuery: any = {}
 
     // Add domain to the query if provided
@@ -73,25 +73,55 @@ export class SHIPStorage {
       mongoQuery.identityKey = query.identityKey
     }
 
-    return await this.shipRecords
+    // Build the query with pagination
+    let cursor = this.shipRecords
       .find(mongoQuery)
-      .project<UTXOReference>({ txid: 1, outputIndex: 1 })
+      .project<UTXOReference>({ txid: 1, outputIndex: 1, createdAt: 1 })
+
+    cursor.sort({ createdAt: query.sortOrder ?? -1 })
+
+    // Apply pagination if provided
+    if (typeof query.skip === 'number' && query.skip > 0) {
+      cursor = cursor.skip(query.skip)
+    }
+
+    if (typeof query.limit === 'number' && query.limit > 0) {
+      cursor = cursor.limit(query.limit)
+    }
+
+    return await cursor
       .toArray()
       .then((results) =>
         results.map((record) => ({
           txid: record.txid,
-          outputIndex: record.outputIndex,
+          outputIndex: record.outputIndex
         }))
       )
   }
 
   /**
- * Returns all results tracked by the overlay
- * @returns {Promise<UTXOReference[]>} returns matching UTXO references
- */
-  async findAll(): Promise<UTXOReference[]> {
-    return await this.shipRecords.find({})
-      .project<UTXOReference>({ txid: 1, outputIndex: 1 })
+   * Returns all results tracked by the overlay
+   * @param {number} limit Optional limit for pagination
+   * @param {number} skip Optional skip for pagination
+   * @param {string} sortOrder Optional sort order
+   * @returns {Promise<UTXOReference[]>} returns matching UTXO references
+   */
+  async findAll (limit?: number, skip?: number, sortOrder?: 'asc' | 'desc'): Promise<UTXOReference[]> {
+    let cursor = this.shipRecords.find({})
+      .project<UTXOReference>({ txid: 1, outputIndex: 1, createdAt: 1 })
+
+    // Apply pagination if provided
+    cursor.sort({ createdAt: sortOrder ?? -1 })
+
+    if (typeof skip === 'number' && skip > 0) {
+      cursor = cursor.skip(skip)
+    }
+
+    if (typeof limit === 'number' && limit > 0) {
+      cursor = cursor.limit(limit)
+    }
+
+    return await cursor
       .toArray()
       .then(results => results.map(shipRecords => ({
         txid: shipRecords.txid,

package/src/SHIP/SHIPTopicManager.ts

@@ -19,7 +19,7 @@ export class SHIPTopicManager implements TopicManager {
    * @param previousCoins - The previous coins to consider.
    * @returns A promise that resolves with the admittance instructions.
    */
-  async identifyAdmissibleOutputs(beef: number[], previousCoins: number[]): Promise<AdmittanceInstructions> {
+  async identifyAdmissibleOutputs (beef: number[], previousCoins: number[]): Promise<AdmittanceInstructions> {
     const outputsToAdmit: number[] = []
     try {
       const parsedTransaction = Transaction.fromBEEF(beef)
@@ -75,7 +75,7 @@ export class SHIPTopicManager implements TopicManager {
    * Returns documentation specific to the SHIP topic manager.
    * @returns A promise that resolves to the documentation string.
    */
-  async getDocumentation(): Promise<string> {
+  async getDocumentation (): Promise<string> {
     return SHIPTopicDocs
   }
 
@@ -83,7 +83,7 @@ export class SHIPTopicManager implements TopicManager {
    * Returns metadata associated with this topic manager.
    * @returns A promise that resolves to an object containing metadata.
    */
-  async getMetaData(): Promise<{
+  async getMetaData (): Promise<{
     name: string
     shortDescription: string
     iconURL?: string

package/src/SLAP/SLAPLookup.docs.ts

@@ -91,4 +91,4 @@ You will typically provide a [LookupQuestion](https://www.npmjs.com/package/@bsv
 
 - **SLAPTopicManager**: Learn how SLAP outputs are detected and admitted.
 - **BRC-101 Overlays**: The higher-level specification for modular overlay availability schemes.
-`
+`

package/src/SLAP/SLAPLookupService.ts

@@ -14,9 +14,9 @@ import SLAPLookupDocs from './SLAPLookup.docs.js'
 export class SLAPLookupService implements LookupService {
   admissionMode: AdmissionMode = 'locking-script'
   spendNotificationMode: SpendNotificationMode = 'none'
-  constructor(public storage: SLAPStorage) { }
+  constructor (public storage: SLAPStorage) { }
 
-  async outputAdmittedByTopic(payload: OutputAdmittedByTopic): Promise<void> {
+  async outputAdmittedByTopic (payload: OutputAdmittedByTopic): Promise<void> {
     if (payload.mode !== 'locking-script') throw new Error('Invalid mode')
     const { txid, outputIndex, lockingScript, topic } = payload
     if (topic !== 'tm_slap') return
@@ -29,7 +29,7 @@ export class SLAPLookupService implements LookupService {
     await this.storage.storeSLAPRecord(txid, outputIndex, identityKey, domain, service)
   }
 
-  async outputSpent(payload: OutputSpent): Promise<void> {
+  async outputSpent (payload: OutputSpent): Promise<void> {
     if (payload.mode !== 'none') throw new Error('Invalid payload')
     const { topic, txid, outputIndex } = payload
     if (topic !== 'tm_slap') return
@@ -40,7 +40,7 @@ export class SLAPLookupService implements LookupService {
     await this.storage.deleteSLAPRecord(txid, outputIndex)
   }
 
-  async lookup(question: LookupQuestion): Promise<LookupFormula> {
+  async lookup (question: LookupQuestion): Promise<LookupFormula> {
     if (question.query === undefined || question.query === null) {
       throw new Error('A valid query must be provided!')
     }
@@ -48,40 +48,78 @@ export class SLAPLookupService implements LookupService {
       throw new Error('Lookup service not supported!')
     }
 
+    // Handle legacy "findAll" string query
     if (question.query === 'findAll') {
       return await this.storage.findAll()
     }
 
-    // Validate lookup query
-    const { domain, service, identityKey } = question.query as SLAPQuery
+    // Handle object-based query
+    if (typeof question.query === 'object') {
+      const query = question.query as SLAPQuery
 
-    // Validate that provided values are strings.
-    if (domain !== undefined && typeof domain !== 'string') {
-      throw new Error('query.domain must be a string if provided')
-    }
-    if (service !== undefined && typeof service !== 'string') {
-      throw new Error('query.service must be a string if provided')
-    }
-    if (identityKey !== undefined && typeof identityKey !== 'string') {
-      throw new Error('query.identityKey must be a string if provided')
-    }
+      // Handle new findAll mode with pagination
+      if (query.findAll) {
+        const { limit, skip, sortOrder } = query
+
+        // Validate pagination parameters
+        if (typeof limit !== 'undefined' && (typeof limit !== 'number' || limit < 0)) {
+          throw new Error('query.limit must be a positive number if provided')
+        }
+        if (typeof skip !== 'undefined' && (typeof skip !== 'number' || skip < 0)) {
+          throw new Error('query.skip must be a non-negative number if provided')
+        }
+        if (typeof sortOrder !== 'undefined' && sortOrder !== 'asc' && sortOrder !== 'desc') {
+          throw new Error('query.sortOrder must be "asc" or "desc" if provided')
+        }
+
+        return await this.storage.findAll(limit, skip, sortOrder)
+      }
 
-    // Build the query object dynamically to omit any undefined values.
-    const query: Partial<SLAPQuery> = {}
-    if (domain !== undefined) query.domain = domain
-    if (service !== undefined) query.service = service
-    if (identityKey !== undefined) query.identityKey = identityKey
+      // Handle specific query with domain, service, identityKey
+      const { domain, service, identityKey, limit, skip, sortOrder } = query
+
+      // Validate query parameters
+      if (typeof domain !== 'undefined' && typeof domain !== 'string') {
+        throw new Error('query.domain must be a string if provided')
+      }
+      if (typeof service !== 'undefined' && typeof service !== 'string') {
+        throw new Error('query.service must be a string if provided')
+      }
+      if (typeof identityKey !== 'undefined' && typeof identityKey !== 'string') {
+        throw new Error('query.identityKey must be a string if provided')
+      }
+
+      // Validate pagination parameters
+      if (typeof limit !== 'undefined' && (typeof limit !== 'number' || limit < 0)) {
+        throw new Error('query.limit must be a positive number if provided')
+      }
+      if (typeof skip !== 'undefined' && (typeof skip !== 'number' || skip < 0)) {
+        throw new Error('query.skip must be a non-negative number if provided')
+      }
+      if (typeof sortOrder !== 'undefined' && sortOrder !== 'asc' && sortOrder !== 'desc') {
+        throw new Error('query.sortOrder must be "asc" or "desc" if provided')
+      }
+
+      // Build the query object dynamically to omit any undefined values
+      const queryParams: Partial<SLAPQuery> = {}
+      if (domain !== undefined) queryParams.domain = domain
+      if (service !== undefined) queryParams.service = service
+      if (identityKey !== undefined) queryParams.identityKey = identityKey
+      if (limit !== undefined) queryParams.limit = limit
+      if (skip !== undefined) queryParams.skip = skip
+      if (sortOrder !== undefined) queryParams.sortOrder = sortOrder
+
+      return await this.storage.findRecord(queryParams)
+    }
 
-    const result = await this.storage.findRecord(query)
-    console.log('LOOKUP RESULT', result)
-    return result
+    throw new Error('Invalid query format. Query must be "findAll" string or an object with valid parameters.')
   }
 
-  async getDocumentation(): Promise<string> {
+  async getDocumentation (): Promise<string> {
     return SLAPLookupDocs
   }
 
-  async getMetaData(): Promise<{
+  async getMetaData (): Promise<{
     name: string
     shortDescription: string
     iconURL?: string

package/src/SLAP/SLAPStorage.ts

@@ -11,14 +11,14 @@ export class SLAPStorage {
    * Constructs a new SLAPStorage instance
    * @param {Db} db - connected mongo database instance
    */
-  constructor(private readonly db: Db) {
+  constructor (private readonly db: Db) {
     this.slapRecords = db.collection<SLAPRecord>('slapRecords')
   }
 
   /**
    * Ensures the necessary indexes are created for the collections.
    */
-  async ensureIndexes(): Promise<void> {
+  async ensureIndexes (): Promise<void> {
     await this.slapRecords.createIndex({ domain: 1, service: 1 })
   }
 
@@ -30,7 +30,7 @@ export class SLAPStorage {
    * @param {string} domain domain name
    * @param {string} service service name
    */
-  async storeSLAPRecord(txid: string, outputIndex: number, identityKey: string, domain: string, service: string): Promise<void> {
+  async storeSLAPRecord (txid: string, outputIndex: number, identityKey: string, domain: string, service: string): Promise<void> {
     await this.slapRecords.insertOne({
       txid,
       outputIndex,
@@ -46,7 +46,7 @@ export class SLAPStorage {
    * @param {string} txid transaction id
    * @param {number} outputIndex index of the UTXO
    */
-  async deleteSLAPRecord(txid: string, outputIndex: number): Promise<void> {
+  async deleteSLAPRecord (txid: string, outputIndex: number): Promise<void> {
     await this.slapRecords.deleteOne({ txid, outputIndex })
   }
 
@@ -55,7 +55,7 @@ export class SLAPStorage {
    * @param {Object} query The query object which may contain properties for domain, service, and/or identityKey.
    * @returns {Promise<UTXOReference[]>} returns matching UTXO references
    */
-  async findRecord(query: SLAPQuery): Promise<UTXOReference[]> {
+  async findRecord (query: SLAPQuery): Promise<UTXOReference[]> {
     const mongoQuery: any = {}
 
     // Add domain to the query if provided
@@ -72,10 +72,24 @@ export class SLAPStorage {
     if (typeof query.identityKey === 'string') {
       mongoQuery.identityKey = query.identityKey
     }
-    console.log(mongoQuery)
 
-    return await this.slapRecords.find(mongoQuery)
-      .project<UTXOReference>({ txid: 1, outputIndex: 1 })
+    // Build the query with pagination
+    let cursor = this.slapRecords
+      .find(mongoQuery)
+      .project<UTXOReference>({ txid: 1, outputIndex: 1, createdAt: 1 })
+
+    cursor.sort({ createdAt: query.sortOrder ?? -1 })
+
+    // Apply pagination if provided
+    if (typeof query.skip === 'number' && query.skip > 0) {
+      cursor = cursor.skip(query.skip)
+    }
+
+    if (typeof query.limit === 'number' && query.limit > 0) {
+      cursor = cursor.limit(query.limit)
+    }
+
+    return await cursor
       .toArray()
       .then(results => results.map(record => ({
         txid: record.txid,
@@ -85,11 +99,27 @@ export class SLAPStorage {
 
   /**
   * Returns all results tracked by the overlay
+  * @param {number} limit Optional limit for pagination
+  * @param {number} skip Optional skip for pagination
+  * @param {string} sortOrder Optional sort order
   * @returns {Promise<UTXOReference[]>} returns matching UTXO references
   */
-  async findAll(): Promise<UTXOReference[]> {
-    return await this.slapRecords.find({})
-      .project<UTXOReference>({ txid: 1, outputIndex: 1 })
+  async findAll (limit?: number, skip?: number, sortOrder?: 'asc' | 'desc'): Promise<UTXOReference[]> {
+    let cursor = this.slapRecords.find({})
+      .project<UTXOReference>({ txid: 1, outputIndex: 1, createdAt: 1 })
+
+    // Apply pagination if provided
+    cursor.sort({ createdAt: sortOrder ?? -1 })
+
+    if (typeof skip === 'number' && skip > 0) {
+      cursor = cursor.skip(skip)
+    }
+
+    if (typeof limit === 'number' && limit > 0) {
+      cursor = cursor.limit(limit)
+    }
+
+    return await cursor
       .toArray()
       .then(results => results.map(slapRecords => ({
         txid: slapRecords.txid,

package/src/SLAP/SLAPTopicManager.ts

@@ -19,7 +19,7 @@ export class SLAPTopicManager implements TopicManager {
    * @param previousCoins - The previous coins to consider.
    * @returns A promise that resolves with the admittance instructions.
    */
-  async identifyAdmissibleOutputs(
+  async identifyAdmissibleOutputs (
     beef: number[],
     previousCoins: number[]
   ): Promise<AdmittanceInstructions> {
@@ -79,7 +79,7 @@ export class SLAPTopicManager implements TopicManager {
    * Returns documentation specific to the SLAP topic manager.
    * @returns A promise that resolves to the documentation string.
    */
-  async getDocumentation(): Promise<string> {
+  async getDocumentation (): Promise<string> {
     return SLAPTopicDocs
   }
 
@@ -87,7 +87,7 @@ export class SLAPTopicManager implements TopicManager {
    * Returns metadata associated with this topic manager.
    * @returns A promise that resolves to an object containing metadata.
    */
-  async getMetaData(): Promise<{
+  async getMetaData (): Promise<{
     name: string
     shortDescription: string
     iconURL?: string

package/src/types.ts

@@ -22,13 +22,21 @@ export interface SLAPRecord {
 }
 
 export interface SHIPQuery {
+  findAll?: boolean
   domain?: string
   topics?: string[]
   identityKey?: string
+  limit?: number
+  skip?: number
+  sortOrder?: 'asc' | 'desc'
 }
 
 export interface SLAPQuery {
+  findAll?: boolean
   domain?: string
   service?: string
   identityKey?: string
+  limit?: number
+  skip?: number
+  sortOrder?: 'asc' | 'desc'
 }