nostr-wot-sdk 0.3.2 → 0.4.1

package/CHANGELOG.md

@@ -5,6 +5,49 @@ 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.4.1] - 2025-02-05
+
+### Changed
+
+- **`getDetails` now returns `score`** in addition to `hops` and `paths`
+  - Extension: `{ hops: 2, paths: 5, score: 0.65 }`
+  - Oracle fallback: `{ hops: 2, paths: 5, score: 0 }` (score is 0 when using oracle)
+
+- **`getDistanceBatch` now accepts options object** instead of boolean
+  - `{ includePaths: true }` - Include path counts
+  - `{ includeScores: true }` - Include trust scores
+  - `{ includePaths: true, includeScores: true }` - Include both
+  - Legacy boolean `true` still works (backwards compatible, same as `{ includePaths: true }`)
+
+### Added
+
+- New `DistanceBatchOptions` type exported for TypeScript users
+
+## [0.4.0] - 2025-02-05
+
+### Breaking Changes
+
+- **Removed `useExtension` option** - The SDK now always uses the extension when available
+  - Extension-first is now the only mode; no need to opt-in
+  - `WoTOptions.useExtension` has been removed from the type
+  - Simply create `new WoT()` or `new WoT({ fallback: { myPubkey: '...' } })`
+
+- **Removed local sync functionality** - Use the browser extension for local graph storage
+  - Removed `src/local/` directory entirely
+  - Removed `nostr-wot-sdk/local` export
+  - Extension handles all syncing and local storage
+
+- **Trust scores now come from extension only**
+  - Removed SDK-side trust score calculation
+  - `getTrustScore(target)` no longer accepts options parameter
+  - Returns 0 when extension is not available
+
+### Changed
+
+- `WoT` constructor now has all parameters optional
+- `WoTProvider` no longer has `useExtension` option
+- Simplified codebase with extension-first architecture
+
 ## [0.3.2] - 2025-02-05
 
 ### Changed
@@ -128,6 +171,8 @@ function Profile({ pubkey }) {
 - TypeScript support with full type definitions
 - Error classes: `WoTError`, `NetworkError`, `NotFoundError`, `TimeoutError`, `ValidationError`
 
+[0.4.1]: https://github.com/nostr-wot/nostr-wot-sdk/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/nostr-wot/nostr-wot-sdk/compare/v0.3.2...v0.4.0
 [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

package/README.md

@@ -16,9 +16,8 @@ Install the [Nostr WoT Extension](https://github.com/nostr-wot/nostr-wot-extensi
 ```javascript
 import { WoT } from 'nostr-wot-sdk';
 
-// Extension mode - no pubkey needed, uses extension's data
+// The SDK automatically uses the extension when available
 const wot = new WoT({
-  useExtension: true,
   fallback: {
     oracle: 'https://nostr-wot.com',
     myPubkey: 'abc123...'  // Used only if extension unavailable
@@ -33,21 +32,21 @@ console.log(hops); // 2
 const trusted = await wot.isInMyWoT('def456...', { maxHops: 3 });
 console.log(trusted); // true
 
-// Trust score
+// Trust score (from extension)
 const score = await wot.getTrustScore('def456...');
 console.log(score); // 0.72
 ```
 
 When the extension is installed, **it always takes priority** — the SDK uses the extension's pubkey and locally-cached follow graph automatically.
 
-### Without Extension (Oracle Mode)
+### Without Extension (Oracle Fallback)
 
 ```javascript
 import { WoT } from 'nostr-wot-sdk';
 
 const wot = new WoT({
   oracle: 'https://nostr-wot.com',
-  myPubkey: 'abc123...'  // Required in oracle-only mode
+  myPubkey: 'abc123...'  // Required for oracle fallback
 });
 
 const hops = await wot.getDistance('def456...');
@@ -59,7 +58,6 @@ const hops = await wot.getDistance('def456...');
 - **Simple API** — Three methods cover most use cases
 - **Cross-Site Trust** — Extension provides same WoT data on all websites
 - **Offline Support** — Extension caches data locally for offline queries
-- **Custom Scoring** — Define your own trust weights
 - **Batch Queries** — Check multiple pubkeys efficiently
 - **TypeScript** — Full type definitions included
 
@@ -72,17 +70,15 @@ const wot = new WoT(options);
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `useExtension` | boolean | `false`* | Use browser extension if available (recommended) |
-| `oracle` | string | `'https://nostr-wot.com'` | Oracle API URL (fallback) |
-| `myPubkey` | string | — | Your pubkey (optional with extension, required otherwise) |
+| `oracle` | string | `'https://nostr-wot.com'` | Oracle API URL (fallback when extension unavailable) |
+| `myPubkey` | string | — | Your pubkey (optional - fetched from extension when available) |
 | `maxHops` | number | `3` | Default max search depth |
 | `timeout` | number | `5000` | Request timeout (ms) |
-| `scoring` | object | See below | Trust score weights |
 | `fallback` | object | — | Fallback config when extension unavailable |
 
-*Note: When using the React `WoTProvider`, `useExtension` defaults to `true`.
+Trust scores are calculated by the extension and not configurable via the SDK.
 
-**Note:** When `useExtension: true` and the extension is installed, the extension's pubkey and data are always used, regardless of `myPubkey` or `oracle` settings.
+**Note:** When the extension is installed, it always takes priority over `myPubkey` or `oracle` settings.
 
 ### Methods
 
@@ -102,12 +98,12 @@ const trusted = await wot.isInMyWoT('def456...', { maxHops: 2 });
 // Returns: boolean
 ```
 
-#### `getTrustScore(target, options?)`
+#### `getTrustScore(target)`
 
-Get computed trust score based on distance and weights.
+Get computed trust score from the extension.
 ```javascript
 const score = await wot.getTrustScore('def456...');
-// Returns: number (0-1)
+// Returns: number (0-1), or 0 if extension unavailable
 ```
 
 #### `getDistanceBetween(from, to, options?)`
@@ -128,11 +124,11 @@ const results = await wot.batchCheck(['pk1...', 'pk2...', 'pk3...']);
 
 #### `getDetails(target, options?)`
 
-Get distance and path count details.
+Get distance, path count, and score details.
 ```javascript
 const details = await wot.getDetails('def456...');
-// Returns: { hops: 2, paths: 5 }
-// Oracle may also return: bridges, mutual
+// Returns: { hops: 2, paths: 5, score: 0.65 }
+// Oracle may also return: bridges, mutual (but score will be 0)
 ```
 
 #### `getMyPubkey()`
@@ -153,7 +149,7 @@ const usingExt = await wot.isUsingExtension();
 
 #### `getExtensionConfig()`
 
-Get extension's configuration (only when using extension).
+Get extension's configuration.
 ```javascript
 const config = await wot.getExtensionConfig();
 // Returns: { maxHops: 3, timeout: 5000, scoring: {...} } or null
@@ -161,22 +157,33 @@ const config = await wot.getExtensionConfig();
 
 ### Batch Operations
 
-#### `getDistanceBatch(targets, includePaths?)`
+#### `getDistanceBatch(targets, options?)`
 
 Get distances for multiple pubkeys in a single call.
 ```javascript
-// Without paths (faster, default)
+// Default (just hops)
 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);
+// With paths
+const withPaths = await wot.getDistanceBatch(['pk1...', 'pk2...'], { includePaths: true });
 // Returns: { 'pk1...': { hops: 2, paths: 5 }, 'pk2...': null }
+
+// With scores
+const withScores = await wot.getDistanceBatch(['pk1...', 'pk2...'], { includeScores: true });
+// Returns: { 'pk1...': { hops: 2, score: 0.65 }, 'pk2...': null }
+
+// With both
+const full = await wot.getDistanceBatch(['pk1...', 'pk2...'], { includePaths: true, includeScores: true });
+// Returns: { 'pk1...': { hops: 2, paths: 5, score: 0.65 }, 'pk2...': null }
+
+// Legacy boolean still works (backwards compatible)
+const legacy = await wot.getDistanceBatch(['pk1...'], true);  // same as { includePaths: true }
 ```
 
 #### `getTrustScoreBatch(targets)`
 
-Get trust scores for multiple pubkeys in a single call. Uses path counts internally for accurate scoring.
+Get trust scores for multiple pubkeys in a single call.
 ```javascript
 const scores = await wot.getTrustScoreBatch(['pk1...', 'pk2...']);
 // Returns: { 'pk1...': 0.72, 'pk2...': null }
@@ -248,7 +255,6 @@ The SDK automatically detects and connects to the extension using an event-based
 
 ```javascript
 const wot = new WoT({
-  useExtension: true,
   fallback: {
     oracle: 'https://nostr-wot.com',
     myPubkey: 'abc123...'
@@ -307,60 +313,6 @@ The SDK uses a standard event-based protocol to communicate with the extension:
 | `nostr-wot-ready` | Extension → Page | API is ready at `window.nostr.wot` |
 | `nostr-wot-error` | Extension → Page | Injection failed with error |
 
-## Custom Scoring
-
-Define how trust scores are calculated:
-```javascript
-const wot = new WoT({
-  useExtension: true,
-  scoring: {
-    // Distance weights (score multiplier per hop)
-    distanceWeights: {
-      1: 1.0,    // Direct follows
-      2: 0.5,    // 2 hops
-      3: 0.25,   // 3 hops
-      4: 0.1,    // 4+ hops
-    },
-    // 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) + 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
-
-For Node.js/server environments where the browser extension isn't available:
-
-```javascript
-import { LocalWoT } from 'nostr-wot-sdk/local';
-
-const wot = new LocalWoT({
-  myPubkey: 'abc123...',
-  relays: ['wss://relay.damus.io', 'wss://nos.lol']
-});
-
-// Sync follow graph (2 hops from your pubkey)
-await wot.sync({ depth: 2 });
-
-// Now queries run locally
-const hops = await wot.getDistance('def456...');
-```
-
-Storage options: `'memory'` (default), `'indexeddb'` (browser), or custom adapter.
-
 ## Framework Integration
 
 ### React
@@ -416,12 +368,6 @@ function Profile({ pubkey }) {
   fallback: { myPubkey: 'abc123...' }
 }}>
 
-// Oracle-only mode (no extension)
-<WoTProvider options={{
-  useExtension: false,
-  myPubkey: 'abc123...'
-}}>
-
 // Custom extension connection timeouts
 <WoTProvider extensionOptions={{
   checkTimeout: 100,    // Extension detection timeout (ms)
@@ -462,8 +408,7 @@ Full type definitions included:
 ```typescript
 import { WoT, DistanceResult, WoTOptions } from 'nostr-wot-sdk';
 
-const options: WoTOptions = { useExtension: true };
-const wot = new WoT(options);
+const wot = new WoT();
 const result: DistanceResult | null = await wot.getDetails(pubkey);
 const score: number = await wot.getTrustScore(pubkey);
 ```

package/dist/index.cjs

@@ -44,35 +44,8 @@ var ValidationError = class extends WoTError {
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
-var StorageError = class extends WoTError {
-  constructor(operation, message) {
-    super(message || `Storage operation failed: ${operation}`);
-    this.name = "StorageError";
-    this.operation = operation;
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-};
-var RelayError = class extends WoTError {
-  constructor(relay, message) {
-    super(message || `Relay connection failed: ${relay}`);
-    this.name = "RelayError";
-    this.relay = relay;
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-};
 
 // src/utils.ts
-var DEFAULT_SCORING = {
-  distanceWeights: {
-    1: 1,
-    2: 0.5,
-    3: 0.25,
-    4: 0.1
-  },
-  mutualBonus: 0.5,
-  pathBonus: 0.1,
-  maxPathBonus: 0.5
-};
 var DEFAULT_ORACLE = "https://nostr-wot.com";
 var DEFAULT_MAX_HOPS = 3;
 var DEFAULT_TIMEOUT = 5e3;
@@ -87,49 +60,10 @@ function isValidOracleUrl(url) {
     return false;
   }
 }
-function isValidRelayUrl(url) {
-  try {
-    const parsed = new URL(url);
-    return parsed.protocol === "wss:" || parsed.protocol === "ws:";
-  } catch (e) {
-    return false;
-  }
-}
 var MAX_BATCH_SIZE = 1e4;
 function normalizePubkey(pubkey) {
   return pubkey.toLowerCase();
 }
-function mergeScoringConfig(partial) {
-  var _a, _b, _c;
-  if (!partial) return { ...DEFAULT_SCORING };
-  return {
-    distanceWeights: {
-      ...DEFAULT_SCORING.distanceWeights,
-      ...partial.distanceWeights
-    },
-    mutualBonus: (_a = partial.mutualBonus) != null ? _a : DEFAULT_SCORING.mutualBonus,
-    pathBonus: (_b = partial.pathBonus) != null ? _b : DEFAULT_SCORING.pathBonus,
-    maxPathBonus: (_c = partial.maxPathBonus) != null ? _c : DEFAULT_SCORING.maxPathBonus
-  };
-}
-function calculateTrustScore(result, scoring) {
-  var _a, _b;
-  const { hops, paths, mutual } = result;
-  const { distanceWeights, mutualBonus, pathBonus, maxPathBonus } = scoring;
-  const baseScore = 1 / (hops + 1);
-  const maxDefinedHop = Math.max(...Object.keys(distanceWeights).map(Number));
-  const distanceWeight = (_b = (_a = distanceWeights[hops]) != null ? _a : distanceWeights[maxDefinedHop]) != null ? _b : 0.1;
-  let bonuses = 0;
-  if (mutual === true) {
-    bonuses += mutualBonus;
-  }
-  if (paths > 1) {
-    const pathCountBonus = Math.min(pathBonus * (paths - 1), maxPathBonus);
-    bonuses += pathCountBonus;
-  }
-  const score = baseScore * distanceWeight + bonuses;
-  return Math.min(1, Math.max(0, score));
-}
 async function fetchWithTimeout(url, options = {}) {
   const { timeout = DEFAULT_TIMEOUT, ...fetchOptions } = options;
   const controller = new AbortController();
@@ -378,41 +312,26 @@ function resetDefaultConnector() {
 
 // src/wot.ts
 var WoT = class {
-  constructor(options) {
+  constructor(options = {}) {
     this.extension = null;
     this.extensionChecked = false;
     this.extensionPubkey = null;
-    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n;
-    this.useExtension = (_a = options.useExtension) != null ? _a : false;
-    this.fallbackOptions = (_b = options.fallback) != null ? _b : null;
-    if (!this.useExtension) {
-      if (!options.myPubkey) {
-        throw new ValidationError("myPubkey is required when not using extension", "myPubkey");
-      }
-      if (!isValidPubkey(options.myPubkey)) {
-        throw new ValidationError(
-          "myPubkey must be a valid 64-character hex string",
-          "myPubkey"
-        );
-      }
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k;
+    this.fallbackOptions = (_a = options.fallback) != null ? _a : null;
+    if (options.myPubkey && isValidPubkey(options.myPubkey)) {
       this.fallbackPubkey = normalizePubkey(options.myPubkey);
+    } else if ((_b = this.fallbackOptions) == null ? void 0 : _b.myPubkey) {
+      this.fallbackPubkey = normalizePubkey(this.fallbackOptions.myPubkey);
     } else {
-      if (options.myPubkey && isValidPubkey(options.myPubkey)) {
-        this.fallbackPubkey = normalizePubkey(options.myPubkey);
-      } else if ((_c = this.fallbackOptions) == null ? void 0 : _c.myPubkey) {
-        this.fallbackPubkey = normalizePubkey(this.fallbackOptions.myPubkey);
-      } else {
-        this.fallbackPubkey = null;
-      }
+      this.fallbackPubkey = null;
     }
-    const oracleUrl = (_f = (_e = options.oracle) != null ? _e : (_d = this.fallbackOptions) == null ? void 0 : _d.oracle) != null ? _f : DEFAULT_ORACLE;
+    const oracleUrl = (_e = (_d = options.oracle) != null ? _d : (_c = this.fallbackOptions) == null ? void 0 : _c.oracle) != null ? _e : DEFAULT_ORACLE;
     if (!isValidOracleUrl(oracleUrl)) {
       throw new ValidationError("oracle must be a valid HTTPS URL", "oracle");
     }
     this.oracle = oracleUrl;
-    this.maxHops = (_i = (_h = options.maxHops) != null ? _h : (_g = this.fallbackOptions) == null ? void 0 : _g.maxHops) != null ? _i : DEFAULT_MAX_HOPS;
-    this.timeout = (_l = (_k = options.timeout) != null ? _k : (_j = this.fallbackOptions) == null ? void 0 : _j.timeout) != null ? _l : DEFAULT_TIMEOUT;
-    this.scoring = mergeScoringConfig((_n = options.scoring) != null ? _n : (_m = this.fallbackOptions) == null ? void 0 : _m.scoring);
+    this.maxHops = (_h = (_g = options.maxHops) != null ? _g : (_f = this.fallbackOptions) == null ? void 0 : _f.maxHops) != null ? _h : DEFAULT_MAX_HOPS;
+    this.timeout = (_k = (_j = options.timeout) != null ? _j : (_i = this.fallbackOptions) == null ? void 0 : _i.timeout) != null ? _k : DEFAULT_TIMEOUT;
   }
   /**
    * Checks if browser extension is available and returns it
@@ -420,7 +339,6 @@ var WoT = class {
    */
   async getExtension() {
     var _a, _b;
-    if (!this.useExtension) return null;
     if (this.extensionChecked) return this.extension;
     this.extensionChecked = true;
     if (typeof window === "undefined") return null;
@@ -565,23 +483,18 @@ var WoT = class {
     return distance !== null && distance <= maxHops;
   }
   /**
-   * Get computed trust score based on distance and weights
+   * Get computed trust score from extension
    * @param target - Target pubkey (hex)
-   * @param options - Query options
-   * @returns Trust score between 0 and 1, or 0 if not connected
+   * @returns Trust score between 0 and 1, or 0 if not connected or extension unavailable
    */
-  async getTrustScore(target, options) {
+  async getTrustScore(target) {
     const normalizedTarget = this.validatePubkey(target, "target");
     const ext = await this.getExtension();
     if (ext) {
       const score = await ext.getTrustScore(normalizedTarget);
       return score != null ? score : 0;
     }
-    const details = await this.getDetails(normalizedTarget, options);
-    if (!details) {
-      return 0;
-    }
-    return calculateTrustScore(details, this.scoring);
+    return 0;
   }
   /**
    * Get distance between any two pubkeys
@@ -619,7 +532,7 @@ var WoT = class {
    * @returns Map of pubkey to result
    */
   async batchCheck(targets, options) {
-    var _a, _b, _c, _d;
+    var _a, _b, _c;
     if (!Array.isArray(targets) || targets.length === 0) {
       throw new ValidationError("targets must be a non-empty array", "targets");
     }
@@ -663,17 +576,11 @@ var WoT = class {
         );
         for (const item of response.results) {
           const inWoT = item.distance !== null && item.distance <= maxHops;
-          const score = item.distance !== null ? calculateTrustScore(
-            {
-              hops: item.distance,
-              paths: (_d = item.paths) != null ? _d : 1
-            },
-            this.scoring
-          ) : 0;
           results.set(item.pubkey, {
             pubkey: item.pubkey,
             distance: item.distance,
-            score,
+            score: 0,
+            // Trust scores only available via extension
             inWoT
           });
         }
@@ -714,10 +621,11 @@ var WoT = class {
     const myPubkey = await this.getEffectivePubkey();
     const maxHops = (_a = options == null ? void 0 : options.maxHops) != null ? _a : this.maxHops;
     try {
-      return await this.apiRequest(
+      const response = await this.apiRequest(
         `/details/${myPubkey}/${normalizedTarget}?maxHops=${maxHops}`,
         options
       );
+      return { ...response, score: 0 };
     } catch (error) {
       if (error instanceof NotFoundError) {
         return null;
@@ -738,12 +646,6 @@ var WoT = class {
   getOracle() {
     return this.oracle;
   }
-  /**
-   * Get the current scoring configuration
-   */
-  getScoringConfig() {
-    return { ...this.scoring };
-  }
   /**
    * Check if extension is available and being used
    */
@@ -844,26 +746,32 @@ var WoT = class {
     const normalizedTarget = this.validatePubkey(target, "target");
     return ext.getPath(normalizedTarget);
   }
-  async getDistanceBatch(targets, includePaths = false) {
+  async getDistanceBatch(targets, options = false) {
     if (!Array.isArray(targets) || targets.length === 0) {
       return {};
     }
     const normalizedTargets = targets.map(
       (t, i) => this.validatePubkey(t, `targets[${i}]`)
     );
+    const opts = typeof options === "boolean" ? { includePaths: options } : options || {};
+    const { includePaths, includeScores } = opts;
     const ext = await this.getExtension();
     if (ext) {
-      if (includePaths) {
-        return ext.getDistanceBatch(normalizedTargets, true);
-      }
-      return ext.getDistanceBatch(normalizedTargets, false);
+      return ext.getDistanceBatch(normalizedTargets, opts);
     }
-    if (includePaths) {
+    if (includePaths || includeScores) {
       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;
+          if (!details) {
+            results2[pubkey] = null;
+            return;
+          }
+          const result = { hops: details.hops };
+          if (includePaths) result.paths = details.paths;
+          if (includeScores) result.score = details.score;
+          results2[pubkey] = result;
         })
       );
       return results2;
@@ -905,25 +813,20 @@ var WoT = class {
 
 exports.DEFAULT_MAX_HOPS = DEFAULT_MAX_HOPS;
 exports.DEFAULT_ORACLE = DEFAULT_ORACLE;
-exports.DEFAULT_SCORING = DEFAULT_SCORING;
 exports.DEFAULT_TIMEOUT = DEFAULT_TIMEOUT;
 exports.ExtensionConnector = ExtensionConnector;
 exports.MAX_BATCH_SIZE = MAX_BATCH_SIZE;
 exports.NetworkError = NetworkError;
 exports.NotFoundError = NotFoundError;
-exports.RelayError = RelayError;
-exports.StorageError = StorageError;
 exports.TimeoutError = TimeoutError;
 exports.ValidationError = ValidationError;
 exports.WoT = WoT;
 exports.WoTError = WoTError;
-exports.calculateTrustScore = calculateTrustScore;
 exports.checkAndConnect = checkAndConnect;
 exports.checkExtension = checkExtension;
 exports.connectExtension = connectExtension;
 exports.getDefaultConnector = getDefaultConnector;
 exports.isValidOracleUrl = isValidOracleUrl;
 exports.isValidPubkey = isValidPubkey;
-exports.isValidRelayUrl = isValidRelayUrl;
 exports.normalizePubkey = normalizePubkey;
 exports.resetDefaultConnector = resetDefaultConnector;