@nostrwatch/kuma 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Sandwich Farm LLC
+
+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,150 @@
+# @nostrwatch/kuma
+
+Uptime Kuma PUSH monitor for Nostr relays.
+
+[![npm version](https://img.shields.io/npm/v/@nostrwatch/kuma?style=flat-square&label=npm)](https://www.npmjs.com/package/@nostrwatch/kuma)
+[![License](https://img.shields.io/github/license/sandwichfarm/nostr-watch?style=flat-square)](LICENSE)
+[![Status](https://img.shields.io/badge/status-alpha-orange?style=flat-square)](https://github.com/sandwichfarm/nostr-watch)
+[![Runtime](https://img.shields.io/badge/runtime-cli-blue?style=flat-square)](https://github.com/sandwichfarm/nostr-watch)
+
+## Overview
+
+`@nostrwatch/kuma` integrates Nostr relay (a WebSocket server that stores and forwards events) health checks with [Uptime Kuma](https://github.com/louislam/uptime-kuma) push monitors. It runs `open`, `read`, and optional `write` checks against a relay using the `@nostrwatch/nocap` WebSocket adapter, then pushes the result — status (`up` or `down`) and latency — to an Uptime Kuma push URL. Available as both a CLI tool and a TypeScript library.
+
+## Prerequisites
+
+Node.js >=18 and pnpm >=9.
+
+An Uptime Kuma instance with a configured push-type monitor. The push URL looks like `https://kuma.example.com/api/push/<key>`.
+
+## Installation
+
+```sh
+pnpm add @nostrwatch/kuma
+```
+
+Or with npm:
+
+```sh
+npm install @nostrwatch/kuma
+```
+
+## Quick Start
+
+Run a one-shot check via CLI:
+
+```sh
+npx nostrwatch-kuma \
+  --relay wss://relay.damus.io \
+  --push-url https://kuma.example.com/api/push/abc123 \
+  --once
+```
+
+Or use the library API:
+
+```ts
+import {runOnce} from '@nostrwatch/kuma'
+
+await runOnce({
+  relayUrl: 'wss://relay.damus.io',
+  pushUrl: 'https://kuma.example.com/api/push/abc123',
+  checks: ['open', 'read']
+})
+// Checks the relay and pushes status=up/down + ping to Uptime Kuma
+```
+
+## API
+
+### Library API
+
+#### `runChecks(options)`
+
+```ts
+async function runChecks(options: KumaMonitorOptions): Promise<CheckResultSummary>
+```
+
+Runs nocap relay checks and returns a summary without pushing to Uptime Kuma. Use this to inspect results before deciding whether to push.
+
+#### `runOnce(options)`
+
+```ts
+async function runOnce(options: KumaMonitorOptions): Promise<void>
+```
+
+Runs checks and pushes the result to Uptime Kuma once. Resolves when the push completes. Rejects if the push request fails.
+
+#### `runForever(options)`
+
+```ts
+async function runForever(options: KumaMonitorOptions): Promise<() => void>
+```
+
+Runs checks and pushes on a repeating interval. Returns a `stop` function that halts the loop when called. The first check runs immediately.
+
+#### `buildKumaPayload(summary, strategy?)`
+
+```ts
+function buildKumaPayload(summary: CheckResultSummary, strategy?: PingStrategy): KumaPushPayload
+```
+
+Converts a `CheckResultSummary` to a `KumaPushPayload`. Exposed for custom push implementations.
+
+### `KumaMonitorOptions`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `relayUrl` | `string` | — | WebSocket URL of the relay to check |
+| `pushUrl` | `string` | — | Full Uptime Kuma push URL |
+| `checks` | `CheckKey[]` | `['open','read']` | Which checks to run: `'open'`, `'read'`, `'write'` |
+| `requiredChecks` | `CheckKey[]` | same as `checks` | Checks that must pass for status to be `up` |
+| `pingStrategy` | `'sum' \| 'max'` | `'sum'` | How to aggregate check durations into ping value |
+| `intervalMs` | `number` | `60000` | Loop interval for `runForever` in milliseconds |
+| `nocap` | `Partial<NocapConfig>` | — | Pass-through config for `@nostrwatch/nocap` |
+| `headers` | `boolean` | `true` | Include HTTP headers in nocap result |
+
+### `CheckResultSummary`
+
+```ts
+interface CheckResultSummary {
+  ok: boolean
+  failing: CheckKey[]
+  result: any
+  durations: Partial<Record<CheckKey, number>>
+}
+```
+
+`ok` is `true` only when all `requiredChecks` pass. `durations` contains per-check millisecond timings.
+
+### CLI Reference
+
+```sh
+nostrwatch-kuma [options]
+
+Options:
+  --relay <url>             Relay WebSocket URL (or RELAY_URL env var)
+  --push-url <url>          Uptime Kuma push URL (or KUMA_PUSH_URL env var)
+  --checks <list>           Comma-separated: open,read[,write] (default: open,read)
+  --once                    Run once and exit (or KUMA_ONCE=true)
+  --interval <ms>           Loop interval in milliseconds (default: 60000)
+  --log-level <level>       Nocap log level: debug, info, warn (or NOCAP_LOG_LEVEL)
+  --write-sample-json <json> JSON event for write check (or NOCAP_WRITE_SAMPLE_JSON)
+```
+
+Environment variables: `RELAY_URL`, `KUMA_PUSH_URL`, `CHECKS`, `KUMA_ONCE`, `KUMA_INTERVAL_MS`, `NOCAP_LOG_LEVEL`, `NOCAP_WRITE_SAMPLE_JSON`.
+
+## Known Limitations
+
+No known limitations at this time.
+
+## Agent Skills
+
+No agent skills defined yet for this package.
+
+## Related Packages
+
+- [`@nostrwatch/nocap`](../nocap/README.md) — relay check engine that `kuma` uses internally for open/read/write checks
+- [`@nostrwatch/nocap-websocket-adapter-default`](../websocket/README.md) — default WebSocket adapter used by `nocap`
+
+## License
+
+[MIT](../../LICENSE)

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { runOnce, runForever } from './index.js';
+function parseArgs(argv) {
+    const args = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith('--'))
+            continue;
+        const key = a.slice(2);
+        const next = argv[i + 1];
+        if (next && !next.startsWith('--')) {
+            args[key] = next;
+            i++;
+        }
+        else {
+            args[key] = true;
+        }
+    }
+    return args;
+}
+function asChecks(value) {
+    if (!value || typeof value !== 'string')
+        return undefined;
+    return value.split(',').map(s => s.trim()).filter(Boolean);
+}
+function asNumber(value) {
+    if (!value || typeof value !== 'string')
+        return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const a = parseArgs(argv);
+    const relayUrl = a.relay || (process.env.RELAY_URL ?? '');
+    const pushUrl = a['push-url'] || (process.env.KUMA_PUSH_URL ?? '');
+    const checks = asChecks(a.checks) || (process.env.CHECKS ? asChecks(process.env.CHECKS) : undefined);
+    const includeWrite = a.write === true || process.env.CHECK_WRITE === 'true';
+    const once = a.once === true || process.env.KUMA_ONCE === 'true';
+    const intervalMs = asNumber(a.interval) ?? (process.env.KUMA_INTERVAL_MS ? Number(process.env.KUMA_INTERVAL_MS) : undefined);
+    const logLevel = a['log-level'] || process.env.NOCAP_LOG_LEVEL;
+    if (!relayUrl || !pushUrl) {
+        console.error('Usage: nostrwatch-kuma --relay <wss://relay> --push-url <https://kuma/api/push/<key>> [--checks open,read[,write]] [--once] [--interval 60000] [--log-level debug] [--write-sample-json <json>]');
+        process.exit(2);
+    }
+    const opts = {
+        relayUrl,
+        pushUrl,
+        checks: checks ?? (includeWrite ? ['open', 'read', 'write'] : ['open', 'read']),
+        requiredChecks: undefined, // default = checks
+        nocap: {
+            logLevel: logLevel || 'info',
+        },
+        headers: true,
+        once,
+        intervalMs: intervalMs ?? 60000,
+    };
+    const writeSample = a['write-sample-json'] || process.env.NOCAP_WRITE_SAMPLE_JSON;
+    if (writeSample) {
+        try {
+            opts.nocap = opts.nocap || {};
+            opts.nocap.event_sample = JSON.parse(writeSample);
+        }
+        catch (e) {
+            console.warn('Ignoring invalid --write-sample-json (must be valid JSON)');
+        }
+    }
+    if (opts.once) {
+        await runOnce(opts);
+    }
+    else {
+        await runForever(opts);
+    }
+}
+main().catch(err => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import { KumaMonitorOptions, CheckKey, CheckResultSummary, KumaPushPayload, PingStrategy } from './types.js';
+export declare function normalizeChecks(input?: CheckKey[]): CheckKey[];
+export declare function aggregatePing(durations: Partial<Record<CheckKey, number>>, strategy?: PingStrategy): number;
+export declare function summarizeResult(result: any, checks: CheckKey[], requiredChecks?: CheckKey[]): CheckResultSummary;
+export declare function runChecks(options: KumaMonitorOptions): Promise<CheckResultSummary>;
+export declare function buildKumaPayload(summary: CheckResultSummary, strategy?: PingStrategy): KumaPushPayload;
+export declare function appendQuery(url: string, params: Record<string, string | number | undefined>): string;
+export declare function pushToKuma(pushUrl: string, payload: KumaPushPayload): Promise<void>;
+export declare function runOnce(options: KumaMonitorOptions): Promise<void>;
+export declare function runForever(options: KumaMonitorOptions): Promise<() => void>;
+declare const _default: {
+    runChecks: typeof runChecks;
+    runOnce: typeof runOnce;
+    runForever: typeof runForever;
+    buildKumaPayload: typeof buildKumaPayload;
+    pushToKuma: typeof pushToKuma;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,143 @@
+import Nocap from '@nostrwatch/nocap';
+import WebsocketAdapterDefault from '@nostrwatch/nocap-websocket-adapter-default';
+// Simple, dependency-free URL fetch wrapper supporting Node >=18 and Deno
+async function httpGet(url) {
+    // Global fetch in Node >= 18 and Deno
+    if (typeof fetch === 'function')
+        return fetch(url);
+    // Lazy import fallback if needed (should not usually happen in this monorepo)
+    const { default: nodeFetch } = await import('node-fetch');
+    return nodeFetch(url);
+}
+export function normalizeChecks(input) {
+    if (!input || input.length === 0)
+        return ['open', 'read'];
+    // Remove duplicates and keep order
+    const seen = new Set();
+    const out = [];
+    for (const k of input) {
+        if (!seen.has(k)) {
+            seen.add(k);
+            out.push(k);
+        }
+    }
+    return out;
+}
+export function aggregatePing(durations, strategy = 'sum') {
+    const vals = Object.values(durations).filter((v) => typeof v === 'number' && v >= 0);
+    if (vals.length === 0)
+        return -1;
+    if (strategy === 'max')
+        return Math.max(...vals);
+    return vals.reduce((a, b) => a + b, 0);
+}
+export function summarizeResult(result, checks, requiredChecks) {
+    const durations = {};
+    const failing = [];
+    for (const k of checks) {
+        const data = (result?.[k]?.data ?? result?.[k]);
+        const dkey = `${k}_duration`;
+        const dur = typeof result?.[dkey] === 'number' ? result[dkey] : result?.[k]?.duration;
+        if (typeof dur === 'number')
+            durations[k] = dur;
+        if (data !== true)
+            failing.push(k);
+    }
+    const req = new Set((requiredChecks && requiredChecks.length ? requiredChecks : checks));
+    const requiredFailed = failing.filter(f => req.has(f));
+    const ok = requiredFailed.length === 0;
+    return { ok, failing: requiredFailed, result, durations };
+}
+export async function runChecks(options) {
+    const checks = normalizeChecks(options.checks);
+    const required = normalizeChecks(options.requiredChecks ?? checks);
+    const nocapCfg = options.nocap ?? {};
+    if (!nocapCfg.checked_by)
+        nocapCfg.checked_by = '@nostrwatch/kuma';
+    const nc = new Nocap(options.relayUrl, nocapCfg);
+    await nc.useAdapter(WebsocketAdapterDefault);
+    // nocap always terminates websocket unless configured otherwise
+    const headers = options.headers ?? true;
+    const raw = await nc.check(checks, headers);
+    return summarizeResult(raw, checks, required);
+}
+export function buildKumaPayload(summary, strategy = 'sum') {
+    const status = summary.ok ? 'up' : 'down';
+    const ping = aggregatePing(summary.durations, strategy);
+    let msg;
+    if (summary.ok) {
+        // show durations for visibility
+        const parts = Object.entries(summary.durations)
+            .map(([k, v]) => `${k}=${v}ms`)
+            .join(', ');
+        msg = parts ? `OK (${parts})` : 'OK';
+    }
+    else {
+        msg = `Fail: ${summary.failing.join(', ')}`;
+    }
+    const payload = { status, msg };
+    if (ping >= 0)
+        payload.ping = ping;
+    return payload;
+}
+export function appendQuery(url, params) {
+    const u = new URL(url);
+    for (const [k, v] of Object.entries(params)) {
+        if (v === undefined)
+            continue;
+        u.searchParams.set(k, String(v));
+    }
+    return u.toString();
+}
+export async function pushToKuma(pushUrl, payload) {
+    const finalUrl = appendQuery(pushUrl, {
+        status: payload.status,
+        msg: payload.msg ?? '',
+        ping: payload.ping ?? undefined,
+    });
+    const res = await httpGet(finalUrl);
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`Kuma push failed: ${res.status} ${res.statusText} ${text}`);
+    }
+}
+export async function runOnce(options) {
+    const summary = await runChecks(options);
+    const payload = buildKumaPayload(summary, options.pingStrategy ?? 'sum');
+    await pushToKuma(options.pushUrl, payload);
+}
+export async function runForever(options) {
+    const interval = options.intervalMs ?? 60000; // default 60s
+    let stopped = false;
+    const tick = async () => {
+        if (stopped)
+            return;
+        try {
+            await runOnce(options);
+        }
+        catch (err) {
+            // As a safety net, signal down push if check or push threw synchronously
+            try {
+                const msg = err instanceof Error ? err.message : String(err);
+                await pushToKuma(options.pushUrl, { status: 'down', msg });
+            }
+            catch { }
+        }
+        finally {
+            if (!stopped)
+                setTimeout(tick, interval);
+        }
+    };
+    // Prime immediately
+    void tick();
+    return () => {
+        stopped = true;
+    };
+}
+export default {
+    runChecks,
+    runOnce,
+    runForever,
+    buildKumaPayload,
+    pushToKuma,
+};

package/dist/types.d.ts

@@ -0,0 +1,42 @@
+export type CheckKey = 'open' | 'read' | 'write';
+export type PingStrategy = 'sum' | 'max';
+export interface KumaPushPayload {
+    status: 'up' | 'down' | 'paused';
+    msg?: string;
+    ping?: number;
+}
+export interface KumaMonitorOptions {
+    relayUrl: string;
+    pushUrl: string;
+    checks?: CheckKey[];
+    requiredChecks?: CheckKey[];
+    pingStrategy?: PingStrategy;
+    nocap?: Partial<{
+        logLevel: string;
+        checked_by: string;
+        timeout: Partial<{
+            open: number;
+            read: number;
+            write: number;
+        }>;
+        tooManyEventsLimit: number;
+        autoDepsIgnoredInResult: boolean;
+        removeFromResult: string[];
+        failAllChecksOnConnectFailure: boolean;
+        rejectOnConnectFailure: boolean;
+        websocketAlwaysTerminate: boolean;
+        event_sample: any;
+        adapterOptions: Partial<{
+            websocket: Record<string, any>;
+        }>;
+    }>;
+    headers?: boolean;
+    once?: boolean;
+    intervalMs?: number;
+}
+export interface CheckResultSummary {
+    ok: boolean;
+    failing: CheckKey[];
+    result: any;
+    durations: Partial<Record<CheckKey, number>>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@nostrwatch/kuma",
+  "version": "0.1.0",
+  "description": "Uptime Kuma PUSH monitor for Nostr relays using @nostrwatch/nocap (websocket adapter).",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./cli": {
+      "import": "./dist/cli.js",
+      "types": "./dist/cli.d.ts"
+    }
+  },
+  "bin": {
+    "nostrwatch-kuma": "dist/cli.js"
+  },
+  "dependencies": {
+    "@nostrwatch/nocap": "^0.9.1",
+    "@nostrwatch/nocap-websocket-adapter-default": "^1.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.30",
+    "node-fetch": "^3.3.2",
+    "typescript": "^5.6.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -w -p tsconfig.json",
+    "bun:compile": "bun build --compile ./src/cli.ts --outfile ./dist/nostrwatch-kuma",
+    "build:bin:bun": "pnpm build && pnpm bun:compile"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import { runOnce, runForever } from './index.js';
+import type { CheckKey, KumaMonitorOptions } from './types.js';
+
+function parseArgs(argv: string[]): Record<string, string | boolean> {
+  const args: Record<string, string | boolean> = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) continue;
+    const key = a.slice(2);
+    const next = argv[i + 1];
+    if (next && !next.startsWith('--')) {
+      args[key] = next;
+      i++;
+    } else {
+      args[key] = true;
+    }
+  }
+  return args;
+}
+
+function asChecks(value?: string | boolean): CheckKey[] | undefined {
+  if (!value || typeof value !== 'string') return undefined;
+  return value.split(',').map(s => s.trim()).filter(Boolean) as CheckKey[];
+}
+
+function asNumber(value?: string | boolean): number | undefined {
+  if (!value || typeof value !== 'string') return undefined;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const a = parseArgs(argv);
+
+  const relayUrl = (a.relay as string) || (process.env.RELAY_URL ?? '');
+  const pushUrl = (a['push-url'] as string) || (process.env.KUMA_PUSH_URL ?? '');
+  const checks = asChecks(a.checks) || (process.env.CHECKS ? asChecks(process.env.CHECKS) : undefined);
+  const includeWrite = a.write === true || process.env.CHECK_WRITE === 'true';
+  const once = a.once === true || process.env.KUMA_ONCE === 'true';
+  const intervalMs = asNumber(a.interval) ?? (process.env.KUMA_INTERVAL_MS ? Number(process.env.KUMA_INTERVAL_MS) : undefined);
+  const logLevel = (a['log-level'] as string) || process.env.NOCAP_LOG_LEVEL;
+
+  if (!relayUrl || !pushUrl) {
+    console.error('Usage: nostrwatch-kuma --relay <wss://relay> --push-url <https://kuma/api/push/<key>> [--checks open,read[,write]] [--once] [--interval 60000] [--log-level debug] [--write-sample-json <json>]');
+    process.exit(2);
+  }
+
+  const opts: KumaMonitorOptions = {
+    relayUrl,
+    pushUrl,
+    checks: checks ?? (includeWrite ? ['open', 'read', 'write'] : ['open', 'read']),
+    requiredChecks: undefined, // default = checks
+    nocap: {
+      logLevel: logLevel || 'info',
+    },
+    headers: true,
+    once,
+    intervalMs: intervalMs ?? 60000,
+  };
+
+  const writeSample = (a['write-sample-json'] as string) || process.env.NOCAP_WRITE_SAMPLE_JSON;
+  if (writeSample) {
+    try {
+      opts.nocap = opts.nocap || {};
+      opts.nocap.event_sample = JSON.parse(writeSample);
+    } catch (e) {
+      console.warn('Ignoring invalid --write-sample-json (must be valid JSON)');
+    }
+  }
+
+  if (opts.once) {
+    await runOnce(opts);
+  } else {
+    await runForever(opts);
+  }
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});
+

package/src/index.ts

@@ -0,0 +1,149 @@
+import Nocap from '@nostrwatch/nocap';
+import WebsocketAdapterDefault from '@nostrwatch/nocap-websocket-adapter-default';
+import { KumaMonitorOptions, CheckKey, CheckResultSummary, KumaPushPayload, PingStrategy } from './types.js';
+
+// Simple, dependency-free URL fetch wrapper supporting Node >=18 and Deno
+async function httpGet(url: string): Promise<Response> {
+  // Global fetch in Node >= 18 and Deno
+  if (typeof fetch === 'function') return fetch(url);
+  // Lazy import fallback if needed (should not usually happen in this monorepo)
+  const { default: nodeFetch } = await import('node-fetch');
+  return nodeFetch(url) as unknown as Response;
+}
+
+export function normalizeChecks(input?: CheckKey[]): CheckKey[] {
+  if (!input || input.length === 0) return ['open', 'read'];
+  // Remove duplicates and keep order
+  const seen = new Set<CheckKey>();
+  const out: CheckKey[] = [];
+  for (const k of input) {
+    if (!seen.has(k)) {
+      seen.add(k);
+      out.push(k);
+    }
+  }
+  return out;
+}
+
+export function aggregatePing(durations: Partial<Record<CheckKey, number>>, strategy: PingStrategy = 'sum'): number {
+  const vals = Object.values(durations).filter((v): v is number => typeof v === 'number' && v >= 0);
+  if (vals.length === 0) return -1;
+  if (strategy === 'max') return Math.max(...vals);
+  return vals.reduce((a, b) => a + b, 0);
+}
+
+export function summarizeResult(result: any, checks: CheckKey[], requiredChecks?: CheckKey[]): CheckResultSummary {
+  const durations: Partial<Record<CheckKey, number>> = {};
+  const failing: CheckKey[] = [];
+  for (const k of checks) {
+    const data = (result?.[k]?.data ?? result?.[k]);
+    const dkey = `${k}_duration` as const;
+    const dur = typeof result?.[dkey] === 'number' ? result[dkey] : result?.[k]?.duration;
+    if (typeof dur === 'number') durations[k] = dur;
+    if (data !== true) failing.push(k);
+  }
+  const req = new Set<CheckKey>((requiredChecks && requiredChecks.length ? requiredChecks : checks));
+  const requiredFailed = failing.filter(f => req.has(f));
+  const ok = requiredFailed.length === 0;
+  return { ok, failing: requiredFailed, result, durations };
+}
+
+export async function runChecks(options: KumaMonitorOptions): Promise<CheckResultSummary> {
+  const checks = normalizeChecks(options.checks);
+  const required = normalizeChecks(options.requiredChecks ?? checks);
+
+  const nocapCfg: any = options.nocap ?? {};
+  if (!nocapCfg.checked_by) nocapCfg.checked_by = '@nostrwatch/kuma';
+
+  const nc = new Nocap(options.relayUrl, nocapCfg);
+  await nc.useAdapter(WebsocketAdapterDefault);
+
+  // nocap always terminates websocket unless configured otherwise
+  const headers = options.headers ?? true;
+  const raw = await nc.check(checks, headers);
+
+  return summarizeResult(raw, checks, required);
+}
+
+export function buildKumaPayload(summary: CheckResultSummary, strategy: PingStrategy = 'sum'): KumaPushPayload {
+  const status: KumaPushPayload['status'] = summary.ok ? 'up' : 'down';
+  const ping = aggregatePing(summary.durations, strategy);
+
+  let msg: string;
+  if (summary.ok) {
+    // show durations for visibility
+    const parts = Object.entries(summary.durations)
+      .map(([k, v]) => `${k}=${v}ms`)
+      .join(', ');
+    msg = parts ? `OK (${parts})` : 'OK';
+  } else {
+    msg = `Fail: ${summary.failing.join(', ')}`;
+  }
+
+  const payload: KumaPushPayload = { status, msg };
+  if (ping >= 0) payload.ping = ping;
+  return payload;
+}
+
+export function appendQuery(url: string, params: Record<string, string | number | undefined>): string {
+  const u = new URL(url);
+  for (const [k, v] of Object.entries(params)) {
+    if (v === undefined) continue;
+    u.searchParams.set(k, String(v));
+  }
+  return u.toString();
+}
+
+export async function pushToKuma(pushUrl: string, payload: KumaPushPayload): Promise<void> {
+  const finalUrl = appendQuery(pushUrl, {
+    status: payload.status,
+    msg: payload.msg ?? '',
+    ping: payload.ping ?? undefined,
+  });
+  const res = await httpGet(finalUrl);
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`Kuma push failed: ${res.status} ${res.statusText} ${text}`);
+  }
+}
+
+export async function runOnce(options: KumaMonitorOptions): Promise<void> {
+  const summary = await runChecks(options);
+  const payload = buildKumaPayload(summary, options.pingStrategy ?? 'sum');
+  await pushToKuma(options.pushUrl, payload);
+}
+
+export async function runForever(options: KumaMonitorOptions): Promise<() => void> {
+  const interval = options.intervalMs ?? 60000; // default 60s
+  let stopped = false;
+
+  const tick = async () => {
+    if (stopped) return;
+    try {
+      await runOnce(options);
+    } catch (err) {
+      // As a safety net, signal down push if check or push threw synchronously
+      try {
+        const msg = err instanceof Error ? err.message : String(err);
+        await pushToKuma(options.pushUrl, { status: 'down', msg });
+      } catch {}
+    } finally {
+      if (!stopped) setTimeout(tick, interval);
+    }
+  };
+
+  // Prime immediately
+  void tick();
+
+  return () => {
+    stopped = true;
+  };
+}
+
+export default {
+  runChecks,
+  runOnce,
+  runForever,
+  buildKumaPayload,
+  pushToKuma,
+};

package/src/types.ts

@@ -0,0 +1,51 @@
+export type CheckKey = 'open' | 'read' | 'write';
+
+export type PingStrategy = 'sum' | 'max';
+
+export interface KumaPushPayload {
+  status: 'up' | 'down' | 'paused';
+  msg?: string;
+  ping?: number;
+}
+
+export interface KumaMonitorOptions {
+  relayUrl: string;
+  pushUrl: string; // Full Uptime Kuma push URL
+  checks?: CheckKey[]; // default: ['open','read']
+  requiredChecks?: CheckKey[]; // default: same as checks
+  pingStrategy?: PingStrategy;
+
+  // nocap passthrough config
+  nocap?: Partial<{
+    logLevel: string;
+    checked_by: string;
+    timeout: Partial<{
+      open: number;
+      read: number;
+      write: number;
+    }>;
+    tooManyEventsLimit: number;
+    autoDepsIgnoredInResult: boolean;
+    removeFromResult: string[];
+    failAllChecksOnConnectFailure: boolean;
+    rejectOnConnectFailure: boolean;
+    websocketAlwaysTerminate: boolean;
+    event_sample: any; // NostrEvent shape; permissive typing here
+    adapterOptions: Partial<{
+      websocket: Record<string, any>;
+    }>;
+  }>;
+
+  // behavior
+  headers?: boolean; // include headers in nocap result
+  once?: boolean; // run once then exit
+  intervalMs?: number; // when not once, run every N ms
+}
+
+export interface CheckResultSummary {
+  ok: boolean;
+  failing: CheckKey[];
+  result: any;
+  durations: Partial<Record<CheckKey, number>>;
+}
+

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "declaration": true,
+    "emitDeclarationOnly": false,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}