@cronwatch/sdk 0.3.0 → 0.4.0

package/dist/client-B7bqnkI5.d.cts

@@ -0,0 +1,450 @@
+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-Ddq1MUPL.cjs';
+
+/** What a job function receives. */
+interface JobContext {
+    readonly name: string;
+    readonly runId: string;
+    readonly startedAt: number;
+    /** Aborts when the job's timeout elapses. Honour it if the work can stop. */
+    readonly signal: AbortSignal;
+    /** Append a line of output. Kept with the run, capped at 16 KB, shown in alerts and the dashboard. */
+    log(...parts: unknown[]): void;
+    /** Report a number for this run: tokens, cost, rows, anything. Watched against budgets and baselines. */
+    metric(name: string, value: number): void;
+    metrics(values: Record<string, number>): void;
+}
+
+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
+     * and serve them open everywhere, for example behind your own auth.
+     *
+     * The check endpoint (/api/check) also accepts the client's cronSecret, so
+     * a platform cron that sends `Authorization: Bearer <CRON_SECRET>` can
+     * trigger checks without knowing the dashboard token.
+     */
+    token?: string | null;
+    /** Where the routes are mounted, so links resolve. Default "/cronwatch". */
+    basePath?: string;
+    /**
+     * The public origin the dashboard is served from, such as
+     * "https://app.example.com", for an app behind a proxy whose request URLs
+     * carry an internal host or scheme. Used in place of the request URL's
+     * origin for the cross-site check on writes, the sign-in redirect (its
+     * cookie is Secure when this is https, and the redirect back after a form
+     * follows a Referer on this origin) and the development sign-in line.
+     * Takes precedence over trustProxy.
+     */
+    origin?: string;
+    /**
+     * Take the public origin from X-Forwarded-Proto and X-Forwarded-Host (the
+     * first value of each, falling back to the request URL's scheme or host
+     * for whichever is missing) when a request carries either. Only for an app
+     * whose proxy sets or overwrites both headers: a client can send them too.
+     * Default false, which ignores them.
+     */
+    trustProxy?: boolean;
+}
+type FetchHandler = (request: Request) => Promise<Response>;
+interface Routes {
+    handler: FetchHandler;
+    GET: FetchHandler;
+    POST: FetchHandler;
+    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();
+ */
+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;
+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.
+     */
+    secret?: string | null;
+}
+interface JobHandle {
+    readonly name: string;
+    readonly definition: JobDefinition;
+    /** Run the function now, recording the run. Rethrows whatever the function throws. */
+    run<T>(fn: JobFn<T>, options?: {
+        trigger?: string;
+    }): Promise<T>;
+    /** A fetch-style request handler (Next.js route, Hono, Bun, Deno) that runs the function and records the run. */
+    handler<T>(fn: HandlerFn<T>, options?: HandlerOptions): (request: Request) => Promise<Response>;
+    /**
+     * Record a running run now and finish it later, perhaps from another
+     * process (see resume()). Store failures go to onError; it never throws for
+     * them. A run that is never finished is marked stuck by the first check
+     * after the job's timeout.
+     */
+    start(options?: StartOptions): Promise<RunHandle>;
+    /** A handle on a run this job started elsewhere, by its id, so this process can log to it and finish it. */
+    resume(runId: string): Promise<RunHandle>;
+}
+interface StartOptions {
+    /** What started the run, as with run(). Default "start". */
+    trigger?: string;
+    /**
+     * Your own stable id for the run, such as an Inngest run id, 1 to 200
+     * characters, not starting with "pgcron:" (the pg_cron source's). A start
+     * with an id already recorded for this job records nothing and returns a
+     * handle on that run instead; an id recorded for another job throws,
+     * whether that job's start is still in flight or long done.
+     */
+    id?: string;
+}
+/**
+ * How a started run ended. `{ error }` is a failure, recorded like an error
+ * run() caught. Otherwise the run succeeded, and `result` (or a string
+ * passed on its own) is treated like the value run()'s function returns:
+ * a string is the output when nothing was logged, `expect` is checked, and
+ * a Response with status 400 or above is a failure.
+ */
+type RunOutcome = {
+    status?: "ok";
+    result?: unknown;
+} | {
+    error: unknown;
+};
+/** A run recorded by job.start() or found by job.resume(), to finish later. */
+interface RunHandle {
+    readonly id: string;
+    readonly job: string;
+    /** When the run started; null when a resumed run could not be read. */
+    readonly startedAt: number | null;
+    /** False once finished, and from the start for a resumed run that already finished or does not exist. */
+    readonly active: boolean;
+    /** Add a line of output. Kept in the handle until flush() or finish(). */
+    log(...parts: unknown[]): void;
+    /** Report a number for this run. A later value for the same name replaces an earlier one. */
+    metric(name: string, value: number): void;
+    metrics(values: Record<string, number>): void;
+    /**
+     * Append the lines and metrics added so far to the stored run, which must
+     * still be running and belong to this job. A read, change and write of the
+     * run's row, written only while it is still running: two processes
+     * appending to one run at the same moment can lose one's lines, but a flush
+     * never undoes a finish. The first 16 KB of everything flushed stay in the
+     * handle, so an expect rule at finish() sees an early line as run() would.
+     */
+    flush(): Promise<void>;
+    /**
+     * Finish the run, judge it like any other and send what that produces.
+     * Resolves to the run as recorded, or null when nothing was recorded: the
+     * run was already finished (here or elsewhere), was not found, or belongs
+     * to another job, which is reported to onError. When several processes
+     * finish one run, only the one whose write lands judges it. Never throws
+     * for the store: a store that fails is reported, nothing is recorded, and
+     * the handle stays active so finish() can be called again.
+     */
+    finish(outcome?: RunOutcome | string): Promise<Run | null>;
+    /** finish({ error }). */
+    fail(error: unknown): Promise<Run | null>;
+}
+/**
+ * What a Source may use of the client: declare jobs, read the store, and
+ * record runs it found elsewhere. A CronWatch is one.
+ */
+interface SourceHost {
+    /** Declare a job, as CronWatch.job(). Throws for an invalid name or option. */
+    job(name: string, options?: JobOptions): unknown;
+    /** See CronWatch.recordRun(). */
+    recordRun(run: Run, options?: RecordRunOptions): Promise<Alert[]>;
+    readonly store: Store;
+    readonly now: () => number;
+    readonly onError: (error: unknown, where: string) => void;
+}
+/**
+ * Runs that happen somewhere CronWatch cannot wrap, such as inside the
+ * database (see @cronwatch/sdk/pg-cron). check() calls sync() on each source
+ * first, so what it records is evaluated in the same check.
+ */
+interface Source {
+    name: string;
+    /** Declare the jobs and record their new runs. Returns the alerts recording them sent. */
+    sync(host: SourceHost): Promise<Alert[] | void>;
+}
+interface RecordRunOptions {
+    /** False stores the run without evaluating it, for history imported on first sight. Default true. */
+    evaluate?: boolean;
+}
+interface CronWatchOptions {
+    /** Where jobs, runs and state live. Defaults to an in-memory store that forgets on restart. */
+    store?: Store;
+    /**
+     * Where runs this process does not wrap come from, such as pg_cron jobs.
+     * Each is synced at the start of every check(); one that throws is
+     * reported to onError and the check carries on.
+     */
+    sources?: Source[];
+    /** Where alerts go. Defaults to the console. */
+    alerts?: AlertChannel[];
+    /** Adds a short diagnosis to every alert except recoveries. See @cronwatch/sdk/anthropic. */
+    triage?: TriageFn;
+    /**
+     * 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.
+     */
+    cronSecret?: string | null;
+    /** How long finished runs are kept. Default "30d". */
+    retention?: Duration;
+    /** Applied to every job unless the job sets its own. */
+    defaults?: Pick<JobOptions, "grace" | "timeout" | "timezone" | "failuresBeforeAlert">;
+    /**
+     * Applied to every run's output and error before it is stored, shown or
+     * sent to an alert channel or triage. The default blanks values that look
+     * like secrets (password=..., Authorization headers, URL credentials, bearer
+     * tokens, JWTs, PEM private keys, webhook URLs, AWS, GitHub, Slack, Stripe,
+     * Google and API key formats). Pass your own function, or false to keep
+     * output exactly as logged. A function that throws or returns something
+     * other than a string is reported to onError and the default is used.
+     */
+    redact?: ((text: string) => string) | false;
+    /**
+     * "now" (the default) sends alerts from this process. "check" sends nothing
+     * from here: each alert is queued in the store and the next check, in a
+     * process that delivers now, sends it (with triage). For a process that
+     * records runs but cannot reach the network, such as a sandboxed backup job.
+     * Its `alerts` and `triage` are not used.
+     */
+    deliver?: "now" | "check";
+    /** Called with anything that goes wrong outside a job: the store failing, an alert channel failing, a triage timeout. */
+    onError?: (error: unknown, where: string) => void;
+    /** The clock. Tests use this. */
+    now?: () => number;
+}
+declare class CronWatch {
+    readonly store: Store;
+    readonly alerts: AlertChannel[];
+    readonly triage: TriageFn | undefined;
+    readonly sources: Source[];
+    /** The secret handler() requests must carry, or null when none is set. */
+    readonly cronSecret: string | null;
+    readonly retentionMs: number;
+    readonly now: () => number;
+    readonly onError: (error: unknown, where: string) => void;
+    /** 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. */
+    private readonly deferDelivery;
+    private readonly defaults;
+    private readonly definitions;
+    private readonly synced;
+    /** The tail of each job's queue of state updates. See serial(). */
+    private readonly queues;
+    /** start() calls with an id still in flight, so two at once in this process record one run. */
+    private readonly starting;
+    private ready;
+    private checking;
+    private lastPruneAt;
+    private timer;
+    private firstTick;
+    private usingDefaultStore;
+    private warnedNoSecret;
+    private warnedDeferredStart;
+    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. */
+    run<T>(name: string, fn: JobFn<T>): Promise<T>;
+    run<T>(name: string, options: JobOptions, fn: JobFn<T>): Promise<T>;
+    /** The definitions declared in this process. */
+    definedJobs(): JobDefinition[];
+    /** A handle on a run started elsewhere, as job(name).resume(runId). The job must be declared in this process. */
+    resumeRun(name: string, runId: string): Promise<RunHandle>;
+    private handle;
+    private warnNoSecret;
+    /** onError, for places that must carry on even when onError itself throws. */
+    private report;
+    private ensureReady;
+    private sync;
+    /**
+     * 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
+     * the job's state over each other. Other processes are coordinated by
+     * updateState() instead.
+     */
+    private serial;
+    private readState;
+    /**
+     * Every read-modify-write of a job's state goes through here. In turn with
+     * this process's other updates to the job (serial()), it reads the state,
+     * asks `change` for the next one, and writes it with the version one
+     * higher, only if the stored version is still the one read. When another
+     * process wrote in between, the write is refused and it starts again from
+     * a fresh read, up to STATE_ATTEMPTS times. So `change` may run more than
+     * once and must only compute: whatever it returns from the attempt that
+     * was written is the result. Nothing is written when the state is
+     * unchanged. Returns the state as stored.
+     */
+    private updateState;
+    /** A conditional write, or for a store without compareAndSetState, a plain one that always succeeds. */
+    private writeState;
+    /**
+     * Runs a function as a recorded run. The function always runs, whatever
+     * the store is doing: store errors go to onError, and the result is the
+     * function's own outcome. Never throws for the job's own error; see `threw`.
+     */
+    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().
+     */
+    private conclude;
+    /**
+     * Writes a finished run and evaluates it. `recorded` says whether its
+     * start was written; if not, it is inserted now. Returns why nothing was
+     * recorded (another process finished the run first, say), or null. Throws
+     * when the store does, so a handle can be finished again. Shared by
+     * execute() and RunHandle.finish().
+     */
+    private recordFinish;
+    /** A conditional write (Store.updateRunIf), or for a store without one, a read then a plain write. */
+    private writeRunIf;
+    /**
+     * Writes a finished run over its stored row, only while that row is still
+     * running, or else still marked timeout by a check. Only the process whose
+     * write lands goes on to evaluate the run; for the others it returns why
+     * nothing was written. `lateAfterTimeout` means a check already counted
+     * the run as a stuck failure: a late failure must not count twice, while
+     * a late success still closes stuck and recovers. Throws when the store does.
+     */
+    private claimFinish;
+    /** job.start(): records a running run and returns a handle to finish it. See JobHandle.start. */
+    private startRun;
+    /**
+     * The start of execute() without the function: the run is inserted and
+     * missed and stuck close (onRunStart). A store that fails is reported and
+     * the handle inserts the finished run instead, as execute() does.
+     */
+    private recordStart;
+    /** job.resume() and cw.resumeRun(). A store that cannot be read is reported, and finish() reads it again. */
+    private resumeHandle;
+    /** A handle on a stored run. One still running, or marked timeout by a check, can be finished. */
+    private existingHandle;
+    /**
+     * The handle itself. `base` is the run as last known here, `recorded`
+     * whether its start is in the store, and `inactive` why finish() has
+     * nothing to do, or null. Lines and metrics wait in the handle until
+     * flush() or finish() merges them onto a fresh read of the stored run.
+     */
+    private runHandle;
+    /**
+     * Record a run that happened outside this process, for a Source. Its job
+     * must be declared with job() first. Runs are keyed by id: a new one is
+     * inserted, a stored one still running (or marked timeout by a check) is
+     * finished when this one is not running, and anything else is left alone,
+     * so recording the same run twice changes nothing. Finishing is
+     * conditional (see Store.updateRunIf): when two processes record the same
+     * finish, only the one whose write lands evaluates it, and the other
+     * reports it as already finished. A stored run of another job is left
+     * 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.
+     */
+    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.
+     */
+    private finishRun;
+    /**
+     * The runs before `run`, newest first, with up to BASELINE_WINDOW
+     * successful ones when the store has them. One small read normally; a
+     * larger one only when failures crowd the successes out of it.
+     */
+    private history;
+    /**
+     * Look for missed and stuck runs across every job, send alerts, retry
+     * alerts no channel accepted, and prune old runs. Call it from an interval
+     * (start()), a cron hitting the mounted routes, or by hand. Concurrent
+     * calls share one check.
+     */
+    check(): Promise<CheckResult>;
+    private runCheck;
+    /** A job's summary and its newest runs, without alerting. A job that cannot be evaluated is reported and shown as failing. */
+    private snapshot;
+    /** The summary of a job whose evaluation failed, from whatever can still be read. */
+    private unevaluable;
+    /** Every job the store knows about, with its health. Does not send alerts. */
+    jobs(): Promise<JobSummary[]>;
+    /** Every job's summary with its newest `limit` runs, read together. What the dashboard shows. */
+    jobsWithRuns(limit?: number): Promise<{
+        job: JobSummary;
+        runs: Run[];
+    }[]>;
+    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. */
+    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. */
+    forget(name: string): Promise<void>;
+    /** The dashboard and JSON API as fetch-style handlers. See createRoutes(). */
+    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.
+     */
+    start(every?: Duration): void;
+    stop(): void;
+    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.
+     */
+    private dispatch;
+    /**
+     * Send the alerts that no channel accepted last time, once each, oldest
+     * first. `state` is the job's state as this check left it: an alert that
+     * no longer describes it (staleAlert) is dropped instead. Retries across a
+     * check share RETRY_BUDGET_MS of wall-clock time; once it is spent the rest
+     * stay queued for the next check.
+     */
+    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.
+     */
+    private recordDelivery;
+    /** Send to every channel at once. True when at least one accepted it, or there are none. */
+    private deliver;
+    /** Sets alert.triage to the diagnosis, or to null when there is none, so it is tried once per alert. */
+    private addTriage;
+}
+/** Writes alerts to the console. The default channel. */
+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 };