nostr-wot-sdk 0.1.0 → 0.3.0

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
@@ -157,9 +159,79 @@ 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:
+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
@@ -167,7 +239,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({
@@ -186,6 +258,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:
@@ -241,19 +357,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);
 
@@ -271,14 +401,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);
 ```
 
@@ -299,8 +478,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