sermon-js 0.0.0-stage → 0.2.0

package/dist/types-CctvUAs2.d.cts

@@ -0,0 +1,192 @@
+/** The five statuses every service reports */
+type Status = "up" | "degraded" | "down" | "sleeping" | "unconfigured";
+/** What a check itself can report: "unconfigured" is decided by the library, never by a check */
+type OutcomeStatus = Exclude<Status, "unconfigured">;
+type ScoreLabel = "operational" | "degraded" | "outage" | "unknown";
+/** Small labelled values shown as chips (balance, machine count, VM state…) */
+type Metrics = Record<string, string | number>;
+/** A consumable quota, rendered as a usage bar */
+type Usage = {
+    label: string;
+    used: number;
+    limit: number;
+    unit?: string;
+    /** When the quota resets (ms epoch), if the provider says */
+    resetsAt?: number;
+};
+/** One machine/region of a multi-instance service, tracked individually */
+type Instance = {
+    /** Stable across deploys (e.g. the region, suffixed when a region runs several machines) */
+    key: string;
+    region?: string;
+    /** Platform identifier of the machine/instance */
+    id?: string;
+    /** Raw platform state: started, suspended, RUNNING… */
+    state?: string;
+    status: OutcomeStatus;
+    latencyMs?: number;
+    httpStatus?: number;
+    error?: string;
+};
+/** What a check returns */
+type CheckOutcome = {
+    status: OutcomeStatus;
+    /** Measured for you (wall time of the check) when omitted */
+    latencyMs?: number;
+    httpStatus?: number;
+    /** Shown publicly: secrets are redacted and long text is truncated */
+    error?: string;
+    metrics?: Metrics;
+    usage?: Usage[];
+    instances?: Instance[];
+    /** Set to false when the target was deliberately not touched (e.g. a sleeping machine) */
+    probed?: boolean;
+};
+/** `true`/nothing → up, `false` → down, or a full outcome */
+type CheckReturn = CheckOutcome | boolean | void;
+/** The stored result of one check run */
+type CheckResult = Omit<CheckOutcome, "status" | "probed"> & {
+    key: string;
+    status: Status;
+    checkedAt: number;
+    probed: boolean;
+};
+type HttpInit = RequestInit & {
+    /** Extra statuses that mean "reachable and healthy" besides 2xx/3xx */
+    okStatuses?: number[];
+};
+type HttpResult = {
+    /** 2xx/3xx, or one of `okStatuses` */
+    ok: boolean;
+    /** Undefined when the request never got a response (network error, timeout) */
+    status?: number;
+    latencyMs: number;
+    text: string;
+    /** Parsed body, or undefined when it isn't JSON */
+    json: unknown;
+    headers?: Headers;
+    /** Ready-made outcome: 2xx/3xx up, 429 degraded, anything else down */
+    outcome: CheckOutcome;
+};
+type ProbeHelpers = {
+    /** Timed `fetch` that never throws */
+    http: (url: string, init?: HttpInit) => Promise<HttpResult>;
+    /** Times any async call (SDK, database, TCP…); a throw becomes a down outcome */
+    measure: (fn: () => Promise<CheckReturn>) => Promise<CheckOutcome>;
+    /** Merges several probes of the same service: worst status wins */
+    combine: (outcomes: CheckOutcome[]) => CheckOutcome;
+};
+/** Small key/value cache backed by the store, for checks that keep state between runs */
+type CheckCache = {
+    get: (key: string) => Promise<string | null>;
+    set: (key: string, value: string, ttlMs: number) => Promise<void>;
+};
+type CheckContext<Secrets extends SecretsInput = SecretsInput> = ProbeHelpers & {
+    /** The secrets given to the service; every key is guaranteed non-empty */
+    secrets: {
+        [K in keyof Secrets]-?: string;
+    };
+    /** Aborted when the check's time budget is over */
+    signal: AbortSignal;
+    timeoutMs: number;
+    /** Latency above this turns "up" into "degraded" */
+    slowMs: number;
+    cache: CheckCache;
+    now: number;
+};
+type SecretsInput = Record<string, string | undefined>;
+/** Options shared by every service (the five concerns, minus what the preset defines) */
+type CommonOptions = {
+    /** How to call it */
+    name?: string;
+    description?: string;
+    /** Critical services weigh more in the score, and one being down means "outage" */
+    critical?: boolean;
+    /** Latency above this turns "up" into "degraded" (default 2000) */
+    slowMs?: number;
+    /** Hard cap for one check (default 10000) */
+    timeoutMs?: number;
+};
+/** Per-service statistics computed from history */
+type InstanceStats = {
+    uptime24h: number | null;
+    p50: number | null;
+    samples24h: number;
+};
+type ServiceStats = {
+    /** Share of runs that were not "down", in percent */
+    uptime24h: number | null;
+    uptime7d: number | null;
+    p50: number | null;
+    p95: number | null;
+    samples24h: number;
+    /** Latency series over the last 24h, oldest first (for sparklines) */
+    latency: Array<number | null>;
+    lastFailure?: {
+        at: number;
+        status: Status;
+        error?: string;
+    };
+    instances?: Record<string, InstanceStats>;
+};
+type ServiceSnapshot = {
+    type: "service";
+    /** Derived, internal: only used for anchors, single-service runs and history routes */
+    key: string;
+    /** The preset kind: "custom", "generic.http", "fly.app"… */
+    kind: string;
+    name: string;
+    description?: string;
+    critical: boolean;
+    slowMs: number;
+    configured: boolean;
+    /** Which required secrets/fields are missing when not configured */
+    missing?: string[];
+    result?: CheckResult;
+    stats?: ServiceStats;
+};
+type GroupSnapshot = {
+    type: "group";
+    key: string;
+    title: string;
+    description?: string;
+    children: SnapshotNode[];
+};
+type SnapshotNode = GroupSnapshot | ServiceSnapshot;
+type Trigger = "scheduled" | "manual";
+type StatusSnapshot = {
+    schemaVersion: 1;
+    generatedAt: number;
+    /** Most recent check of any service */
+    lastCheckedAt: number | null;
+    /** Last run of every service, and how it was triggered */
+    lastRunAt: number | null;
+    lastRunTrigger: Trigger | null;
+    /** When the next full run is due, based on `interval` */
+    nextDueAt: number | null;
+    intervalMs: number;
+    /** How long history is kept */
+    retentionMs: number;
+    score: number | null;
+    label: ScoreLabel;
+    counts: Record<Status, number>;
+    tree: SnapshotNode[];
+};
+type HistoryRange = "24h" | "7d";
+type HistoryBar = {
+    start: number;
+    /** Worst score in the bucket; null when no run happened */
+    score: number | null;
+    label: ScoreLabel;
+    runs: number;
+    /** Services that were degraded or down in the bucket ("down" wins) */
+    failing: Record<string, Status>;
+};
+type HistoryPayload = {
+    schemaVersion: 1;
+    range: HistoryRange;
+    bucketMs: number;
+    bars: HistoryBar[];
+};
+
+export type { CheckOutcome as C, GroupSnapshot as G, HistoryRange as H, Instance as I, Metrics as M, OutcomeStatus as O, ProbeHelpers as P, ServiceStats as S, Trigger as T, Usage as U, HistoryBar as a, HttpInit as b, HttpResult as c, CheckReturn as d, CheckCache as e, CheckContext as f, CheckResult as g, CommonOptions as h, HistoryPayload as i, InstanceStats as j, ScoreLabel as k, SecretsInput as l, ServiceSnapshot as m, SnapshotNode as n, Status as o, StatusSnapshot as p };

package/dist/types-CctvUAs2.d.ts

@@ -0,0 +1,192 @@
+/** The five statuses every service reports */
+type Status = "up" | "degraded" | "down" | "sleeping" | "unconfigured";
+/** What a check itself can report: "unconfigured" is decided by the library, never by a check */
+type OutcomeStatus = Exclude<Status, "unconfigured">;
+type ScoreLabel = "operational" | "degraded" | "outage" | "unknown";
+/** Small labelled values shown as chips (balance, machine count, VM state…) */
+type Metrics = Record<string, string | number>;
+/** A consumable quota, rendered as a usage bar */
+type Usage = {
+    label: string;
+    used: number;
+    limit: number;
+    unit?: string;
+    /** When the quota resets (ms epoch), if the provider says */
+    resetsAt?: number;
+};
+/** One machine/region of a multi-instance service, tracked individually */
+type Instance = {
+    /** Stable across deploys (e.g. the region, suffixed when a region runs several machines) */
+    key: string;
+    region?: string;
+    /** Platform identifier of the machine/instance */
+    id?: string;
+    /** Raw platform state: started, suspended, RUNNING… */
+    state?: string;
+    status: OutcomeStatus;
+    latencyMs?: number;
+    httpStatus?: number;
+    error?: string;
+};
+/** What a check returns */
+type CheckOutcome = {
+    status: OutcomeStatus;
+    /** Measured for you (wall time of the check) when omitted */
+    latencyMs?: number;
+    httpStatus?: number;
+    /** Shown publicly: secrets are redacted and long text is truncated */
+    error?: string;
+    metrics?: Metrics;
+    usage?: Usage[];
+    instances?: Instance[];
+    /** Set to false when the target was deliberately not touched (e.g. a sleeping machine) */
+    probed?: boolean;
+};
+/** `true`/nothing → up, `false` → down, or a full outcome */
+type CheckReturn = CheckOutcome | boolean | void;
+/** The stored result of one check run */
+type CheckResult = Omit<CheckOutcome, "status" | "probed"> & {
+    key: string;
+    status: Status;
+    checkedAt: number;
+    probed: boolean;
+};
+type HttpInit = RequestInit & {
+    /** Extra statuses that mean "reachable and healthy" besides 2xx/3xx */
+    okStatuses?: number[];
+};
+type HttpResult = {
+    /** 2xx/3xx, or one of `okStatuses` */
+    ok: boolean;
+    /** Undefined when the request never got a response (network error, timeout) */
+    status?: number;
+    latencyMs: number;
+    text: string;
+    /** Parsed body, or undefined when it isn't JSON */
+    json: unknown;
+    headers?: Headers;
+    /** Ready-made outcome: 2xx/3xx up, 429 degraded, anything else down */
+    outcome: CheckOutcome;
+};
+type ProbeHelpers = {
+    /** Timed `fetch` that never throws */
+    http: (url: string, init?: HttpInit) => Promise<HttpResult>;
+    /** Times any async call (SDK, database, TCP…); a throw becomes a down outcome */
+    measure: (fn: () => Promise<CheckReturn>) => Promise<CheckOutcome>;
+    /** Merges several probes of the same service: worst status wins */
+    combine: (outcomes: CheckOutcome[]) => CheckOutcome;
+};
+/** Small key/value cache backed by the store, for checks that keep state between runs */
+type CheckCache = {
+    get: (key: string) => Promise<string | null>;
+    set: (key: string, value: string, ttlMs: number) => Promise<void>;
+};
+type CheckContext<Secrets extends SecretsInput = SecretsInput> = ProbeHelpers & {
+    /** The secrets given to the service; every key is guaranteed non-empty */
+    secrets: {
+        [K in keyof Secrets]-?: string;
+    };
+    /** Aborted when the check's time budget is over */
+    signal: AbortSignal;
+    timeoutMs: number;
+    /** Latency above this turns "up" into "degraded" */
+    slowMs: number;
+    cache: CheckCache;
+    now: number;
+};
+type SecretsInput = Record<string, string | undefined>;
+/** Options shared by every service (the five concerns, minus what the preset defines) */
+type CommonOptions = {
+    /** How to call it */
+    name?: string;
+    description?: string;
+    /** Critical services weigh more in the score, and one being down means "outage" */
+    critical?: boolean;
+    /** Latency above this turns "up" into "degraded" (default 2000) */
+    slowMs?: number;
+    /** Hard cap for one check (default 10000) */
+    timeoutMs?: number;
+};
+/** Per-service statistics computed from history */
+type InstanceStats = {
+    uptime24h: number | null;
+    p50: number | null;
+    samples24h: number;
+};
+type ServiceStats = {
+    /** Share of runs that were not "down", in percent */
+    uptime24h: number | null;
+    uptime7d: number | null;
+    p50: number | null;
+    p95: number | null;
+    samples24h: number;
+    /** Latency series over the last 24h, oldest first (for sparklines) */
+    latency: Array<number | null>;
+    lastFailure?: {
+        at: number;
+        status: Status;
+        error?: string;
+    };
+    instances?: Record<string, InstanceStats>;
+};
+type ServiceSnapshot = {
+    type: "service";
+    /** Derived, internal: only used for anchors, single-service runs and history routes */
+    key: string;
+    /** The preset kind: "custom", "generic.http", "fly.app"… */
+    kind: string;
+    name: string;
+    description?: string;
+    critical: boolean;
+    slowMs: number;
+    configured: boolean;
+    /** Which required secrets/fields are missing when not configured */
+    missing?: string[];
+    result?: CheckResult;
+    stats?: ServiceStats;
+};
+type GroupSnapshot = {
+    type: "group";
+    key: string;
+    title: string;
+    description?: string;
+    children: SnapshotNode[];
+};
+type SnapshotNode = GroupSnapshot | ServiceSnapshot;
+type Trigger = "scheduled" | "manual";
+type StatusSnapshot = {
+    schemaVersion: 1;
+    generatedAt: number;
+    /** Most recent check of any service */
+    lastCheckedAt: number | null;
+    /** Last run of every service, and how it was triggered */
+    lastRunAt: number | null;
+    lastRunTrigger: Trigger | null;
+    /** When the next full run is due, based on `interval` */
+    nextDueAt: number | null;
+    intervalMs: number;
+    /** How long history is kept */
+    retentionMs: number;
+    score: number | null;
+    label: ScoreLabel;
+    counts: Record<Status, number>;
+    tree: SnapshotNode[];
+};
+type HistoryRange = "24h" | "7d";
+type HistoryBar = {
+    start: number;
+    /** Worst score in the bucket; null when no run happened */
+    score: number | null;
+    label: ScoreLabel;
+    runs: number;
+    /** Services that were degraded or down in the bucket ("down" wins) */
+    failing: Record<string, Status>;
+};
+type HistoryPayload = {
+    schemaVersion: 1;
+    range: HistoryRange;
+    bucketMs: number;
+    bars: HistoryBar[];
+};
+
+export type { CheckOutcome as C, GroupSnapshot as G, HistoryRange as H, Instance as I, Metrics as M, OutcomeStatus as O, ProbeHelpers as P, ServiceStats as S, Trigger as T, Usage as U, HistoryBar as a, HttpInit as b, HttpResult as c, CheckReturn as d, CheckCache as e, CheckContext as f, CheckResult as g, CommonOptions as h, HistoryPayload as i, InstanceStats as j, ScoreLabel as k, SecretsInput as l, ServiceSnapshot as m, SnapshotNode as n, Status as o, StatusSnapshot as p };

package/package.json

@@ -1,6 +1,236 @@
 {
   "name": "sermon-js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Service monitor: build status pages fast. Typed checks and presets, sleep-safe probes, scoring, history, a host-agnostic API and a React UI kit.",
+  "license": "MIT",
+  "author": "BSide-Tech",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bside-tech/sermon-js.git"
+  },
+  "homepage": "https://github.com/bside-tech/sermon-js#readme",
+  "bugs": "https://github.com/bside-tech/sermon-js/issues",
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "api": [
+        "./dist/api/index.d.cts"
+      ],
+      "presets": [
+        "./dist/presets/index.d.cts"
+      ],
+      "stores/upstash": [
+        "./dist/stores/upstash.d.cts"
+      ],
+      "stores/redis": [
+        "./dist/stores/redis.d.cts"
+      ],
+      "stores/sql": [
+        "./dist/stores/sql.d.cts"
+      ],
+      "stores/mongodb": [
+        "./dist/stores/mongodb.d.cts"
+      ],
+      "react": [
+        "./dist/react/index.d.cts"
+      ],
+      "react/heroui": [
+        "./dist/react/heroui/index.d.cts"
+      ],
+      "testing": [
+        "./dist/testing/index.d.cts"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./api": {
+      "import": {
+        "types": "./dist/api/index.d.ts",
+        "default": "./dist/api/index.js"
+      },
+      "require": {
+        "types": "./dist/api/index.d.cts",
+        "default": "./dist/api/index.cjs"
+      }
+    },
+    "./presets": {
+      "import": {
+        "types": "./dist/presets/index.d.ts",
+        "default": "./dist/presets/index.js"
+      },
+      "require": {
+        "types": "./dist/presets/index.d.cts",
+        "default": "./dist/presets/index.cjs"
+      }
+    },
+    "./stores/upstash": {
+      "import": {
+        "types": "./dist/stores/upstash.d.ts",
+        "default": "./dist/stores/upstash.js"
+      },
+      "require": {
+        "types": "./dist/stores/upstash.d.cts",
+        "default": "./dist/stores/upstash.cjs"
+      }
+    },
+    "./stores/redis": {
+      "import": {
+        "types": "./dist/stores/redis.d.ts",
+        "default": "./dist/stores/redis.js"
+      },
+      "require": {
+        "types": "./dist/stores/redis.d.cts",
+        "default": "./dist/stores/redis.cjs"
+      }
+    },
+    "./stores/sql": {
+      "import": {
+        "types": "./dist/stores/sql.d.ts",
+        "default": "./dist/stores/sql.js"
+      },
+      "require": {
+        "types": "./dist/stores/sql.d.cts",
+        "default": "./dist/stores/sql.cjs"
+      }
+    },
+    "./stores/mongodb": {
+      "import": {
+        "types": "./dist/stores/mongodb.d.ts",
+        "default": "./dist/stores/mongodb.js"
+      },
+      "require": {
+        "types": "./dist/stores/mongodb.d.cts",
+        "default": "./dist/stores/mongodb.cjs"
+      }
+    },
+    "./react": {
+      "import": {
+        "types": "./dist/react/index.d.ts",
+        "default": "./dist/react/index.js"
+      },
+      "require": {
+        "types": "./dist/react/index.d.cts",
+        "default": "./dist/react/index.cjs"
+      }
+    },
+    "./react/heroui": {
+      "import": {
+        "types": "./dist/react/heroui/index.d.ts",
+        "default": "./dist/react/heroui/index.js"
+      },
+      "require": {
+        "types": "./dist/react/heroui/index.d.cts",
+        "default": "./dist/react/heroui/index.cjs"
+      }
+    },
+    "./react/heroui/styles.css": "./dist/react/heroui/styles.css",
+    "./testing": {
+      "import": {
+        "types": "./dist/testing/index.d.ts",
+        "default": "./dist/testing/index.js"
+      },
+      "require": {
+        "types": "./dist/testing/index.d.cts",
+        "default": "./dist/testing/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "status-page",
+    "uptime",
+    "monitoring",
+    "health-check",
+    "service-monitor"
+  ],
+  "devDependencies": {
+    "@changesets/cli": "^2.27.9",
+    "@edge-runtime/vm": "^5.0.0",
+    "@eslint/js": "^9.22.0",
+    "@heroui/react": "^3.2.6",
+    "@heroui/styles": "^3.2.6",
+    "@tanstack/react-query": "^5.104.2",
+    "@testing-library/react": "^16.3.3",
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/node": "^22.18.6",
+    "@types/pg": "^8.23.1",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "better-sqlite3": "^12.11.1",
+    "esbuild": "^0.28.2",
+    "eslint": "^9.22.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^16.0.0",
+    "happy-dom": "^20.14.6",
+    "ioredis": "^6.0.0",
+    "mongodb": "^7.7.0",
+    "mysql2": "^3.24.5",
+    "pg": "^8.23.1",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "tailwind-variants": "^3.3.1",
+    "tailwindcss": "^4.3.3",
+    "tsup": "^8.3.5",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.26.1",
+    "vitest": "^2.1.6"
+  },
+  "dependencies": {
+    "aws4fetch": "^1.0.20"
+  },
+  "peerDependencies": {
+    "@heroui/react": ">=3",
+    "@tanstack/react-query": ">=5",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "@heroui/react": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest --run --typecheck",
+    "test:watch": "vitest",
+    "changeset": "changeset",
+    "release": "node scripts/assert-versioned.mjs && pnpm build && changeset publish",
+    "prebuild": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "version": "changeset version"
+  }
 }