@openstatus/health-convex 0.1.4-dev.0

package/README.md

@@ -0,0 +1,93 @@
+# @openstatus/health-convex
+
+[Convex](https://www.convex.dev/) probe for
+[`@openstatus/health`](https://jsr.io/@openstatus/health). Runs one query
+function of your deployment over its
+[HTTP API](https://docs.convex.dev/http-api/) — `POST {url}/api/query` —
+and fails the check unless it answers `status: "success"`. With `fetch`
+alone, on every runtime, and without the Convex client.
+
+```sh
+deno add jsr:@openstatus/health jsr:@openstatus/health-convex
+npm install @openstatus/health @openstatus/health-convex
+```
+
+Add a trivial query to your `convex/` directory once:
+
+```ts
+// convex/health.ts
+import { query } from "./_generated/server";
+
+export const ping = query({
+  args: {},
+  handler: () => "pong",
+});
+```
+
+Then point the probe at it:
+
+```ts
+import { createHealthHandler, readEnv } from "@openstatus/health";
+import { convexProbe } from "@openstatus/health-convex";
+
+const url = readEnv("CONVEX_URL");
+
+Deno.serve(
+  createHealthHandler({
+    probes: [
+      // the factory validates `url` at construction, so pass a placeholder
+      // and let `skip` keep the unconfigured check from running.
+      convexProbe({
+        url: url ?? "https://unconfigured.convex.cloud",
+        path: "health:ping",
+        skip: () => url == null,
+      }),
+    ],
+  }),
+);
+```
+
+`url` is the deployment URL (`CONVEX_URL` / `NEXT_PUBLIC_CONVEX_URL`, the
+`.convex.cloud` host — not the `.convex.site` host of HTTP actions).
+`path` names the function as `module:function`. A query is read-only and
+runs inside the deployment, so a success proves the deployment, its
+database and your code are all up. Pass `args` for a query that takes
+them, and `token` — a deploy key or a user's JWT — when the query checks
+authentication. Like every probe here, this one never reads the environment
+itself — pass the values in, and use `skip` for environments where Convex
+is not configured.
+
+```ts
+convexProbe({
+  url,
+  path: "health:ping",
+  // optional overrides from the Probe contract
+  name: "convex",
+  critical: false,
+  timeoutMs: 2000,
+  skip: () => env.CONVEX_URL == null,
+});
+```
+
+Critical by default: Convex is usually the application's database, so a
+deployment that does not answer turns the report `unhealthy` and takes the
+instance out of rotation. Set `critical: false` when the service can serve
+without it.
+
+## About openstatus
+
+[openstatus](https://www.openstatus.dev/) is the open-source uptime monitoring
+and status page platform. This package is part of
+[`@openstatus/health`](https://github.com/openstatusHQ/health), the `/health`
+endpoints behind openstatus's own services, extracted so any JavaScript server
+can expose one. Point an
+[openstatus monitor](https://www.openstatus.dev/docs/reference/http-monitor)
+at the endpoint and assert on `status` in the body to be alerted on
+`degraded` before it becomes `unhealthy`.
+
+Source: [github.com/openstatusHQ/health](https://github.com/openstatusHQ/health).
+Issues and PRs welcome.
+
+## License
+
+[MIT](https://github.com/openstatusHQ/health/blob/main/LICENSE)

package/dist/_virtual/rolldown_runtime.cjs

@@ -0,0 +1,30 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+
+Object.defineProperty(exports, '__toESM', {
+  enumerable: true,
+  get: function () {
+    return __toESM;
+  }
+});

package/dist/mod.cjs

@@ -0,0 +1,48 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const __openstatus_health = require_rolldown_runtime.__toESM(require("@openstatus/health"));
+
+//#region src/mod.ts
+/** Probe name when `name` is unset. */
+const convexDefaultName = "database";
+/** A probe that runs `path` over the HTTP API and expects `status: "success"`; critical by default. Throws `ProbeConfigError` for an invalid `url`, an empty `path` or an empty or non-string `token`. */
+function convexProbe(options) {
+	const doFetch = options.fetch ?? globalThis.fetch;
+	const url = (0, __openstatus_health.probeUrl)({
+		probe: "convexProbe",
+		field: "url",
+		value: options.url,
+		path: "/api/query"
+	});
+	if (typeof options.path !== "string" || options.path.length === 0) throw new __openstatus_health.ProbeConfigError("convexProbe", "path", typeof options.path !== "string" ? `must be a string, got ${String(options.path)}` : "must not be empty");
+	if (options.token != null && (typeof options.token !== "string" || options.token.length === 0)) throw new __openstatus_health.ProbeConfigError("convexProbe", "token", typeof options.token !== "string" ? `must be a string, got ${String(options.token)}` : "must not be empty");
+	const headers = { "content-type": "application/json" };
+	if (options.token != null) headers.authorization = `Bearer ${options.token}`;
+	const body = JSON.stringify({
+		path: options.path,
+		args: options.args ?? {},
+		format: "json"
+	});
+	return {
+		name: options.name ?? convexDefaultName,
+		critical: options.critical ?? true,
+		timeoutMs: options.timeoutMs,
+		skip: options.skip,
+		run: async (signal) => {
+			const res = await doFetch(url, {
+				method: "POST",
+				headers,
+				body,
+				signal
+			});
+			const result = await res.json().catch(() => null);
+			if (result?.status === "error") throw new Error(result.errorMessage ?? `query failed with status ${res.status}`);
+			if (!res.ok) throw new Error(`unexpected status ${res.status}`);
+			if (result?.status === "success") return;
+			throw new Error("unexpected response shape");
+		}
+	};
+}
+
+//#endregion
+exports.convexDefaultName = convexDefaultName;
+exports.convexProbe = convexProbe;

package/dist/mod.d.cts

@@ -0,0 +1,32 @@
+import { JsonObject, Probe, ProbeOverrides } from "@openstatus/health";
+
+//#region src/mod.d.ts
+
+/** Probe name when `name` is unset. */
+declare const convexDefaultName = "database";
+/** Options for `convexProbe()`. */
+interface ConvexProbeOptions extends ProbeOverrides {
+  /** The deployment URL, e.g. `https://happy-animal-123.convex.cloud`. */
+  readonly url: string | URL;
+  /** The query function to run, as `module:function`, e.g. `"health:ping"`. */
+  readonly path: string;
+  /** Arguments for the query. Default `{}`. */
+  readonly args?: JsonObject;
+  /** A deploy key or user token, sent as a bearer token when the query requires auth. */
+  readonly token?: string;
+  /** Replacement `fetch`, for tests. */
+  readonly fetch?: typeof fetch;
+}
+/** What `POST /api/query` answers. */
+type ConvexQueryResponse = {
+  readonly status: "success";
+} | {
+  readonly status: "error";
+  readonly errorMessage?: string;
+};
+/** A probe that runs `path` over the HTTP API and expects `status: "success"`; critical by default. Throws `ProbeConfigError` for an invalid `url`, an empty `path` or an empty or non-string `token`. */
+declare function convexProbe(options: ConvexProbeOptions): Probe;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { ConvexProbeOptions, ConvexQueryResponse, convexDefaultName, convexProbe };
+//# sourceMappingURL=mod.d.cts.map

package/dist/mod.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.cts","names":[],"sources":["../src/mod.ts"],"sourcesContent":[],"mappings":";;;;;AA4CqC,cAtBxB,iBAAA,GAsBwB,UAAA;;AAA0B,UAnB9C,kBAAA,SAA2B,cAmBmB,CAAA;;yBAjBtC;;;;kBAIP;;;;0BAIQ;;;KAId,mBAAA;;;;;;;iBAKI,WAAA,UAAqB,qBAAqB"}

package/dist/mod.d.ts

@@ -0,0 +1,32 @@
+import { JsonObject, Probe, ProbeOverrides } from "@openstatus/health";
+
+//#region src/mod.d.ts
+
+/** Probe name when `name` is unset. */
+declare const convexDefaultName = "database";
+/** Options for `convexProbe()`. */
+interface ConvexProbeOptions extends ProbeOverrides {
+  /** The deployment URL, e.g. `https://happy-animal-123.convex.cloud`. */
+  readonly url: string | URL;
+  /** The query function to run, as `module:function`, e.g. `"health:ping"`. */
+  readonly path: string;
+  /** Arguments for the query. Default `{}`. */
+  readonly args?: JsonObject;
+  /** A deploy key or user token, sent as a bearer token when the query requires auth. */
+  readonly token?: string;
+  /** Replacement `fetch`, for tests. */
+  readonly fetch?: typeof fetch;
+}
+/** What `POST /api/query` answers. */
+type ConvexQueryResponse = {
+  readonly status: "success";
+} | {
+  readonly status: "error";
+  readonly errorMessage?: string;
+};
+/** A probe that runs `path` over the HTTP API and expects `status: "success"`; critical by default. Throws `ProbeConfigError` for an invalid `url`, an empty `path` or an empty or non-string `token`. */
+declare function convexProbe(options: ConvexProbeOptions): Probe;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { ConvexProbeOptions, ConvexQueryResponse, convexDefaultName, convexProbe };
+//# sourceMappingURL=mod.d.ts.map

package/dist/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","names":[],"sources":["../src/mod.ts"],"sourcesContent":[],"mappings":";;;;;AA4CqC,cAtBxB,iBAAA,GAsBwB,UAAA;;AAA0B,UAnB9C,kBAAA,SAA2B,cAmBmB,CAAA;;yBAjBtC;;;;kBAIP;;;;0BAIQ;;;KAId,mBAAA;;;;;;;iBAKI,WAAA,UAAqB,qBAAqB"}

package/dist/mod.js

@@ -0,0 +1,47 @@
+import { ProbeConfigError, probeUrl } from "@openstatus/health";
+
+//#region src/mod.ts
+/** Probe name when `name` is unset. */
+const convexDefaultName = "database";
+/** A probe that runs `path` over the HTTP API and expects `status: "success"`; critical by default. Throws `ProbeConfigError` for an invalid `url`, an empty `path` or an empty or non-string `token`. */
+function convexProbe(options) {
+	const doFetch = options.fetch ?? globalThis.fetch;
+	const url = probeUrl({
+		probe: "convexProbe",
+		field: "url",
+		value: options.url,
+		path: "/api/query"
+	});
+	if (typeof options.path !== "string" || options.path.length === 0) throw new ProbeConfigError("convexProbe", "path", typeof options.path !== "string" ? `must be a string, got ${String(options.path)}` : "must not be empty");
+	if (options.token != null && (typeof options.token !== "string" || options.token.length === 0)) throw new ProbeConfigError("convexProbe", "token", typeof options.token !== "string" ? `must be a string, got ${String(options.token)}` : "must not be empty");
+	const headers = { "content-type": "application/json" };
+	if (options.token != null) headers.authorization = `Bearer ${options.token}`;
+	const body = JSON.stringify({
+		path: options.path,
+		args: options.args ?? {},
+		format: "json"
+	});
+	return {
+		name: options.name ?? convexDefaultName,
+		critical: options.critical ?? true,
+		timeoutMs: options.timeoutMs,
+		skip: options.skip,
+		run: async (signal) => {
+			const res = await doFetch(url, {
+				method: "POST",
+				headers,
+				body,
+				signal
+			});
+			const result = await res.json().catch(() => null);
+			if (result?.status === "error") throw new Error(result.errorMessage ?? `query failed with status ${res.status}`);
+			if (!res.ok) throw new Error(`unexpected status ${res.status}`);
+			if (result?.status === "success") return;
+			throw new Error("unexpected response shape");
+		}
+	};
+}
+
+//#endregion
+export { convexDefaultName, convexProbe };
+//# sourceMappingURL=mod.js.map

package/dist/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","names":["options: ConvexProbeOptions","headers: Record<string, string>","result: ConvexQueryResponse | null"],"sources":["../src/mod.ts"],"sourcesContent":["/**\n * Convex probe for `@openstatus/health`: runs one query function over the\n * deployment's HTTP API (`POST /api/query`) and fails unless it succeeds.\n *\n * ```ts\n * import { convexProbe } from \"@openstatus/health-convex\";\n *\n * const probe = convexProbe({ url: env.CONVEX_URL, path: \"health:ping\" });\n * ```\n *\n * @module\n */\n\nimport {\n  type JsonObject,\n  type Probe,\n  ProbeConfigError,\n  type ProbeOverrides,\n  probeUrl,\n} from \"@openstatus/health\";\n\n/** Probe name when `name` is unset. */\nexport const convexDefaultName = \"database\";\n\n/** Options for `convexProbe()`. */\nexport interface ConvexProbeOptions extends ProbeOverrides {\n  /** The deployment URL, e.g. `https://happy-animal-123.convex.cloud`. */\n  readonly url: string | URL;\n  /** The query function to run, as `module:function`, e.g. `\"health:ping\"`. */\n  readonly path: string;\n  /** Arguments for the query. Default `{}`. */\n  readonly args?: JsonObject;\n  /** A deploy key or user token, sent as a bearer token when the query requires auth. */\n  readonly token?: string;\n  /** Replacement `fetch`, for tests. */\n  readonly fetch?: typeof fetch;\n}\n\n/** What `POST /api/query` answers. */\nexport type ConvexQueryResponse =\n  | { readonly status: \"success\" }\n  | { readonly status: \"error\"; readonly errorMessage?: string };\n\n/** A probe that runs `path` over the HTTP API and expects `status: \"success\"`; critical by default. Throws `ProbeConfigError` for an invalid `url`, an empty `path` or an empty or non-string `token`. */\nexport function convexProbe(options: ConvexProbeOptions): Probe {\n  const doFetch = options.fetch ?? globalThis.fetch;\n  const url = probeUrl({\n    probe: \"convexProbe\",\n    field: \"url\",\n    value: options.url,\n    path: \"/api/query\",\n  });\n  if (typeof options.path !== \"string\" || options.path.length === 0) {\n    throw new ProbeConfigError(\n      \"convexProbe\",\n      \"path\",\n      typeof options.path !== \"string\"\n        ? `must be a string, got ${String(options.path)}`\n        : \"must not be empty\",\n    );\n  }\n  if (\n    options.token != null &&\n    (typeof options.token !== \"string\" || options.token.length === 0)\n  ) {\n    throw new ProbeConfigError(\n      \"convexProbe\",\n      \"token\",\n      typeof options.token !== \"string\"\n        ? `must be a string, got ${String(options.token)}`\n        : \"must not be empty\",\n    );\n  }\n  const headers: Record<string, string> = {\n    \"content-type\": \"application/json\",\n  };\n  if (options.token != null) headers.authorization = `Bearer ${options.token}`;\n  const body = JSON.stringify({\n    path: options.path,\n    args: options.args ?? {},\n    format: \"json\",\n  });\n  return {\n    name: options.name ?? convexDefaultName,\n    critical: options.critical ?? true,\n    timeoutMs: options.timeoutMs,\n    skip: options.skip,\n    run: async (signal) => {\n      const res = await doFetch(url, { method: \"POST\", headers, body, signal });\n      const result: ConvexQueryResponse | null = await res.json()\n        .catch(() => null);\n      if (result?.status === \"error\") {\n        throw new Error(\n          result.errorMessage ?? `query failed with status ${res.status}`,\n        );\n      }\n      if (!res.ok) throw new Error(`unexpected status ${res.status}`);\n      if (result?.status === \"success\") return;\n      throw new Error(\"unexpected response shape\");\n    },\n  };\n}\n"],"mappings":";;;;AAsBA,MAAa,oBAAoB;;AAsBjC,SAAgB,YAAYA,SAAoC;CAC9D,MAAM,UAAU,QAAQ,SAAS,WAAW;CAC5C,MAAM,MAAM,SAAS;EACnB,OAAO;EACP,OAAO;EACP,OAAO,QAAQ;EACf,MAAM;CACP,EAAC;AACF,YAAW,QAAQ,SAAS,YAAY,QAAQ,KAAK,WAAW,EAC9D,OAAM,IAAI,iBACR,eACA,eACO,QAAQ,SAAS,YACnB,wBAAwB,OAAO,QAAQ,KAAK,CAAC,IAC9C;AAGR,KACE,QAAQ,SAAS,gBACT,QAAQ,UAAU,YAAY,QAAQ,MAAM,WAAW,GAE/D,OAAM,IAAI,iBACR,eACA,gBACO,QAAQ,UAAU,YACpB,wBAAwB,OAAO,QAAQ,MAAM,CAAC,IAC/C;CAGR,MAAMC,UAAkC,EACtC,gBAAgB,mBACjB;AACD,KAAI,QAAQ,SAAS,KAAM,SAAQ,iBAAiB,SAAS,QAAQ,MAAM;CAC3E,MAAM,OAAO,KAAK,UAAU;EAC1B,MAAM,QAAQ;EACd,MAAM,QAAQ,QAAQ,CAAE;EACxB,QAAQ;CACT,EAAC;AACF,QAAO;EACL,MAAM,QAAQ,QAAQ;EACtB,UAAU,QAAQ,YAAY;EAC9B,WAAW,QAAQ;EACnB,MAAM,QAAQ;EACd,KAAK,OAAO,WAAW;GACrB,MAAM,MAAM,MAAM,QAAQ,KAAK;IAAE,QAAQ;IAAQ;IAAS;IAAM;GAAQ,EAAC;GACzE,MAAMC,SAAqC,MAAM,IAAI,MAAM,CACxD,MAAM,MAAM,KAAK;AACpB,OAAI,QAAQ,WAAW,QACrB,OAAM,IAAI,MACR,OAAO,iBAAiB,2BAA2B,IAAI,OAAO;AAGlE,QAAK,IAAI,GAAI,OAAM,IAAI,OAAO,oBAAoB,IAAI,OAAO;AAC7D,OAAI,QAAQ,WAAW,UAAW;AAClC,SAAM,IAAI,MAAM;EACjB;CACF;AACF"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@openstatus/health-convex",
+  "version": "0.1.4-dev.0",
+  "description": "Convex probe for @openstatus/health",
+  "keywords": [
+    "openstatus",
+    "health",
+    "healthcheck",
+    "convex",
+    "database",
+    "backend"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "openstatus",
+    "url": "https://www.openstatus.dev/"
+  },
+  "homepage": "https://github.com/openstatusHQ/health",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openstatusHQ/health.git",
+    "directory": "packages/convex/"
+  },
+  "bugs": {
+    "url": "https://github.com/openstatusHQ/health/issues"
+  },
+  "type": "module",
+  "module": "./dist/mod.js",
+  "main": "./dist/mod.cjs",
+  "types": "./dist/mod.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/mod.d.ts",
+        "require": "./dist/mod.d.cts"
+      },
+      "import": "./dist/mod.js",
+      "require": "./dist/mod.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist/"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "@openstatus/health": "^0.1.4-dev.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.12.7",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepack": "tsdown",
+    "test": "node --experimental-transform-types --test"
+  }
+}