@orangecheck/nostr-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OrangeCheck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @orangecheck/nostr-core
+
+Browser-compatible Nostr client used by every OrangeCheck family web app. Raw NIP-01 over WebSocket against a list of relays.
+
+## Install
+
+```bash
+yarn add @orangecheck/nostr-core
+# or
+npm install @orangecheck/nostr-core
+```
+
+No dependencies — uses the platform `WebSocket` global. Works in any runtime that ships a WHATWG WebSocket (browsers, Node 22+, Deno, Bun, Cloudflare Workers).
+
+## Use
+
+```ts
+import { DEFAULT_RELAYS, publishEvent, queryEvents } from '@orangecheck/nostr-core';
+import type { NostrEvent, Filter } from '@orangecheck/nostr-core';
+
+// Publish a kind-30078 event to the family default relay set.
+const event: NostrEvent = { /* signed by your wallet, see oc-pledge-protocol */ };
+const results = await publishEvent(event);
+const accepted = results.filter((r) => r.ok).length;
+console.log(`${accepted}/${results.length} relays accepted`);
+
+// Query events across the racing read pool.
+const filter: Filter = { kinds: [30078], '#t': ['bc1q…'] };
+const { events, relayStatus } = await queryEvents(filter);
+console.log(`${events.length} unique events from ${relayStatus.filter(r => r.ok).length} relays`);
+```
+
+## What's in `DEFAULT_RELAYS`
+
+Five relays, in order:
+
+1. `wss://relay.nostr.band`
+2. `wss://nos.lol`
+3. `wss://relay.primal.net`
+4. `wss://offchain.pub`
+5. `wss://relay.ochk.io` — the OC family's first-party kind-allowlisted relay (see [`oc-relay-infra`](https://github.com/orangecheck/oc-relay-infra))
+
+**`DEFAULT_RELAYS` is enforced at the type level to never collapse to `relay.ochk.io` alone or to fewer than two entries.** See the `_ValidRelaySet` invariant in `src/index.ts`. A future change that violates the invariant fails `tsc` at build time.
+
+## Why it exists
+
+Five OC web repos (`oc-vote-web`, `oc-pledge-web`, `oc-stamp-web`, `oc-lock-web`, `oc-fleet-web`) used to carry near-identical 200-line `client.ts` files via fork-and-paste. Drift between them was already visible before extraction. Now each repo imports from this package; the family stays in sync via a single `yarn upgrade @orangecheck/nostr-core`.
+
+Product-specific helpers (`fetchPollEvent` for OC Vote, `fetchPledgeOutcomes` for OC Pledge, etc.) stay local to each app — they're shape-specific to one verb and don't generalize.
+
+## License
+
+MIT.

package/dist/index.d.mts

@@ -0,0 +1,43 @@
+declare const DEFAULT_RELAYS: readonly string[];
+interface NostrEvent {
+    id: string;
+    kind: number;
+    pubkey: string;
+    created_at: number;
+    content: string;
+    tags: string[][];
+    sig: string;
+}
+interface PublishResult {
+    relay: string;
+    ok: boolean;
+    reason?: string;
+    attempts: number;
+}
+interface Filter {
+    kinds?: number[];
+    authors?: string[];
+    ids?: string[];
+    limit?: number;
+    since?: number;
+    until?: number;
+    '#d'?: string[];
+    '#t'?: string[];
+    '#poll_id'?: string[];
+    '#voter'?: string[];
+    '#creator'?: string[];
+    [key: `#${string}`]: string[] | undefined;
+}
+interface QueryResult {
+    events: NostrEvent[];
+    relayStatus: {
+        relay: string;
+        ok: boolean;
+        reason?: string;
+        events: number;
+    }[];
+}
+declare function publishEvent(event: NostrEvent, relays?: readonly string[], timeoutMs?: number): Promise<PublishResult[]>;
+declare function queryEvents(filter: Filter, relays?: readonly string[], timeoutMs?: number): Promise<QueryResult>;
+
+export { DEFAULT_RELAYS, type Filter, type NostrEvent, type PublishResult, type QueryResult, publishEvent, queryEvents };

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+declare const DEFAULT_RELAYS: readonly string[];
+interface NostrEvent {
+    id: string;
+    kind: number;
+    pubkey: string;
+    created_at: number;
+    content: string;
+    tags: string[][];
+    sig: string;
+}
+interface PublishResult {
+    relay: string;
+    ok: boolean;
+    reason?: string;
+    attempts: number;
+}
+interface Filter {
+    kinds?: number[];
+    authors?: string[];
+    ids?: string[];
+    limit?: number;
+    since?: number;
+    until?: number;
+    '#d'?: string[];
+    '#t'?: string[];
+    '#poll_id'?: string[];
+    '#voter'?: string[];
+    '#creator'?: string[];
+    [key: `#${string}`]: string[] | undefined;
+}
+interface QueryResult {
+    events: NostrEvent[];
+    relayStatus: {
+        relay: string;
+        ok: boolean;
+        reason?: string;
+        events: number;
+    }[];
+}
+declare function publishEvent(event: NostrEvent, relays?: readonly string[], timeoutMs?: number): Promise<PublishResult[]>;
+declare function queryEvents(filter: Filter, relays?: readonly string[], timeoutMs?: number): Promise<QueryResult>;
+
+export { DEFAULT_RELAYS, type Filter, type NostrEvent, type PublishResult, type QueryResult, publishEvent, queryEvents };

package/dist/index.js

@@ -0,0 +1,233 @@
+'use strict';
+
+// src/index.ts
+var _RELAYS = [
+  "wss://relay.nostr.band",
+  "wss://nos.lol",
+  "wss://relay.primal.net",
+  "wss://offchain.pub",
+  // First-party family relay — kind allowlist 30078–30086 + canonical
+  // OC d-tag prefixes. Always co-published with public relays; never
+  // the only copy. See https://github.com/orangecheck/oc-relay-infra.
+  "wss://relay.ochk.io"
+];
+var DEFAULT_RELAYS = Object.freeze([..._RELAYS]);
+function parseFrame(raw) {
+  try {
+    const arr = JSON.parse(raw);
+    if (!Array.isArray(arr) || arr.length === 0) return null;
+    const type = arr[0];
+    if (type === "OK" || type === "EVENT" || type === "EOSE" || type === "NOTICE" || type === "CLOSED") {
+      return { type, payload: arr.slice(1) };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+var DEFAULT_RETRY = {
+  attempts: 3,
+  timeoutMs: 5e3,
+  initialBackoffMs: 500,
+  maxBackoffMs: 4e3
+};
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function publishOne(url, event, retry) {
+  let attempts = 0;
+  let backoff = retry.initialBackoffMs;
+  let lastReason;
+  while (attempts < retry.attempts) {
+    attempts++;
+    const attempt = await attemptPublish(url, event, retry.timeoutMs);
+    if (attempt.ok) {
+      return {
+        relay: url,
+        ok: true,
+        attempts,
+        ...attempt.reason ? { reason: attempt.reason } : {}
+      };
+    }
+    lastReason = attempt.reason;
+    if (attempt.retryable && attempts < retry.attempts) {
+      await delay(backoff);
+      backoff = Math.min(backoff * 2, retry.maxBackoffMs);
+      continue;
+    }
+    break;
+  }
+  return {
+    relay: url,
+    ok: false,
+    attempts,
+    ...lastReason ? { reason: lastReason } : {}
+  };
+}
+function attemptPublish(url, event, timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let ws = null;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      try {
+        ws?.close();
+      } catch {
+      }
+      resolve({ ok: false, reason: "timeout", retryable: true });
+    }, timeoutMs);
+    try {
+      ws = new WebSocket(url);
+      ws.onopen = () => ws?.send(JSON.stringify(["EVENT", event]));
+      ws.onmessage = (msg) => {
+        const frame = parseFrame(msg.data);
+        if (!frame) return;
+        if (frame.type === "OK" && frame.payload[0] === event.id) {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          try {
+            ws?.close();
+          } catch {
+          }
+          const ok = frame.payload[1] === true;
+          const reason = frame.payload[2];
+          resolve({
+            ok,
+            ...reason ? { reason } : {},
+            retryable: false
+          });
+        }
+      };
+      ws.onerror = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve({ ok: false, reason: "websocket_error", retryable: true });
+      };
+      ws.onclose = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve({ ok: false, reason: "closed_early", retryable: true });
+      };
+    } catch (err) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({
+        ok: false,
+        reason: err instanceof Error ? err.message : "unknown",
+        retryable: true
+      });
+    }
+  });
+}
+async function publishEvent(event, relays = DEFAULT_RELAYS, timeoutMs = 5e3) {
+  const retry = { ...DEFAULT_RETRY, timeoutMs };
+  return Promise.all(relays.map((r) => publishOne(r, event, retry)));
+}
+async function queryEvents(filter, relays = DEFAULT_RELAYS, timeoutMs = 1500) {
+  const subId = "ocnc-" + Math.random().toString(36).slice(2, 10);
+  const byId = /* @__PURE__ */ new Map();
+  const status = [];
+  await Promise.all(
+    relays.map(
+      (url) => new Promise((resolve) => {
+        let settled = false;
+        let count = 0;
+        let reason;
+        let ws = null;
+        const timer = setTimeout(() => {
+          if (settled) return;
+          settled = true;
+          try {
+            ws?.close();
+          } catch {
+          }
+          status.push({
+            relay: url,
+            ok: count > 0,
+            reason: reason ?? "timeout",
+            events: count
+          });
+          resolve();
+        }, timeoutMs);
+        try {
+          ws = new WebSocket(url);
+          ws.onopen = () => ws?.send(JSON.stringify(["REQ", subId, filter]));
+          ws.onmessage = (msg) => {
+            const frame = parseFrame(msg.data);
+            if (!frame) return;
+            if (frame.type === "EVENT" && frame.payload[0] === subId) {
+              const event = frame.payload[1];
+              if (event && event.id) {
+                byId.set(event.id, event);
+                count++;
+              }
+            } else if (frame.type === "EOSE" && frame.payload[0] === subId) {
+              if (settled) return;
+              settled = true;
+              clearTimeout(timer);
+              try {
+                ws?.send(JSON.stringify(["CLOSE", subId]));
+                ws?.close();
+              } catch {
+              }
+              status.push({ relay: url, ok: true, events: count });
+              resolve();
+            } else if (frame.type === "NOTICE") {
+              reason = String(frame.payload[0] ?? "notice");
+            }
+          };
+          ws.onerror = () => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            status.push({
+              relay: url,
+              ok: false,
+              reason: "ws_error",
+              events: count
+            });
+            resolve();
+          };
+          ws.onclose = () => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            status.push({
+              relay: url,
+              ok: count > 0,
+              reason: reason ?? "closed_early",
+              events: count
+            });
+            resolve();
+          };
+        } catch (err) {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          status.push({
+            relay: url,
+            ok: false,
+            reason: err instanceof Error ? err.message : "unknown",
+            events: count
+          });
+          resolve();
+        }
+      })
+    )
+  );
+  return {
+    events: Array.from(byId.values()).sort((a, b) => b.created_at - a.created_at),
+    relayStatus: status
+  };
+}
+
+exports.DEFAULT_RELAYS = DEFAULT_RELAYS;
+exports.publishEvent = publishEvent;
+exports.queryEvents = queryEvents;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @orangecheck/nostr-core\n *\n * Browser-compatible Nostr client used by every OrangeCheck family web\n * app. Raw NIP-01 over WebSocket against a list of relays. Every operation\n * races all relays in parallel and reports per-relay status so the caller\n * can distinguish \"nobody replied\" from \"one relay rejected.\" Retries with\n * exponential backoff on transport errors only.\n *\n * No dependencies — uses the platform `WebSocket` global. Works in any\n * runtime that ships a WHATWG WebSocket (browser, Node 22+, Deno, Bun,\n * Cloudflare Workers).\n *\n * Source-of-truth `DEFAULT_RELAYS` for the OC family. Co-publishes to four\n * public relays plus `wss://relay.ochk.io` (the family's first-party\n * kind-allowlisted relay — see https://github.com/orangecheck/oc-relay-infra).\n *\n * **Hard invariant:** `DEFAULT_RELAYS` MUST contain at least two entries,\n * and MUST NOT be `relay.ochk.io` alone. Enforced at the type level — a\n * future engineer simplifying to ours-only fails `tsc`. See `_validate`\n * below.\n */\n\n// ─────────────────────────────────────────────────────────────────────────\n// Build-time invariants + default relay set.\n// ─────────────────────────────────────────────────────────────────────────\n\n/**\n * Family-relay invariants applied to `DEFAULT_RELAYS`. The relay set must:\n *   1. Contain at least two relays — single-relay defaults are always wrong\n *      because the family's BYPASS principle requires public-relay co-publish.\n *   2. Not be `wss://relay.ochk.io` alone — relay.ochk.io is additive, never\n *      a single point of failure. See oc-relay-infra/BYPASS.md.\n *\n * If `T` violates either rule, this resolves to `never` and the assignment\n * below fails at `tsc` time.\n */\ntype ValidRelaySet<T extends readonly string[]> =\n    T['length'] extends 0 | 1 ? never :\n    T extends readonly ['wss://relay.ochk.io'] ? never :\n    T;\n\nconst _RELAYS: ValidRelaySet<readonly [\n    'wss://relay.nostr.band',\n    'wss://nos.lol',\n    'wss://relay.primal.net',\n    'wss://offchain.pub',\n    'wss://relay.ochk.io',\n]> = [\n    'wss://relay.nostr.band',\n    'wss://nos.lol',\n    'wss://relay.primal.net',\n    'wss://offchain.pub',\n    // First-party family relay — kind allowlist 30078–30086 + canonical\n    // OC d-tag prefixes. Always co-published with public relays; never\n    // the only copy. See https://github.com/orangecheck/oc-relay-infra.\n    'wss://relay.ochk.io',\n] as const;\n\n/**\n * Default relay set for OrangeCheck family Nostr publishes + queries.\n *\n * Frozen at runtime; consumers MAY pass an explicit `relays` arg to any\n * function in this package to override.\n */\nexport const DEFAULT_RELAYS: readonly string[] = Object.freeze([..._RELAYS]);\n\n// ─────────────────────────────────────────────────────────────────────────\n// Wire types — NIP-01 event + filter + result shapes.\n// ─────────────────────────────────────────────────────────────────────────\n\nexport interface NostrEvent {\n    id: string;\n    kind: number;\n    pubkey: string;\n    created_at: number;\n    content: string;\n    tags: string[][];\n    sig: string;\n}\n\nexport interface PublishResult {\n    relay: string;\n    ok: boolean;\n    reason?: string;\n    attempts: number;\n}\n\nexport interface Filter {\n    kinds?: number[];\n    authors?: string[];\n    ids?: string[];\n    limit?: number;\n    since?: number;\n    until?: number;\n    /** NIP-12 indexable `d`-tag filter. */\n    '#d'?: string[];\n    /** NIP-12 indexable single-letter tag filter. */\n    '#t'?: string[];\n    /** Used by OC Vote (kind 30081 ballots). */\n    '#poll_id'?: string[];\n    /** Used by OC Vote (kind 30081 ballots). */\n    '#voter'?: string[];\n    /** Used by OC Vote (kind 30080 polls). */\n    '#creator'?: string[];\n    /** Other indexable single-letter tags clients may filter on. */\n    [key: `#${string}`]: string[] | undefined;\n}\n\nexport interface QueryResult {\n    events: NostrEvent[];\n    relayStatus: { relay: string; ok: boolean; reason?: string; events: number }[];\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Internal — frame parsing + retry config.\n// ─────────────────────────────────────────────────────────────────────────\n\ntype FrameType = 'OK' | 'EVENT' | 'EOSE' | 'NOTICE' | 'CLOSED';\ninterface RelayFrame {\n    type: FrameType;\n    payload: unknown[];\n}\n\nfunction parseFrame(raw: string): RelayFrame | null {\n    try {\n        const arr = JSON.parse(raw) as unknown[];\n        if (!Array.isArray(arr) || arr.length === 0) return null;\n        const type = arr[0];\n        if (\n            type === 'OK' ||\n            type === 'EVENT' ||\n            type === 'EOSE' ||\n            type === 'NOTICE' ||\n            type === 'CLOSED'\n        ) {\n            return { type: type as FrameType, payload: arr.slice(1) };\n        }\n        return null;\n    } catch {\n        return null;\n    }\n}\n\ninterface RetryOptions {\n    attempts: number;\n    timeoutMs: number;\n    initialBackoffMs: number;\n    maxBackoffMs: number;\n}\n\nconst DEFAULT_RETRY: RetryOptions = {\n    attempts: 3,\n    timeoutMs: 5000,\n    initialBackoffMs: 500,\n    maxBackoffMs: 4000,\n};\n\nfunction delay(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Publish — write an event to one or more relays in parallel, with retry.\n// ─────────────────────────────────────────────────────────────────────────\n\nasync function publishOne(\n    url: string,\n    event: NostrEvent,\n    retry: RetryOptions\n): Promise<PublishResult> {\n    let attempts = 0;\n    let backoff = retry.initialBackoffMs;\n    let lastReason: string | undefined;\n\n    while (attempts < retry.attempts) {\n        attempts++;\n        const attempt = await attemptPublish(url, event, retry.timeoutMs);\n        if (attempt.ok) {\n            return {\n                relay: url,\n                ok: true,\n                attempts,\n                ...(attempt.reason ? { reason: attempt.reason } : {}),\n            };\n        }\n        lastReason = attempt.reason;\n        if (attempt.retryable && attempts < retry.attempts) {\n            await delay(backoff);\n            backoff = Math.min(backoff * 2, retry.maxBackoffMs);\n            continue;\n        }\n        break;\n    }\n    return {\n        relay: url,\n        ok: false,\n        attempts,\n        ...(lastReason ? { reason: lastReason } : {}),\n    };\n}\n\nfunction attemptPublish(\n    url: string,\n    event: NostrEvent,\n    timeoutMs: number\n): Promise<{ ok: boolean; reason?: string; retryable: boolean }> {\n    return new Promise((resolve) => {\n        let settled = false;\n        let ws: WebSocket | null = null;\n        const timer = setTimeout(() => {\n            if (settled) return;\n            settled = true;\n            try {\n                ws?.close();\n            } catch {}\n            resolve({ ok: false, reason: 'timeout', retryable: true });\n        }, timeoutMs);\n        try {\n            ws = new WebSocket(url);\n            ws.onopen = () => ws?.send(JSON.stringify(['EVENT', event]));\n            ws.onmessage = (msg) => {\n                const frame = parseFrame(msg.data as string);\n                if (!frame) return;\n                if (frame.type === 'OK' && frame.payload[0] === event.id) {\n                    if (settled) return;\n                    settled = true;\n                    clearTimeout(timer);\n                    try {\n                        ws?.close();\n                    } catch {}\n                    const ok = frame.payload[1] === true;\n                    const reason = frame.payload[2] as string | undefined;\n                    resolve({\n                        ok,\n                        ...(reason ? { reason } : {}),\n                        retryable: false,\n                    });\n                }\n            };\n            ws.onerror = () => {\n                if (settled) return;\n                settled = true;\n                clearTimeout(timer);\n                resolve({ ok: false, reason: 'websocket_error', retryable: true });\n            };\n            ws.onclose = () => {\n                if (settled) return;\n                settled = true;\n                clearTimeout(timer);\n                resolve({ ok: false, reason: 'closed_early', retryable: true });\n            };\n        } catch (err) {\n            if (settled) return;\n            settled = true;\n            clearTimeout(timer);\n            resolve({\n                ok: false,\n                reason: err instanceof Error ? err.message : 'unknown',\n                retryable: true,\n            });\n        }\n    });\n}\n\n/**\n * Publish a NIP-01 event to all `relays` in parallel. Returns one\n * `PublishResult` per relay. Default timeout 5000ms.\n */\nexport async function publishEvent(\n    event: NostrEvent,\n    relays: readonly string[] = DEFAULT_RELAYS,\n    timeoutMs = 5000\n): Promise<PublishResult[]> {\n    const retry: RetryOptions = { ...DEFAULT_RETRY, timeoutMs };\n    return Promise.all(relays.map((r) => publishOne(r, event, retry)));\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Query — REQ → EOSE → close. Races all relays; first to EOSE wins.\n// ─────────────────────────────────────────────────────────────────────────\n\n/**\n * Issue a NIP-01 REQ across all `relays` in parallel. Returns deduplicated\n * events sorted newest-first plus per-relay status.\n *\n * Default timeout 1500ms — short enough that a momentary blip on any one\n * relay (including relay.ochk.io) never holds up the racing reads. Pass an\n * explicit `timeoutMs` for slow filters or for use cases where waiting on\n * the slowest relay matters.\n */\nexport async function queryEvents(\n    filter: Filter,\n    relays: readonly string[] = DEFAULT_RELAYS,\n    timeoutMs = 1500\n): Promise<QueryResult> {\n    const subId = 'ocnc-' + Math.random().toString(36).slice(2, 10);\n    const byId = new Map<string, NostrEvent>();\n    const status: QueryResult['relayStatus'] = [];\n\n    await Promise.all(\n        relays.map(\n            (url) =>\n                new Promise<void>((resolve) => {\n                    let settled = false;\n                    let count = 0;\n                    let reason: string | undefined;\n                    let ws: WebSocket | null = null;\n                    const timer = setTimeout(() => {\n                        if (settled) return;\n                        settled = true;\n                        try {\n                            ws?.close();\n                        } catch {}\n                        status.push({\n                            relay: url,\n                            ok: count > 0,\n                            reason: reason ?? 'timeout',\n                            events: count,\n                        });\n                        resolve();\n                    }, timeoutMs);\n                    try {\n                        ws = new WebSocket(url);\n                        ws.onopen = () => ws?.send(JSON.stringify(['REQ', subId, filter]));\n                        ws.onmessage = (msg) => {\n                            const frame = parseFrame(msg.data as string);\n                            if (!frame) return;\n                            if (frame.type === 'EVENT' && frame.payload[0] === subId) {\n                                const event = frame.payload[1] as NostrEvent | undefined;\n                                if (event && event.id) {\n                                    byId.set(event.id, event);\n                                    count++;\n                                }\n                            } else if (frame.type === 'EOSE' && frame.payload[0] === subId) {\n                                if (settled) return;\n                                settled = true;\n                                clearTimeout(timer);\n                                try {\n                                    ws?.send(JSON.stringify(['CLOSE', subId]));\n                                    ws?.close();\n                                } catch {}\n                                status.push({ relay: url, ok: true, events: count });\n                                resolve();\n                            } else if (frame.type === 'NOTICE') {\n                                reason = String(frame.payload[0] ?? 'notice');\n                            }\n                        };\n                        ws.onerror = () => {\n                            if (settled) return;\n                            settled = true;\n                            clearTimeout(timer);\n                            status.push({\n                                relay: url,\n                                ok: false,\n                                reason: 'ws_error',\n                                events: count,\n                            });\n                            resolve();\n                        };\n                        ws.onclose = () => {\n                            if (settled) return;\n                            settled = true;\n                            clearTimeout(timer);\n                            status.push({\n                                relay: url,\n                                ok: count > 0,\n                                reason: reason ?? 'closed_early',\n                                events: count,\n                            });\n                            resolve();\n                        };\n                    } catch (err) {\n                        if (settled) return;\n                        settled = true;\n                        clearTimeout(timer);\n                        status.push({\n                            relay: url,\n                            ok: false,\n                            reason: err instanceof Error ? err.message : 'unknown',\n                            events: count,\n                        });\n                        resolve();\n                    }\n                })\n        )\n    );\n\n    return {\n        events: Array.from(byId.values()).sort((a, b) => b.created_at - a.created_at),\n        relayStatus: status,\n    };\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,229 @@
+// src/index.ts
+var _RELAYS = [
+  "wss://relay.nostr.band",
+  "wss://nos.lol",
+  "wss://relay.primal.net",
+  "wss://offchain.pub",
+  // First-party family relay — kind allowlist 30078–30086 + canonical
+  // OC d-tag prefixes. Always co-published with public relays; never
+  // the only copy. See https://github.com/orangecheck/oc-relay-infra.
+  "wss://relay.ochk.io"
+];
+var DEFAULT_RELAYS = Object.freeze([..._RELAYS]);
+function parseFrame(raw) {
+  try {
+    const arr = JSON.parse(raw);
+    if (!Array.isArray(arr) || arr.length === 0) return null;
+    const type = arr[0];
+    if (type === "OK" || type === "EVENT" || type === "EOSE" || type === "NOTICE" || type === "CLOSED") {
+      return { type, payload: arr.slice(1) };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+var DEFAULT_RETRY = {
+  attempts: 3,
+  timeoutMs: 5e3,
+  initialBackoffMs: 500,
+  maxBackoffMs: 4e3
+};
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function publishOne(url, event, retry) {
+  let attempts = 0;
+  let backoff = retry.initialBackoffMs;
+  let lastReason;
+  while (attempts < retry.attempts) {
+    attempts++;
+    const attempt = await attemptPublish(url, event, retry.timeoutMs);
+    if (attempt.ok) {
+      return {
+        relay: url,
+        ok: true,
+        attempts,
+        ...attempt.reason ? { reason: attempt.reason } : {}
+      };
+    }
+    lastReason = attempt.reason;
+    if (attempt.retryable && attempts < retry.attempts) {
+      await delay(backoff);
+      backoff = Math.min(backoff * 2, retry.maxBackoffMs);
+      continue;
+    }
+    break;
+  }
+  return {
+    relay: url,
+    ok: false,
+    attempts,
+    ...lastReason ? { reason: lastReason } : {}
+  };
+}
+function attemptPublish(url, event, timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let ws = null;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      try {
+        ws?.close();
+      } catch {
+      }
+      resolve({ ok: false, reason: "timeout", retryable: true });
+    }, timeoutMs);
+    try {
+      ws = new WebSocket(url);
+      ws.onopen = () => ws?.send(JSON.stringify(["EVENT", event]));
+      ws.onmessage = (msg) => {
+        const frame = parseFrame(msg.data);
+        if (!frame) return;
+        if (frame.type === "OK" && frame.payload[0] === event.id) {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          try {
+            ws?.close();
+          } catch {
+          }
+          const ok = frame.payload[1] === true;
+          const reason = frame.payload[2];
+          resolve({
+            ok,
+            ...reason ? { reason } : {},
+            retryable: false
+          });
+        }
+      };
+      ws.onerror = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve({ ok: false, reason: "websocket_error", retryable: true });
+      };
+      ws.onclose = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve({ ok: false, reason: "closed_early", retryable: true });
+      };
+    } catch (err) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({
+        ok: false,
+        reason: err instanceof Error ? err.message : "unknown",
+        retryable: true
+      });
+    }
+  });
+}
+async function publishEvent(event, relays = DEFAULT_RELAYS, timeoutMs = 5e3) {
+  const retry = { ...DEFAULT_RETRY, timeoutMs };
+  return Promise.all(relays.map((r) => publishOne(r, event, retry)));
+}
+async function queryEvents(filter, relays = DEFAULT_RELAYS, timeoutMs = 1500) {
+  const subId = "ocnc-" + Math.random().toString(36).slice(2, 10);
+  const byId = /* @__PURE__ */ new Map();
+  const status = [];
+  await Promise.all(
+    relays.map(
+      (url) => new Promise((resolve) => {
+        let settled = false;
+        let count = 0;
+        let reason;
+        let ws = null;
+        const timer = setTimeout(() => {
+          if (settled) return;
+          settled = true;
+          try {
+            ws?.close();
+          } catch {
+          }
+          status.push({
+            relay: url,
+            ok: count > 0,
+            reason: reason ?? "timeout",
+            events: count
+          });
+          resolve();
+        }, timeoutMs);
+        try {
+          ws = new WebSocket(url);
+          ws.onopen = () => ws?.send(JSON.stringify(["REQ", subId, filter]));
+          ws.onmessage = (msg) => {
+            const frame = parseFrame(msg.data);
+            if (!frame) return;
+            if (frame.type === "EVENT" && frame.payload[0] === subId) {
+              const event = frame.payload[1];
+              if (event && event.id) {
+                byId.set(event.id, event);
+                count++;
+              }
+            } else if (frame.type === "EOSE" && frame.payload[0] === subId) {
+              if (settled) return;
+              settled = true;
+              clearTimeout(timer);
+              try {
+                ws?.send(JSON.stringify(["CLOSE", subId]));
+                ws?.close();
+              } catch {
+              }
+              status.push({ relay: url, ok: true, events: count });
+              resolve();
+            } else if (frame.type === "NOTICE") {
+              reason = String(frame.payload[0] ?? "notice");
+            }
+          };
+          ws.onerror = () => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            status.push({
+              relay: url,
+              ok: false,
+              reason: "ws_error",
+              events: count
+            });
+            resolve();
+          };
+          ws.onclose = () => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            status.push({
+              relay: url,
+              ok: count > 0,
+              reason: reason ?? "closed_early",
+              events: count
+            });
+            resolve();
+          };
+        } catch (err) {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          status.push({
+            relay: url,
+            ok: false,
+            reason: err instanceof Error ? err.message : "unknown",
+            events: count
+          });
+          resolve();
+        }
+      })
+    )
+  );
+  return {
+    events: Array.from(byId.values()).sort((a, b) => b.created_at - a.created_at),
+    relayStatus: status
+  };
+}
+
+export { DEFAULT_RELAYS, publishEvent, queryEvents };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * @orangecheck/nostr-core\n *\n * Browser-compatible Nostr client used by every OrangeCheck family web\n * app. Raw NIP-01 over WebSocket against a list of relays. Every operation\n * races all relays in parallel and reports per-relay status so the caller\n * can distinguish \"nobody replied\" from \"one relay rejected.\" Retries with\n * exponential backoff on transport errors only.\n *\n * No dependencies — uses the platform `WebSocket` global. Works in any\n * runtime that ships a WHATWG WebSocket (browser, Node 22+, Deno, Bun,\n * Cloudflare Workers).\n *\n * Source-of-truth `DEFAULT_RELAYS` for the OC family. Co-publishes to four\n * public relays plus `wss://relay.ochk.io` (the family's first-party\n * kind-allowlisted relay — see https://github.com/orangecheck/oc-relay-infra).\n *\n * **Hard invariant:** `DEFAULT_RELAYS` MUST contain at least two entries,\n * and MUST NOT be `relay.ochk.io` alone. Enforced at the type level — a\n * future engineer simplifying to ours-only fails `tsc`. See `_validate`\n * below.\n */\n\n// ─────────────────────────────────────────────────────────────────────────\n// Build-time invariants + default relay set.\n// ─────────────────────────────────────────────────────────────────────────\n\n/**\n * Family-relay invariants applied to `DEFAULT_RELAYS`. The relay set must:\n *   1. Contain at least two relays — single-relay defaults are always wrong\n *      because the family's BYPASS principle requires public-relay co-publish.\n *   2. Not be `wss://relay.ochk.io` alone — relay.ochk.io is additive, never\n *      a single point of failure. See oc-relay-infra/BYPASS.md.\n *\n * If `T` violates either rule, this resolves to `never` and the assignment\n * below fails at `tsc` time.\n */\ntype ValidRelaySet<T extends readonly string[]> =\n    T['length'] extends 0 | 1 ? never :\n    T extends readonly ['wss://relay.ochk.io'] ? never :\n    T;\n\nconst _RELAYS: ValidRelaySet<readonly [\n    'wss://relay.nostr.band',\n    'wss://nos.lol',\n    'wss://relay.primal.net',\n    'wss://offchain.pub',\n    'wss://relay.ochk.io',\n]> = [\n    'wss://relay.nostr.band',\n    'wss://nos.lol',\n    'wss://relay.primal.net',\n    'wss://offchain.pub',\n    // First-party family relay — kind allowlist 30078–30086 + canonical\n    // OC d-tag prefixes. Always co-published with public relays; never\n    // the only copy. See https://github.com/orangecheck/oc-relay-infra.\n    'wss://relay.ochk.io',\n] as const;\n\n/**\n * Default relay set for OrangeCheck family Nostr publishes + queries.\n *\n * Frozen at runtime; consumers MAY pass an explicit `relays` arg to any\n * function in this package to override.\n */\nexport const DEFAULT_RELAYS: readonly string[] = Object.freeze([..._RELAYS]);\n\n// ─────────────────────────────────────────────────────────────────────────\n// Wire types — NIP-01 event + filter + result shapes.\n// ─────────────────────────────────────────────────────────────────────────\n\nexport interface NostrEvent {\n    id: string;\n    kind: number;\n    pubkey: string;\n    created_at: number;\n    content: string;\n    tags: string[][];\n    sig: string;\n}\n\nexport interface PublishResult {\n    relay: string;\n    ok: boolean;\n    reason?: string;\n    attempts: number;\n}\n\nexport interface Filter {\n    kinds?: number[];\n    authors?: string[];\n    ids?: string[];\n    limit?: number;\n    since?: number;\n    until?: number;\n    /** NIP-12 indexable `d`-tag filter. */\n    '#d'?: string[];\n    /** NIP-12 indexable single-letter tag filter. */\n    '#t'?: string[];\n    /** Used by OC Vote (kind 30081 ballots). */\n    '#poll_id'?: string[];\n    /** Used by OC Vote (kind 30081 ballots). */\n    '#voter'?: string[];\n    /** Used by OC Vote (kind 30080 polls). */\n    '#creator'?: string[];\n    /** Other indexable single-letter tags clients may filter on. */\n    [key: `#${string}`]: string[] | undefined;\n}\n\nexport interface QueryResult {\n    events: NostrEvent[];\n    relayStatus: { relay: string; ok: boolean; reason?: string; events: number }[];\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Internal — frame parsing + retry config.\n// ─────────────────────────────────────────────────────────────────────────\n\ntype FrameType = 'OK' | 'EVENT' | 'EOSE' | 'NOTICE' | 'CLOSED';\ninterface RelayFrame {\n    type: FrameType;\n    payload: unknown[];\n}\n\nfunction parseFrame(raw: string): RelayFrame | null {\n    try {\n        const arr = JSON.parse(raw) as unknown[];\n        if (!Array.isArray(arr) || arr.length === 0) return null;\n        const type = arr[0];\n        if (\n            type === 'OK' ||\n            type === 'EVENT' ||\n            type === 'EOSE' ||\n            type === 'NOTICE' ||\n            type === 'CLOSED'\n        ) {\n            return { type: type as FrameType, payload: arr.slice(1) };\n        }\n        return null;\n    } catch {\n        return null;\n    }\n}\n\ninterface RetryOptions {\n    attempts: number;\n    timeoutMs: number;\n    initialBackoffMs: number;\n    maxBackoffMs: number;\n}\n\nconst DEFAULT_RETRY: RetryOptions = {\n    attempts: 3,\n    timeoutMs: 5000,\n    initialBackoffMs: 500,\n    maxBackoffMs: 4000,\n};\n\nfunction delay(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Publish — write an event to one or more relays in parallel, with retry.\n// ─────────────────────────────────────────────────────────────────────────\n\nasync function publishOne(\n    url: string,\n    event: NostrEvent,\n    retry: RetryOptions\n): Promise<PublishResult> {\n    let attempts = 0;\n    let backoff = retry.initialBackoffMs;\n    let lastReason: string | undefined;\n\n    while (attempts < retry.attempts) {\n        attempts++;\n        const attempt = await attemptPublish(url, event, retry.timeoutMs);\n        if (attempt.ok) {\n            return {\n                relay: url,\n                ok: true,\n                attempts,\n                ...(attempt.reason ? { reason: attempt.reason } : {}),\n            };\n        }\n        lastReason = attempt.reason;\n        if (attempt.retryable && attempts < retry.attempts) {\n            await delay(backoff);\n            backoff = Math.min(backoff * 2, retry.maxBackoffMs);\n            continue;\n        }\n        break;\n    }\n    return {\n        relay: url,\n        ok: false,\n        attempts,\n        ...(lastReason ? { reason: lastReason } : {}),\n    };\n}\n\nfunction attemptPublish(\n    url: string,\n    event: NostrEvent,\n    timeoutMs: number\n): Promise<{ ok: boolean; reason?: string; retryable: boolean }> {\n    return new Promise((resolve) => {\n        let settled = false;\n        let ws: WebSocket | null = null;\n        const timer = setTimeout(() => {\n            if (settled) return;\n            settled = true;\n            try {\n                ws?.close();\n            } catch {}\n            resolve({ ok: false, reason: 'timeout', retryable: true });\n        }, timeoutMs);\n        try {\n            ws = new WebSocket(url);\n            ws.onopen = () => ws?.send(JSON.stringify(['EVENT', event]));\n            ws.onmessage = (msg) => {\n                const frame = parseFrame(msg.data as string);\n                if (!frame) return;\n                if (frame.type === 'OK' && frame.payload[0] === event.id) {\n                    if (settled) return;\n                    settled = true;\n                    clearTimeout(timer);\n                    try {\n                        ws?.close();\n                    } catch {}\n                    const ok = frame.payload[1] === true;\n                    const reason = frame.payload[2] as string | undefined;\n                    resolve({\n                        ok,\n                        ...(reason ? { reason } : {}),\n                        retryable: false,\n                    });\n                }\n            };\n            ws.onerror = () => {\n                if (settled) return;\n                settled = true;\n                clearTimeout(timer);\n                resolve({ ok: false, reason: 'websocket_error', retryable: true });\n            };\n            ws.onclose = () => {\n                if (settled) return;\n                settled = true;\n                clearTimeout(timer);\n                resolve({ ok: false, reason: 'closed_early', retryable: true });\n            };\n        } catch (err) {\n            if (settled) return;\n            settled = true;\n            clearTimeout(timer);\n            resolve({\n                ok: false,\n                reason: err instanceof Error ? err.message : 'unknown',\n                retryable: true,\n            });\n        }\n    });\n}\n\n/**\n * Publish a NIP-01 event to all `relays` in parallel. Returns one\n * `PublishResult` per relay. Default timeout 5000ms.\n */\nexport async function publishEvent(\n    event: NostrEvent,\n    relays: readonly string[] = DEFAULT_RELAYS,\n    timeoutMs = 5000\n): Promise<PublishResult[]> {\n    const retry: RetryOptions = { ...DEFAULT_RETRY, timeoutMs };\n    return Promise.all(relays.map((r) => publishOne(r, event, retry)));\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Query — REQ → EOSE → close. Races all relays; first to EOSE wins.\n// ─────────────────────────────────────────────────────────────────────────\n\n/**\n * Issue a NIP-01 REQ across all `relays` in parallel. Returns deduplicated\n * events sorted newest-first plus per-relay status.\n *\n * Default timeout 1500ms — short enough that a momentary blip on any one\n * relay (including relay.ochk.io) never holds up the racing reads. Pass an\n * explicit `timeoutMs` for slow filters or for use cases where waiting on\n * the slowest relay matters.\n */\nexport async function queryEvents(\n    filter: Filter,\n    relays: readonly string[] = DEFAULT_RELAYS,\n    timeoutMs = 1500\n): Promise<QueryResult> {\n    const subId = 'ocnc-' + Math.random().toString(36).slice(2, 10);\n    const byId = new Map<string, NostrEvent>();\n    const status: QueryResult['relayStatus'] = [];\n\n    await Promise.all(\n        relays.map(\n            (url) =>\n                new Promise<void>((resolve) => {\n                    let settled = false;\n                    let count = 0;\n                    let reason: string | undefined;\n                    let ws: WebSocket | null = null;\n                    const timer = setTimeout(() => {\n                        if (settled) return;\n                        settled = true;\n                        try {\n                            ws?.close();\n                        } catch {}\n                        status.push({\n                            relay: url,\n                            ok: count > 0,\n                            reason: reason ?? 'timeout',\n                            events: count,\n                        });\n                        resolve();\n                    }, timeoutMs);\n                    try {\n                        ws = new WebSocket(url);\n                        ws.onopen = () => ws?.send(JSON.stringify(['REQ', subId, filter]));\n                        ws.onmessage = (msg) => {\n                            const frame = parseFrame(msg.data as string);\n                            if (!frame) return;\n                            if (frame.type === 'EVENT' && frame.payload[0] === subId) {\n                                const event = frame.payload[1] as NostrEvent | undefined;\n                                if (event && event.id) {\n                                    byId.set(event.id, event);\n                                    count++;\n                                }\n                            } else if (frame.type === 'EOSE' && frame.payload[0] === subId) {\n                                if (settled) return;\n                                settled = true;\n                                clearTimeout(timer);\n                                try {\n                                    ws?.send(JSON.stringify(['CLOSE', subId]));\n                                    ws?.close();\n                                } catch {}\n                                status.push({ relay: url, ok: true, events: count });\n                                resolve();\n                            } else if (frame.type === 'NOTICE') {\n                                reason = String(frame.payload[0] ?? 'notice');\n                            }\n                        };\n                        ws.onerror = () => {\n                            if (settled) return;\n                            settled = true;\n                            clearTimeout(timer);\n                            status.push({\n                                relay: url,\n                                ok: false,\n                                reason: 'ws_error',\n                                events: count,\n                            });\n                            resolve();\n                        };\n                        ws.onclose = () => {\n                            if (settled) return;\n                            settled = true;\n                            clearTimeout(timer);\n                            status.push({\n                                relay: url,\n                                ok: count > 0,\n                                reason: reason ?? 'closed_early',\n                                events: count,\n                            });\n                            resolve();\n                        };\n                    } catch (err) {\n                        if (settled) return;\n                        settled = true;\n                        clearTimeout(timer);\n                        status.push({\n                            relay: url,\n                            ok: false,\n                            reason: err instanceof Error ? err.message : 'unknown',\n                            events: count,\n                        });\n                        resolve();\n                    }\n                })\n        )\n    );\n\n    return {\n        events: Array.from(byId.values()).sort((a, b) => b.created_at - a.created_at),\n        relayStatus: status,\n    };\n}\n"]}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@orangecheck/nostr-core",
+  "version": "0.1.0",
+  "description": "Browser-compatible Nostr client used by every OrangeCheck family web app. Raw NIP-01 over WebSocket against a list of relays. publishEvent / queryEvents / DEFAULT_RELAYS.",
+  "keywords": [
+    "nostr",
+    "nip-01",
+    "websocket",
+    "relay",
+    "orangecheck"
+  ],
+  "author": "OrangeCheck",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/orangecheck/oc-packages.git",
+    "directory": "nostr-core"
+  },
+  "homepage": "https://github.com/orangecheck/oc-packages/tree/main/nostr-core",
+  "bugs": {
+    "url": "https://github.com/orangecheck/oc-packages/issues"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,393 @@
+/**
+ * @orangecheck/nostr-core
+ *
+ * Browser-compatible Nostr client used by every OrangeCheck family web
+ * app. Raw NIP-01 over WebSocket against a list of relays. Every operation
+ * races all relays in parallel and reports per-relay status so the caller
+ * can distinguish "nobody replied" from "one relay rejected." Retries with
+ * exponential backoff on transport errors only.
+ *
+ * No dependencies — uses the platform `WebSocket` global. Works in any
+ * runtime that ships a WHATWG WebSocket (browser, Node 22+, Deno, Bun,
+ * Cloudflare Workers).
+ *
+ * Source-of-truth `DEFAULT_RELAYS` for the OC family. Co-publishes to four
+ * public relays plus `wss://relay.ochk.io` (the family's first-party
+ * kind-allowlisted relay — see https://github.com/orangecheck/oc-relay-infra).
+ *
+ * **Hard invariant:** `DEFAULT_RELAYS` MUST contain at least two entries,
+ * and MUST NOT be `relay.ochk.io` alone. Enforced at the type level — a
+ * future engineer simplifying to ours-only fails `tsc`. See `_validate`
+ * below.
+ */
+
+// ─────────────────────────────────────────────────────────────────────────
+// Build-time invariants + default relay set.
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Family-relay invariants applied to `DEFAULT_RELAYS`. The relay set must:
+ *   1. Contain at least two relays — single-relay defaults are always wrong
+ *      because the family's BYPASS principle requires public-relay co-publish.
+ *   2. Not be `wss://relay.ochk.io` alone — relay.ochk.io is additive, never
+ *      a single point of failure. See oc-relay-infra/BYPASS.md.
+ *
+ * If `T` violates either rule, this resolves to `never` and the assignment
+ * below fails at `tsc` time.
+ */
+type ValidRelaySet<T extends readonly string[]> =
+    T['length'] extends 0 | 1 ? never :
+    T extends readonly ['wss://relay.ochk.io'] ? never :
+    T;
+
+const _RELAYS: ValidRelaySet<readonly [
+    'wss://relay.nostr.band',
+    'wss://nos.lol',
+    'wss://relay.primal.net',
+    'wss://offchain.pub',
+    'wss://relay.ochk.io',
+]> = [
+    'wss://relay.nostr.band',
+    'wss://nos.lol',
+    'wss://relay.primal.net',
+    'wss://offchain.pub',
+    // First-party family relay — kind allowlist 30078–30086 + canonical
+    // OC d-tag prefixes. Always co-published with public relays; never
+    // the only copy. See https://github.com/orangecheck/oc-relay-infra.
+    'wss://relay.ochk.io',
+] as const;
+
+/**
+ * Default relay set for OrangeCheck family Nostr publishes + queries.
+ *
+ * Frozen at runtime; consumers MAY pass an explicit `relays` arg to any
+ * function in this package to override.
+ */
+export const DEFAULT_RELAYS: readonly string[] = Object.freeze([..._RELAYS]);
+
+// ─────────────────────────────────────────────────────────────────────────
+// Wire types — NIP-01 event + filter + result shapes.
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface NostrEvent {
+    id: string;
+    kind: number;
+    pubkey: string;
+    created_at: number;
+    content: string;
+    tags: string[][];
+    sig: string;
+}
+
+export interface PublishResult {
+    relay: string;
+    ok: boolean;
+    reason?: string;
+    attempts: number;
+}
+
+export interface Filter {
+    kinds?: number[];
+    authors?: string[];
+    ids?: string[];
+    limit?: number;
+    since?: number;
+    until?: number;
+    /** NIP-12 indexable `d`-tag filter. */
+    '#d'?: string[];
+    /** NIP-12 indexable single-letter tag filter. */
+    '#t'?: string[];
+    /** Used by OC Vote (kind 30081 ballots). */
+    '#poll_id'?: string[];
+    /** Used by OC Vote (kind 30081 ballots). */
+    '#voter'?: string[];
+    /** Used by OC Vote (kind 30080 polls). */
+    '#creator'?: string[];
+    /** Other indexable single-letter tags clients may filter on. */
+    [key: `#${string}`]: string[] | undefined;
+}
+
+export interface QueryResult {
+    events: NostrEvent[];
+    relayStatus: { relay: string; ok: boolean; reason?: string; events: number }[];
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Internal — frame parsing + retry config.
+// ─────────────────────────────────────────────────────────────────────────
+
+type FrameType = 'OK' | 'EVENT' | 'EOSE' | 'NOTICE' | 'CLOSED';
+interface RelayFrame {
+    type: FrameType;
+    payload: unknown[];
+}
+
+function parseFrame(raw: string): RelayFrame | null {
+    try {
+        const arr = JSON.parse(raw) as unknown[];
+        if (!Array.isArray(arr) || arr.length === 0) return null;
+        const type = arr[0];
+        if (
+            type === 'OK' ||
+            type === 'EVENT' ||
+            type === 'EOSE' ||
+            type === 'NOTICE' ||
+            type === 'CLOSED'
+        ) {
+            return { type: type as FrameType, payload: arr.slice(1) };
+        }
+        return null;
+    } catch {
+        return null;
+    }
+}
+
+interface RetryOptions {
+    attempts: number;
+    timeoutMs: number;
+    initialBackoffMs: number;
+    maxBackoffMs: number;
+}
+
+const DEFAULT_RETRY: RetryOptions = {
+    attempts: 3,
+    timeoutMs: 5000,
+    initialBackoffMs: 500,
+    maxBackoffMs: 4000,
+};
+
+function delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Publish — write an event to one or more relays in parallel, with retry.
+// ─────────────────────────────────────────────────────────────────────────
+
+async function publishOne(
+    url: string,
+    event: NostrEvent,
+    retry: RetryOptions
+): Promise<PublishResult> {
+    let attempts = 0;
+    let backoff = retry.initialBackoffMs;
+    let lastReason: string | undefined;
+
+    while (attempts < retry.attempts) {
+        attempts++;
+        const attempt = await attemptPublish(url, event, retry.timeoutMs);
+        if (attempt.ok) {
+            return {
+                relay: url,
+                ok: true,
+                attempts,
+                ...(attempt.reason ? { reason: attempt.reason } : {}),
+            };
+        }
+        lastReason = attempt.reason;
+        if (attempt.retryable && attempts < retry.attempts) {
+            await delay(backoff);
+            backoff = Math.min(backoff * 2, retry.maxBackoffMs);
+            continue;
+        }
+        break;
+    }
+    return {
+        relay: url,
+        ok: false,
+        attempts,
+        ...(lastReason ? { reason: lastReason } : {}),
+    };
+}
+
+function attemptPublish(
+    url: string,
+    event: NostrEvent,
+    timeoutMs: number
+): Promise<{ ok: boolean; reason?: string; retryable: boolean }> {
+    return new Promise((resolve) => {
+        let settled = false;
+        let ws: WebSocket | null = null;
+        const timer = setTimeout(() => {
+            if (settled) return;
+            settled = true;
+            try {
+                ws?.close();
+            } catch {}
+            resolve({ ok: false, reason: 'timeout', retryable: true });
+        }, timeoutMs);
+        try {
+            ws = new WebSocket(url);
+            ws.onopen = () => ws?.send(JSON.stringify(['EVENT', event]));
+            ws.onmessage = (msg) => {
+                const frame = parseFrame(msg.data as string);
+                if (!frame) return;
+                if (frame.type === 'OK' && frame.payload[0] === event.id) {
+                    if (settled) return;
+                    settled = true;
+                    clearTimeout(timer);
+                    try {
+                        ws?.close();
+                    } catch {}
+                    const ok = frame.payload[1] === true;
+                    const reason = frame.payload[2] as string | undefined;
+                    resolve({
+                        ok,
+                        ...(reason ? { reason } : {}),
+                        retryable: false,
+                    });
+                }
+            };
+            ws.onerror = () => {
+                if (settled) return;
+                settled = true;
+                clearTimeout(timer);
+                resolve({ ok: false, reason: 'websocket_error', retryable: true });
+            };
+            ws.onclose = () => {
+                if (settled) return;
+                settled = true;
+                clearTimeout(timer);
+                resolve({ ok: false, reason: 'closed_early', retryable: true });
+            };
+        } catch (err) {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({
+                ok: false,
+                reason: err instanceof Error ? err.message : 'unknown',
+                retryable: true,
+            });
+        }
+    });
+}
+
+/**
+ * Publish a NIP-01 event to all `relays` in parallel. Returns one
+ * `PublishResult` per relay. Default timeout 5000ms.
+ */
+export async function publishEvent(
+    event: NostrEvent,
+    relays: readonly string[] = DEFAULT_RELAYS,
+    timeoutMs = 5000
+): Promise<PublishResult[]> {
+    const retry: RetryOptions = { ...DEFAULT_RETRY, timeoutMs };
+    return Promise.all(relays.map((r) => publishOne(r, event, retry)));
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Query — REQ → EOSE → close. Races all relays; first to EOSE wins.
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Issue a NIP-01 REQ across all `relays` in parallel. Returns deduplicated
+ * events sorted newest-first plus per-relay status.
+ *
+ * Default timeout 1500ms — short enough that a momentary blip on any one
+ * relay (including relay.ochk.io) never holds up the racing reads. Pass an
+ * explicit `timeoutMs` for slow filters or for use cases where waiting on
+ * the slowest relay matters.
+ */
+export async function queryEvents(
+    filter: Filter,
+    relays: readonly string[] = DEFAULT_RELAYS,
+    timeoutMs = 1500
+): Promise<QueryResult> {
+    const subId = 'ocnc-' + Math.random().toString(36).slice(2, 10);
+    const byId = new Map<string, NostrEvent>();
+    const status: QueryResult['relayStatus'] = [];
+
+    await Promise.all(
+        relays.map(
+            (url) =>
+                new Promise<void>((resolve) => {
+                    let settled = false;
+                    let count = 0;
+                    let reason: string | undefined;
+                    let ws: WebSocket | null = null;
+                    const timer = setTimeout(() => {
+                        if (settled) return;
+                        settled = true;
+                        try {
+                            ws?.close();
+                        } catch {}
+                        status.push({
+                            relay: url,
+                            ok: count > 0,
+                            reason: reason ?? 'timeout',
+                            events: count,
+                        });
+                        resolve();
+                    }, timeoutMs);
+                    try {
+                        ws = new WebSocket(url);
+                        ws.onopen = () => ws?.send(JSON.stringify(['REQ', subId, filter]));
+                        ws.onmessage = (msg) => {
+                            const frame = parseFrame(msg.data as string);
+                            if (!frame) return;
+                            if (frame.type === 'EVENT' && frame.payload[0] === subId) {
+                                const event = frame.payload[1] as NostrEvent | undefined;
+                                if (event && event.id) {
+                                    byId.set(event.id, event);
+                                    count++;
+                                }
+                            } else if (frame.type === 'EOSE' && frame.payload[0] === subId) {
+                                if (settled) return;
+                                settled = true;
+                                clearTimeout(timer);
+                                try {
+                                    ws?.send(JSON.stringify(['CLOSE', subId]));
+                                    ws?.close();
+                                } catch {}
+                                status.push({ relay: url, ok: true, events: count });
+                                resolve();
+                            } else if (frame.type === 'NOTICE') {
+                                reason = String(frame.payload[0] ?? 'notice');
+                            }
+                        };
+                        ws.onerror = () => {
+                            if (settled) return;
+                            settled = true;
+                            clearTimeout(timer);
+                            status.push({
+                                relay: url,
+                                ok: false,
+                                reason: 'ws_error',
+                                events: count,
+                            });
+                            resolve();
+                        };
+                        ws.onclose = () => {
+                            if (settled) return;
+                            settled = true;
+                            clearTimeout(timer);
+                            status.push({
+                                relay: url,
+                                ok: count > 0,
+                                reason: reason ?? 'closed_early',
+                                events: count,
+                            });
+                            resolve();
+                        };
+                    } catch (err) {
+                        if (settled) return;
+                        settled = true;
+                        clearTimeout(timer);
+                        status.push({
+                            relay: url,
+                            ok: false,
+                            reason: err instanceof Error ? err.message : 'unknown',
+                            events: count,
+                        });
+                        resolve();
+                    }
+                })
+        )
+    );
+
+    return {
+        events: Array.from(byId.values()).sort((a, b) => b.created_at - a.created_at),
+        relayStatus: status,
+    };
+}