nostr-wot-sdk 0.1.0 → 0.2.0

package/README.md

@@ -157,6 +157,76 @@ const config = await wot.getExtensionConfig();
 // Returns: { maxHops: 3, timeout: 5000, scoring: {...} } or null
 ```
 
+### Batch Operations
+
+#### `getDistanceBatch(targets)`
+
+Get distances for multiple pubkeys in a single call.
+```javascript
+const distances = await wot.getDistanceBatch(['pk1...', 'pk2...']);
+// Returns: { 'pk1...': 2, 'pk2...': null }
+```
+
+#### `getTrustScoreBatch(targets)`
+
+Get trust scores for multiple pubkeys in a single call.
+```javascript
+const scores = await wot.getTrustScoreBatch(['pk1...', 'pk2...']);
+// Returns: { 'pk1...': 0.72, 'pk2...': null }
+```
+
+#### `filterByWoT(pubkeys, options?)`
+
+Filter a list of pubkeys to only those within the Web of Trust.
+```javascript
+const trusted = await wot.filterByWoT(['pk1...', 'pk2...', 'pk3...']);
+// Returns: ['pk1...', 'pk3...'] (only those in WoT)
+```
+
+### Graph Queries (Extension-only)
+
+These methods require the browser extension and return `null`/empty when unavailable.
+
+#### `getFollows(pubkey?)`
+
+Get the follow list for a pubkey (defaults to your pubkey).
+```javascript
+const follows = await wot.getFollows();
+// Returns: ['pk1...', 'pk2...', ...]
+```
+
+#### `getCommonFollows(pubkey)`
+
+Get mutual follows between you and a target.
+```javascript
+const common = await wot.getCommonFollows('def456...');
+// Returns: ['pk1...', 'pk2...'] (people you both follow)
+```
+
+#### `getPath(target)`
+
+Get the actual path from you to a target.
+```javascript
+const path = await wot.getPath('def456...');
+// Returns: ['myPubkey', 'friend', 'friendOfFriend', 'def456...']
+```
+
+#### `getStats()`
+
+Get graph statistics.
+```javascript
+const stats = await wot.getStats();
+// Returns: { nodes: 50000, edges: 150000, lastSync: 1699999999, size: '12 MB' }
+```
+
+#### `isConfigured()`
+
+Check if the extension is configured and ready.
+```javascript
+const status = await wot.isConfigured();
+// Returns: { configured: true, mode: 'local', hasLocalGraph: true }
+```
+
 ## Browser Extension
 
 Install the [Nostr WoT Extension](https://github.com/mappingbitcoin/nostr-wot-extension) for:

package/dist/index.cjs

@@ -181,10 +181,14 @@ var WoT = class {
     const win = window;
     if ((_a = win.nostr) == null ? void 0 : _a.wot) {
       this.extension = win.nostr.wot;
-      if ((_b = win.nostr) == null ? void 0 : _b.getPublicKey) {
-        try {
-          this.extensionPubkey = await win.nostr.getPublicKey();
-        } catch (e) {
+      try {
+        this.extensionPubkey = await this.extension.getMyPubkey();
+      } catch (e) {
+        if ((_b = win.nostr) == null ? void 0 : _b.getPublicKey) {
+          try {
+            this.extensionPubkey = await win.nostr.getPublicKey();
+          } catch (e2) {
+          }
         }
       }
     }
@@ -309,13 +313,14 @@ var WoT = class {
    * Get computed trust score based on distance and weights
    * @param target - Target pubkey (hex)
    * @param options - Query options
-   * @returns Trust score between 0 and 1
+   * @returns Trust score between 0 and 1, or 0 if not connected
    */
   async getTrustScore(target, options) {
     const normalizedTarget = this.validatePubkey(target, "target");
     const ext = await this.getExtension();
     if (ext) {
-      return ext.getTrustScore(normalizedTarget);
+      const score = await ext.getTrustScore(normalizedTarget);
+      return score != null ? score : 0;
     }
     const details = await this.getDetails(normalizedTarget, options);
     if (!details) {
@@ -357,12 +362,9 @@ var WoT = class {
    * @param targets - Array of target pubkeys (hex)
    * @param options - Query options
    * @returns Map of pubkey to result
-   *
-   * Note: When using extension, this falls back to individual queries
-   * since the extension doesn't have a batch API.
    */
   async batchCheck(targets, options) {
-    var _a, _b;
+    var _a, _b, _c, _d;
     if (!Array.isArray(targets) || targets.length === 0) {
       throw new ValidationError("targets must be a non-empty array", "targets");
     }
@@ -373,29 +375,20 @@ var WoT = class {
     const ext = await this.getExtension();
     if (ext) {
       const results2 = /* @__PURE__ */ new Map();
-      await Promise.all(
-        normalizedTargets.map(async (pubkey) => {
-          try {
-            const [distance, score] = await Promise.all([
-              ext.getDistance(pubkey),
-              ext.getTrustScore(pubkey)
-            ]);
-            results2.set(pubkey, {
-              pubkey,
-              distance,
-              score,
-              inWoT: distance !== null && distance <= maxHops
-            });
-          } catch (e) {
-            results2.set(pubkey, {
-              pubkey,
-              distance: null,
-              score: 0,
-              inWoT: false
-            });
-          }
-        })
-      );
+      const [distances, scores] = await Promise.all([
+        ext.getDistanceBatch(normalizedTargets),
+        ext.getTrustScoreBatch(normalizedTargets)
+      ]);
+      for (const pubkey of normalizedTargets) {
+        const distance = (_b = distances[pubkey]) != null ? _b : null;
+        const score = (_c = scores[pubkey]) != null ? _c : 0;
+        results2.set(pubkey, {
+          pubkey,
+          distance,
+          score,
+          inWoT: distance !== null && distance <= maxHops
+        });
+      }
       return results2;
     }
     const myPubkey = await this.getEffectivePubkey();
@@ -412,7 +405,7 @@ var WoT = class {
           const score = item.distance !== null ? calculateTrustScore(
             {
               hops: item.distance,
-              paths: (_b = item.paths) != null ? _b : 1
+              paths: (_d = item.paths) != null ? _d : 1
             },
             this.scoring
           ) : 0;
@@ -508,6 +501,139 @@ var WoT = class {
     if (!ext) return null;
     return ext.getConfig();
   }
+  // ============================================
+  // Extension-only methods (require extension)
+  // ============================================
+  /**
+   * Check if the extension is configured and ready
+   * @returns Status object with configuration state, or null if not using extension
+   */
+  async isConfigured() {
+    const ext = await this.getExtension();
+    if (!ext) return null;
+    return ext.isConfigured();
+  }
+  /**
+   * Filter a list of pubkeys to only those within the Web of Trust
+   * @param pubkeys - Array of pubkeys to filter
+   * @param options - Query options (maxHops)
+   * @returns Filtered array of pubkeys within WoT
+   *
+   * Note: Extension-only. Falls back to batchCheck when extension unavailable.
+   */
+  async filterByWoT(pubkeys, options) {
+    var _a;
+    if (!Array.isArray(pubkeys) || pubkeys.length === 0) {
+      return [];
+    }
+    const normalizedPubkeys = pubkeys.filter((pk) => isValidPubkey(pk)).map((pk) => normalizePubkey(pk));
+    const maxHops = (_a = options == null ? void 0 : options.maxHops) != null ? _a : this.maxHops;
+    const ext = await this.getExtension();
+    if (ext) {
+      return ext.filterByWoT(normalizedPubkeys, maxHops);
+    }
+    const results = await this.batchCheck(normalizedPubkeys, options);
+    return Array.from(results.entries()).filter(([, result]) => result.inWoT).map(([pubkey]) => pubkey);
+  }
+  /**
+   * Get the follow list for a pubkey
+   * @param pubkey - Optional, defaults to user's pubkey
+   * @returns Array of followed pubkeys
+   *
+   * Note: Extension-only. Returns empty array if extension unavailable.
+   */
+  async getFollows(pubkey) {
+    const ext = await this.getExtension();
+    if (!ext) return [];
+    const normalizedPubkey = pubkey ? this.validatePubkey(pubkey, "pubkey") : void 0;
+    return ext.getFollows(normalizedPubkey);
+  }
+  /**
+   * Get mutual follows between the user and a target
+   * @param pubkey - Target pubkey
+   * @returns Array of common followed pubkeys
+   *
+   * Note: Extension-only. Returns empty array if extension unavailable.
+   */
+  async getCommonFollows(pubkey) {
+    const ext = await this.getExtension();
+    if (!ext) return [];
+    const normalizedPubkey = this.validatePubkey(pubkey, "pubkey");
+    return ext.getCommonFollows(normalizedPubkey);
+  }
+  /**
+   * Get graph statistics
+   * @returns Stats object with node/edge counts and sync info
+   *
+   * Note: Extension-only. Returns null if extension unavailable.
+   */
+  async getStats() {
+    const ext = await this.getExtension();
+    if (!ext) return null;
+    return ext.getStats();
+  }
+  /**
+   * Get an actual path from the user to the target
+   * @param target - Target pubkey
+   * @returns Array of pubkeys [user, ..., target], or null if not connected
+   *
+   * Note: Extension-only. Returns null if extension unavailable.
+   */
+  async getPath(target) {
+    const ext = await this.getExtension();
+    if (!ext) return null;
+    const normalizedTarget = this.validatePubkey(target, "target");
+    return ext.getPath(normalizedTarget);
+  }
+  /**
+   * Get distances for multiple pubkeys in a single call
+   * @param targets - Array of target pubkeys
+   * @returns Record of pubkey to hop count (null if not connected)
+   */
+  async getDistanceBatch(targets) {
+    if (!Array.isArray(targets) || targets.length === 0) {
+      return {};
+    }
+    const normalizedTargets = targets.map(
+      (t, i) => this.validatePubkey(t, `targets[${i}]`)
+    );
+    const ext = await this.getExtension();
+    if (ext) {
+      return ext.getDistanceBatch(normalizedTargets);
+    }
+    const results = {};
+    await Promise.all(
+      normalizedTargets.map(async (pubkey) => {
+        results[pubkey] = await this.getDistance(pubkey);
+      })
+    );
+    return results;
+  }
+  /**
+   * Get trust scores for multiple pubkeys in a single call
+   * @param targets - Array of target pubkeys
+   * @returns Record of pubkey to trust score (null if not connected)
+   */
+  async getTrustScoreBatch(targets) {
+    if (!Array.isArray(targets) || targets.length === 0) {
+      return {};
+    }
+    const normalizedTargets = targets.map(
+      (t, i) => this.validatePubkey(t, `targets[${i}]`)
+    );
+    const ext = await this.getExtension();
+    if (ext) {
+      return ext.getTrustScoreBatch(normalizedTargets);
+    }
+    const results = {};
+    await Promise.all(
+      normalizedTargets.map(async (pubkey) => {
+        const score = await this.getTrustScore(pubkey);
+        results[pubkey] = score > 0 ? score : null;
+      })
+    );
+    return results;
+  }
 };
 
 exports.DEFAULT_MAX_HOPS = DEFAULT_MAX_HOPS;
@@ -525,5 +651,3 @@ exports.WoTError = WoTError;
 exports.calculateTrustScore = calculateTrustScore;
 exports.isValidPubkey = isValidPubkey;
 exports.normalizePubkey = normalizePubkey;
-//# sourceMappingURL=index.cjs.map
-//# sourceMappingURL=index.cjs.map

package/dist/index.d.cts

@@ -251,6 +251,44 @@ interface ExtensionConfig {
      */
     scoring: Partial<ScoringConfig>;
 }
+/**
+ * Extension status returned by isConfigured()
+ */
+interface ExtensionStatus {
+    /**
+     * Whether the extension is configured and ready
+     */
+    configured: boolean;
+    /**
+     * Operating mode
+     */
+    mode: 'remote' | 'local' | 'hybrid';
+    /**
+     * Whether local graph data is available
+     */
+    hasLocalGraph: boolean;
+}
+/**
+ * Graph statistics returned by getStats()
+ */
+interface GraphStats {
+    /**
+     * Number of nodes (pubkeys) in the graph
+     */
+    nodes: number;
+    /**
+     * Number of edges (follow relationships) in the graph
+     */
+    edges: number;
+    /**
+     * Timestamp of last sync, or null if never synced
+     */
+    lastSync: number | null;
+    /**
+     * Human-readable size of the graph data
+     */
+    size: string;
+}
 /**
  * Extension WoT interface (window.nostr.wot)
  * Based on https://github.com/mappingbitcoin/nostr-wot-extension
@@ -260,33 +298,80 @@ interface NostrWoTExtension {
      * Get shortest path length to target pubkey
      * @returns Number of hops, or null if not connected
      */
-    getDistance(targetPubkey: string): Promise<number | null>;
-    /**
-     * Get computed trust score based on distance and configured weights
-     * @returns Trust score between 0 and 1
-     */
-    getTrustScore(targetPubkey: string): Promise<number>;
+    getDistance(target: string): Promise<number | null>;
     /**
      * Check if target is within your Web of Trust
      * @param maxHops - Optional max hops (uses extension config default if not specified)
      * @returns true if target is within maxHops
      */
-    isInMyWoT(targetPubkey: string, maxHops?: number): Promise<boolean>;
+    isInMyWoT(target: string, maxHops?: number): Promise<boolean>;
     /**
      * Get distance between any two pubkeys
-     * @returns Number of hops between the pubkeys
+     * @returns Number of hops between the pubkeys, or null if not connected
+     */
+    getDistanceBetween(from: string, to: string): Promise<number | null>;
+    /**
+     * Get computed trust score based on distance and path count
+     * @returns Trust score between 0 and 1, or null if not connected
      */
-    getDistanceBetween(fromPubkey: string, toPubkey: string): Promise<number | null>;
+    getTrustScore(target: string): Promise<number | null>;
     /**
      * Get distance and path count details
-     * @returns Object with hops and paths count
+     * @returns Object with hops and paths count, or null if not connected
      */
-    getDetails(targetPubkey: string): Promise<ExtensionDistanceResult | null>;
+    getDetails(target: string): Promise<ExtensionDistanceResult | null>;
     /**
      * Get current extension configuration
      * @returns Configuration object with maxHops, timeout, and scoring
      */
     getConfig(): Promise<ExtensionConfig>;
+    /**
+     * Get distances for multiple pubkeys in a single call
+     * @returns Map of pubkey to hop count (null if not connected)
+     */
+    getDistanceBatch(targets: string[]): Promise<Record<string, number | null>>;
+    /**
+     * Get trust scores for multiple pubkeys in a single call
+     * @returns Map of pubkey to trust score (null if not connected)
+     */
+    getTrustScoreBatch(targets: string[]): Promise<Record<string, number | null>>;
+    /**
+     * Filter a list of pubkeys to only those within the Web of Trust
+     * @param maxHops - Optional max hops override
+     * @returns Filtered array of pubkeys within WoT
+     */
+    filterByWoT(pubkeys: string[], maxHops?: number): Promise<string[]>;
+    /**
+     * Get the configured user's pubkey
+     * @returns User's pubkey or null if not configured
+     */
+    getMyPubkey(): Promise<string | null>;
+    /**
+     * Check if the extension is configured and ready
+     * @returns Status object with configuration state
+     */
+    isConfigured(): Promise<ExtensionStatus>;
+    /**
+     * Get the follow list for a pubkey
+     * @param pubkey - Optional, defaults to user's pubkey
+     * @returns Array of followed pubkeys
+     */
+    getFollows(pubkey?: string): Promise<string[]>;
+    /**
+     * Get mutual follows between the user and a target
+     * @returns Array of common followed pubkeys
+     */
+    getCommonFollows(pubkey: string): Promise<string[]>;
+    /**
+     * Get graph statistics
+     * @returns Stats object with node/edge counts and sync info
+     */
+    getStats(): Promise<GraphStats>;
+    /**
+     * Get an actual path from the user to the target
+     * @returns Array of pubkeys [user, ..., target], or null if not connected
+     */
+    getPath(target: string): Promise<string[] | null>;
 }
 /**
  * Window with nostr extension
@@ -351,7 +436,7 @@ declare class WoT {
      * Get computed trust score based on distance and weights
      * @param target - Target pubkey (hex)
      * @param options - Query options
-     * @returns Trust score between 0 and 1
+     * @returns Trust score between 0 and 1, or 0 if not connected
      */
     getTrustScore(target: string, options?: QueryOptions): Promise<number>;
     /**
@@ -367,9 +452,6 @@ declare class WoT {
      * @param targets - Array of target pubkeys (hex)
      * @param options - Query options
      * @returns Map of pubkey to result
-     *
-     * Note: When using extension, this falls back to individual queries
-     * since the extension doesn't have a batch API.
      */
     batchCheck(targets: string[], options?: QueryOptions): Promise<Map<string, BatchResult>>;
     /**
@@ -404,6 +486,63 @@ declare class WoT {
      * @returns Extension config or null if not using extension
      */
     getExtensionConfig(): Promise<ExtensionConfig | null>;
+    /**
+     * Check if the extension is configured and ready
+     * @returns Status object with configuration state, or null if not using extension
+     */
+    isConfigured(): Promise<ExtensionStatus | null>;
+    /**
+     * Filter a list of pubkeys to only those within the Web of Trust
+     * @param pubkeys - Array of pubkeys to filter
+     * @param options - Query options (maxHops)
+     * @returns Filtered array of pubkeys within WoT
+     *
+     * Note: Extension-only. Falls back to batchCheck when extension unavailable.
+     */
+    filterByWoT(pubkeys: string[], options?: QueryOptions): Promise<string[]>;
+    /**
+     * Get the follow list for a pubkey
+     * @param pubkey - Optional, defaults to user's pubkey
+     * @returns Array of followed pubkeys
+     *
+     * Note: Extension-only. Returns empty array if extension unavailable.
+     */
+    getFollows(pubkey?: string): Promise<string[]>;
+    /**
+     * Get mutual follows between the user and a target
+     * @param pubkey - Target pubkey
+     * @returns Array of common followed pubkeys
+     *
+     * Note: Extension-only. Returns empty array if extension unavailable.
+     */
+    getCommonFollows(pubkey: string): Promise<string[]>;
+    /**
+     * Get graph statistics
+     * @returns Stats object with node/edge counts and sync info
+     *
+     * Note: Extension-only. Returns null if extension unavailable.
+     */
+    getStats(): Promise<GraphStats | null>;
+    /**
+     * Get an actual path from the user to the target
+     * @param target - Target pubkey
+     * @returns Array of pubkeys [user, ..., target], or null if not connected
+     *
+     * Note: Extension-only. Returns null if extension unavailable.
+     */
+    getPath(target: string): Promise<string[] | null>;
+    /**
+     * Get distances for multiple pubkeys in a single call
+     * @param targets - Array of target pubkeys
+     * @returns Record of pubkey to hop count (null if not connected)
+     */
+    getDistanceBatch(targets: string[]): Promise<Record<string, number | null>>;
+    /**
+     * Get trust scores for multiple pubkeys in a single call
+     * @param targets - Array of target pubkeys
+     * @returns Record of pubkey to trust score (null if not connected)
+     */
+    getTrustScoreBatch(targets: string[]): Promise<Record<string, number | null>>;
 }
 
 /**
@@ -494,4 +633,4 @@ declare function normalizePubkey(pubkey: string): string;
  */
 declare function calculateTrustScore(result: DistanceResult, scoring: ScoringConfig): number;
 
-export { type BatchResult, DEFAULT_MAX_HOPS, DEFAULT_ORACLE, DEFAULT_SCORING, DEFAULT_TIMEOUT, type DistanceResult, type ExtensionConfig, type ExtensionDistanceResult, type LocalWoTOptions, NetworkError, type NostrContactEvent, type NostrWindow, type NostrWoTExtension, NotFoundError, type QueryOptions, RelayError, type ScoringConfig, type StorageAdapter, StorageError, type SyncOptions, type SyncProgress, TimeoutError, ValidationError, WoT, WoTError, type WoTFallbackOptions, type WoTOptions, calculateTrustScore, isValidPubkey, normalizePubkey };
+export { type BatchResult, DEFAULT_MAX_HOPS, DEFAULT_ORACLE, DEFAULT_SCORING, DEFAULT_TIMEOUT, type DistanceResult, type ExtensionConfig, type ExtensionDistanceResult, type ExtensionStatus, type GraphStats, type LocalWoTOptions, NetworkError, type NostrContactEvent, type NostrWindow, type NostrWoTExtension, NotFoundError, type QueryOptions, RelayError, type ScoringConfig, type StorageAdapter, StorageError, type SyncOptions, type SyncProgress, TimeoutError, ValidationError, WoT, WoTError, type WoTFallbackOptions, type WoTOptions, calculateTrustScore, isValidPubkey, normalizePubkey };