@bsv/sdk 2.0.15 → 2.0.16

package/docs/reference/kvstore.md

@@ -249,7 +249,8 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ### Interface: KVStoreQuery
 
 Query parameters for KVStore lookups from overlay services.
-Used when searching for existing key-value pairs in the network.
+Must include at least one selector: key, controller, protocolID, or non-empty tags.
+Pagination and ordering fields only refine selector-based lookups.
 
 ```ts
 export interface KVStoreQuery {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "2.0.15",
+  "version": "2.0.16",
   "type": "module",
   "description": "BSV Blockchain Software Development Kit",
   "main": "dist/cjs/mod.js",

package/src/kvstore/GlobalKVStore.ts

@@ -106,9 +106,7 @@ export class GlobalKVStore {
    * @returns {Promise<KVStoreEntry | KVStoreEntry[] | undefined>} Single entry for key+controller queries, array for all other queries
    */
   async get (query: KVStoreQuery, options: KVStoreGetOptions = {}): Promise<KVStoreEntry | KVStoreEntry[] | undefined> {
-    if (Object.keys(query).length === 0) {
-      throw new Error('Must specify either key, controller, or protocolID')
-    }
+    this.validateQuerySelectors(query)
     if (query.key != null && query.controller != null) {
       // Specific key+controller query - return single entry
       const entries = await this.queryOverlay(query, options)
@@ -117,6 +115,24 @@ export class GlobalKVStore {
     return await this.queryOverlay(query, options)
   }
 
+  /**
+   * Ensures lookup pagination and ordering options are only used with a real KV selector.
+   *
+   * @param {KVStoreQuery} query - Query parameters sent to overlay.
+   * @throws {Error} If the query does not include a valid selector.
+   */
+  private validateQuerySelectors (query: KVStoreQuery): void {
+    const hasSelector =
+      (typeof query.key === 'string' && query.key.length > 0) ||
+      (typeof query.controller === 'string' && query.controller.length > 0) ||
+      (Array.isArray(query.protocolID) && query.protocolID.length === 2) ||
+      (Array.isArray(query.tags) && query.tags.length > 0)
+
+    if (!hasSelector) {
+      throw new Error('Must specify at least one selector: key, controller, protocolID, or tags')
+    }
+  }
+
   /**
    * Sets a key-value pair. The current user (wallet identity) becomes the controller.
    *

package/src/kvstore/__tests/GlobalKVStore.test.ts

@@ -577,7 +577,30 @@ describe('GlobalKVStore', () => {
 
     describe('sad paths', () => {
       it('rejects when no query parameters provided', async () => {
-        await expect(kvStore.get({})).rejects.toThrow('Must specify either key, controller, or protocolID')
+        await expect(kvStore.get({})).rejects.toThrow(
+          'Must specify at least one selector: key, controller, protocolID, or tags'
+        )
+      })
+
+      it('rejects pagination-only queries before resolving overlay hosts', async () => {
+        await expect(kvStore.get({ limit: 10 })).rejects.toThrow(
+          'Must specify at least one selector: key, controller, protocolID, or tags'
+        )
+        expect(mockResolver.query).not.toHaveBeenCalled()
+      })
+
+      it('rejects ordering-only queries before resolving overlay hosts', async () => {
+        await expect(kvStore.get({ sortOrder: 'desc' })).rejects.toThrow(
+          'Must specify at least one selector: key, controller, protocolID, or tags'
+        )
+        expect(mockResolver.query).not.toHaveBeenCalled()
+      })
+
+      it('rejects empty tag selector queries before resolving overlay hosts', async () => {
+        await expect(kvStore.get({ tags: [] })).rejects.toThrow(
+          'Must specify at least one selector: key, controller, protocolID, or tags'
+        )
+        expect(mockResolver.query).not.toHaveBeenCalled()
       })
 
       it('propagates overlay errors', async () => {

package/src/kvstore/types.ts

@@ -37,7 +37,8 @@ export interface KVStoreConfig {
 
 /**
  * Query parameters for KVStore lookups from overlay services.
- * Used when searching for existing key-value pairs in the network.
+ * Must include at least one selector: key, controller, protocolID, or non-empty tags.
+ * Pagination and ordering fields only refine selector-based lookups.
  */
 export interface KVStoreQuery {
   key?: string