@cronwatch/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,219 @@
+import { S as Store, a as AlertChannel, T as TriageFn, D as Duration, J as JobOptions, b as JobDefinition, R as Run, C as CheckResult, c as JobSummary, d as JobState, A as Alert, e as Condition, f as StoredJobDefinition } from './types-BQ1P8z55.js';
+export { g as AlertType, E as ExpectRule, h as JobHealth, i as RunStatus, j as StoredJob, k as TriageContext } from './types-BQ1P8z55.js';
+import { Cron } from 'croner';
+
+/** 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. With no token at all, the routes
+     * are open in development and refuse to serve in production.
+     *
+     * 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;
+}
+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). 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>;
+}
+interface CronWatchOptions {
+    /** Where jobs, runs and state live. Defaults to an in-memory store that forgets on restart. */
+    store?: Store;
+    /** Where alerts go. Defaults to the console. */
+    alerts?: AlertChannel[];
+    /** Adds a short diagnosis to failure alerts. See @cronwatch/sdk/anthropic. */
+    triage?: TriageFn;
+    /** Shared secret that handler() requests must carry. Defaults to process.env.CRON_SECRET. */
+    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">;
+    /** Called with anything that goes wrong outside a job: an alert channel failing, a triage timeout. */
+    onError?: (error: unknown, where: string) => void;
+    /** The clock. Tests use this. */
+    now?: () => number;
+}
+interface ExecuteResult<T> {
+    run: Run;
+    result: T | undefined;
+    error: unknown;
+    threw: boolean;
+}
+declare class CronWatch {
+    readonly store: Store;
+    readonly alerts: AlertChannel[];
+    readonly triage: TriageFn | undefined;
+    readonly cronSecret: string | null;
+    readonly retentionMs: number;
+    readonly now: () => number;
+    readonly onError: (error: unknown, where: string) => void;
+    private readonly defaults;
+    private readonly definitions;
+    private readonly synced;
+    private ready;
+    private checking;
+    private lastPruneAt;
+    private timer;
+    private usingDefaultStore;
+    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[];
+    private handle;
+    private ensureReady;
+    private sync;
+    /** Runs a function as a recorded run. Never throws for the job's own error; see `threw`. */
+    execute<T>(definition: JobDefinition, fn: JobFn<T>, trigger: string): Promise<ExecuteResult<T>>;
+    /**
+     * Look for missed and stuck runs across every job, send alerts, 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;
+    /** Every job the store knows about, with its health. Does not send alerts. */
+    jobs(): Promise<JobSummary[]>;
+    jobSummary(name: string): Promise<JobSummary | null>;
+    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>;
+    /** 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. */
+    start(every?: Duration): void;
+    stop(): void;
+    close(): Promise<void>;
+    private summarize;
+    /** Save an evaluation's state, honouring silence, and send its alerts. */
+    private settle;
+    private dispatch;
+}
+/** 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;
+
+declare function json(body: unknown, status?: number, headers?: Record<string, string>): Response;
+
+/**
+ * Keeps everything in process memory. The default when no store is given,
+ * good for tests and for trying the library out. State is gone on restart,
+ * so a missed run cannot be noticed across one.
+ */
+declare function memory(): Store;
+
+/**
+ * "15m" -> 900000. Accepts a plain number of milliseconds, and compound
+ * strings such as "1h30m". Whitespace between parts is fine.
+ */
+declare function parseDuration(value: Duration, label?: string): number;
+/** 90000 -> "1m 30s". For messages, not for parsing back. */
+declare function formatDuration(ms: number): string;
+/** "5 minutes ago", "in 2h". Relative to `now`. */
+declare function formatRelative(at: number, now: number): string;
+
+interface ParsedSchedule {
+    kind: "cron" | "interval";
+    source: string;
+    /** For intervals, the period in milliseconds. */
+    everyMs?: number;
+    cron?: Cron;
+}
+/**
+ * "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,
+ * like crontab. Vercel and GitHub Actions run their crons in UTC, so pass
+ * timezone: "UTC" for those.
+ */
+declare function parseSchedule(schedule: string, timezone?: string): ParsedSchedule;
+/** The next time the cron fires strictly after `from`. */
+declare function nextFire(parsed: ParsedSchedule, from: number, lastRunAt: number | null): number | null;
+/**
+ * The most recent time the cron fired at or before `now`, or null when the
+ * expression never fires in the year before `now`.
+ *
+ * croner only looks forward, so this searches: widen a window behind `now`
+ * until a fire time falls inside it, then bisect on the window's start for
+ * the latest start whose next fire is still at or before `now`.
+ */
+declare function previousFire(parsed: ParsedSchedule, now: number): number | null;
+
+interface AlertDraft {
+    type: Condition | "recovered";
+    run: Run | null;
+    details: Record<string, unknown>;
+}
+
+/** Turns a draft into the title and message every channel shows. */
+declare function composeAlert(draft: AlertDraft, def: StoredJobDefinition, now: number): Alert;
+
+/**
+ * Create a CronWatch client. One per app, at module level:
+ *
+ *   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;
+
+export { Alert, AlertChannel, CheckResult, Condition, CronWatch, type CronWatchOptions, Duration, type HandlerFn, type HandlerOptions, type JobContext, JobDefinition, type JobFn, type JobHandle, JobOptions, JobState, JobSummary, type Routes, type RoutesOptions, Run, Store, StoredJobDefinition, TriageFn, composeAlert, consoleChannel, createRoutes, cronwatch, custom, formatDuration, formatRelative, json, memory, nextFire, parseDuration, parseSchedule, previousFire };