nostr-wot-sdk 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -0,0 +1,135 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.2] - 2025-02-05
+
+### Changed
+
+- **Scoring formula changed from multiplicative to additive** to match extension
+  - Old: `score = baseScore × distanceWeight × (1 + bonuses)`
+  - New: `score = (baseScore × distanceWeight) + bonuses`
+  - Example: 2 hops + 30% path bonus = 0.5 + 0.3 = 0.80 (was 0.65)
+  - This produces higher scores for pubkeys with multiple paths
+
+## [0.3.1] - 2025-02-05
+
+### Added
+
+- `getDistanceBatch(targets, includePaths?)` now accepts an optional `includePaths` parameter
+  - When `false` (default): returns `{ pubkey: hops }` - backwards compatible
+  - When `true`: returns `{ pubkey: { hops, paths } }` - includes path count for scoring
+
+### Changed
+
+- `getTrustScoreBatch` now uses path counts internally for accurate trust score calculation with path bonuses
+
+## [0.3.0] - 2025-02-05
+
+### Added
+
+- **Automatic Extension Connection for React** - Zero-config React integration
+  - `WoTProvider` now auto-connects to the extension by default (`useExtension: true`)
+  - New `useExtension()` hook for accessing extension connection state
+  - Extension state includes: `isConnected`, `isConnecting`, `isInstalled`, `isChecked`, `error`, `connect()`
+
+- **Event-based Extension Connection Flow**
+  - New `src/extension.ts` module with reliable extension detection
+  - `checkExtension(timeout?)` - Check if extension is installed using `nostr-wot-check` → `nostr-wot-present` handshake
+  - `connectExtension(timeout?)` - Connect to extension using `nostr-wot-connect` → `nostr-wot-ready` handshake
+  - `checkAndConnect(options?)` - Combined check and connect in one call
+  - `ExtensionConnector` class - Stateful connector with subscription support for state changes
+  - `getDefaultConnector()` / `resetDefaultConnector()` - Singleton pattern for shared connector
+
+- **New Extension Events Protocol**
+  | Event | Direction | Purpose |
+  |-------|-----------|---------|
+  | `nostr-wot-check` | Page → Extension | Check if extension installed |
+  | `nostr-wot-present` | Extension → Page | Response confirming presence |
+  | `nostr-wot-connect` | Page → Extension | Request API injection |
+  | `nostr-wot-ready` | Extension → Page | API is ready at `window.nostr.wot` |
+  | `nostr-wot-error` | Extension → Page | Injection failed with error |
+
+### Changed
+
+- `WoTProvider` props are now optional - just `<WoTProvider>` works out of the box
+- `WoT` class `getExtension()` now uses event-based connection flow for reliable detection
+
+### Usage
+
+```tsx
+import { WoTProvider, useWoT, useExtension } from 'nostr-wot-sdk/react';
+
+// Just wrap your app - no config needed
+function App() {
+  return (
+    <WoTProvider>
+      <YourApp />
+    </WoTProvider>
+  );
+}
+
+// Check extension status
+function Status() {
+  const { isConnected, isConnecting } = useExtension();
+  if (isConnecting) return <span>Connecting...</span>;
+  return <span>{isConnected ? 'Connected' : 'Not connected'}</span>;
+}
+
+// Use WoT data
+function Profile({ pubkey }) {
+  const { distance, score, loading } = useWoT(pubkey);
+  // ...
+}
+```
+
+## [0.2.0] - 2025-02-04
+
+### Added
+
+- Full extension API support matching [nostr-wot-extension](https://github.com/nostr-wot/nostr-wot-extension)
+- Extension-first architecture: extension always takes priority when available
+- New extension-only methods:
+  - `getFollows(pubkey?)` - Get follow list
+  - `getCommonFollows(pubkey)` - Get mutual follows
+  - `getPath(target)` - Get actual path to target
+  - `getStats()` - Get graph statistics
+  - `isConfigured()` - Check extension configuration status
+  - `getExtensionConfig()` - Get extension configuration
+- Batch operations:
+  - `getDistanceBatch(targets)` - Batch distance queries
+  - `getTrustScoreBatch(targets)` - Batch trust score queries
+  - `filterByWoT(pubkeys, options?)` - Filter pubkeys by WoT membership
+- React integration (`nostr-wot-sdk/react`):
+  - `WoTProvider` - Context provider
+  - `useWoT(pubkey)` - Full WoT data hook
+  - `useIsInWoT(pubkey)` - Boolean WoT check
+  - `useTrustScore(pubkey)` - Trust score hook
+  - `useBatchWoT(pubkeys)` - Batch queries hook
+- Local mode (`nostr-wot-sdk/local`) for server-side usage
+- GitHub Actions workflows for CI and npm publishing
+
+### Changed
+
+- `WoTOptions.useExtension` controls extension usage (default: `false`)
+- Fallback configuration via `WoTOptions.fallback` for oracle mode when extension unavailable
+
+## [0.1.0] - 2025-02-03
+
+### Added
+
+- Initial release
+- Core `WoT` class with oracle-based queries
+- Methods: `getDistance`, `isInMyWoT`, `getTrustScore`, `getDistanceBetween`, `batchCheck`, `getDetails`
+- Custom scoring configuration
+- TypeScript support with full type definitions
+- Error classes: `WoTError`, `NetworkError`, `NotFoundError`, `TimeoutError`, `ValidationError`
+
+[0.3.2]: https://github.com/nostr-wot/nostr-wot-sdk/compare/v0.3.1...v0.3.2
+[0.3.1]: https://github.com/nostr-wot/nostr-wot-sdk/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/nostr-wot/nostr-wot-sdk/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/nostr-wot/nostr-wot-sdk/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/nostr-wot/nostr-wot-sdk/releases/tag/v0.1.0

package/README.md

@@ -161,17 +161,22 @@ const config = await wot.getExtensionConfig();
 
 ### Batch Operations
 
-#### `getDistanceBatch(targets)`
+#### `getDistanceBatch(targets, includePaths?)`
 
 Get distances for multiple pubkeys in a single call.
 ```javascript
+// Without paths (faster, default)
 const distances = await wot.getDistanceBatch(['pk1...', 'pk2...']);
 // Returns: { 'pk1...': 2, 'pk2...': null }
+
+// With paths (includes path count for scoring)
+const details = await wot.getDistanceBatch(['pk1...', 'pk2...'], true);
+// Returns: { 'pk1...': { hops: 2, paths: 5 }, 'pk2...': null }
 ```
 
 #### `getTrustScoreBatch(targets)`
 
-Get trust scores for multiple pubkeys in a single call.
+Get trust scores for multiple pubkeys in a single call. Uses path counts internally for accurate scoring.
 ```javascript
 const scores = await wot.getTrustScoreBatch(['pk1...', 'pk2...']);
 // Returns: { 'pk1...': 0.72, 'pk2...': null }
@@ -316,21 +321,23 @@ const wot = new WoT({
       3: 0.25,   // 3 hops
       4: 0.1,    // 4+ hops
     },
-    // Bonus multipliers
-    mutualBonus: 0.5,      // +50% for mutual follows
-    pathBonus: 0.1,        // +10% per additional path
-    maxPathBonus: 0.5,     // Cap path bonus at +50%
+    // Bonus values (additive)
+    mutualBonus: 0.5,      // +0.5 for mutual follows
+    pathBonus: 0.1,        // +0.1 per additional path
+    maxPathBonus: 0.5,     // Cap path bonus at +0.5
   }
 });
 ```
 
 ### Scoring Formula
 ```
-score = baseScore × distanceWeight × (1 + bonuses)
+score = (baseScore × distanceWeight) + bonuses
 
 where:
   baseScore = 1 / (hops + 1)
   bonuses = mutualBonus (if mutual) + min(pathBonus × (paths - 1), maxPathBonus)
+
+Example: 2 hops + 30% path bonus = 0.5 + 0.3 = 0.80
 ```
 
 ## Server-Side Local Mode

package/dist/index.cjs

@@ -127,7 +127,7 @@ function calculateTrustScore(result, scoring) {
     const pathCountBonus = Math.min(pathBonus * (paths - 1), maxPathBonus);
     bonuses += pathCountBonus;
   }
-  const score = baseScore * distanceWeight * (1 + bonuses);
+  const score = baseScore * distanceWeight + bonuses;
   return Math.min(1, Math.max(0, score));
 }
 async function fetchWithTimeout(url, options = {}) {
@@ -844,12 +844,7 @@ var WoT = class {
     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) {
+  async getDistanceBatch(targets, includePaths = false) {
     if (!Array.isArray(targets) || targets.length === 0) {
       return {};
     }
@@ -858,7 +853,20 @@ var WoT = class {
     );
     const ext = await this.getExtension();
     if (ext) {
-      return ext.getDistanceBatch(normalizedTargets);
+      if (includePaths) {
+        return ext.getDistanceBatch(normalizedTargets, true);
+      }
+      return ext.getDistanceBatch(normalizedTargets, false);
+    }
+    if (includePaths) {
+      const results2 = {};
+      await Promise.all(
+        normalizedTargets.map(async (pubkey) => {
+          const details = await this.getDetails(pubkey);
+          results2[pubkey] = details ? { hops: details.hops, paths: details.paths } : null;
+        })
+      );
+      return results2;
     }
     const results = {};
     await Promise.all(

package/dist/index.d.cts

@@ -328,9 +328,19 @@ interface NostrWoTExtension {
     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>>;
+     * @param targets - Array of target pubkeys
+     * @param includePaths - When true, includes path count for each target
+     * @returns Map of pubkey to hop count (or { hops, paths } if includePaths is true)
+     */
+    getDistanceBatch(targets: string[], includePaths?: false): Promise<Record<string, number | null>>;
+    getDistanceBatch(targets: string[], includePaths: true): Promise<Record<string, {
+        hops: number;
+        paths: number;
+    } | null>>;
+    getDistanceBatch(targets: string[], includePaths?: boolean): Promise<Record<string, number | {
+        hops: number;
+        paths: number;
+    } | null>>;
     /**
      * Get trust scores for multiple pubkeys in a single call
      * @returns Map of pubkey to trust score (null if not connected)
@@ -537,9 +547,18 @@ declare class WoT {
     /**
      * 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>>;
+     * @param includePaths - When true, includes path count for each target
+     * @returns Record of pubkey to hop count (or { hops, paths } if includePaths is true)
+     */
+    getDistanceBatch(targets: string[], includePaths?: false): Promise<Record<string, number | null>>;
+    getDistanceBatch(targets: string[], includePaths: true): Promise<Record<string, {
+        hops: number;
+        paths: number;
+    } | null>>;
+    getDistanceBatch(targets: string[], includePaths?: boolean): Promise<Record<string, number | {
+        hops: number;
+        paths: number;
+    } | null>>;
     /**
      * Get trust scores for multiple pubkeys in a single call
      * @param targets - Array of target pubkeys
@@ -742,12 +761,14 @@ declare function normalizePubkey(pubkey: string): string;
  * Calculates trust score based on distance result and scoring config
  *
  * Formula:
- * score = baseScore × distanceWeight × (1 + bonuses)
+ * score = (baseScore × distanceWeight) + bonuses
  *
  * where:
  *   baseScore = 1 / (hops + 1)
  *   bonuses = mutualBonus (if mutual) + min(pathBonus × (paths - 1), maxPathBonus)
  *
+ * Example: 2 hops + 30% path bonus = 0.5 + 0.3 = 0.80
+ *
  * Note: `mutual` is optional (only available from oracle, not extension)
  */
 declare function calculateTrustScore(result: DistanceResult, scoring: ScoringConfig): number;

package/dist/index.d.ts

@@ -328,9 +328,19 @@ interface NostrWoTExtension {
     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>>;
+     * @param targets - Array of target pubkeys
+     * @param includePaths - When true, includes path count for each target
+     * @returns Map of pubkey to hop count (or { hops, paths } if includePaths is true)
+     */
+    getDistanceBatch(targets: string[], includePaths?: false): Promise<Record<string, number | null>>;
+    getDistanceBatch(targets: string[], includePaths: true): Promise<Record<string, {
+        hops: number;
+        paths: number;
+    } | null>>;
+    getDistanceBatch(targets: string[], includePaths?: boolean): Promise<Record<string, number | {
+        hops: number;
+        paths: number;
+    } | null>>;
     /**
      * Get trust scores for multiple pubkeys in a single call
      * @returns Map of pubkey to trust score (null if not connected)
@@ -537,9 +547,18 @@ declare class WoT {
     /**
      * 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>>;
+     * @param includePaths - When true, includes path count for each target
+     * @returns Record of pubkey to hop count (or { hops, paths } if includePaths is true)
+     */
+    getDistanceBatch(targets: string[], includePaths?: false): Promise<Record<string, number | null>>;
+    getDistanceBatch(targets: string[], includePaths: true): Promise<Record<string, {
+        hops: number;
+        paths: number;
+    } | null>>;
+    getDistanceBatch(targets: string[], includePaths?: boolean): Promise<Record<string, number | {
+        hops: number;
+        paths: number;
+    } | null>>;
     /**
      * Get trust scores for multiple pubkeys in a single call
      * @param targets - Array of target pubkeys
@@ -742,12 +761,14 @@ declare function normalizePubkey(pubkey: string): string;
  * Calculates trust score based on distance result and scoring config
  *
  * Formula:
- * score = baseScore × distanceWeight × (1 + bonuses)
+ * score = (baseScore × distanceWeight) + bonuses
  *
  * where:
  *   baseScore = 1 / (hops + 1)
  *   bonuses = mutualBonus (if mutual) + min(pathBonus × (paths - 1), maxPathBonus)
  *
+ * Example: 2 hops + 30% path bonus = 0.5 + 0.3 = 0.80
+ *
  * Note: `mutual` is optional (only available from oracle, not extension)
  */
 declare function calculateTrustScore(result: DistanceResult, scoring: ScoringConfig): number;

package/dist/index.js

@@ -125,7 +125,7 @@ function calculateTrustScore(result, scoring) {
     const pathCountBonus = Math.min(pathBonus * (paths - 1), maxPathBonus);
     bonuses += pathCountBonus;
   }
-  const score = baseScore * distanceWeight * (1 + bonuses);
+  const score = baseScore * distanceWeight + bonuses;
   return Math.min(1, Math.max(0, score));
 }
 async function fetchWithTimeout(url, options = {}) {
@@ -842,12 +842,7 @@ var WoT = class {
     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) {
+  async getDistanceBatch(targets, includePaths = false) {
     if (!Array.isArray(targets) || targets.length === 0) {
       return {};
     }
@@ -856,7 +851,20 @@ var WoT = class {
     );
     const ext = await this.getExtension();
     if (ext) {
-      return ext.getDistanceBatch(normalizedTargets);
+      if (includePaths) {
+        return ext.getDistanceBatch(normalizedTargets, true);
+      }
+      return ext.getDistanceBatch(normalizedTargets, false);
+    }
+    if (includePaths) {
+      const results2 = {};
+      await Promise.all(
+        normalizedTargets.map(async (pubkey) => {
+          const details = await this.getDetails(pubkey);
+          results2[pubkey] = details ? { hops: details.hops, paths: details.paths } : null;
+        })
+      );
+      return results2;
     }
     const results = {};
     await Promise.all(

package/dist/local/index.cjs

@@ -92,7 +92,7 @@ function calculateTrustScore(result, scoring) {
     const pathCountBonus = Math.min(pathBonus * (paths - 1), maxPathBonus);
     bonuses += pathCountBonus;
   }
-  const score = baseScore * distanceWeight * (1 + bonuses);
+  const score = baseScore * distanceWeight + bonuses;
   return Math.min(1, Math.max(0, score));
 }
 function chunk(array, size) {