@cronwatch/sdk 0.10.0 → 0.11.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { C as CronWatchOptions, a as CronWatch } from './client-DUoSea7X.cjs';
-export { F as FetchHandler, H as HandlerFn, b as HandlerOptions, J as JobContext, c as JobFn, d as JobHandle, R as RecordRunOptions, e as Routes, f as RoutesOptions, g as RunHandle, h as RunOutcome, S as Source, i as SourceHost, j as StartOptions, k as consoleChannel, l as createRoutes, m as custom } from './client-DUoSea7X.cjs';
-import { S as Store, D as Duration, b as AlertDraft, c as StoredJobDefinition, A as Alert } from './types-DyWCxlSi.cjs';
-export { a as AlertChannel, d as AlertDetails, e as AlertType, B as BudgetBreach, C as ChannelContext, f as CheckResult, g as Condition, E as ExpectRule, J as JobDefinition, h as JobHealth, i as JobOptions, j as JobState, k as JobSummary, R as Run, l as RunStatus, m as SendingAlert, n as StoredJob, T as TriageContext, o as TriageFn } from './types-DyWCxlSi.cjs';
+import { C as CronwatchOptions, a as Cronwatch } from './client-CRMfhylq.cjs';
+export { b as CronWatch, c as CronWatchOptions, F as FetchHandler, H as HandlerFn, d as HandlerOptions, J as JobContext, e as JobFn, f as JobHandle, R as RecordRunOptions, g as Routes, h as RoutesOptions, i as RunHandle, j as RunOutcome, S as Source, k as SourceHost, l as StartOptions, m as consoleChannel, n as createRoutes, o as custom } from './client-CRMfhylq.cjs';
+import { S as Store, D as Duration, b as AlertDraft, c as StoredJobDefinition, A as Alert } from './types-DLnlUie8.cjs';
+export { a as AlertChannel, d as AlertDetails, e as AlertType, B as BudgetBreach, C as ChannelContext, f as CheckResult, g as Condition, E as ExpectRule, h as JobDefinition, i as JobHealth, J as JobOptions, j as JobState, k as JobSummary, R as Run, l as RunStatus, m as SendingAlert, n as StoredJob, T as TriageContext, o as TriageFn } from './types-DLnlUie8.cjs';
 
 /**
  * Keeps everything in process memory. The default when no store is given,
@@ -10,6 +10,9 @@ export { a as AlertChannel, d as AlertDetails, e as AlertType, B as BudgetBreach
  */
 declare function memory(): Store;
 
+/** This release of @cronwatch/sdk. scripts/release.mjs keeps it in step with package.json. */
+declare const VERSION = "0.11.0";
+
 /**
  * "15m" -> 900000. Accepts a plain number of milliseconds, and compound
  * strings such as "1h30m". Whitespace between parts is fine.
@@ -28,9 +31,12 @@ interface ParsedSchedule {
 }
 /**
  * "0 2 * * *" (cron, five or six fields), "@hourly", or "every 5m".
- * Parsed once per (schedule, timezone) pair and cached. The croner instance
- * gets no callback, so it schedules nothing; it is only used to compute fire
- * times. Without a timezone the expression is read in the process timezone,
+ * Text with a colon after its first character, which croner would take for
+ * a one-time date, is refused. A cron that names a date no month has
+ * ("0 0 30 2 *") is read, and never fires: nothing is ever due, so it is
+ * never missed. Parsed once per (schedule, timezone) pair and cached. The
+ * croner instance gets no callback, so it schedules nothing; it is only used
+ * to compute fire times. Without a timezone the expression is read in the process timezone,
  * like crontab. Vercel and GitHub Actions run their crons in UTC, so pass
  * timezone: "UTC" for those.
  */
@@ -47,6 +53,6 @@ declare function composeAlert(draft: AlertDraft, def: StoredJobDefinition, now:
  *   export const cw = cronwatch({ store: sqlite({ path: "./data/cronwatch.db" }), alerts: [slack({ webhookUrl })] });
  *   export const nightly = cw.job("nightly-report", { schedule: "0 2 * * *", grace: "15m" });
  */
-declare function cronwatch(options?: CronWatchOptions): CronWatch;
+declare function cronwatch(options?: CronwatchOptions): Cronwatch;
 
-export { Alert, AlertDraft, CronWatch, CronWatchOptions, Duration, type ParsedSchedule, Store, StoredJobDefinition, composeAlert, cronwatch, formatDuration, memory, nextFire, parseDuration, parseSchedule };
+export { Alert, AlertDraft, Cronwatch, CronwatchOptions, Duration, type ParsedSchedule, Store, StoredJobDefinition, VERSION, composeAlert, cronwatch, formatDuration, memory, nextFire, parseDuration, parseSchedule };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { C as CronWatchOptions, a as CronWatch } from './client-BcIjVBiZ.js';
-export { F as FetchHandler, H as HandlerFn, b as HandlerOptions, J as JobContext, c as JobFn, d as JobHandle, R as RecordRunOptions, e as Routes, f as RoutesOptions, g as RunHandle, h as RunOutcome, S as Source, i as SourceHost, j as StartOptions, k as consoleChannel, l as createRoutes, m as custom } from './client-BcIjVBiZ.js';
-import { S as Store, D as Duration, b as AlertDraft, c as StoredJobDefinition, A as Alert } from './types-DyWCxlSi.js';
-export { a as AlertChannel, d as AlertDetails, e as AlertType, B as BudgetBreach, C as ChannelContext, f as CheckResult, g as Condition, E as ExpectRule, J as JobDefinition, h as JobHealth, i as JobOptions, j as JobState, k as JobSummary, R as Run, l as RunStatus, m as SendingAlert, n as StoredJob, T as TriageContext, o as TriageFn } from './types-DyWCxlSi.js';
+import { C as CronwatchOptions, a as Cronwatch } from './client-D2Xk2600.js';
+export { b as CronWatch, c as CronWatchOptions, F as FetchHandler, H as HandlerFn, d as HandlerOptions, J as JobContext, e as JobFn, f as JobHandle, R as RecordRunOptions, g as Routes, h as RoutesOptions, i as RunHandle, j as RunOutcome, S as Source, k as SourceHost, l as StartOptions, m as consoleChannel, n as createRoutes, o as custom } from './client-D2Xk2600.js';
+import { S as Store, D as Duration, b as AlertDraft, c as StoredJobDefinition, A as Alert } from './types-DLnlUie8.js';
+export { a as AlertChannel, d as AlertDetails, e as AlertType, B as BudgetBreach, C as ChannelContext, f as CheckResult, g as Condition, E as ExpectRule, h as JobDefinition, i as JobHealth, J as JobOptions, j as JobState, k as JobSummary, R as Run, l as RunStatus, m as SendingAlert, n as StoredJob, T as TriageContext, o as TriageFn } from './types-DLnlUie8.js';
 
 /**
  * Keeps everything in process memory. The default when no store is given,
@@ -10,6 +10,9 @@ export { a as AlertChannel, d as AlertDetails, e as AlertType, B as BudgetBreach
  */
 declare function memory(): Store;
 
+/** This release of @cronwatch/sdk. scripts/release.mjs keeps it in step with package.json. */
+declare const VERSION = "0.11.0";
+
 /**
  * "15m" -> 900000. Accepts a plain number of milliseconds, and compound
  * strings such as "1h30m". Whitespace between parts is fine.
@@ -28,9 +31,12 @@ interface ParsedSchedule {
 }
 /**
  * "0 2 * * *" (cron, five or six fields), "@hourly", or "every 5m".
- * Parsed once per (schedule, timezone) pair and cached. The croner instance
- * gets no callback, so it schedules nothing; it is only used to compute fire
- * times. Without a timezone the expression is read in the process timezone,
+ * Text with a colon after its first character, which croner would take for
+ * a one-time date, is refused. A cron that names a date no month has
+ * ("0 0 30 2 *") is read, and never fires: nothing is ever due, so it is
+ * never missed. Parsed once per (schedule, timezone) pair and cached. The
+ * croner instance gets no callback, so it schedules nothing; it is only used
+ * to compute fire times. Without a timezone the expression is read in the process timezone,
  * like crontab. Vercel and GitHub Actions run their crons in UTC, so pass
  * timezone: "UTC" for those.
  */
@@ -47,6 +53,6 @@ declare function composeAlert(draft: AlertDraft, def: StoredJobDefinition, now:
  *   export const cw = cronwatch({ store: sqlite({ path: "./data/cronwatch.db" }), alerts: [slack({ webhookUrl })] });
  *   export const nightly = cw.job("nightly-report", { schedule: "0 2 * * *", grace: "15m" });
  */
-declare function cronwatch(options?: CronWatchOptions): CronWatch;
+declare function cronwatch(options?: CronwatchOptions): Cronwatch;
 
-export { Alert, AlertDraft, CronWatch, CronWatchOptions, Duration, type ParsedSchedule, Store, StoredJobDefinition, composeAlert, cronwatch, formatDuration, memory, nextFire, parseDuration, parseSchedule };
+export { Alert, AlertDraft, Cronwatch, CronwatchOptions, Duration, type ParsedSchedule, Store, StoredJobDefinition, VERSION, composeAlert, cronwatch, formatDuration, memory, nextFire, parseDuration, parseSchedule };

package/dist/index.js

@@ -78,13 +78,46 @@ function beyondDates(at) {
 function readEnv(name) {
   return typeof process === "undefined" || !process.env ? void 0 : process.env[name];
 }
+function readSecretEnv(name) {
+  const value = readEnv(name);
+  return value === void 0 || value.trim() === "" ? void 0 : value;
+}
+function secretOption(value, what) {
+  if (value === void 0 || value === null) return value;
+  if (typeof value !== "string") {
+    throw new TypeError(`${what} must be a string, or null to opt out, not ${Array.isArray(value) ? "an array" : typeof value}`);
+  }
+  return value.trim() === "" ? void 0 : value;
+}
+function environment() {
+  if (typeof process === "undefined" || !process.env) return "";
+  for (const value of [process.env.CRONWATCH_ENV, process.env.APP_ENV, process.env.NODE_ENV]) {
+    const name = typeof value === "string" ? value.trim().toLowerCase() : "";
+    if (name === "") continue;
+    if (name === "prod") return "production";
+    if (name === "dev" || name === "local" || name === "test" || name === "testing") return "development";
+    return name;
+  }
+  return "";
+}
 function isDevelopment() {
-  if (typeof process === "undefined" || !process.env) return false;
-  const mode = process.env.NODE_ENV;
-  return mode === "development" || mode === "test";
+  return environment() === "development";
+}
+function isProduction() {
+  return environment() === "production";
 }
 var cache = /* @__PURE__ */ new Map();
 var crons = /* @__PURE__ */ new WeakMap();
+var never = /* @__PURE__ */ new WeakSet();
+var PROBE_FROM_MS = Date.UTC(2e3, 0, 1);
+function neverFires(cron) {
+  try {
+    return cron.nextRuns(1, new Date(PROBE_FROM_MS)).length === 0;
+  } catch (error) {
+    return error instanceof RangeError && /call stack/i.test(error.message);
+  }
+}
+var ONE_TIME_DATE = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/;
 var EARLY_SLACK_MS = 6e4;
 function parseSchedule(schedule, timezone) {
   const key = `${timezone ?? ""}|${schedule}`;
@@ -98,6 +131,10 @@ function parseSchedule(schedule, timezone) {
     if (everyMs < 1e3) throw new Error(`schedule "${schedule}" is shorter than one second`);
     parsed = { kind: "interval", source: text, everyMs };
   } else {
+    if (text.slice(1).includes(":")) {
+      const reason = ONE_TIME_DATE.test(text) ? "CronPattern: a one-time date is not supported" : "Invalid ISO8601 passed to timezone parser.";
+      throw new Error(`schedule "${schedule}" is not a cron expression or "every <duration>": ${reason}`);
+    }
     let cron;
     try {
       cron = new Cron(text, timezone ? { timezone } : {});
@@ -106,6 +143,7 @@ function parseSchedule(schedule, timezone) {
     }
     parsed = { kind: "cron", source: text, ...timezone ? { timezone } : {} };
     crons.set(parsed, cron);
+    if (neverFires(cron)) never.add(parsed);
   }
   cache.set(key, parsed);
   return parsed;
@@ -132,6 +170,7 @@ function countFrom(from) {
 function fireAfter(parsed, from) {
   const cron = crons.get(parsed);
   if (!cron) throw new Error(`schedule "${parsed.source}" was not made by parseSchedule`);
+  if (never.has(parsed)) return null;
   const start = countFrom(from);
   if (start === null) return null;
   let probe = start;
@@ -147,6 +186,7 @@ function fireAfter(parsed, from) {
 function firesBetween(parsed, from, to, limit) {
   const cron = crons.get(parsed);
   if (!cron) throw new Error(`schedule "${parsed.source}" was not made by parseSchedule`);
+  if (never.has(parsed)) return [];
   const out = [];
   const start = countFrom(from);
   if (start === null) return out;
@@ -281,16 +321,24 @@ function failureCount(state) {
 function emptyState(job) {
   return { job, open: {}, consecutiveFailures: 0, silencedUntil: null, lastAlertAt: null, pendingRecovery: [], undelivered: [] };
 }
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function normalizeState(state, job) {
-  if (!state) return emptyState(job);
+  if (!isObject(state)) return emptyState(job);
   const { sending, ...rest } = state;
+  const open = isObject(state.open) ? Object.fromEntries(Object.entries(state.open).filter(([, at]) => typeof at === "number")) : {};
+  const number = (value) => typeof value === "number" ? value : null;
+  const list = (value) => Array.isArray(value) ? value : [];
   return {
     ...emptyState(job),
     ...rest,
-    open: { ...state.open },
+    open,
     consecutiveFailures: failureCount(state),
-    pendingRecovery: [...state.pendingRecovery ?? []],
-    undelivered: [...state.undelivered ?? []],
+    silencedUntil: number(state.silencedUntil),
+    lastAlertAt: number(state.lastAlertAt),
+    pendingRecovery: list(state.pendingRecovery).filter((c) => typeof c === "string"),
+    undelivered: list(state.undelivered).filter((alert) => isObject(alert)),
     ...Array.isArray(sending) && sending.length > 0 ? { sending: [...sending] } : {}
   };
 }
@@ -494,8 +542,12 @@ function applySilence(previous, evaluation, now) {
   return { state: muteOpens(previous, evaluation.state), alerts: [] };
 }
 function staleAlert(alert, state) {
-  if (alert.type === "recovered") return alert.details.after.some((condition) => state.open[condition] !== void 0);
-  return state.open[alert.type] !== alert.at;
+  if (alert.type === "recovered") {
+    const after2 = isObject(alert.details) ? alert.details.after : void 0;
+    if (!Array.isArray(after2)) return true;
+    return after2.some((condition) => typeof condition !== "string" || state.open[condition] !== void 0);
+  }
+  return typeof alert.at !== "number" || state.open[alert.type] !== alert.at;
 }
 function jobHealth(def, lastRun, state, now) {
   const open = openConditions(state);
@@ -808,6 +860,15 @@ function checkExpectation(expect, output) {
   }
   return ok ? null : "Output did not pass the expect() check";
 }
+function readStoredJob(stored) {
+  const definition = stored.definition;
+  if (typeof definition !== "object" || definition === null || Array.isArray(definition)) {
+    return { job: { ...stored, definition: { name: stored.name } }, readable: false };
+  }
+  const read = { ...definition };
+  if ("tags" in read && !(Array.isArray(read.tags) && read.tags.every((tag) => typeof tag === "string"))) delete read.tags;
+  return { job: { ...stored, definition: read }, readable: true };
+}
 
 // src/routes/escape.ts
 function escapeHtml(value) {
@@ -1579,12 +1640,18 @@ function jobPage(job, runs, now, base, complete = true) {
   return layout(`${job.name}: CronWatch`, body, base, { refresh: 60 });
 }
 function messagePage(title, message, base, signIn = false) {
-  const form = signIn ? `<form class="signin" method="get" action="${h(base)}/"><label for="token">Token</label><input id="token" name="token" type="password" autocomplete="current-password" autocapitalize="off" spellcheck="false" required><button class="primary" type="submit">Sign in</button></form>` : "";
+  const form = signIn ? `<form class="signin" method="post" action="${h(base)}/signin"><label for="token">Token</label><input id="token" name="token" type="password" autocomplete="current-password" autocapitalize="off" spellcheck="false" required><button class="primary" type="submit">Sign in</button></form>` : "";
   return layout(title, `<header class="top">${brand(base)}</header><main class="message"><h1>${h(title)}</h1><p>${h(message)}</p>${form}</main>`, base);
 }
 
+// src/version.ts
+var VERSION = "0.11.0";
+var API_VERSION = 1;
+
 // src/routes/index.ts
 var COOKIE = "cronwatch_token";
+var LIBRARY = "@cronwatch/sdk";
+var LANGUAGE = "typescript";
 async function cookieValue(token) {
   const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(`cronwatch-cookie:${token}`));
   return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
@@ -1668,6 +1735,20 @@ function forwardedOrigin(request, url) {
     return url.origin;
   }
 }
+function bearerToken(header) {
+  const match = header === null ? null : /^Bearer\s+([\s\S]*)$/i.exec(header);
+  return match ? match[1] : null;
+}
+function signInReturn(referer, publicOrigin, base) {
+  if (referer === null || !referer.startsWith(publicOrigin + "/")) return `${base}/`;
+  let url;
+  try {
+    url = new URL(referer);
+  } catch {
+    return `${base}/`;
+  }
+  return url.searchParams.has("token") ? `${base}/` : referer;
+}
 function stripBase(pathname, base) {
   let path = pathname.startsWith(base) ? pathname.slice(base.length) : pathname;
   if (path === "") path = "/";
@@ -1710,8 +1791,12 @@ function runsLimit(value) {
   return Number.isFinite(n) ? Math.min(MAX_RUNS, Math.max(1, n)) : DEFAULT_RUNS;
 }
 function createRoutes(cw, options = {}) {
+  return cw.routes(options);
+}
+function buildRoutes(cw, options = {}) {
   const optedOut = options.token === null;
-  const configured = optedOut ? null : options.token || readEnv("CRONWATCH_TOKEN") || null;
+  const given = secretOption(options.token, "routes: token");
+  const configured = optedOut ? null : given || readSecretEnv("CRONWATCH_TOKEN") || null;
   const base = (options.basePath ?? "/cronwatch").replace(/\/+$/, "");
   const developing = isDevelopment();
   const fixedOrigin = configuredOrigin(options.origin);
@@ -1743,7 +1828,17 @@ function createRoutes(cw, options = {}) {
     if (method !== "GET" && method !== "HEAD" && crossSite(request, publicOrigin)) {
       return wantsHtml ? html(messagePage("Cross-site request refused", "Changes can only be made from the dashboard itself.", base), 403) : api({ ok: false, error: "Cross-site request refused" }, 403);
     }
-    const bearer = request.headers.get("authorization")?.replace(/^Bearer\s+/i, "") ?? null;
+    const bearer = bearerToken(request.headers.get("authorization"));
+    const signInCookie = async () => {
+      const secure = publicOrigin.startsWith("https:") ? "; Secure" : "";
+      return `${COOKIE}=${await expectedCookie(token)}; Path=${base || "/"}; HttpOnly; SameSite=Lax; Max-Age=${60 * 60 * 24 * 30}${secure}`;
+    };
+    const signInPage = () => generated ? html(messagePage("Sign in", "CRONWATCH_TOKEN is not set, so this development server made a token. The sign-in link is in the server log: open it once, or enter the token from it below, and this browser stays signed in.", base, true), 401) : html(messagePage("Sign in", "Enter your CRONWATCH_TOKEN and this browser stays signed in.", base, true), 401);
+    if (token && method === "POST" && path === "/signin") {
+      const sent = (await readBody(request)).token;
+      if (sent === void 0 || !constantTimeEqual(sent, token)) return signInPage();
+      return redirect(signInReturn(request.headers.get("referer"), publicOrigin, base), { "set-cookie": await signInCookie() });
+    }
     if (token) {
       const query = wantsHtml && method === "GET" ? url.searchParams.get("token") : null;
       const sent = readCookie(request, COOKIE);
@@ -1751,17 +1846,12 @@ function createRoutes(cw, options = {}) {
       const cronSecretOk = isCheck && bearer !== null && cw.cronSecret !== null && constantTimeEqual(bearer, cw.cronSecret);
       const tokenOk = bearer !== null ? constantTimeEqual(bearer, token) : query !== null ? constantTimeEqual(query, token) : sent !== null && constantTimeEqual(sent, await expectedCookie(token));
       if (!cronSecretOk && !tokenOk) {
-        if (generated) {
-          return wantsHtml ? html(messagePage("Sign in", "CRONWATCH_TOKEN is not set, so this development server made a token. The sign-in link is in the server log: open it once and this browser stays signed in.", base, true), 401) : api({ ok: false, error: "Unauthorized: CRONWATCH_TOKEN is not set, so this development server made a token; it is in the server log" }, 401);
-        }
-        return wantsHtml ? html(messagePage("Sign in", `Open this page with ?token=<your CRONWATCH_TOKEN> once and it will stay signed in.`, base, true), 401) : api({ ok: false, error: "Unauthorized" }, 401);
+        if (wantsHtml) return signInPage();
+        return generated ? api({ ok: false, error: "Unauthorized: CRONWATCH_TOKEN is not set, so this development server made a token; it is in the server log" }, 401) : api({ ok: false, error: "Unauthorized" }, 401);
       }
       if (query !== null) {
         url.searchParams.delete("token");
-        const secure = publicOrigin.startsWith("https:") ? "; Secure" : "";
-        return redirect(url.pathname + (url.search || ""), {
-          "set-cookie": `${COOKIE}=${await expectedCookie(token)}; Path=${base || "/"}; HttpOnly; SameSite=Lax; Max-Age=${60 * 60 * 24 * 30}${secure}`
-        });
+        return redirect(url.pathname + (url.search || ""), { "set-cookie": await signInCookie() });
       }
     }
     const redirectBack = () => {
@@ -1812,6 +1902,9 @@ function createRoutes(cw, options = {}) {
     }
     if (parts[0] === "api") {
       const rest = parts.slice(1);
+      if (method === "GET" && rest.length === 0) {
+        return api({ ok: true, library: LIBRARY, language: LANGUAGE, version: VERSION, api: API_VERSION });
+      }
       if (method === "GET" && rest[0] === "jobs" && rest.length === 1) {
         return api({ ok: true, jobs: await cw.jobs() });
       }
@@ -1839,9 +1932,13 @@ function createRoutes(cw, options = {}) {
           } catch (e) {
             return api({ ok: false, error: e.message }, 400);
           }
-          return api({ ok: true, state: await cw.silence(name, duration) });
+          await cw.silence(name, duration);
+          return api({ ok: true, job: await cw.jobSummary(name) });
+        }
+        if (rest[2] === "unsilence") {
+          await cw.unsilence(name);
+          return api({ ok: true, job: await cw.jobSummary(name) });
         }
-        if (rest[2] === "unsilence") return api({ ok: true, state: await cw.unsilence(name) });
       }
       if (rest[0] === "check" && rest.length === 1) {
         if (method === "GET" && bearer === null) {
@@ -2049,7 +2146,7 @@ function validateDefinition(def) {
 function sameState(a, b) {
   return JSON.stringify(a) === JSON.stringify(b);
 }
-var CronWatch = class {
+var Cronwatch = class {
   store;
   alerts;
   triage;
@@ -2062,7 +2159,7 @@ var CronWatch = class {
   /** cronSecret was passed as null: handlers may run without a secret. */
   secretOptOut;
   redact;
-  /** "check": queue alerts for another process's check instead of sending them. See CronWatchOptions.deliver. */
+  /** "check": queue alerts for another process's check instead of sending them. See CronwatchOptions.deliver. */
   deferDelivery;
   defaults;
   definitions = /* @__PURE__ */ new Map();
@@ -2081,12 +2178,15 @@ var CronWatch = class {
   usingDefaultStore = false;
   warnedNoSecret = false;
   warnedDeferredStart = false;
+  /** Stored jobs read with a definition that was not a JSON object (see readJob). */
+  unreadable = /* @__PURE__ */ new WeakSet();
   constructor(options = {}) {
     this.store = options.store ?? (this.usingDefaultStore = true, memory());
     this.alerts = options.alerts ?? [consoleChannel()];
     this.triage = options.triage;
     this.sources = options.sources ?? [];
-    const secret = options.cronSecret === void 0 ? readEnv("CRON_SECRET") : options.cronSecret;
+    const given = secretOption(options.cronSecret, "cronSecret");
+    const secret = options.cronSecret === void 0 ? readSecretEnv("CRON_SECRET") : given;
     this.cronSecret = secret ? secret : null;
     this.secretOptOut = options.cronSecret === null;
     this.retentionMs = parseDuration(options.retention ?? "30d", "retention");
@@ -2147,7 +2247,7 @@ var CronWatch = class {
         return outcome.result;
       },
       handler(fn, options) {
-        const own = options?.secret;
+        const own = secretOption(options?.secret, "handler: secret");
         const secret = own === null ? null : own ? own : self.cronSecret;
         const optedOut = own === null || !own && self.secretOptOut;
         return async (request) => {
@@ -2199,7 +2299,7 @@ var CronWatch = class {
     if (!this.ready) {
       this.ready = (async () => {
         if (this.store.init) await this.store.init();
-        if (this.usingDefaultStore && readEnv("NODE_ENV") === "production") {
+        if (this.usingDefaultStore && isProduction()) {
           console.warn("[cronwatch] using the in-memory store: runs and state are lost on restart. Pass a store from @cronwatch/sdk/sqlite or @cronwatch/sdk/postgres.");
         }
       })().catch((error) => {
@@ -2249,13 +2349,23 @@ var CronWatch = class {
     const jobs = await this.store.listJobs();
     const listed = new Set(jobs.map((job) => job.name));
     const missing = [...this.definitions.values()].filter((definition) => !listed.has(definition.name));
-    if (missing.length === 0) return jobs;
+    if (missing.length === 0) return jobs.map((job) => this.readJob(job));
     for (const definition of missing) {
       if (this.definitions.get(definition.name) !== definition) continue;
       this.synced.delete(definition.name);
       await this.sync(definition);
     }
-    return this.store.listJobs();
+    return (await this.store.listJobs()).map((job) => this.readJob(job));
+  }
+  /** A stored job read leniently (readStoredJob); one whose definition is unreadable is remembered, so that evaluating it throws. */
+  readJob(stored) {
+    const { job, readable } = readStoredJob(stored);
+    if (!readable) this.unreadable.add(job);
+    return job;
+  }
+  /** Throws for a job whose stored definition was not a JSON object: reported, and shown as failing, while the others carry on. */
+  evaluable(stored) {
+    if (this.unreadable.has(stored)) throw new Error(`job "${stored.name}": its stored definition is not a JSON object`);
   }
   /**
    * Runs `fn` after every earlier state update for the same job has settled,
@@ -2674,6 +2784,10 @@ ${id}`;
   async recordRun(input, options = {}) {
     const declared = this.definitions.get(input.job);
     if (!declared) throw new Error(`recordRun: job "${input.job}" is not declared; call job() first`);
+    if (typeof input.id !== "string" || input.id.length === 0 || input.id.length > MAX_RUN_ID) {
+      const got = typeof input.id === "string" ? `${input.id.length} characters` : typeof input.id;
+      throw new Error(`recordRun: run ids must be 1 to ${MAX_RUN_ID} characters (got ${got}; job "${input.job}")`);
+    }
     if (input.id.includes("\0")) throw new Error(`recordRun: run ids cannot contain a NUL character (job "${input.job}")`);
     for (const [metric, value] of Object.entries(input.metrics ?? {})) {
       if (typeof value !== "number" || !Number.isFinite(value)) {
@@ -2802,7 +2916,10 @@ ${id}`;
     for (const listed of await this.store.runningRuns()) {
       try {
         const declared = this.definitions.get(listed.job);
-        const definition = declared ? toStored(declared) : (await this.store.getJob(listed.job))?.definition;
+        const found = declared ? null : await this.store.getJob(listed.job);
+        const stored = found ? this.readJob(found) : null;
+        if (stored) this.evaluable(stored);
+        const definition = declared ? toStored(declared) : stored?.definition;
         if (!definition || !isStuck(definition, listed, now)) continue;
         const run = await this.store.getRun(listed.id);
         if (!run || run.status !== "running" || run.job !== listed.job) continue;
@@ -2821,6 +2938,7 @@ ${id}`;
     const retries = { spentMs: 0 };
     for (const stored of await this.storedJobs()) {
       try {
+        this.evaluable(stored);
         const recent = await this.store.listRuns(stored.name, BASELINE_WINDOW);
         let nextExpectedAt = null;
         const { state, result: held } = await this.updateState(stored.name, (previous) => {
@@ -2856,6 +2974,7 @@ ${id}`;
     let recent = [];
     try {
       recent = await this.store.listRuns(stored.name, Math.max(runs, BASELINE_WINDOW));
+      this.evaluable(stored);
       const state = await this.readState(stored.name);
       const { nextExpectedAt } = onCheck(stored.definition, stored, recent[0] ?? null, state, now);
       return { job: summarize(stored, recent, state, nextExpectedAt, now), runs: recent.slice(0, runs) };
@@ -2890,7 +3009,7 @@ ${id}`;
     if (definition) await this.sync(definition, true);
     const stored = await this.store.getJob(name);
     if (!stored) return null;
-    return (await this.snapshot(stored, this.now(), 0)).job;
+    return (await this.snapshot(this.readJob(stored), this.now(), 0)).job;
   }
   /** A job's runs, newest first. `limit` is a whole number from 1 to 500. */
   async runs(name, limit = 50) {
@@ -2937,21 +3056,27 @@ ${id}`;
     this.synced.delete(name);
     await this.store.deleteJob(name);
   }
-  /** The dashboard and JSON API as fetch-style handlers. See createRoutes(). */
+  /**
+   * The dashboard and JSON API as fetch-style handlers: the one way to mount
+   * them. A Next.js app exports them from app/cronwatch/[[...path]]/route.ts:
+   *
+   *   export const { GET, POST, DELETE } = cw.routes();
+   */
   routes(options) {
-    return createRoutes(this, options);
+    return buildRoutes(this, options);
   }
   /**
    * Check on an interval, for long-running servers. Default every minute.
    * Not for serverless functions or Cloudflare Workers, where nothing runs
-   * between requests: call check() from a cron there instead.
+   * between requests: call check() from a cron there instead. (A job's
+   * start() opens a run; this starts the checks.)
    */
-  start(every = "1m") {
+  startChecking(every = "1m") {
     if (this.timer) return;
     const ms = Math.min(TIMER_MAX_MS, Math.max(5e3, parseDuration(every, "check interval")));
     if (this.deferDelivery && !this.warnedDeferredStart) {
       this.warnedDeferredStart = true;
-      console.warn('[cronwatch] start() was called with deliver: "check", so these checks send no alerts. Another process must run checks with deliver: "now" (the default) to send them.');
+      console.warn('[cronwatch] startChecking() was called with deliver: "check", so these checks send no alerts. Another process must run checks with deliver: "now" (the default) to send them.');
     }
     const tick = () => this.check().catch((e) => this.onError(e, "check"));
     this.timer = setInterval(tick, ms);
@@ -2962,6 +3087,15 @@ ${id}`;
     }, 1e3);
     if (typeof this.firstTick === "object" && "unref" in this.firstTick) this.firstTick.unref();
   }
+  /**
+   * startChecking(), under its former name.
+   * @deprecated Renamed `startChecking`, since a job's `start()` opens a run.
+   * This name still works through 1.x and goes in 2.0.
+   */
+  start(every = "1m") {
+    this.startChecking(every);
+  }
+  /** Stop the checks startChecking() began. */
   stop() {
     if (this.timer) clearInterval(this.timer);
     if (this.firstTick) clearTimeout(this.firstTick);
@@ -3074,9 +3208,10 @@ ${id}`;
   }
 };
 var RESERVED_RUN_ID_PREFIX = "pgcron:";
+var MAX_RUN_ID = 200;
 function checkRunId(job, id, method) {
-  if (typeof id !== "string" || id.length === 0 || id.length > 200) {
-    throw new Error(`job "${job}": ${method}() needs a run id of 1 to 200 characters (got ${typeof id === "string" ? `${id.length} characters` : typeof id})`);
+  if (typeof id !== "string" || id.length === 0 || id.length > MAX_RUN_ID) {
+    throw new Error(`job "${job}": ${method}() needs a run id of 1 to ${MAX_RUN_ID} characters (got ${typeof id === "string" ? `${id.length} characters` : typeof id})`);
   }
   if (id.includes("\0")) throw new Error(`job "${job}": ${method}() cannot take a run id containing a NUL character`);
   if (id.startsWith(RESERVED_RUN_ID_PREFIX)) {
@@ -3137,12 +3272,13 @@ function custom(name, send) {
     await send(alert);
   } };
 }
+var CronWatch = Cronwatch;
 
 // src/index.ts
 function cronwatch(options = {}) {
-  return new CronWatch(options);
+  return new Cronwatch(options);
 }
 
-export { CronWatch, composeAlert, consoleChannel, createRoutes, cronwatch, custom, formatDuration, memory, nextFire, parseDuration, parseSchedule };
+export { CronWatch, Cronwatch, VERSION, composeAlert, consoleChannel, createRoutes, cronwatch, custom, formatDuration, memory, nextFire, parseDuration, parseSchedule };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map