@kehto/nip 0.1.0

package/README.md

@@ -0,0 +1,37 @@
+# @kehto/nip
+
+A tree-shakable bundle of unique Nostr NIP utilities for napplet runtimes. Each
+NIP lives at its own subpath so consumers import only what they use; the package
+is `sideEffects: false`, so bundlers drop any NIP that isn't referenced.
+
+## NIPs
+
+| Subpath | NIP | What it provides |
+|---------|-----|------------------|
+| `@kehto/nip/66` | NIP-66 | kind-30166 relay-discovery aggregator (`createNip66Aggregator`) |
+
+More unique NIPs are added as their own subpath (`@kehto/nip/<n>`) over time.
+
+## Usage
+
+```ts
+// Import only the NIP you need — nothing else is bundled.
+import { createNip66Aggregator } from '@kehto/nip/66';
+
+const aggregator = createNip66Aggregator({
+  pool: myPoolAdapter,
+  bootstrap: ['wss://monitor.example.com'],
+});
+aggregator.start();
+```
+
+A convenience barrel re-export is also available at the package root
+(`@kehto/nip`), but prefer subpath imports for the smallest bundles.
+
+## Adding a NIP
+
+1. Add `src/<n>.ts` implementing the NIP utility (framework-agnostic, no
+   module-global state, inject relay/pool concerns via interfaces).
+2. Add `src/<n>.ts` to the `tsup` `entry` array and the `./<n>` `exports` entry
+   in `package.json`.
+3. Re-export it from `src/index.ts` for the barrel.

package/dist/66.d.ts

@@ -0,0 +1,192 @@
+import { NostrEvent } from 'nostr-tools';
+
+/**
+ * Minimal relay-pool contract `@kehto/nip/66` depends on. Consumers implement
+ * this against their pool library of choice (nostr-tools SimplePool,
+ * applesauce-relay, @snort/worker-relay, etc.). Intentionally smaller than
+ * RxJS-style observable pools — one callback, one unsubscribe handle.
+ *
+ * @example
+ * ```ts
+ * import { SimplePool } from 'nostr-tools/pool';
+ * const pool = new SimplePool();
+ * const adapter: Nip66RelayPool = {
+ *   subscribe: (relays, filter, onEvent) => {
+ *     const sub = pool.subscribeMany(relays, [filter], { onevent: onEvent });
+ *     return () => sub.close();
+ *   },
+ * };
+ * ```
+ */
+interface Nip66RelayPool {
+    /**
+     * Open a kind-30166 subscription against a set of monitor relays.
+     *
+     * @param relays - WebSocket URLs to subscribe against (the aggregator passes its bootstrap list)
+     * @param filter - A kind-30166 filter, optionally narrowed with `#n` network tags
+     * @param onEvent - Called synchronously with every matching event; the aggregator parses each one
+     * @returns An unsubscribe handle the aggregator calls on `resync()` or teardown
+     */
+    subscribe(relays: ReadonlyArray<string>, filter: Nip66Filter, onEvent: (event: NostrEvent) => void): () => void;
+}
+/**
+ * Minimal filter shape for kind-30166 subscriptions. `#n` optionally narrows
+ * by network type (e.g. `['clearnet']`, `['clearnet', 'tor']`).
+ *
+ * @example
+ * ```ts
+ * const filter: Nip66Filter = { kinds: [30166], '#n': ['clearnet'] };
+ * ```
+ */
+type Nip66Filter = {
+    kinds: [30166];
+    '#n'?: ReadonlyArray<string>;
+};
+/**
+ * Options for {@link createNip66Aggregator}.
+ *
+ * @example
+ * ```ts
+ * const options: Nip66AggregatorOptions = {
+ *   pool: myPoolAdapter,
+ *   bootstrap: ['wss://monitor1.example.com', 'wss://monitor2.example.com'],
+ *   networks: ['clearnet'],
+ * };
+ * ```
+ */
+interface Nip66AggregatorOptions {
+    /** A {@link Nip66RelayPool} adapter supplied by the consumer. */
+    pool: Nip66RelayPool;
+    /** Required non-empty list of monitor relay URLs to subscribe against. No default ships in the package. */
+    bootstrap: ReadonlyArray<string>;
+    /** Optional network-type narrowing passed to the filter as `#n` (e.g. `['clearnet', 'tor']`). Omit to receive every network. */
+    networks?: ReadonlyArray<string>;
+    /**
+     * Optional named relay-attribute groups for interpreting ad hoc kind-30166 tags.
+     * Omit to use {@link DEFAULT_RELAY_ATTRIBUTE_GROUPS}.
+     */
+    relayAttributeGroups?: RelayAttributeGroups;
+}
+/** A tag/value matcher for ad hoc relay attributes carried on kind-30166 events. */
+interface RelayAttributeMatcher {
+    /** Tag name to match, for example `T`, `t`, or `k`. */
+    tag: string;
+    /** Optional accepted values. If omitted, any value for the tag matches. */
+    values?: ReadonlyArray<string>;
+}
+/** Named groups of relay-attribute matchers. Matchers within a group are OR-ed. */
+type RelayAttributeGroups = Readonly<Record<string, ReadonlyArray<RelayAttributeMatcher>>>;
+/** Parsed attributes observed for one NIP-66 relay URL. */
+interface Nip66RelayAttributes {
+    /** Raw tag copies from the latest observed kind-30166 event for the relay. */
+    tags: ReadonlyArray<ReadonlyArray<string>>;
+    /** Tag-value index, keyed by tag name. */
+    values: ReadonlyMap<string, ReadonlySet<string>>;
+    /** Parsed uppercase `N` tag support for convenience. */
+    supportedNips: ReadonlySet<number>;
+}
+declare const DEFAULT_RELAY_ATTRIBUTE_GROUPS: RelayAttributeGroups;
+/**
+ * Aggregator handle returned by {@link createNip66Aggregator}. Each call
+ * returns a fresh instance with its own closure-scoped state — multi-instance
+ * safe (unlike a module-globals pattern).
+ *
+ * @example
+ * ```ts
+ * const aggregator = createNip66Aggregator({ pool, bootstrap: ['wss://monitor.example.com'] });
+ * aggregator.start();
+ * const relays = aggregator.getRelaySet();
+ * ```
+ */
+interface Nip66Aggregator {
+    /** Begin subscribing against the bootstrap relay set. Idempotent — calling twice is a no-op. */
+    start(): void;
+    /** Tear down the current subscription, clear accumulated state, and re-subscribe. Call when `networks` semantics change upstream. */
+    resync(): void;
+    /**
+     * Tear down the current subscription. Idempotent — calling without a prior
+     * `start()` is a safe no-op. Preserves accumulated state (`getRelaySet`,
+     * `relaySupportsNip`) — use `resync()` if you need to clear state AND
+     * re-subscribe in one step. A subsequent `start()` re-subscribes against
+     * the bootstrap relays (identical contract to the first start).
+     *
+     * Wire this to your consumer's teardown path (browser: `beforeunload`;
+     * React: effect cleanup; Electron: `app.before-quit`) — the aggregator
+     * holds a pool subscription that otherwise lives for the tab lifetime
+     * (PITFALLS.md M-03).
+     */
+    stop(): void;
+    /** The current set of relay URLs discovered from kind-30166 `d`-tags. Empty until `start()` fires at least one event. */
+    getRelaySet(): ReadonlySet<string>;
+    /**
+     * Relay URLs whose `N`-tags declare support for the given NIP number.
+     *
+     * @param nip - NIP number to query support for (e.g. 44 for NIP-44 encrypted DMs)
+     * @returns Array of relay URLs supporting that NIP
+     */
+    getRelaysSupportingNip(nip: number): string[];
+    /**
+     * Whether the relay at `url` has been seen with an `N`-tag declaring support for `nip`.
+     *
+     * @param url - Relay WebSocket URL to check
+     * @param nip - NIP number to query support for
+     * @returns `true` iff the relay has been observed with a matching `N`-tag
+     */
+    relaySupportsNip(url: string, nip: number): boolean;
+    /**
+     * Return parsed relay attributes for a relay URL, if that relay has been
+     * observed in a kind-30166 event.
+     */
+    getRelayAttributes(url: string): Nip66RelayAttributes | undefined;
+    /**
+     * Return relays matching any supplied ad hoc attribute matcher.
+     *
+     * @param matchers - Tag/value matchers, OR semantics
+     */
+    getRelaysMatchingAttributes(matchers: ReadonlyArray<RelayAttributeMatcher>): string[];
+    /**
+     * Return relays in a named attribute group. Uses the group table passed to
+     * `createNip66Aggregator`, or {@link DEFAULT_RELAY_ATTRIBUTE_GROUPS}.
+     */
+    getRelaysForAttributeGroup(groupName: string, groups?: RelayAttributeGroups): string[];
+}
+/**
+ * Create a NIP-66 kind-30166 relay-discovery aggregator with closure-scoped state.
+ *
+ * Subscribes to kind-30166 events via the injected {@link Nip66RelayPool},
+ * extracts relay URLs from `d`-tags, and parses `N`-tags to track which NIP
+ * numbers each relay supports. Multi-instance safe — each factory call owns
+ * its own `Set` + `Map`; multiple aggregators share nothing at module scope.
+ *
+ * The aggregator is framework-agnostic: it knows nothing about negentropy
+ * (NIP-77), OPFS caching, worker relays, or network-type config stores.
+ * Consumers inject those concerns through their {@link Nip66RelayPool}
+ * implementation. `start()` is synchronous and idempotent — consumers
+ * schedule their own cadence (delayed start, retry, etc.).
+ *
+ * @param options - Pool adapter + bootstrap monitor relays (+ optional network filter)
+ * @returns A fresh {@link Nip66Aggregator} handle
+ *
+ * @example
+ * ```ts
+ * import { createNip66Aggregator } from '@kehto/nip/66';
+ * import { SimplePool } from 'nostr-tools/pool';
+ *
+ * const pool = new SimplePool();
+ * const aggregator = createNip66Aggregator({
+ *   pool: {
+ *     subscribe: (relays, filter, onEvent) => {
+ *       const sub = pool.subscribeMany(relays, [filter], { onevent: onEvent });
+ *       return () => sub.close();
+ *     },
+ *   },
+ *   bootstrap: ['wss://monitor1.example.com'],
+ * });
+ * aggregator.start();
+ * // Later — inside a ShellAdapter hook:
+ * const suggestions = Array.from(aggregator.getRelaySet());
+ * ```
+ */
+declare function createNip66Aggregator(options: Nip66AggregatorOptions): Nip66Aggregator;
+
+export { DEFAULT_RELAY_ATTRIBUTE_GROUPS, type Nip66Aggregator, type Nip66AggregatorOptions, type Nip66Filter, type Nip66RelayAttributes, type Nip66RelayPool, type RelayAttributeGroups, type RelayAttributeMatcher, createNip66Aggregator };

package/dist/66.js

@@ -0,0 +1,9 @@
+import {
+  DEFAULT_RELAY_ATTRIBUTE_GROUPS,
+  createNip66Aggregator
+} from "./chunk-N4WPLKIJ.js";
+export {
+  DEFAULT_RELAY_ATTRIBUTE_GROUPS,
+  createNip66Aggregator
+};
+//# sourceMappingURL=66.js.map

package/dist/66.js.map

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

package/dist/chunk-N4WPLKIJ.js

@@ -0,0 +1,141 @@
+// src/66.ts
+var DEFAULT_RELAY_ATTRIBUTE_GROUPS = {
+  Indexer: [
+    { tag: "T", values: ["Indexer", "indexer"] },
+    { tag: "t", values: ["Indexer", "indexer"] },
+    { tag: "k", values: ["10002"] }
+  ],
+  RelayIndexer: [
+    { tag: "T", values: ["RelayIndexer", "relay-indexer", "relay_indexer"] },
+    { tag: "t", values: ["RelayIndexer", "relay-indexer", "relay_indexer"] },
+    { tag: "k", values: ["30166", "10166"] }
+  ]
+};
+function createNip66Aggregator(options) {
+  const relaySet = /* @__PURE__ */ new Set();
+  const relaySupportedNips = /* @__PURE__ */ new Map();
+  const relayAttributeTags = /* @__PURE__ */ new Map();
+  const relayAttributeValues = /* @__PURE__ */ new Map();
+  const relayAttributeGroups = options.relayAttributeGroups ?? DEFAULT_RELAY_ATTRIBUTE_GROUPS;
+  let unsubscribe = null;
+  function buildFilter() {
+    const filter = { kinds: [30166] };
+    if (options.networks && options.networks.length > 0) {
+      filter["#n"] = options.networks;
+    }
+    return filter;
+  }
+  function processEvent(event) {
+    const dTag = event.tags.find((t) => t[0] === "d");
+    const relayUrl = dTag?.[1];
+    if (!relayUrl) return;
+    relaySet.add(relayUrl);
+    captureRelayAttributes(relayUrl, event.tags);
+    const nips = /* @__PURE__ */ new Set();
+    for (const tag of event.tags) {
+      if (tag[0] === "N" && tag[1]) {
+        const nipNum = parseInt(tag[1], 10);
+        if (!Number.isNaN(nipNum)) nips.add(nipNum);
+      }
+    }
+    if (nips.size > 0) relaySupportedNips.set(relayUrl, nips);
+  }
+  function captureRelayAttributes(relayUrl, tags) {
+    const tagCopies = tags.map((tag) => [...tag]);
+    const values = /* @__PURE__ */ new Map();
+    for (const tag of tags) {
+      const [name, value] = tag;
+      if (!name || value === void 0) continue;
+      let bucket = values.get(name);
+      if (!bucket) {
+        bucket = /* @__PURE__ */ new Set();
+        values.set(name, bucket);
+      }
+      bucket.add(value);
+    }
+    relayAttributeTags.set(relayUrl, tagCopies);
+    relayAttributeValues.set(relayUrl, values);
+  }
+  function start() {
+    if (unsubscribe) return;
+    unsubscribe = options.pool.subscribe(options.bootstrap, buildFilter(), processEvent);
+  }
+  function resync() {
+    if (unsubscribe) {
+      unsubscribe();
+      unsubscribe = null;
+    }
+    relaySet.clear();
+    relaySupportedNips.clear();
+    relayAttributeTags.clear();
+    relayAttributeValues.clear();
+    unsubscribe = options.pool.subscribe(options.bootstrap, buildFilter(), processEvent);
+  }
+  function stop() {
+    if (unsubscribe) {
+      unsubscribe();
+      unsubscribe = null;
+    }
+  }
+  function getRelaySet() {
+    return relaySet;
+  }
+  function getRelaysSupportingNip(nip) {
+    const result = [];
+    for (const [url, nips] of relaySupportedNips) {
+      if (nips.has(nip)) result.push(url);
+    }
+    return result;
+  }
+  function relaySupportsNip(url, nip) {
+    return relaySupportedNips.get(url)?.has(nip) ?? false;
+  }
+  function getRelayAttributes(url) {
+    const tagCopies = relayAttributeTags.get(url);
+    const values = relayAttributeValues.get(url);
+    if (!tagCopies || !values) return void 0;
+    return {
+      tags: tagCopies.map((tag) => [...tag]),
+      values: new Map(Array.from(values, ([tag, tagValues]) => [tag, new Set(tagValues)])),
+      supportedNips: new Set(relaySupportedNips.get(url) ?? [])
+    };
+  }
+  function matcherMatches(url, matcher) {
+    const values = relayAttributeValues.get(url)?.get(matcher.tag);
+    if (!values || values.size === 0) return false;
+    if (!matcher.values || matcher.values.length === 0) return true;
+    const accepted = new Set(matcher.values.map((value) => value.toLowerCase()));
+    for (const value of values) {
+      if (accepted.has(value.toLowerCase())) return true;
+    }
+    return false;
+  }
+  function getRelaysMatchingAttributes(matchers) {
+    const result = [];
+    for (const url of relaySet) {
+      if (matchers.some((matcher) => matcherMatches(url, matcher))) result.push(url);
+    }
+    return result;
+  }
+  function getRelaysForAttributeGroup(groupName, groups) {
+    const group = (groups ?? relayAttributeGroups)[groupName] ?? [];
+    return getRelaysMatchingAttributes(group);
+  }
+  return {
+    start,
+    resync,
+    stop,
+    getRelaySet,
+    getRelaysSupportingNip,
+    relaySupportsNip,
+    getRelayAttributes,
+    getRelaysMatchingAttributes,
+    getRelaysForAttributeGroup
+  };
+}
+
+export {
+  DEFAULT_RELAY_ATTRIBUTE_GROUPS,
+  createNip66Aggregator
+};
+//# sourceMappingURL=chunk-N4WPLKIJ.js.map

package/dist/chunk-N4WPLKIJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/66.ts"],"sourcesContent":["import type { NostrEvent } from 'nostr-tools';\n\n/**\n * Minimal relay-pool contract `@kehto/nip/66` depends on. Consumers implement\n * this against their pool library of choice (nostr-tools SimplePool,\n * applesauce-relay, @snort/worker-relay, etc.). Intentionally smaller than\n * RxJS-style observable pools — one callback, one unsubscribe handle.\n *\n * @example\n * ```ts\n * import { SimplePool } from 'nostr-tools/pool';\n * const pool = new SimplePool();\n * const adapter: Nip66RelayPool = {\n *   subscribe: (relays, filter, onEvent) => {\n *     const sub = pool.subscribeMany(relays, [filter], { onevent: onEvent });\n *     return () => sub.close();\n *   },\n * };\n * ```\n */\nexport interface Nip66RelayPool {\n  /**\n   * Open a kind-30166 subscription against a set of monitor relays.\n   *\n   * @param relays - WebSocket URLs to subscribe against (the aggregator passes its bootstrap list)\n   * @param filter - A kind-30166 filter, optionally narrowed with `#n` network tags\n   * @param onEvent - Called synchronously with every matching event; the aggregator parses each one\n   * @returns An unsubscribe handle the aggregator calls on `resync()` or teardown\n   */\n  subscribe(\n    relays: ReadonlyArray<string>,\n    filter: Nip66Filter,\n    onEvent: (event: NostrEvent) => void,\n  ): () => void;\n}\n\n/**\n * Minimal filter shape for kind-30166 subscriptions. `#n` optionally narrows\n * by network type (e.g. `['clearnet']`, `['clearnet', 'tor']`).\n *\n * @example\n * ```ts\n * const filter: Nip66Filter = { kinds: [30166], '#n': ['clearnet'] };\n * ```\n */\nexport type Nip66Filter = { kinds: [30166]; '#n'?: ReadonlyArray<string> };\n\n/**\n * Options for {@link createNip66Aggregator}.\n *\n * @example\n * ```ts\n * const options: Nip66AggregatorOptions = {\n *   pool: myPoolAdapter,\n *   bootstrap: ['wss://monitor1.example.com', 'wss://monitor2.example.com'],\n *   networks: ['clearnet'],\n * };\n * ```\n */\nexport interface Nip66AggregatorOptions {\n  /** A {@link Nip66RelayPool} adapter supplied by the consumer. */\n  pool: Nip66RelayPool;\n  /** Required non-empty list of monitor relay URLs to subscribe against. No default ships in the package. */\n  bootstrap: ReadonlyArray<string>;\n  /** Optional network-type narrowing passed to the filter as `#n` (e.g. `['clearnet', 'tor']`). Omit to receive every network. */\n  networks?: ReadonlyArray<string>;\n  /**\n   * Optional named relay-attribute groups for interpreting ad hoc kind-30166 tags.\n   * Omit to use {@link DEFAULT_RELAY_ATTRIBUTE_GROUPS}.\n   */\n  relayAttributeGroups?: RelayAttributeGroups;\n}\n\n/** A tag/value matcher for ad hoc relay attributes carried on kind-30166 events. */\nexport interface RelayAttributeMatcher {\n  /** Tag name to match, for example `T`, `t`, or `k`. */\n  tag: string;\n  /** Optional accepted values. If omitted, any value for the tag matches. */\n  values?: ReadonlyArray<string>;\n}\n\n/** Named groups of relay-attribute matchers. Matchers within a group are OR-ed. */\nexport type RelayAttributeGroups = Readonly<Record<string, ReadonlyArray<RelayAttributeMatcher>>>;\n\n/** Parsed attributes observed for one NIP-66 relay URL. */\nexport interface Nip66RelayAttributes {\n  /** Raw tag copies from the latest observed kind-30166 event for the relay. */\n  tags: ReadonlyArray<ReadonlyArray<string>>;\n  /** Tag-value index, keyed by tag name. */\n  values: ReadonlyMap<string, ReadonlySet<string>>;\n  /** Parsed uppercase `N` tag support for convenience. */\n  supportedNips: ReadonlySet<number>;\n}\n\nexport const DEFAULT_RELAY_ATTRIBUTE_GROUPS: RelayAttributeGroups = {\n  Indexer: [\n    { tag: 'T', values: ['Indexer', 'indexer'] },\n    { tag: 't', values: ['Indexer', 'indexer'] },\n    { tag: 'k', values: ['10002'] },\n  ],\n  RelayIndexer: [\n    { tag: 'T', values: ['RelayIndexer', 'relay-indexer', 'relay_indexer'] },\n    { tag: 't', values: ['RelayIndexer', 'relay-indexer', 'relay_indexer'] },\n    { tag: 'k', values: ['30166', '10166'] },\n  ],\n};\n\n/**\n * Aggregator handle returned by {@link createNip66Aggregator}. Each call\n * returns a fresh instance with its own closure-scoped state — multi-instance\n * safe (unlike a module-globals pattern).\n *\n * @example\n * ```ts\n * const aggregator = createNip66Aggregator({ pool, bootstrap: ['wss://monitor.example.com'] });\n * aggregator.start();\n * const relays = aggregator.getRelaySet();\n * ```\n */\nexport interface Nip66Aggregator {\n  /** Begin subscribing against the bootstrap relay set. Idempotent — calling twice is a no-op. */\n  start(): void;\n  /** Tear down the current subscription, clear accumulated state, and re-subscribe. Call when `networks` semantics change upstream. */\n  resync(): void;\n  /**\n   * Tear down the current subscription. Idempotent — calling without a prior\n   * `start()` is a safe no-op. Preserves accumulated state (`getRelaySet`,\n   * `relaySupportsNip`) — use `resync()` if you need to clear state AND\n   * re-subscribe in one step. A subsequent `start()` re-subscribes against\n   * the bootstrap relays (identical contract to the first start).\n   *\n   * Wire this to your consumer's teardown path (browser: `beforeunload`;\n   * React: effect cleanup; Electron: `app.before-quit`) — the aggregator\n   * holds a pool subscription that otherwise lives for the tab lifetime\n   * (PITFALLS.md M-03).\n   */\n  stop(): void;\n  /** The current set of relay URLs discovered from kind-30166 `d`-tags. Empty until `start()` fires at least one event. */\n  getRelaySet(): ReadonlySet<string>;\n  /**\n   * Relay URLs whose `N`-tags declare support for the given NIP number.\n   *\n   * @param nip - NIP number to query support for (e.g. 44 for NIP-44 encrypted DMs)\n   * @returns Array of relay URLs supporting that NIP\n   */\n  getRelaysSupportingNip(nip: number): string[];\n  /**\n   * Whether the relay at `url` has been seen with an `N`-tag declaring support for `nip`.\n   *\n   * @param url - Relay WebSocket URL to check\n   * @param nip - NIP number to query support for\n   * @returns `true` iff the relay has been observed with a matching `N`-tag\n   */\n  relaySupportsNip(url: string, nip: number): boolean;\n  /**\n   * Return parsed relay attributes for a relay URL, if that relay has been\n   * observed in a kind-30166 event.\n   */\n  getRelayAttributes(url: string): Nip66RelayAttributes | undefined;\n  /**\n   * Return relays matching any supplied ad hoc attribute matcher.\n   *\n   * @param matchers - Tag/value matchers, OR semantics\n   */\n  getRelaysMatchingAttributes(matchers: ReadonlyArray<RelayAttributeMatcher>): string[];\n  /**\n   * Return relays in a named attribute group. Uses the group table passed to\n   * `createNip66Aggregator`, or {@link DEFAULT_RELAY_ATTRIBUTE_GROUPS}.\n   */\n  getRelaysForAttributeGroup(groupName: string, groups?: RelayAttributeGroups): string[];\n}\n\n/**\n * Create a NIP-66 kind-30166 relay-discovery aggregator with closure-scoped state.\n *\n * Subscribes to kind-30166 events via the injected {@link Nip66RelayPool},\n * extracts relay URLs from `d`-tags, and parses `N`-tags to track which NIP\n * numbers each relay supports. Multi-instance safe — each factory call owns\n * its own `Set` + `Map`; multiple aggregators share nothing at module scope.\n *\n * The aggregator is framework-agnostic: it knows nothing about negentropy\n * (NIP-77), OPFS caching, worker relays, or network-type config stores.\n * Consumers inject those concerns through their {@link Nip66RelayPool}\n * implementation. `start()` is synchronous and idempotent — consumers\n * schedule their own cadence (delayed start, retry, etc.).\n *\n * @param options - Pool adapter + bootstrap monitor relays (+ optional network filter)\n * @returns A fresh {@link Nip66Aggregator} handle\n *\n * @example\n * ```ts\n * import { createNip66Aggregator } from '@kehto/nip/66';\n * import { SimplePool } from 'nostr-tools/pool';\n *\n * const pool = new SimplePool();\n * const aggregator = createNip66Aggregator({\n *   pool: {\n *     subscribe: (relays, filter, onEvent) => {\n *       const sub = pool.subscribeMany(relays, [filter], { onevent: onEvent });\n *       return () => sub.close();\n *     },\n *   },\n *   bootstrap: ['wss://monitor1.example.com'],\n * });\n * aggregator.start();\n * // Later — inside a ShellAdapter hook:\n * const suggestions = Array.from(aggregator.getRelaySet());\n * ```\n */\nexport function createNip66Aggregator(options: Nip66AggregatorOptions): Nip66Aggregator {\n  const relaySet = new Set<string>();\n  const relaySupportedNips = new Map<string, Set<number>>();\n  const relayAttributeTags = new Map<string, string[][]>();\n  const relayAttributeValues = new Map<string, Map<string, Set<string>>>();\n  const relayAttributeGroups = options.relayAttributeGroups ?? DEFAULT_RELAY_ATTRIBUTE_GROUPS;\n  let unsubscribe: (() => void) | null = null;\n\n  function buildFilter(): Nip66Filter {\n    const filter: Nip66Filter = { kinds: [30166] };\n    if (options.networks && options.networks.length > 0) {\n      filter['#n'] = options.networks;\n    }\n    return filter;\n  }\n\n  function processEvent(event: NostrEvent): void {\n    const dTag = event.tags.find((t) => t[0] === 'd');\n    const relayUrl = dTag?.[1];\n    if (!relayUrl) return;\n    relaySet.add(relayUrl);\n    captureRelayAttributes(relayUrl, event.tags);\n\n    const nips = new Set<number>();\n    for (const tag of event.tags) {\n      if (tag[0] === 'N' && tag[1]) {\n        const nipNum = parseInt(tag[1], 10);\n        if (!Number.isNaN(nipNum)) nips.add(nipNum);\n      }\n    }\n    if (nips.size > 0) relaySupportedNips.set(relayUrl, nips);\n  }\n\n  function captureRelayAttributes(relayUrl: string, tags: string[][]): void {\n    const tagCopies = tags.map((tag) => [...tag]);\n    const values = new Map<string, Set<string>>();\n    for (const tag of tags) {\n      const [name, value] = tag;\n      if (!name || value === undefined) continue;\n      let bucket = values.get(name);\n      if (!bucket) {\n        bucket = new Set<string>();\n        values.set(name, bucket);\n      }\n      bucket.add(value);\n    }\n    relayAttributeTags.set(relayUrl, tagCopies);\n    relayAttributeValues.set(relayUrl, values);\n  }\n\n  function start(): void {\n    if (unsubscribe) return; // idempotent — already subscribed\n    unsubscribe = options.pool.subscribe(options.bootstrap, buildFilter(), processEvent);\n  }\n\n  function resync(): void {\n    if (unsubscribe) {\n      unsubscribe();\n      unsubscribe = null;\n    }\n    relaySet.clear();\n    relaySupportedNips.clear();\n    relayAttributeTags.clear();\n    relayAttributeValues.clear();\n    unsubscribe = options.pool.subscribe(options.bootstrap, buildFilter(), processEvent);\n  }\n\n  function stop(): void {\n    if (unsubscribe) {\n      unsubscribe();\n      unsubscribe = null;\n    }\n  }\n\n  function getRelaySet(): ReadonlySet<string> {\n    return relaySet;\n  }\n\n  function getRelaysSupportingNip(nip: number): string[] {\n    const result: string[] = [];\n    for (const [url, nips] of relaySupportedNips) {\n      if (nips.has(nip)) result.push(url);\n    }\n    return result;\n  }\n\n  function relaySupportsNip(url: string, nip: number): boolean {\n    return relaySupportedNips.get(url)?.has(nip) ?? false;\n  }\n\n  function getRelayAttributes(url: string): Nip66RelayAttributes | undefined {\n    const tagCopies = relayAttributeTags.get(url);\n    const values = relayAttributeValues.get(url);\n    if (!tagCopies || !values) return undefined;\n    return {\n      tags: tagCopies.map((tag) => [...tag]),\n      values: new Map(Array.from(values, ([tag, tagValues]) => [tag, new Set(tagValues)])),\n      supportedNips: new Set(relaySupportedNips.get(url) ?? []),\n    };\n  }\n\n  function matcherMatches(url: string, matcher: RelayAttributeMatcher): boolean {\n    const values = relayAttributeValues.get(url)?.get(matcher.tag);\n    if (!values || values.size === 0) return false;\n    if (!matcher.values || matcher.values.length === 0) return true;\n    const accepted = new Set(matcher.values.map((value) => value.toLowerCase()));\n    for (const value of values) {\n      if (accepted.has(value.toLowerCase())) return true;\n    }\n    return false;\n  }\n\n  function getRelaysMatchingAttributes(matchers: ReadonlyArray<RelayAttributeMatcher>): string[] {\n    const result: string[] = [];\n    for (const url of relaySet) {\n      if (matchers.some((matcher) => matcherMatches(url, matcher))) result.push(url);\n    }\n    return result;\n  }\n\n  function getRelaysForAttributeGroup(groupName: string, groups?: RelayAttributeGroups): string[] {\n    const group = (groups ?? relayAttributeGroups)[groupName] ?? [];\n    return getRelaysMatchingAttributes(group);\n  }\n\n  return {\n    start,\n    resync,\n    stop,\n    getRelaySet,\n    getRelaysSupportingNip,\n    relaySupportsNip,\n    getRelayAttributes,\n    getRelaysMatchingAttributes,\n    getRelaysForAttributeGroup,\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { DEFAULT_RELAY_ATTRIBUTE_GROUPS, Nip66Aggregator, Nip66AggregatorOptions, Nip66Filter, Nip66RelayAttributes, Nip66RelayPool, RelayAttributeGroups, RelayAttributeMatcher, createNip66Aggregator } from './66.js';
+import 'nostr-tools';

package/dist/index.js

@@ -0,0 +1,9 @@
+import {
+  DEFAULT_RELAY_ATTRIBUTE_GROUPS,
+  createNip66Aggregator
+} from "./chunk-N4WPLKIJ.js";
+export {
+  DEFAULT_RELAY_ATTRIBUTE_GROUPS,
+  createNip66Aggregator
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@kehto/nip",
+  "version": "0.1.0",
+  "description": "Tree-shakable bundle of unique Nostr NIP utilities for napplet runtimes — each NIP at its own subpath (e.g. @kehto/nip/66)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./66": {
+      "types": "./dist/66.d.ts",
+      "import": "./dist/66.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "nostr-tools": ">=2.23.3 <3.0.0"
+  },
+  "devDependencies": {
+    "nostr-tools": "^2.23.3",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.2"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kehto/web.git",
+    "directory": "packages/nip"
+  },
+  "keywords": [
+    "nostr",
+    "nip",
+    "nip66",
+    "relay-discovery",
+    "kehto",
+    "napplet"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "type-check": "tsc --noEmit",
+    "test:unit": "cd ../.. && vitest run --config vitest.config.ts packages/nip/src/66.test.ts",
+    "test": "pnpm test:unit"
+  }
+}