@cronwatch/sdk 0.9.0 → 0.11.0

package/README.md

@@ -25,7 +25,7 @@ export const nightlyReport = cw.job("nightly-report", {
   schedule: "0 2 * * *",     // cron, "@hourly", or "every 15m"
   timezone: "UTC",
   grace: "15m",              // how late a start may be before it is missed
-  timeout: "30m",            // a run still going after this is stuck
+  timeout: "30m",            // a run still going after this is stuck (maxDuration: a finished run longer than it is slow)
   expect: "Report written",  // output must contain this, or the run failed
   budget: { cost: 2 },       // cost above 2 is over budget
 });
@@ -57,7 +57,7 @@ export const { GET, POST, DELETE } = cw.routes();
 await nightlyReport.run(async (job) => { /* ... */ });
 
 // Missed and stuck runs are found by the check: on an interval, or a cron hitting /cronwatch/api/check
-cw.start();
+cw.startChecking();
 ```
 
 ## What it catches
@@ -77,13 +77,13 @@ An `expect` RegExp runs in your process on the runtime's own engine and, like an
 
 | Import | |
 |---|---|
-| `@cronwatch/sdk` | `cronwatch`, `memory`, `custom`, `consoleChannel`, `createRoutes`, types |
+| `@cronwatch/sdk` | `cronwatch`, `Cronwatch`, `memory`, `custom`, `consoleChannel`, types; the dashboard is `cw.routes()` |
 | `@cronwatch/sdk/sqlite` | `sqlite({ path })`, needs `better-sqlite3` (and `@types/better-sqlite3` in TypeScript) |
 | `@cronwatch/sdk/postgres` | `postgres({ connectionString })`, needs `pg` (and `@types/pg` in TypeScript) |
 | `@cronwatch/sdk/d1` | `d1(env.DB)`, the Cloudflare D1 store; needs nothing |
 | `@cronwatch/sdk/pg-cron` | `pgCron(pool)`, a source that reads pg_cron jobs (Supabase Cron included) from Postgres on every check; pass it in `sources` |
 | `@cronwatch/sdk/node` | `toNodeHandler`, `toKoaMiddleware`, `toRequest`, `writeResponse`: fetch handlers on `http.createServer`, Express, Connect, NestJS and Koa |
-| `@cronwatch/sdk/slack`, `/discord`, `/webhook` | chat and signed webhook alert channels |
+| `@cronwatch/sdk/slack`, `/discord`, `/webhook` | chat and signed webhook alert channels; `/webhook` also has `signature(secret, body)` for a receiver |
 | `@cronwatch/sdk/resend`, `/postmark`, `/sendgrid`, `/mailgun`, `/ses` | email alert channels |
 | `@cronwatch/sdk/twilio` | SMS alerts |
 | `@cronwatch/sdk/sentry`, `/honeybadger`, `/datadog`, `/rollbar`, `/bugsnag`, `/newrelic` | alerts as events in an error tracker |

package/dist/anthropic.d.cts

@@ -1,5 +1,5 @@
 import Anthropic from '@anthropic-ai/sdk';
-import { n as TriageFn } from './types-Cz47Boks.cjs';
+import { o as TriageFn } from './types-DLnlUie8.cjs';
 
 interface AnthropicTriageOptions {
     /** Defaults to what the Anthropic SDK resolves: ANTHROPIC_API_KEY, or an `ant auth login` profile. */

package/dist/anthropic.d.ts

@@ -1,5 +1,5 @@
 import Anthropic from '@anthropic-ai/sdk';
-import { n as TriageFn } from './types-Cz47Boks.js';
+import { o as TriageFn } from './types-DLnlUie8.js';
 
 interface AnthropicTriageOptions {
     /** Defaults to what the Anthropic SDK resolves: ANTHROPIC_API_KEY, or an `ant auth login` profile. */

package/dist/bugsnag.d.cts

@@ -1,4 +1,4 @@
-import { A as Alert, a as AlertChannel } from './types-Cz47Boks.cjs';
+import { A as Alert, a as AlertChannel } from './types-DLnlUie8.cjs';
 
 /**
  * Bugsnag, Error Reporting API, payload version 5.

package/dist/bugsnag.d.ts

@@ -1,4 +1,4 @@
-import { A as Alert, a as AlertChannel } from './types-Cz47Boks.js';
+import { A as Alert, a as AlertChannel } from './types-DLnlUie8.js';
 
 /**
  * Bugsnag, Error Reporting API, payload version 5.

package/dist/{client-D35cfnNV.d.cts → client-CRMfhylq.d.cts}

@@ -1,4 +1,4 @@
-import { S as Store, a as AlertChannel, n as TriageFn, i as JobOptions, R as Run, A as Alert, D as Duration, J as JobDefinition, f as CheckResult, k as JobSummary, j as JobState } from './types-Cz47Boks.cjs';
+import { J as JobOptions, R as Run, A as Alert, S as Store, a as AlertChannel, o as TriageFn, D as Duration, h as JobDefinition, f as CheckResult, k as JobSummary, j as JobState } from './types-DLnlUie8.cjs';
 
 /** What a job function receives. */
 interface JobContext {
@@ -19,10 +19,14 @@ interface RoutesOptions {
      * Required to reach anything. Send it as `Authorization: Bearer <token>`,
      * or open the dashboard once with `?token=<token>` and a cookie is set.
      * Defaults to process.env.CRONWATCH_TOKEN (on Cloudflare Workers, which
-     * have no process, pass env.CRONWATCH_TOKEN); an empty string counts as unset.
-     * With no token while NODE_ENV is "development" or "test", the routes make
-     * a random one and print a sign-in link to the server log on their first
-     * request; with no token otherwise they answer 503. Pass `null` to opt out
+     * have no process, pass env.CRONWATCH_TOKEN); an empty string or one of
+     * only whitespace, given here or in the variable, counts as unset, and any
+     * other type (false, a number) throws.
+     * With no token in development (the first of CRONWATCH_ENV, APP_ENV and
+     * NODE_ENV that is set names "development", "dev", "local", "test" or
+     * "testing"), the routes make a random one and print a sign-in link to the
+     * server log on their first request; with no token otherwise they answer
+     * 503. Pass `null` to opt out
      * and serve them open everywhere, for example behind your own auth.
      *
      * The check endpoint (/api/check) also accepts the client's cronSecret, so
@@ -62,12 +66,11 @@ interface Routes {
     DELETE: FetchHandler;
 }
 /**
- * A fetch-style handler serving the dashboard and a small JSON API. Mount it
- * in a Next.js app at app/cronwatch/[[...path]]/route.ts:
- *
- *   export const { GET, POST, DELETE } = cw.routes();
+ * The dashboard and its JSON API for a client.
+ * @deprecated Use `cw.routes(options)`, the one way to mount the dashboard
+ * in every port. This name still works through 1.x and goes in 2.0.
  */
-declare function createRoutes(cw: CronWatch, options?: RoutesOptions): Routes;
+declare function createRoutes(cw: Cronwatch, options?: RoutesOptions): Routes;
 
 type JobFn<T> = (job: JobContext) => Promise<T> | T;
 type HandlerFn<T> = (job: JobContext, request: Request) => Promise<T> | T;
@@ -75,9 +78,12 @@ interface HandlerOptions {
     /**
      * Callers must send `Authorization: Bearer <secret>`. Defaults to the
      * client's cronSecret, which defaults to process.env.CRON_SECRET (what
-     * Vercel sends its cron requests with). An empty string counts as unset.
-     * With no secret at all the handler answers 503 unless NODE_ENV is
-     * "development" or "test". Pass null to allow anyone.
+     * Vercel sends its cron requests with). An empty string, or one of only
+     * whitespace, counts as unset; any other type (false, a number) throws.
+     * With no secret at all the handler answers 503 unless the app is in
+     * development (the first of CRONWATCH_ENV, APP_ENV and NODE_ENV that is
+     * set names "development", "dev", "local", "test" or "testing"). Pass
+     * null to allow anyone.
      */
     secret?: string | null;
 }
@@ -162,12 +168,21 @@ interface RunHandle {
 }
 /**
  * What a Source may use of the client: declare jobs, read the store, and
- * record runs it found elsewhere. A CronWatch is one.
+ * record runs it found elsewhere. A Cronwatch is one.
  */
 interface SourceHost {
-    /** Declare a job, as CronWatch.job(). Throws for an invalid name or option. */
+    /** Declare a job, as Cronwatch.job(). Throws for an invalid name or option. */
     job(name: string, options?: JobOptions): unknown;
-    /** See CronWatch.recordRun(). */
+    /**
+     * The definitions declared now, as Cronwatch.definedJobs(): a source reads
+     * it to declare again a job forgotten since (the dashboard's forget), whose
+     * definition has not changed. A host without it is taken to keep every
+     * job the source declared.
+     */
+    definedJobs?(): {
+        name: string;
+    }[];
+    /** See Cronwatch.recordRun(). */
     recordRun(run: Run, options?: RecordRunOptions): Promise<Alert[]>;
     readonly store: Store;
     readonly now: () => number;
@@ -187,7 +202,7 @@ interface RecordRunOptions {
     /** False stores the run without evaluating it, for history imported on first sight. Default true. */
     evaluate?: boolean;
 }
-interface CronWatchOptions {
+interface CronwatchOptions {
     /** Where jobs, runs and state live. Defaults to an in-memory store that forgets on restart. */
     store?: Store;
     /**
@@ -203,8 +218,9 @@ interface CronWatchOptions {
     /**
      * Shared secret that handler() requests must carry. Defaults to
      * process.env.CRON_SECRET (on Cloudflare Workers, which have no process,
-     * pass env.CRON_SECRET); an empty string counts as unset. Pass null to
-     * let handlers run without one.
+     * pass env.CRON_SECRET); an empty string or one of only whitespace, given
+     * here or in the variable, counts as unset. Pass null to let handlers run
+     * without one. Any other type (false, a number) throws.
      */
     cronSecret?: string | null;
     /** How long finished runs are kept. Default "30d". */
@@ -234,7 +250,7 @@ interface CronWatchOptions {
     /** The clock. Tests use this. */
     now?: () => number;
 }
-declare class CronWatch {
+declare class Cronwatch {
     readonly store: Store;
     readonly alerts: AlertChannel[];
     readonly triage: TriageFn | undefined;
@@ -247,7 +263,7 @@ declare class CronWatch {
     /** cronSecret was passed as null: handlers may run without a secret. */
     private readonly secretOptOut;
     private readonly 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. */
     private readonly deferDelivery;
     private readonly defaults;
     private readonly definitions;
@@ -266,7 +282,9 @@ declare class CronWatch {
     private usingDefaultStore;
     private warnedNoSecret;
     private warnedDeferredStart;
-    constructor(options?: CronWatchOptions);
+    /** Stored jobs read with a definition that was not a JSON object (see readJob). */
+    private readonly unreadable;
+    constructor(options?: CronwatchOptions);
     /** Declare a job. Call it once, at module level, and keep the handle. */
     job(name: string, options?: JobOptions): JobHandle;
     /** Run a job by name without keeping a handle. Defines it on first use. */
@@ -287,9 +305,27 @@ declare class CronWatch {
      * that replaced it, never its own over it, and one forgotten since writes
      * its own. The writes of one name take turns, in the order they were asked
      * for, so one still under way cannot land after a later one; and a name
-     * declared again while its write was under way is still to be written.
+     * declared again while its write was under way is still to be written. A
+     * name is marked as written only while that same declaration stands, so a
+     * forget that lands during the write (deleting the row after it) leaves
+     * the name to be written again, as does one forgotten before it.
+     *
+     * With `confirm`, as a run starts, a name already written is read back:
+     * another process may have forgotten the job since, and a job still
+     * declared here comes back on its next run.
      */
     private sync;
+    /**
+     * Every stored job, once each declaration has been written. A job declared
+     * here that the store no longer has was forgotten by another process after
+     * this one wrote it: it is written again, as its next run would, so it is
+     * checked and shown while any process still declares it.
+     */
+    private storedJobs;
+    /** A stored job read leniently (readStoredJob); one whose definition is unreadable is remembered, so that evaluating it throws. */
+    private readJob;
+    /** Throws for a job whose stored definition was not a JSON object: reported, and shown as failing, while the others carry on. */
+    private evaluable;
     /**
      * Runs `fn` after every earlier state update for the same job has settled,
      * so two runs (or a run and a check) in this process never read and write
@@ -321,7 +357,8 @@ declare class CronWatch {
     private execute;
     /**
      * Sets a finished run's status and error from how it ended, then redacts
-     * its output and error. Shared by execute() and RunHandle.finish().
+     * its output and error and caps them, in that order. Shared by execute()
+     * and RunHandle.finish().
      */
     private conclude;
     /**
@@ -374,17 +411,28 @@ declare class CronWatch {
      * alone and reported. A finished run is judged as if it had been wrapped
      * here (expect, failures, duration, budgets) and its output and error are
      * redacted the same way; one finishing after a check marked it timeout is
-     * judged only when it succeeded, as RunHandle.finish() does. Returns the
-     * alerts it sent.
+     * judged only when it succeeded, as RunHandle.finish() does. A metric that
+     * is not a finite number throws before anything is written, as
+     * job.metric() does. Returns the alerts it sent.
      */
     recordRun(input: Run, options?: RecordRunOptions): Promise<Alert[]>;
     /** recordRun() for a run already stored. */
     private recordOver;
     /**
      * Evaluate a finished run (ok, failed, or timed out by a check), already
-     * written, against the job's state and send what that produces. Never throws.
+     * written, against the job's state and send what that produces. The
+     * alerts are written with that state (see outbox()). Never throws.
      */
     private finishRun;
+    /**
+     * An evaluation as it is written: its drafts composed into alerts and held
+     * in the same state (holdAlerts), so the write that opens a condition also
+     * keeps its alerts, and a process that stops before sending them does not
+     * lose them. Called inside updateState(), so it only computes.
+     */
+    private outbox;
+    /** Reports alerts let go because a job's queue was full. */
+    private reportDropped;
     /**
      * The runs before `run`, newest first, with up to BASELINE_WINDOW
      * successful ones when the store has them. One small read normally; a
@@ -410,31 +458,62 @@ declare class CronWatch {
         job: JobSummary;
         runs: Run[];
     }[]>;
+    /** A job's summary, or null for one the store does not have. One declared here and forgotten elsewhere is written again, as storedJobs() does. */
     jobSummary(name: string): Promise<JobSummary | null>;
     /** A job's runs, newest first. `limit` is a whole number from 1 to 500. */
     runs(name: string, limit?: number): Promise<Run[]>;
     getRun(id: string): Promise<Run | null>;
-    /** Stop alerts for a job for a while. State keeps updating underneath. */
+    /**
+     * Stop alerts for a job for a while. State keeps updating underneath. The
+     * end is a whole millisecond, held at 2^53 - 1 (see silenceEnd).
+     */
     silence(name: string, duration: Duration): Promise<JobState>;
     unsilence(name: string): Promise<JobState>;
     /** Read, change and write one job's state, in turn with every other update to it. */
     private patchState;
-    /** Remove a job and its runs from the store. A job still declared in code comes back on its next run. */
+    /**
+     * Remove a job and its runs from the store. A job still declared in code
+     * comes back: here on its next run, and in any other process that declares
+     * it on its next run there, or at that process's next check or dashboard read.
+     */
     forget(name: string): Promise<void>;
-    /** 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?: RoutesOptions): Routes;
     /**
      * 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.)
+     */
+    startChecking(every?: Duration): void;
+    /**
+     * 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?: Duration): void;
+    /** Stop the checks startChecking() began. */
     stop(): void;
+    /**
+     * Stop the interval, wait for a check already under way (bounded by its
+     * own channel, triage and retry timeouts; what it throws was reported to
+     * whoever started it), then close the store, so that check neither writes
+     * after the store is closed nor loses the alerts it would queue.
+     */
     close(): Promise<void>;
     /**
-     * Compose, triage and send each draft. The state was saved before this
-     * (updateState), so a slow channel holds up nothing else; afterwards only
-     * the delivery fields are written back, onto a fresh read of the state.
+     * Triage and send each alert the outbox holds (see outbox()). The state,
+     * with the alerts in it, was saved before this, so a slow channel holds up
+     * nothing else; afterwards only the delivery fields are written back, onto
+     * a fresh read of the state, and the alerts leave `sending`. Triage is made
+     * here, never stored with the held alert: the write that opens a condition
+     * cannot wait for it, and a retry triages an alert that has none. With
+     * deliver: "check" the alerts were queued for a check elsewhere instead.
      */
     private dispatch;
     /**
@@ -447,8 +526,10 @@ declare class CronWatch {
     private retryUndelivered;
     /**
      * Mark delivered alerts done, drop stale ones, and keep failed ones for the
-     * next check. A failed alert replaces its stored copy, so a triage made on
-     * this attempt is kept. lastAlertAt moves only on a delivery.
+     * next check, taking them all out of `sending` (recordSent). A failed alert
+     * replaces its stored copy, so a triage made on this attempt is kept.
+     * lastAlertAt moves only on a delivery. When this write fails, alerts
+     * still in `sending` are retried once their lease runs out.
      */
     private recordDelivery;
     /** Send to every channel at once. True when at least one accepted it, or there are none. */
@@ -461,4 +542,15 @@ declare function consoleChannel(): AlertChannel;
 /** Wrap any function as an alert channel. */
 declare function custom(name: string, send: (alert: Alert) => Promise<void> | void): AlertChannel;
 
-export { type CronWatchOptions as C, type FetchHandler as F, type HandlerFn as H, type JobContext as J, type RecordRunOptions as R, type Source as S, CronWatch as a, type HandlerOptions as b, type JobFn as c, type JobHandle as d, type Routes as e, type RoutesOptions as f, type RunHandle as g, type RunOutcome as h, type SourceHost as i, type StartOptions as j, consoleChannel as k, createRoutes as l, custom as m };
+/**
+ * The client's former name.
+ * @deprecated Renamed `Cronwatch`, the spelling every port uses. This name
+ * still works through 1.x and goes in 2.0.
+ */
+declare const CronWatch: typeof Cronwatch;
+/** @deprecated Renamed `Cronwatch`; this name goes in 2.0. */
+type CronWatch = Cronwatch;
+/** @deprecated Renamed `CronwatchOptions`; this name goes in 2.0. */
+type CronWatchOptions = CronwatchOptions;
+
+export { type CronwatchOptions as C, type FetchHandler as F, type HandlerFn as H, type JobContext as J, type RecordRunOptions as R, type Source as S, Cronwatch as a, CronWatch as b, type CronWatchOptions as c, type HandlerOptions as d, type JobFn as e, type JobHandle as f, type Routes as g, type RoutesOptions as h, type RunHandle as i, type RunOutcome as j, type SourceHost as k, type StartOptions as l, consoleChannel as m, createRoutes as n, custom as o };