nostr-wot-sdk 0.2.0 → 0.3.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 MappingBitcoin.com
+Copyright (c) 2026 nostr-wot.com
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -11,7 +11,7 @@ npm install nostr-wot-sdk
 
 ### With Browser Extension (Recommended)
 
-Install the [Nostr WoT Extension](https://github.com/mappingbitcoin/nostr-wot-extension) for the best experience. The extension downloads your follow graph locally and works across all websites.
+Install the [Nostr WoT Extension](https://github.com/nostr-wot/nostr-wot-extension) for the best experience. The extension downloads your follow graph locally and works across all websites.
 
 ```javascript
 import { WoT } from 'nostr-wot-sdk';
@@ -72,7 +72,7 @@ const wot = new WoT(options);
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `useExtension` | boolean | `false` | Use browser extension if available (recommended) |
+| `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) |
 | `maxHops` | number | `3` | Default max search depth |
@@ -80,6 +80,8 @@ const wot = new WoT(options);
 | `scoring` | object | See below | Trust score weights |
 | `fallback` | object | — | Fallback config when extension unavailable |
 
+*Note: When using the React `WoTProvider`, `useExtension` defaults to `true`.
+
 **Note:** When `useExtension: true` and the extension is installed, the extension's pubkey and data are always used, regardless of `myPubkey` or `oracle` settings.
 
 ### Methods
@@ -159,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 }
@@ -229,7 +236,7 @@ const status = await wot.isConfigured();
 
 ## Browser Extension
 
-Install the [Nostr WoT Extension](https://github.com/mappingbitcoin/nostr-wot-extension) for:
+Install the [Nostr WoT Extension](https://github.com/nostr-wot/nostr-wot-extension) for:
 
 - **Local Data** — Downloads and caches your follow graph locally
 - **Fast Queries** — No network requests needed after sync
@@ -237,7 +244,7 @@ Install the [Nostr WoT Extension](https://github.com/mappingbitcoin/nostr-wot-ex
 - **Privacy** — Queries never leave your browser
 - **Offline** — Works without internet once synced
 
-The SDK automatically detects `window.nostr.wot` and uses it. When the extension is present, it **always takes priority** over oracle settings.
+The SDK automatically detects and connects to the extension using an event-based handshake. When the extension is present, it **always takes priority** over oracle settings.
 
 ```javascript
 const wot = new WoT({
@@ -256,6 +263,50 @@ if (await wot.isUsingExtension()) {
 }
 ```
 
+### Extension Connection Utilities
+
+For advanced use cases, the SDK exports low-level extension connection functions:
+
+```javascript
+import {
+  checkExtension,     // Check if extension is installed
+  connectExtension,   // Connect to the extension
+  checkAndConnect,    // Check and connect in one call
+  ExtensionConnector  // Stateful connector class
+} from 'nostr-wot-sdk';
+
+// Check if extension is installed (100ms timeout)
+const isInstalled = await checkExtension();
+
+// Connect to extension (5s timeout)
+const extension = await connectExtension();
+
+// Or do both in one call
+const result = await checkAndConnect();
+if (result.state === 'connected') {
+  const distance = await result.extension.getDistance('target...');
+}
+
+// For stateful connection management
+const connector = new ExtensionConnector();
+connector.subscribe((result) => {
+  console.log('State changed:', result.state);
+});
+await connector.connect();
+```
+
+#### Extension Events
+
+The SDK uses a standard event-based protocol to communicate with the extension:
+
+| 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 |
+
 ## Custom Scoring
 
 Define how trust scores are calculated:
@@ -311,19 +362,33 @@ Storage options: `'memory'` (default), `'indexeddb'` (browser), or custom adapte
 ## Framework Integration
 
 ### React
+
+The SDK provides first-class React support with automatic extension detection and connection. Just wrap your app with `WoTProvider` and you're ready to go — no additional configuration needed.
+
 ```javascript
-import { useWoT, WoTProvider } from 'nostr-wot-sdk/react';
+import { WoTProvider, useWoT, useExtension } from 'nostr-wot-sdk/react';
 
-// Wrap your app with the provider
+// Wrap your app - automatically connects to extension
 function App() {
   return (
-    <WoTProvider options={{ useExtension: true }}>
+    <WoTProvider>
       <YourApp />
     </WoTProvider>
   );
 }
 
-// Use hooks in components
+// Check extension status anywhere
+function ExtensionStatus() {
+  const { isConnected, isConnecting, isInstalled, error } = useExtension();
+
+  if (isConnecting) return <span>Connecting to extension...</span>;
+  if (!isInstalled) return <span>Install the WoT extension for best experience</span>;
+  if (error) return <span>Error: {error}</span>;
+  if (isConnected) return <span>Connected to extension!</span>;
+  return null;
+}
+
+// Use WoT data in components
 function Profile({ pubkey }) {
   const { distance, score, loading } = useWoT(pubkey);
 
@@ -341,14 +406,63 @@ function Profile({ pubkey }) {
 }
 ```
 
+#### Provider Options
+
+```javascript
+// With fallback for when extension is not installed
+<WoTProvider options={{
+  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)
+  connectTimeout: 5000  // Connection timeout (ms)
+}}>
+```
+
+#### Available Hooks
+
+| Hook | Description |
+|------|-------------|
+| `useWoT(pubkey)` | Get distance, score, and details for a pubkey |
+| `useIsInWoT(pubkey)` | Check if pubkey is in your WoT (boolean) |
+| `useTrustScore(pubkey)` | Get trust score only |
+| `useBatchWoT(pubkeys[])` | Check multiple pubkeys efficiently |
+| `useExtension()` | Get extension connection state |
+| `useWoTInstance()` | Get raw WoT instance for advanced usage |
+
+#### Extension State
+
+The `useExtension()` hook provides detailed extension status:
+
+```javascript
+const {
+  state,        // 'idle' | 'checking' | 'connecting' | 'connected' | 'not-installed' | 'error'
+  isConnected,  // Extension is connected and ready
+  isConnecting, // Currently checking/connecting
+  isInstalled,  // Extension is installed (may still be connecting)
+  isChecked,    // Initial check complete
+  error,        // Error message if connection failed
+  connect,      // Function to manually retry connection
+} = useExtension();
+```
+
 ## TypeScript
 
 Full type definitions included:
 ```typescript
 import { WoT, DistanceResult, WoTOptions } from 'nostr-wot-sdk';
 
-const wot = new WoT(options: WoTOptions);
-const result: DistanceResult = await wot.getDetails(pubkey);
+const options: WoTOptions = { useExtension: true };
+const wot = new WoT(options);
+const result: DistanceResult | null = await wot.getDetails(pubkey);
 const score: number = await wot.getTrustScore(pubkey);
 ```
 
@@ -369,8 +483,8 @@ try {
 
 ## Related
 
-- [Nostr WoT Extension](https://github.com/mappingbitcoin/nostr-wot-extension) — Browser extension (recommended)
-- [WoT Oracle](https://github.com/mappingbitcoin/wot-oracle) — Backend service
+- [Nostr WoT Extension](https://github.com/nostr-wot/nostr-wot-extension) — Browser extension (recommended)
+- [WoT Oracle](https://github.com/nostr-wot/nostr-wot-oracle) — Backend service
 - [nostr-wot.com](https://nostr-wot.com) — Public oracle & docs
 
 ## License

package/dist/index.cjs

@@ -79,6 +79,23 @@ var DEFAULT_TIMEOUT = 5e3;
 function isValidPubkey(pubkey) {
   return /^[0-9a-f]{64}$/i.test(pubkey);
 }
+function isValidOracleUrl(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "https:";
+  } catch (e) {
+    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();
 }
@@ -118,11 +135,10 @@ async function fetchWithTimeout(url, options = {}) {
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), timeout);
   try {
-    const response = await fetch(url, {
+    return await fetch(url, {
       ...fetchOptions,
       signal: controller.signal
     });
-    return response;
   } finally {
     clearTimeout(timeoutId);
   }
@@ -135,6 +151,231 @@ function chunk(array, size) {
   return chunks;
 }
 
+// src/extension.ts
+function checkExtension(timeout = 100) {
+  return new Promise((resolve) => {
+    var _a;
+    if (typeof window === "undefined") {
+      resolve(false);
+      return;
+    }
+    const win = window;
+    if ((_a = win.nostr) == null ? void 0 : _a.wot) {
+      resolve(true);
+      return;
+    }
+    const handler = () => {
+      window.removeEventListener("nostr-wot-present", handler);
+      clearTimeout(timer);
+      resolve(true);
+    };
+    window.addEventListener("nostr-wot-present", handler);
+    const timer = setTimeout(() => {
+      window.removeEventListener("nostr-wot-present", handler);
+      resolve(false);
+    }, timeout);
+    window.dispatchEvent(new CustomEvent("nostr-wot-check"));
+  });
+}
+function connectExtension(timeout = 5e3) {
+  return new Promise((resolve, reject) => {
+    var _a;
+    if (typeof window === "undefined") {
+      reject(new Error("Not in browser environment"));
+      return;
+    }
+    const win = window;
+    if ((_a = win.nostr) == null ? void 0 : _a.wot) {
+      resolve(win.nostr.wot);
+      return;
+    }
+    let timer;
+    const onReady = () => {
+      var _a2;
+      cleanup();
+      const ext = (_a2 = window.nostr) == null ? void 0 : _a2.wot;
+      if (ext) {
+        resolve(ext);
+      } else {
+        reject(new Error("Extension ready event fired but API not found"));
+      }
+    };
+    const onError = (e) => {
+      cleanup();
+      const detail = e.detail;
+      reject(new Error((detail == null ? void 0 : detail.error) || "Connection failed"));
+    };
+    const cleanup = () => {
+      clearTimeout(timer);
+      window.removeEventListener("nostr-wot-ready", onReady);
+      window.removeEventListener("nostr-wot-error", onError);
+    };
+    window.addEventListener("nostr-wot-ready", onReady);
+    window.addEventListener("nostr-wot-error", onError);
+    window.dispatchEvent(new CustomEvent("nostr-wot-connect"));
+    timer = setTimeout(() => {
+      cleanup();
+      reject(new Error("Connection timeout"));
+    }, timeout);
+  });
+}
+async function checkAndConnect(options = {}) {
+  var _a;
+  const { checkTimeout = 100, connectTimeout = 5e3, autoConnect = true } = options;
+  if (typeof window === "undefined") {
+    return { state: "not-installed", extension: null };
+  }
+  const win = window;
+  if ((_a = win.nostr) == null ? void 0 : _a.wot) {
+    return { state: "connected", extension: win.nostr.wot };
+  }
+  const isInstalled = await checkExtension(checkTimeout);
+  if (!isInstalled) {
+    return { state: "not-installed", extension: null };
+  }
+  if (!autoConnect) {
+    return { state: "idle", extension: null };
+  }
+  try {
+    const extension = await connectExtension(connectTimeout);
+    return { state: "connected", extension };
+  } catch (error) {
+    return {
+      state: "error",
+      extension: null,
+      error: error instanceof Error ? error.message : "Unknown error"
+    };
+  }
+}
+var ExtensionConnector = class {
+  constructor(options = {}) {
+    this.options = options;
+    this.state = "idle";
+    this.extension = null;
+    this.connectionPromise = null;
+    this.listeners = /* @__PURE__ */ new Set();
+  }
+  /**
+   * Get current state
+   */
+  getState() {
+    return this.state;
+  }
+  /**
+   * Get current extension instance
+   */
+  getExtension() {
+    return this.extension;
+  }
+  /**
+   * Get current error
+   */
+  getError() {
+    return this.error;
+  }
+  /**
+   * Get current result
+   */
+  getResult() {
+    return {
+      state: this.state,
+      extension: this.extension,
+      error: this.error
+    };
+  }
+  /**
+   * Subscribe to state changes
+   */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  notify() {
+    const result = this.getResult();
+    for (const listener of this.listeners) {
+      listener(result);
+    }
+  }
+  setState(state, extension = null, error) {
+    this.state = state;
+    this.extension = extension;
+    this.error = error;
+    this.notify();
+  }
+  /**
+   * Connect to the extension
+   * Returns existing promise if already connecting
+   */
+  async connect() {
+    if (this.state === "connected" && this.extension) {
+      return this.getResult();
+    }
+    if (this.connectionPromise) {
+      return this.connectionPromise;
+    }
+    this.connectionPromise = this.doConnect();
+    const result = await this.connectionPromise;
+    this.connectionPromise = null;
+    return result;
+  }
+  async doConnect() {
+    var _a;
+    const { checkTimeout = 100, connectTimeout = 5e3 } = this.options;
+    if (typeof window === "undefined") {
+      this.setState("not-installed");
+      return this.getResult();
+    }
+    const win = window;
+    if ((_a = win.nostr) == null ? void 0 : _a.wot) {
+      this.setState("connected", win.nostr.wot);
+      return this.getResult();
+    }
+    this.setState("checking");
+    const isInstalled = await checkExtension(checkTimeout);
+    if (!isInstalled) {
+      this.setState("not-installed");
+      return this.getResult();
+    }
+    this.setState("connecting");
+    try {
+      const extension = await connectExtension(connectTimeout);
+      this.setState("connected", extension);
+    } catch (error) {
+      this.setState(
+        "error",
+        null,
+        error instanceof Error ? error.message : "Unknown error"
+      );
+    }
+    return this.getResult();
+  }
+  /**
+   * Reset state and disconnect
+   */
+  reset() {
+    this.state = "idle";
+    this.extension = null;
+    this.error = void 0;
+    this.connectionPromise = null;
+    this.notify();
+  }
+};
+var defaultConnector = null;
+function getDefaultConnector(options) {
+  if (!defaultConnector) {
+    defaultConnector = new ExtensionConnector(options);
+  }
+  return defaultConnector;
+}
+function resetDefaultConnector() {
+  if (defaultConnector) {
+    defaultConnector.reset();
+    defaultConnector = null;
+  }
+}
+
 // src/wot.ts
 var WoT = class {
   constructor(options) {
@@ -164,13 +405,18 @@ var WoT = class {
         this.fallbackPubkey = null;
       }
     }
-    this.oracle = (_f = (_e = options.oracle) != null ? _e : (_d = this.fallbackOptions) == null ? void 0 : _d.oracle) != null ? _f : DEFAULT_ORACLE;
+    const oracleUrl = (_f = (_e = options.oracle) != null ? _e : (_d = this.fallbackOptions) == null ? void 0 : _d.oracle) != null ? _f : 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);
   }
   /**
    * Checks if browser extension is available and returns it
+   * Uses event-based connection flow for reliable detection
    */
   async getExtension() {
     var _a, _b;
@@ -181,6 +427,17 @@ var WoT = class {
     const win = window;
     if ((_a = win.nostr) == null ? void 0 : _a.wot) {
       this.extension = win.nostr.wot;
+    } else {
+      const result = await checkAndConnect({
+        checkTimeout: 100,
+        connectTimeout: 5e3,
+        autoConnect: true
+      });
+      if (result.state === "connected" && result.extension) {
+        this.extension = result.extension;
+      }
+    }
+    if (this.extension) {
       try {
         this.extensionPubkey = await this.extension.getMyPubkey();
       } catch (e) {
@@ -217,28 +474,15 @@ var WoT = class {
     var _a;
     const timeout = (_a = options.timeout) != null ? _a : this.timeout;
     const url = `${this.oracle}/api${endpoint}`;
+    let response;
     try {
-      const response = await fetchWithTimeout(url, {
+      response = await fetchWithTimeout(url, {
         timeout,
         headers: {
           "Content-Type": "application/json"
         }
       });
-      if (!response.ok) {
-        if (response.status === 404) {
-          throw new NotFoundError("", `Resource not found: ${endpoint}`);
-        }
-        throw new NetworkError(
-          `HTTP ${response.status}: ${response.statusText}`,
-          response.status,
-          url
-        );
-      }
-      return await response.json();
     } catch (error) {
-      if (error instanceof NotFoundError || error instanceof NetworkError) {
-        throw error;
-      }
       if (error instanceof Error) {
         if (error.name === "AbortError") {
           throw new TimeoutError(timeout);
@@ -247,6 +491,17 @@ var WoT = class {
       }
       throw new NetworkError("Unknown network error", void 0, url);
     }
+    if (!response.ok) {
+      if (response.status === 404) {
+        throw new NotFoundError("", `Resource not found: ${endpoint}`);
+      }
+      throw new NetworkError(
+        `HTTP ${response.status}: ${response.statusText}`,
+        response.status,
+        url
+      );
+    }
+    return await response.json();
   }
   /**
    * Validates a pubkey parameter
@@ -368,6 +623,12 @@ var WoT = class {
     if (!Array.isArray(targets) || targets.length === 0) {
       throw new ValidationError("targets must be a non-empty array", "targets");
     }
+    if (targets.length > MAX_BATCH_SIZE) {
+      throw new ValidationError(
+        `targets array exceeds maximum size of ${MAX_BATCH_SIZE}`,
+        "targets"
+      );
+    }
     const normalizedTargets = targets.map(
       (t, i) => this.validatePubkey(t, `targets[${i}]`)
     );
@@ -448,17 +709,15 @@ var WoT = class {
     const normalizedTarget = this.validatePubkey(target, "target");
     const ext = await this.getExtension();
     if (ext) {
-      const result = await ext.getDetails(normalizedTarget);
-      return result;
+      return ext.getDetails(normalizedTarget);
     }
     const myPubkey = await this.getEffectivePubkey();
     const maxHops = (_a = options == null ? void 0 : options.maxHops) != null ? _a : this.maxHops;
     try {
-      const result = await this.apiRequest(
+      return await this.apiRequest(
         `/details/${myPubkey}/${normalizedTarget}?maxHops=${maxHops}`,
         options
       );
-      return result;
     } catch (error) {
       if (error instanceof NotFoundError) {
         return null;
@@ -585,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 {};
     }
@@ -599,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(
@@ -640,6 +907,8 @@ 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;
@@ -649,5 +918,12 @@ 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;