@cronwatch/sdk 0.4.0 → 0.5.1

package/dist/webhook.js

@@ -1,3 +1,15 @@
+// src/alerts/shared.ts
+function postable(url) {
+  let protocol;
+  try {
+    protocol = new URL(url).protocol;
+  } catch {
+    throw new Error("only http and https URLs can be posted to, not this URL");
+  }
+  if (protocol !== "http:" && protocol !== "https:") throw new Error(`only http and https URLs can be posted to, not ${protocol}`);
+  return url;
+}
+
 // src/alerts/webhook.ts
 var TIMEOUT_MS = 1e4;
 function origin(url) {
@@ -18,7 +30,7 @@ function webhook(options) {
       if (options.secret) {
         headers["x-cronwatch-signature"] = `sha256=${await hmacSha256Hex(options.secret, body)}`;
       }
-      const response = await fetch(options.url, { method: "POST", headers, body, redirect: "error", signal: AbortSignal.timeout(TIMEOUT_MS) });
+      const response = await fetch(postable(options.url), { method: "POST", headers, body, redirect: "error", signal: AbortSignal.timeout(TIMEOUT_MS) });
       if (!response.ok) throw new Error(`Webhook ${origin(options.url)} answered ${response.status}`);
     }
   };

package/dist/webhook.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/alerts/webhook.ts"],"names":[],"mappings":";AAcA,IAAM,UAAA,GAAa,GAAA;AAEnB,SAAS,OAAO,GAAA,EAAqB;AACnC,EAAA,IAAI;AACF,IAAA,OAAO,IAAI,GAAA,CAAI,GAAG,CAAA,CAAE,MAAA;AAAA,EACtB,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,eAAA;AAAA,EACT;AACF;AAOO,SAAS,QAAQ,OAAA,EAAuC;AAC7D,EAAA,IAAI,CAAC,OAAA,CAAQ,GAAA,EAAK,MAAM,IAAI,MAAM,uBAAuB,CAAA;AACzD,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,SAAA;AAAA,IACN,MAAM,KAAK,KAAA,EAAO;AAChB,MAAA,MAAM,IAAA,GAAO,IAAA,CAAK,SAAA,CAAU,KAAK,CAAA;AACjC,MAAA,MAAM,OAAA,GAAkC,EAAE,cAAA,EAAgB,kBAAA,EAAoB,cAAc,WAAA,EAAY;AAExG,MAAA,KAAA,MAAW,CAAC,IAAA,EAAM,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,QAAQ,OAAA,IAAW,EAAE,CAAA,EAAG,OAAA,CAAQ,IAAI,CAAA,GAAI,OAAO,UAAU,QAAA,GAAW,KAAA,CAAM,MAAK,GAAI,KAAA;AAC9H,MAAA,IAAI,QAAQ,MAAA,EAAQ;AAClB,QAAA,OAAA,CAAQ,uBAAuB,IAAI,CAAA,OAAA,EAAU,MAAM,cAAc,OAAA,CAAQ,MAAA,EAAQ,IAAI,CAAC,CAAA,CAAA;AAAA,MACxF;AAEA,MAAA,MAAM,WAAW,MAAM,KAAA,CAAM,OAAA,CAAQ,GAAA,EAAK,EAAE,MAAA,EAAQ,MAAA,EAAQ,OAAA,EAAS,IAAA,EAAM,UAAU,OAAA,EAAS,MAAA,EAAQ,YAAY,OAAA,CAAQ,UAAU,GAAG,CAAA;AAEvI,MAAA,IAAI,CAAC,QAAA,CAAS,EAAA,EAAI,MAAM,IAAI,KAAA,CAAM,CAAA,QAAA,EAAW,MAAA,CAAO,OAAA,CAAQ,GAAG,CAAC,CAAA,UAAA,EAAa,QAAA,CAAS,MAAM,CAAA,CAAE,CAAA;AAAA,IAChG;AAAA,GACF;AACF;AAGA,eAAsB,aAAA,CAAc,QAAgB,IAAA,EAA+B;AACjF,EAAA,MAAM,OAAA,GAAU,IAAI,WAAA,EAAY;AAChC,EAAA,MAAM,MAAM,MAAM,MAAA,CAAO,OAAO,SAAA,CAAU,KAAA,EAAO,QAAQ,MAAA,CAAO,MAAM,GAAG,EAAE,IAAA,EAAM,QAAQ,IAAA,EAAM,SAAA,IAAa,KAAA,EAAO,CAAC,MAAM,CAAC,CAAA;AAC3H,EAAA,MAAM,SAAA,GAAY,IAAI,UAAA,CAAW,MAAM,MAAA,CAAO,MAAA,CAAO,IAAA,CAAK,MAAA,EAAQ,GAAA,EAAK,OAAA,CAAQ,MAAA,CAAO,IAAI,CAAC,CAAC,CAAA;AAC5F,EAAA,OAAO,KAAA,CAAM,IAAA,CAAK,SAAA,EAAW,CAAC,MAAM,CAAA,CAAE,QAAA,CAAS,EAAE,CAAA,CAAE,SAAS,CAAA,EAAG,GAAG,CAAC,CAAA,CAAE,KAAK,EAAE,CAAA;AAC9E","file":"webhook.js","sourcesContent":["import type { AlertChannel } from \"../types.js\";\n\nexport interface WebhookOptions {\n  url: string;\n  /** Extra request headers, for an Authorization header say. Values are trimmed. */\n  headers?: Record<string, string>;\n  /**\n   * When set, each request carries `X-CronWatch-Signature: sha256=<hex>`,\n   * the HMAC-SHA256 of the raw body with this secret, so the receiver can\n   * verify it.\n   */\n  secret?: string;\n}\n\nconst TIMEOUT_MS = 10_000;\n\nfunction origin(url: string): string {\n  try {\n    return new URL(url).origin;\n  } catch {\n    return \"(invalid URL)\";\n  }\n}\n\n/**\n * POSTs the alert as JSON to any URL. The body is the Alert object:\n * { type, job, title, message, run, details, triage, at, definition }.\n * A redirect is an error: point the url at where the receiver really is.\n */\nexport function webhook(options: WebhookOptions): AlertChannel {\n  if (!options.url) throw new Error(\"webhook() needs a url\");\n  return {\n    name: \"webhook\",\n    async send(alert) {\n      const body = JSON.stringify(alert);\n      const headers: Record<string, string> = { \"content-type\": \"application/json\", \"user-agent\": \"cronwatch\" };\n      // A pasted Authorization value often carries a stray space or newline, which fetch would refuse.\n      for (const [name, value] of Object.entries(options.headers ?? {})) headers[name] = typeof value === \"string\" ? value.trim() : value;\n      if (options.secret) {\n        headers[\"x-cronwatch-signature\"] = `sha256=${await hmacSha256Hex(options.secret, body)}`;\n      }\n      // A redirect is refused, not followed: the headers (and the signature) would go with it.\n      const response = await fetch(options.url, { method: \"POST\", headers, body, redirect: \"error\", signal: AbortSignal.timeout(TIMEOUT_MS) });\n      // Only the origin: a webhook URL's path or query often is the credential.\n      if (!response.ok) throw new Error(`Webhook ${origin(options.url)} answered ${response.status}`);\n    },\n  };\n}\n\n/** HMAC-SHA256 as lowercase hex, with Web Crypto so it runs on Workers and Deno too. */\nexport async function hmacSha256Hex(secret: string, body: string): Promise<string> {\n  const encoder = new TextEncoder();\n  const key = await crypto.subtle.importKey(\"raw\", encoder.encode(secret), { name: \"HMAC\", hash: \"SHA-256\" }, false, [\"sign\"]);\n  const signature = new Uint8Array(await crypto.subtle.sign(\"HMAC\", key, encoder.encode(body)));\n  return Array.from(signature, (b) => b.toString(16).padStart(2, \"0\")).join(\"\");\n}\n"]}
+{"version":3,"sources":["../src/alerts/shared.ts","../src/alerts/webhook.ts"],"names":[],"mappings":";AAgCO,SAAS,SAAS,GAAA,EAAqB;AAC5C,EAAA,IAAI,QAAA;AACJ,EAAA,IAAI;AACF,IAAA,QAAA,GAAW,IAAI,GAAA,CAAI,GAAG,CAAA,CAAE,QAAA;AAAA,EAC1B,CAAA,CAAA,MAAQ;AACN,IAAA,MAAM,IAAI,MAAM,yDAAyD,CAAA;AAAA,EAC3E;AACA,EAAA,IAAI,QAAA,KAAa,WAAW,QAAA,KAAa,QAAA,QAAgB,IAAI,KAAA,CAAM,CAAA,+CAAA,EAAkD,QAAQ,CAAA,CAAE,CAAA;AAC/H,EAAA,OAAO,GAAA;AACT;;;AC1BA,IAAM,UAAA,GAAa,GAAA;AAEnB,SAAS,OAAO,GAAA,EAAqB;AACnC,EAAA,IAAI;AACF,IAAA,OAAO,IAAI,GAAA,CAAI,GAAG,CAAA,CAAE,MAAA;AAAA,EACtB,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,eAAA;AAAA,EACT;AACF;AAOO,SAAS,QAAQ,OAAA,EAAuC;AAC7D,EAAA,IAAI,CAAC,OAAA,CAAQ,GAAA,EAAK,MAAM,IAAI,MAAM,uBAAuB,CAAA;AACzD,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,SAAA;AAAA,IACN,MAAM,KAAK,KAAA,EAAO;AAChB,MAAA,MAAM,IAAA,GAAO,IAAA,CAAK,SAAA,CAAU,KAAK,CAAA;AACjC,MAAA,MAAM,OAAA,GAAkC,EAAE,cAAA,EAAgB,kBAAA,EAAoB,cAAc,WAAA,EAAY;AAExG,MAAA,KAAA,MAAW,CAAC,IAAA,EAAM,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,QAAQ,OAAA,IAAW,EAAE,CAAA,EAAG,OAAA,CAAQ,IAAI,CAAA,GAAI,OAAO,UAAU,QAAA,GAAW,KAAA,CAAM,MAAK,GAAI,KAAA;AAC9H,MAAA,IAAI,QAAQ,MAAA,EAAQ;AAClB,QAAA,OAAA,CAAQ,uBAAuB,IAAI,CAAA,OAAA,EAAU,MAAM,cAAc,OAAA,CAAQ,MAAA,EAAQ,IAAI,CAAC,CAAA,CAAA;AAAA,MACxF;AAEA,MAAA,MAAM,WAAW,MAAM,KAAA,CAAM,SAAS,OAAA,CAAQ,GAAG,GAAG,EAAE,MAAA,EAAQ,QAAQ,OAAA,EAAS,IAAA,EAAM,UAAU,OAAA,EAAS,MAAA,EAAQ,YAAY,OAAA,CAAQ,UAAU,GAAG,CAAA;AAEjJ,MAAA,IAAI,CAAC,QAAA,CAAS,EAAA,EAAI,MAAM,IAAI,KAAA,CAAM,CAAA,QAAA,EAAW,MAAA,CAAO,OAAA,CAAQ,GAAG,CAAC,CAAA,UAAA,EAAa,QAAA,CAAS,MAAM,CAAA,CAAE,CAAA;AAAA,IAChG;AAAA,GACF;AACF;AAGA,eAAsB,aAAA,CAAc,QAAgB,IAAA,EAA+B;AACjF,EAAA,MAAM,OAAA,GAAU,IAAI,WAAA,EAAY;AAChC,EAAA,MAAM,MAAM,MAAM,MAAA,CAAO,OAAO,SAAA,CAAU,KAAA,EAAO,QAAQ,MAAA,CAAO,MAAM,GAAG,EAAE,IAAA,EAAM,QAAQ,IAAA,EAAM,SAAA,IAAa,KAAA,EAAO,CAAC,MAAM,CAAC,CAAA;AAC3H,EAAA,MAAM,SAAA,GAAY,IAAI,UAAA,CAAW,MAAM,MAAA,CAAO,MAAA,CAAO,IAAA,CAAK,MAAA,EAAQ,GAAA,EAAK,OAAA,CAAQ,MAAA,CAAO,IAAI,CAAC,CAAC,CAAA;AAC5F,EAAA,OAAO,KAAA,CAAM,IAAA,CAAK,SAAA,EAAW,CAAC,MAAM,CAAA,CAAE,QAAA,CAAS,EAAE,CAAA,CAAE,SAAS,CAAA,EAAG,GAAG,CAAC,CAAA,CAAE,KAAK,EAAE,CAAA;AAC9E","file":"webhook.js","sourcesContent":["/**\n * Helpers shared by the provider channels. Only fetch and Web Crypto, so the\n * channels run on Node, Cloudflare Workers, Deno and Bun alike. Not an entry\n * point: each channel bundles its own copy.\n */\nimport type { Alert } from \"../types.js\";\n\nexport const TIMEOUT_MS = 10_000;\n\n/** Severity for trackers that have levels. Recovered is informational. */\nexport type Severity = \"error\" | \"warning\" | \"info\";\n\nexport function severity(type: Alert[\"type\"]): Severity {\n  if (type === \"recovered\") return \"info\";\n  if (type === \"slow\" || type === \"over_budget\") return \"warning\";\n  return \"error\";\n}\n\n/** The scheme, host and port only. A URL's path or query can hold a credential. */\nexport function origin(url: string): string {\n  try {\n    return new URL(url).origin;\n  } catch {\n    return \"(invalid URL)\";\n  }\n}\n\n/**\n * The URL, once it is one fetch can post to. Refused without quoting it:\n * fetch's own error for a URL it cannot parse (\"Failed to parse URL from ...\")\n * quotes the whole URL, and a webhook URL's path is its credential.\n */\nexport function postable(url: string): string {\n  let protocol: string;\n  try {\n    protocol = new URL(url).protocol;\n  } catch {\n    throw new Error(\"only http and https URLs can be posted to, not this URL\");\n  }\n  if (protocol !== \"http:\" && protocol !== \"https:\") throw new Error(`only http and https URLs can be posted to, not ${protocol}`);\n  return url;\n}\n\n/** How much of a provider's error body goes into the error message. */\nexport const ERROR_BODY_MAX = 200;\n\n/**\n * POSTs and throws on a non-2xx answer. The error names the provider and the\n * URL's origin, plus the start of the response body with every secret the\n * channel holds cut out, in case a provider echoes one back. Secrets are cut\n * from a prefix long enough to hold one that starts inside the first\n * ERROR_BODY_MAX characters, and only then is it cut to that length, so no\n * part of a secret survives at the edge. A redirect is refused rather than\n * followed: the credential headers would go with it to wherever it points.\n */\nexport async function post(provider: string, url: string, init: { headers: Record<string, string>; body: string }, secrets: (string | undefined)[] = []): Promise<Response> {\n  const response = await fetch(postable(url), { method: \"POST\", headers: init.headers, body: init.body, redirect: \"error\", signal: AbortSignal.timeout(TIMEOUT_MS) });\n  if (!response.ok) {\n    let text = \"\";\n    try {\n      text = await response.text();\n    } catch {\n      // The status is enough.\n    }\n    throw new Error(`${provider} ${origin(url)} answered ${response.status}${text ? `: ${errorBody(text, secrets)}` : \"\"}`);\n  }\n  return response;\n}\n\n/** The start of an error body, secrets cut out first, then cut to ERROR_BODY_MAX on a code point. */\nexport function errorBody(text: string, secrets: (string | undefined)[] = []): string {\n  const kept = secrets.filter((s): s is string => typeof s === \"string\" && s.length >= 4);\n  const longest = kept.reduce((n, s) => Math.max(n, s.length), 0);\n  let head = cut(text, ERROR_BODY_MAX + longest);\n  for (const secret of kept) head = head.split(secret).join(\"[redacted]\");\n  return cut(head, ERROR_BODY_MAX);\n}\n\n/** A credential with the spaces and newlines a paste leaves around it taken off. Anything not a string is empty. */\nexport function trimmed(value: unknown): string {\n  return typeof value === \"string\" ? value.trim() : \"\";\n}\n\n/** Base64 of UTF-8, without Buffer. */\nexport function base64(text: string): string {\n  let binary = \"\";\n  for (const byte of new TextEncoder().encode(text)) binary += String.fromCharCode(byte);\n  return btoa(binary);\n}\n\nexport function basicAuth(user: string, password: string): string {\n  return `Basic ${base64(`${user}:${password}`)}`;\n}\n\nexport function hex(bytes: ArrayBuffer | Uint8Array): string {\n  return Array.from(bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes), (b) => b.toString(16).padStart(2, \"0\")).join(\"\");\n}\n\nexport async function sha256Hex(text: string): Promise<string> {\n  return hex(await crypto.subtle.digest(\"SHA-256\", new TextEncoder().encode(text)));\n}\n\n/**\n * A stable 32 hex character id for one alert: the same job, type and time\n * always give the same id, so a provider that deduplicates on it drops a\n * resend of an alert it already took.\n */\nexport async function alertId(alert: Alert): Promise<string> {\n  return (await sha256Hex(`${alert.job}\\n${alert.type}\\n${alert.at}`)).slice(0, 32);\n}\n\n/** The same id laid out as a UUID, for APIs that ask for one. */\nexport function asUuid(id: string): string {\n  return `${id.slice(0, 8)}-${id.slice(8, 12)}-${id.slice(12, 16)}-${id.slice(16, 20)}-${id.slice(20, 32)}`;\n}\n\n/** Cuts to at most `max` UTF-16 units without splitting a surrogate pair. */\nexport function cut(text: string, max: number): string {\n  if (text.length <= max) return text;\n  let end = max;\n  const code = text.charCodeAt(end - 1);\n  if (code >= 0xd800 && code <= 0xdbff) end -= 1;\n  return text.slice(0, end);\n}\n\n/** The run fields worth attaching to a tracker event. */\nexport function runSummary(alert: Alert): Record<string, unknown> | null {\n  const run = alert.run;\n  if (!run) return null;\n  return { id: run.id, status: run.status, startedAt: new Date(run.startedAt).toISOString(), durationMs: run.durationMs, trigger: run.trigger };\n}\n\n/** Title, message, triage and link as one plain text block, the way every channel reads. */\nexport function plainText(alert: Alert, link: string | undefined): string {\n  return [alert.title, \"\", alert.message, ...(alert.triage ? [\"\", `Triage: ${alert.triage}`] : []), ...(link ? [\"\", `Open: ${link}`] : [])].join(\"\\n\");\n}\n","import type { AlertChannel } from \"../types.js\";\nimport { postable } from \"./shared.js\";\n\nexport interface WebhookOptions {\n  url: string;\n  /** Extra request headers, for an Authorization header say. Values are trimmed. */\n  headers?: Record<string, string>;\n  /**\n   * When set, each request carries `X-CronWatch-Signature: sha256=<hex>`,\n   * the HMAC-SHA256 of the raw body with this secret, so the receiver can\n   * verify it.\n   */\n  secret?: string;\n}\n\nconst TIMEOUT_MS = 10_000;\n\nfunction origin(url: string): string {\n  try {\n    return new URL(url).origin;\n  } catch {\n    return \"(invalid URL)\";\n  }\n}\n\n/**\n * POSTs the alert as JSON to any URL. The body is the Alert object:\n * { type, job, title, message, run, details, triage, at, definition }.\n * A redirect is an error: point the url at where the receiver really is.\n */\nexport function webhook(options: WebhookOptions): AlertChannel {\n  if (!options.url) throw new Error(\"webhook() needs a url\");\n  return {\n    name: \"webhook\",\n    async send(alert) {\n      const body = JSON.stringify(alert);\n      const headers: Record<string, string> = { \"content-type\": \"application/json\", \"user-agent\": \"cronwatch\" };\n      // A pasted Authorization value often carries a stray space or newline, which fetch would refuse.\n      for (const [name, value] of Object.entries(options.headers ?? {})) headers[name] = typeof value === \"string\" ? value.trim() : value;\n      if (options.secret) {\n        headers[\"x-cronwatch-signature\"] = `sha256=${await hmacSha256Hex(options.secret, body)}`;\n      }\n      // A redirect is refused, not followed: the headers (and the signature) would go with it.\n      const response = await fetch(postable(options.url), { method: \"POST\", headers, body, redirect: \"error\", signal: AbortSignal.timeout(TIMEOUT_MS) });\n      // Only the origin: a webhook URL's path or query often is the credential.\n      if (!response.ok) throw new Error(`Webhook ${origin(options.url)} answered ${response.status}`);\n    },\n  };\n}\n\n/** HMAC-SHA256 as lowercase hex, with Web Crypto so it runs on Workers and Deno too. */\nexport async function hmacSha256Hex(secret: string, body: string): Promise<string> {\n  const encoder = new TextEncoder();\n  const key = await crypto.subtle.importKey(\"raw\", encoder.encode(secret), { name: \"HMAC\", hash: \"SHA-256\" }, false, [\"sign\"]);\n  const signature = new Uint8Array(await crypto.subtle.sign(\"HMAC\", key, encoder.encode(body)));\n  return Array.from(signature, (b) => b.toString(16).padStart(2, \"0\")).join(\"\");\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cronwatch/sdk",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Cron and scheduled-job monitoring that lives inside your app. Wrap a job, mount a route, get told when it is missed, failed, slow or over budget. No server to run.",
   "license": "MIT",
   "repository": {