@nostr-wot/graph 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,413 @@
+/**
+ * Trust-score configuration. Ported verbatim from the extension.
+ */
+interface ScoringConfig {
+    /** Base score per hop distance, e.g. `{ 1: 1.0, 2: 0.5, 3: 0.25, 4: 0.1 }`. */
+    distanceWeights: Record<number, number>;
+    /** Bonus per extra shortest path, keyed by hop level, e.g. `{ 2: 0.15, 3: 0.1, 4: 0.05 }`. */
+    pathBonus: Record<number, number>;
+    /** Maximum path bonus that can be added on top of the base score. */
+    maxPathBonus: number;
+}
+/**
+ * Result of a distance query: hops from root + count of shortest paths.
+ */
+interface DistanceInfo {
+    /** Number of hops from the root (0 = self). */
+    hops: number;
+    /** Count of shortest paths from the root (1 for self). */
+    paths: number;
+}
+/**
+ * Graph metadata persisted alongside the follow edges.
+ */
+interface GraphMeta {
+    /** Root pubkey the graph was last crawled from. */
+    root: string | null;
+    /** Timestamp (ms) of the last completed crawl. */
+    lastCrawl: number | null;
+    /** Max BFS depth of the last crawl. */
+    maxDepth: number | null;
+    /** Storage schema version. */
+    version: number;
+}
+/**
+ * Aggregate storage counts.
+ */
+interface StorageStats {
+    /** Nodes that have a stored follow list. */
+    nodes: number;
+    /** Total follow edges across all nodes. */
+    edges: number;
+    /** Distinct interned pubkeys. */
+    uniquePubkeys: number;
+}
+/**
+ * Progress emitted while crawling.
+ */
+interface CrawlProgress {
+    /** Current BFS depth being fetched. */
+    depth: number;
+    /** Number of pubkeys fetched so far. */
+    fetched: number;
+    /** Number of pubkeys queued for the next depth. */
+    queued: number;
+}
+/**
+ * Options for {@link GraphCrawler.crawl} / {@link WotGraph.crawl}.
+ */
+interface CrawlOptions {
+    /** Max BFS depth. Default 2. */
+    maxDepth?: number;
+    /** Progress callback. */
+    onProgress?: (p: CrawlProgress) => void;
+    /** Abort signal to cancel the crawl. */
+    signal?: AbortSignal;
+}
+/**
+ * Result of a crawl.
+ */
+interface CrawlResult {
+    /** Pubkeys whose kind:3 was successfully fetched. */
+    fetched: number;
+    /** Nodes with a stored follow list after the crawl. */
+    nodes: number;
+    /** Total follow edges after the crawl. */
+    edges: number;
+    /** Deepest BFS depth actually reached. */
+    depth: number;
+    /** Wall-clock duration in ms. */
+    durationMs: number;
+    /** True if the crawl was aborted/stopped before finishing. */
+    stoppedEarly: boolean;
+}
+/**
+ * Options for {@link WotGraph.filterByWoT}.
+ */
+interface FilterByWoTOptions {
+    /** Only keep pubkeys within this many hops. Default 2. */
+    maxHops?: number;
+}
+/**
+ * A pluggable WebSocket constructor forwarded to the underlying pool
+ * (e.g. a proxy-safe implementation).
+ */
+type WebSocketLike = typeof WebSocket;
+/**
+ * Local query source consumed by `@nostr-wot/wot`'s `WoT` class.
+ * Structurally shared: `@nostr-wot/wot` declares an identical interface.
+ */
+interface WoTLocalSource {
+    /** Distance in hops from the root, or `null` if unreached/unknown. */
+    getDistance(target: string): number | null;
+    /** Whether `target` is within `maxHops` of the root. */
+    isInMyWoT(target: string, maxHops?: number): boolean;
+    /** Trusted subset of `pubkeys`, sorted by score descending. */
+    filterByWoT(pubkeys: string[], opts?: FilterByWoTOptions): string[];
+}
+
+/**
+ * IndexedDB storage for the local WoT graph.
+ *
+ * Ported from the extension (`lib/storage.ts`), generalized from per-account
+ * databases to a `namespace` key and wrapped in a class so multiple graphs can
+ * coexist. Preserves the two performance-critical techniques:
+ *
+ * - **Interning**: pubkeys (64-hex) are mapped to small integer ids, so the
+ *   graph is stored/traversed as numbers instead of strings.
+ * - **Delta encoding**: each node's sorted follow-id list is stored as a
+ *   `Uint32Array` of deltas, which compresses well and keeps memory bounded for
+ *   the 100k+ nodes a 2-hop crawl can yield.
+ *
+ * When `indexedDB` is unavailable (Node without a polyfill) the store operates
+ * in memory-only mode: crawl/query still work, nothing is persisted.
+ */
+
+declare function encodeFollows(followIds: ArrayLike<number>): ArrayBuffer;
+declare function decodeFollows(buffer: ArrayBuffer | null | undefined): Uint32Array;
+declare class GraphStorage {
+    readonly namespace: string;
+    private db;
+    private memoryOnly;
+    private opened;
+    private pubkeyToId;
+    private idToPubkey;
+    private nextId;
+    private graphCache;
+    private metaCache;
+    private dirtyFollows;
+    private dirtyPubkeys;
+    constructor(namespace: string);
+    private dbName;
+    /** Open (or create) the namespace DB and hydrate in-memory caches. */
+    open(): Promise<void>;
+    /** Hydrate the in-memory interning + follow maps + meta from the DB. */
+    loadAll(): Promise<void>;
+    private getAll;
+    /** Numeric id for a pubkey, or null if never seen. */
+    getId(pubkey: string): number | null;
+    /** Numeric id for a pubkey, minting and buffering a new one if needed. */
+    getOrCreateId(pubkey: string): number;
+    /** Batch variant of {@link getOrCreateId}. */
+    getOrCreateIds(pubkeys: string[]): number[];
+    /** Pubkey for a numeric id, or null. */
+    getHex(id: number): string | null;
+    /** Highest assigned id (for typed-array sizing). */
+    getMaxId(): number;
+    /** Store `pubkey`'s follow list. Interns everything and updates the cache. */
+    saveFollows(pubkey: string, follows: string[]): void;
+    /** Follow ids for a node id — sync, from the in-memory cache. */
+    getFollowIdsSync(id: number): Uint32Array;
+    /** Follow ids for a pubkey (interned). Empty if unknown. */
+    getFollowIds(pubkey: string): Uint32Array;
+    /** Follow list of `pubkey` as hex strings. */
+    getFollows(pubkey: string): string[];
+    setMeta(key: string, value: unknown): Promise<void>;
+    getMeta<T = unknown>(key: string): T | undefined;
+    /** Read the structured graph meta record. */
+    getGraphMeta(): GraphMeta;
+    /** Flush buffered pubkey + follow writes to IndexedDB. No-op in memory mode. */
+    flush(): Promise<void>;
+    stats(): StorageStats;
+    /** Wipe this namespace: memory caches + persisted stores. */
+    clear(): Promise<void>;
+    /** Close the underlying DB connection. */
+    close(): void;
+}
+
+/**
+ * BFS crawler for kind:3 contact lists.
+ *
+ * Ported from the extension (`lib/sync.ts`, `GraphSync`) but with the raw
+ * `WebSocket` transport replaced by `@nostr-wot/relay`'s pool. The pool handles
+ * connection/reconnect across relays; this class keeps the proven crawl logic:
+ *
+ * - BFS by depth: fetch the root's kind:3, enqueue its follows for the next
+ *   depth, and so on up to `maxDepth`.
+ * - Newest-per-author: for each pubkey, take the kind:3 event with the highest
+ *   `created_at` seen across relays.
+ * - Rate limiting: a base delay between dispatches and a max-concurrent cap.
+ * - Tolerates unreachable relays; throws `CrawlError` only when zero relays are
+ *   configured to connect.
+ * - Abortable via `signal` or `stop()`; a stopped crawl leaves partial data
+ *   usable and reports `stoppedEarly: true`.
+ */
+
+interface CrawlSubCloser {
+    close(): void;
+}
+interface CrawlEvent {
+    created_at: number;
+    tags: string[][];
+    [key: string]: unknown;
+}
+interface CrawlPool {
+    subscribe(filter: {
+        kinds?: number[];
+        authors?: string[];
+        limit?: number;
+        [key: string]: unknown;
+    }, handlers: {
+        onEvent: (e: CrawlEvent) => void;
+        onEose?: () => void;
+        onStatus?: (s: string) => void;
+    }): CrawlSubCloser;
+    getConnectedCount?(): number;
+}
+interface GraphCrawlerOptions {
+    pool: CrawlPool;
+    storage: GraphStorage;
+    relays: string[];
+    /** Base delay (ms) between fetch dispatches. Default 50. */
+    baseDelayMs?: number;
+    /** Max concurrent in-flight fetches. Default 5. */
+    maxConcurrent?: number;
+    /** Per-pubkey response timeout (ms). Default 10000. */
+    requestTimeoutMs?: number;
+}
+declare class CrawlError extends Error {
+    constructor(message: string);
+}
+declare class GraphCrawler {
+    private pool;
+    private storage;
+    private relays;
+    private baseDelayMs;
+    private maxConcurrent;
+    private requestTimeoutMs;
+    private aborted;
+    constructor(options: GraphCrawlerOptions);
+    /** Abort an in-flight crawl. */
+    stop(): void;
+    crawl(rootPubkey: string, opts?: CrawlOptions): Promise<CrawlResult>;
+    /**
+     * Fetch a single pubkey's newest kind:3 follow list across relays.
+     * Resolves to the follow pubkeys, or `null` if no event arrived.
+     */
+    private fetchNewest;
+    /**
+     * Run `worker` over `items` with a max-concurrency cap and a base delay
+     * before each dispatch (preserving the crawler's per-relay rate limiting
+     * intent, now applied at the pool boundary).
+     */
+    private mapLimited;
+}
+
+/**
+ * `WotGraph` — the primary public entry point.
+ *
+ * Ties the four internal layers together: a namespaced {@link GraphStorage},
+ * a BFS {@link LocalGraph}, a {@link GraphCrawler}, and the pure scoring
+ * function. Consumers create one per origin/app, `load()` to rehydrate any
+ * cached graph, `crawl()` to build/refresh it, then run O(1)/O(n) queries.
+ */
+
+interface WotGraphOptions {
+    /** IndexedDB partition key (e.g. the app name). */
+    namespace: string;
+    /** Relay URLs to crawl. */
+    relays: string[];
+    /** Optional shared pool; if omitted one is created from `relays`. */
+    pool?: CrawlPool;
+    /** Scoring overrides merged onto {@link DEFAULT_SCORING}. */
+    scoring?: Partial<ScoringConfig>;
+    /** WebSocket implementation forwarded to the created pool. */
+    websocketImplementation?: WebSocketLike;
+}
+interface WotGraphStats {
+    nodes: number;
+    edges: number;
+    root: string | null;
+    lastCrawl: number | null;
+    maxDepth: number | null;
+}
+declare class WotGraph {
+    readonly namespace: string;
+    private relays;
+    private scoring;
+    private websocketImplementation?;
+    private storage;
+    private graph;
+    private pool;
+    private ownPool;
+    private crawler;
+    private root;
+    private inFlight;
+    private controller;
+    private listeners;
+    constructor(options: WotGraphOptions);
+    /** Hydrate any cached graph from IndexedDB (fast path). */
+    load(): Promise<void>;
+    /**
+     * Build/refresh the graph by crawling kind:3 from `rootPubkey`.
+     * Concurrent calls return the same in-flight promise (idempotent).
+     */
+    crawl(rootPubkey: string, opts?: CrawlOptions): Promise<CrawlResult>;
+    /** Distance info from the crawled root, or `null` if unreached/unknown. */
+    getDistance(pubkey: string): DistanceInfo | null;
+    /** Trust score 0..1 via {@link calculateScore}. */
+    getScore(pubkey: string): number;
+    /** Whether `pubkey` is within `maxHops` of the root. */
+    isInWoT(pubkey: string, maxHops?: number): boolean;
+    /** Trusted subset of `pubkeys`, sorted by score descending. */
+    filterByWoT(pubkeys: string[], opts?: FilterByWoTOptions): string[];
+    /** Follow list of `pubkey` as hex strings. */
+    getFollows(pubkey: string): string[];
+    /** Aggregate stats + crawl meta. */
+    stats(): WotGraphStats;
+    /** True if the last crawl is older than `ttlMs` (or never happened). */
+    isStale(ttlMs: number): boolean;
+    /** Wipe this namespace. */
+    clear(): Promise<void>;
+    /** Abort an in-flight crawl. Partial data stays usable. */
+    stop(): void;
+    /** Adapter for `@nostr-wot/wot`'s `WoT` class. */
+    asWoTSource(): WoTLocalSource;
+    /** The root pubkey the graph is currently answering queries from. */
+    getRoot(): string | null;
+    /** Subscribe to graph changes (crawl / load / clear). Returns an unsubscribe. */
+    onChange(cb: () => void): () => void;
+    /** Release the pool/storage this instance owns. */
+    destroy(): void;
+    private notify;
+    private resolvePool;
+}
+
+/**
+ * Centralized trust score calculation.
+ *
+ * Formula: score = base + pathBonus (capped at maxPathBonus)
+ *
+ * Where:
+ * - base: base score per hop distance (1 hop = 100%, 2 hops = 50%, etc.)
+ * - pathBonus: bonus based on number of shortest paths, capped at maxPathBonus
+ *
+ * Ported verbatim from the extension (`lib/scoring.ts`).
+ */
+
+declare const DEFAULT_SCORING: ScoringConfig;
+/**
+ * Calculate trust score from hops and path count.
+ *
+ * @param hops - Number of hops (0 = self, 1 = direct follow, etc.)
+ * @param paths - Number of shortest paths (null if unknown)
+ * @param scoring - Scoring configuration
+ * @returns Score between 0 and 1
+ */
+declare function calculateScore(hops: number | null | undefined, paths: number | null, scoring?: ScoringConfig): number;
+
+/**
+ * In-memory BFS over the hydrated follow graph.
+ *
+ * Ported from the extension (`lib/graph.ts`, `LocalGraph`). Given the interned
+ * follow map (from {@link GraphStorage}) and a root pubkey, a single BFS pass
+ * fills two typed arrays indexed by node id:
+ *
+ * - `hops`  (`Uint8Array`)  — distance from root, stored as `hop + 1` so `0`
+ *   means "not reached" (255 max).
+ * - `paths` (`Uint32Array`) — count of shortest paths to each node.
+ *
+ * The cache is keyed by root and invalidated on crawl / root change / clear.
+ */
+
+declare class LocalGraph {
+    private storage;
+    private cache;
+    private cachedRoot;
+    constructor(storage: GraphStorage);
+    /** Invalidate the precomputed cache (called on crawl / root change / clear). */
+    invalidateCache(): void;
+    /**
+     * Precompute hops and paths from a root pubkey using a single BFS pass.
+     * Results stored in typed arrays indexed by node id for O(1) lookup.
+     */
+    private buildCache;
+    /** Ensure the cache is built for `root`. */
+    private ensureCache;
+    /**
+     * Distance info from `root` to `pubkey`. Returns `{ hops, paths }`, or `null`
+     * when unreached / unknown. Self → `{ hops: 0, paths: 1 }`.
+     */
+    getDistance(root: string, pubkey: string, maxHops?: number): DistanceInfo | null;
+    /** Follow list of `pubkey` as hex strings. */
+    getFollows(pubkey: string): string[];
+}
+
+/**
+ * Adapter turning a {@link WotGraph} into the small `WoTLocalSource` shape that
+ * `@nostr-wot/wot`'s `WoT` class can consume as a local query source instead of
+ * the remote Oracle.
+ */
+
+/** Minimal surface {@link createWoTSource} needs from a graph. */
+interface WoTSourceGraph {
+    getDistance(pubkey: string): {
+        hops: number;
+        paths: number;
+    } | null;
+    isInWoT(pubkey: string, maxHops?: number): boolean;
+    filterByWoT(pubkeys: string[], opts?: FilterByWoTOptions): string[];
+}
+declare function createWoTSource(graph: WoTSourceGraph): WoTLocalSource;
+
+export { CrawlError, type CrawlEvent, type CrawlOptions, type CrawlPool, type CrawlProgress, type CrawlResult, type CrawlSubCloser, DEFAULT_SCORING, type DistanceInfo, type FilterByWoTOptions, GraphCrawler, type GraphCrawlerOptions, type GraphMeta, GraphStorage, LocalGraph, type ScoringConfig, type StorageStats, type WebSocketLike, type WoTLocalSource, type WoTSourceGraph, WotGraph, type WotGraphOptions, type WotGraphStats, calculateScore, createWoTSource, decodeFollows, encodeFollows };