nostr-wot-sdk 0.6.2 → 0.8.1

package/README.md

@@ -1,480 +1,25 @@
 # nostr-wot-sdk
 
-JavaScript/TypeScript SDK for querying Nostr Web of Trust. Includes first-class React and SolidJS support.
+> **This package is a back-compat meta re-export.** New code should depend on the scoped packages directly.
 
-## Install
-```bash
-npm install nostr-wot-sdk
-```
-
-## Quick Start
-
-### With Browser Extension (Recommended)
-
-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';
-
-// The SDK automatically uses the extension when available
-const wot = new WoT({
-  fallback: {
-    oracle: 'https://nostr-wot.com',
-    myPubkey: 'abc123...'  // Used only if extension unavailable
-  }
-});
-
-// Check distance
-const hops = await wot.getDistance('def456...');
-console.log(hops); // 2
-
-// Boolean check
-const trusted = await wot.isInMyWoT('def456...', { maxHops: 3 });
-console.log(trusted); // true
-
-// 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 Fallback)
-
-```javascript
-import { WoT } from 'nostr-wot-sdk';
-
-const wot = new WoT({
-  oracle: 'https://nostr-wot.com',
-  myPubkey: 'abc123...'  // Required for oracle fallback
-});
-
-const hops = await wot.getDistance('def456...');
-```
-
-## Features
-
-- **Extension-First** — Automatically uses browser extension when available
-- **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
-- **Batch Queries** — Check multiple pubkeys efficiently
-- **TypeScript** — Full type definitions included
-
-## API Reference
-
-### Constructor
-```javascript
-const wot = new WoT(options);
-```
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `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) |
-| `fallback` | object | — | Fallback config when extension unavailable |
-| `extensionId` | string | — | Chrome Web Store extension ID (for detecting "installed but not enabled" state) |
-
-Trust scores are calculated by the extension and not configurable via the SDK.
-
-**Note:** When the extension is installed, it always takes priority over `myPubkey` or `oracle` settings.
-
-### Methods
-
-#### `getDistance(target, options?)`
-
-Get shortest path length to target pubkey.
-```javascript
-const hops = await wot.getDistance('def456...');
-// Returns: number | null
-```
-
-#### `isInMyWoT(target, options?)`
-
-Check if target is within your Web of Trust.
-```javascript
-const trusted = await wot.isInMyWoT('def456...', { maxHops: 2 });
-// Returns: boolean
-```
-
-#### `getTrustScore(target)`
-
-Get computed trust score from the extension.
-```javascript
-const score = await wot.getTrustScore('def456...');
-// Returns: number (0-1), or 0 if extension unavailable
-```
-
-#### `getDistanceBetween(from, to, options?)`
-
-Get distance between any two pubkeys.
-```javascript
-const hops = await wot.getDistanceBetween('abc...', 'def...');
-// Returns: number | null
-```
-
-#### `batchCheck(targets, options?)`
-
-Check multiple pubkeys efficiently.
-```javascript
-const results = await wot.batchCheck(['pk1...', 'pk2...', 'pk3...']);
-// Returns: Map<string, BatchResult>
-```
-
-#### `getDetails(target, options?)`
-
-Get distance, path count, and score details.
-```javascript
-const details = await wot.getDetails('def456...');
-// Returns: { hops: 2, paths: 5, score: 0.65 }
-// Oracle may also return: bridges, mutual (but score will be 0)
-```
-
-#### `getMyPubkey()`
-
-Get the current pubkey (from extension or fallback).
-```javascript
-const pubkey = await wot.getMyPubkey();
-// Returns: string
-```
-
-#### `isUsingExtension()`
-
-Check if extension is available and being used.
-```javascript
-const usingExt = await wot.isUsingExtension();
-// Returns: boolean
-```
-
-#### `getExtensionStatus()`
-
-Get detailed extension connection status. Useful for showing appropriate UI based on why the extension isn't working.
-```javascript
-const status = await wot.getExtensionStatus();
-// Returns: 'connected' | 'not-enabled' | 'unavailable' | 'not-browser'
-```
-
-| Status | Description |
-|--------|-------------|
-| `'connected'` | Extension is enabled and working on this domain |
-| `'not-enabled'` | Extension is installed but not enabled for this domain |
-| `'unavailable'` | Extension is not installed (or using local dev build) |
-| `'not-browser'` | Running in SSR/Node.js environment |
-
-**Note:** Detecting `'not-enabled'` requires providing the `extensionId` option.
-
-#### `getExtensionConfig()`
-
-Get extension's configuration.
-```javascript
-const config = await wot.getExtensionConfig();
-// Returns: { maxHops: 3, timeout: 5000, scoring: {...} } or null
-```
-
-### Batch Operations
-
-#### `getDistanceBatch(targets, options?)`
-
-Get distances for multiple pubkeys in a single call.
-```javascript
-// Default (just hops)
-const distances = await wot.getDistanceBatch(['pk1...', 'pk2...']);
-// Returns: { 'pk1...': 2, 'pk2...': null }
-
-// 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.
-```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 }
-```
+| Old import | New import |
+|---|---|
+| `nostr-wot-sdk` | `@nostr-wot/wot` |
+| `nostr-wot-sdk/react` | `@nostr-wot/wot/react` + `@nostr-wot/data/react` |
+| `nostr-wot-sdk/solid` | `@nostr-wot/wot/solid` |
+| `nostr-wot-sdk/relay` | `@nostr-wot/relay` |
+| `nostr-wot-sdk/relay/react` | `@nostr-wot/relay/react` |
+| `nostr-wot-sdk/data` | `@nostr-wot/data` |
+| `nostr-wot-sdk/data/cache` | `@nostr-wot/data/cache` |
 
-## Browser Extension
+Existing imports keep working — this package just re-exports the scoped packages so older consumers don't break. It will continue to be published in lock-step with `@nostr-wot/*` minor releases.
 
-Install the [Nostr WoT Extension](https://github.com/nostr-wot/nostr-wot-extension) for:
+For new projects, install only the scoped package(s) you actually need:
 
-- **Local Data** — Downloads and caches your follow graph locally
-- **Fast Queries** — No network requests needed after sync
-- **Cross-Site** — Same WoT data available on all websites
-- **Privacy** — Queries never leave your browser
-- **Offline** — Works without internet once synced
-
-The SDK automatically detects the extension via `window.nostr.wot`. When the extension is present (with auto-inject enabled), it **always takes priority** over oracle settings.
-
-```javascript
-const wot = new WoT({
-  fallback: {
-    oracle: 'https://nostr-wot.com',
-    myPubkey: 'abc123...'
-  }
-});
-
-// Check if using extension
-if (await wot.isUsingExtension()) {
-  console.log('Using local extension data');
-} else {
-  console.log('Falling back to oracle');
-}
-```
-
-## Framework Integration
-
-### React
-
-The SDK provides first-class React support with automatic extension detection. Just wrap your app with `WoTProvider` and you're ready to go — no additional configuration needed.
-
-```javascript
-import { WoTProvider, useWoT, useExtension } from 'nostr-wot-sdk/react';
-
-// Wrap your app - automatically detects extension
-function App() {
-  return (
-    <WoTProvider>
-      <YourApp />
-    </WoTProvider>
-  );
-}
-
-// Check extension status anywhere
-function ExtensionStatus() {
-  const { isConnected, isChecking } = useExtension();
-
-  if (isChecking) return <span>Checking for extension...</span>;
-  if (isConnected) return <span>Extension connected!</span>;
-  return <span>Extension not available</span>;
-}
-
-// Use WoT data in components
-function Profile({ pubkey }) {
-  const { distance, score, loading } = useWoT(pubkey);
-
-  if (loading) return <Spinner />;
-
-  return (
-    <div>
-      {distance !== null ? (
-        <span>{distance} hops away (score: {score.toFixed(2)})</span>
-      ) : (
-        <span>Not in your network</span>
-      )}
-    </div>
-  );
-}
-```
-
-#### Provider Options
-
-```javascript
-// With fallback for when extension is not available
-<WoTProvider options={{
-  fallback: { myPubkey: 'abc123...' }
-}}>
-```
-
-#### 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 extension status:
-
-```javascript
-const {
-  state,        // 'checking' | 'connected' | 'not-available'
-  isConnected,  // Extension is connected and ready
-  isChecking,   // Currently checking
-  isChecked,    // Check complete
-  refresh,      // Function to re-check extension availability
-} = useExtension();
-```
-
-### SolidJS
-
-The SDK also provides SolidJS support with reactive primitives and automatic extension detection. Wrap your app with `WoTProvider` and use `create*` primitives for fine-grained reactivity.
-
-```javascript
-import { WoTProvider, useExtension, createWoT } from 'nostr-wot-sdk/solid';
-
-// Wrap your app - automatically detects extension
-function App() {
-  return (
-    <WoTProvider>
-      <YourApp />
-    </WoTProvider>
-  );
-}
-
-// Check extension status anywhere
-function ExtensionStatus() {
-  const ext = useExtension();
-
-  return (
-    <Show when={!ext.isChecking()} fallback={<span>Checking...</span>}>
-      <Show when={ext.isConnected()} fallback={<span>Extension not available</span>}>
-        <span>Extension connected!</span>
-      </Show>
-    </Show>
-  );
-}
-
-// Use WoT data in components
-function Profile(props: { pubkey: string }) {
-  const wot = createWoT(() => props.pubkey);
-
-  return (
-    <Show when={!wot.loading()} fallback={<Spinner />}>
-      <Show when={wot.distance() !== null} fallback={<span>Not in your network</span>}>
-        <span>{wot.distance()} hops away (score: {wot.score().toFixed(2)})</span>
-      </Show>
-    </Show>
-  );
-}
-```
-
-#### Provider Options
-
-```javascript
-// With fallback for when extension is not available
-<WoTProvider options={{
-  fallback: { myPubkey: 'abc123...' }
-}}>
-```
-
-#### Available Primitives
-
-| Primitive | Description |
-|-----------|-------------|
-| `createWoT(pubkey)` | Get distance, score, and details for a pubkey |
-| `createIsInWoT(pubkey)` | Check if pubkey is in your WoT (boolean) |
-| `createTrustScore(pubkey)` | Get trust score only |
-| `createBatchWoT(pubkeys[])` | Check multiple pubkeys efficiently |
-| `useExtension()` | Get extension connection state |
-| `useWoTInstance()` | Get raw WoT instance for advanced usage |
-
-#### Extension State
-
-The `useExtension()` function provides extension status:
-
-```javascript
-const ext = useExtension();
-
-ext.state()        // 'checking' | 'connected' | 'not-available'
-ext.isConnected()  // Extension is connected and ready
-ext.isChecking()   // Currently checking
-ext.isChecked()    // Check complete
-ext.refresh()      // Function to re-check extension availability
-```
-
-## TypeScript
-
-Full type definitions included:
-```typescript
-import { WoT, DistanceResult, WoTOptions } from 'nostr-wot-sdk';
-
-const wot = new WoT();
-const result: DistanceResult | null = await wot.getDetails(pubkey);
-const score: number = await wot.getTrustScore(pubkey);
-```
-
-## Error Handling
-```javascript
-import { WoT, WoTError, NetworkError, NotFoundError } from 'nostr-wot-sdk';
-
-try {
-  const hops = await wot.getDistance('def456...');
-} catch (e) {
-  if (e instanceof NetworkError) {
-    console.log('Oracle unreachable');
-  } else if (e instanceof NotFoundError) {
-    console.log('Pubkey not in graph');
-  }
-}
+```bash
+npm i @nostr-wot/data           # event fetchers + cache + hooks
+npm i @nostr-wot/wot            # WoT scoring + browser-extension bridge
+npm i @nostr-wot/relay          # low-level relay utilities
 ```
 
-## Related
-
-- [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
-
-MIT
+See [the monorepo README](https://github.com/nostr-wot/nostr-wot-sdk) for architecture and per-package docs.

package/dist/data/cache/index.cjs

@@ -0,0 +1,14 @@
+'use strict';
+
+var cache = require('@nostr-wot/data/cache');
+
+
+
+Object.keys(cache).forEach(function (k) {
+	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function () { return cache[k]; }
+	});
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/data/cache/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs","sourcesContent":[]}

package/dist/data/cache/index.d.cts

@@ -0,0 +1 @@
+export * from '@nostr-wot/data/cache';

package/dist/data/cache/index.d.ts

@@ -0,0 +1 @@
+export * from '@nostr-wot/data/cache';

package/dist/data/cache/index.js

@@ -0,0 +1,3 @@
+export * from '@nostr-wot/data/cache';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/data/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js","sourcesContent":[]}

package/dist/data/index.cjs

@@ -0,0 +1,14 @@
+'use strict';
+
+var data = require('@nostr-wot/data');
+
+
+
+Object.keys(data).forEach(function (k) {
+	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function () { return data[k]; }
+	});
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/data/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs","sourcesContent":[]}

package/dist/data/index.d.cts

@@ -0,0 +1 @@
+export * from '@nostr-wot/data';

package/dist/data/index.d.ts

@@ -0,0 +1 @@
+export * from '@nostr-wot/data';

package/dist/data/index.js

@@ -0,0 +1,3 @@
+export * from '@nostr-wot/data';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/data/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js","sourcesContent":[]}