@cronwatch/sdk 0.1.0

package/dist/sqlite.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/stores/sqlite.ts"],"names":[],"mappings":"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","file":"sqlite.js","sourcesContent":["import Database from \"better-sqlite3\";\nimport { chmodSync, mkdirSync } from \"node:fs\";\nimport path from \"node:path\";\nimport type { JobState, Run, Store, StoredJob, StoredJobDefinition } from \"../types.js\";\n\nexport interface SqliteOptions {\n  /** File path. The directory is created if missing. \":memory:\" works too. */\n  path?: string;\n  /** Bring your own open better-sqlite3 database instead. */\n  database?: Database.Database;\n}\n\ninterface JobRow { name: string; definition: string; created_at: number; updated_at: number }\ninterface RunRow {\n  id: string; job: string; status: Run[\"status\"]; started_at: number; finished_at: number | null;\n  duration_ms: number | null; error: string | null; output: string | null; metrics: string; trigger: string;\n}\n\nfunction rowToRun(r: RunRow): Run {\n  return {\n    id: r.id, job: r.job, status: r.status, startedAt: r.started_at, finishedAt: r.finished_at,\n    durationMs: r.duration_ms, error: r.error, output: r.output, metrics: JSON.parse(r.metrics), trigger: r.trigger,\n  };\n}\n\n/**\n * Keeps everything in one SQLite file through better-sqlite3. The right\n * choice for a single server. WAL mode, so the app's reads never block on a\n * run being written.\n */\nexport function sqlite(options: SqliteOptions = {}): Store {\n  let db: Database.Database | null = options.database ?? null;\n  const file = options.path ?? \"./data/cronwatch.db\";\n\n  const open = (): Database.Database => {\n    if (db) return db;\n    if (file !== \":memory:\") {\n      mkdirSync(path.dirname(file), { recursive: true });\n    }\n    db = new Database(file);\n    if (file !== \":memory:\") {\n      try { chmodSync(file, 0o600); } catch { /* best effort: not every filesystem cares */ }\n    }\n    db.pragma(\"journal_mode = WAL\");\n    db.pragma(\"busy_timeout = 5000\");\n    db.pragma(\"synchronous = NORMAL\");\n    return db;\n  };\n\n  return {\n    async init() {\n      const d = open();\n      d.exec(`\n        CREATE TABLE IF NOT EXISTS cronwatch_jobs (\n          name TEXT PRIMARY KEY,\n          definition TEXT NOT NULL,\n          created_at INTEGER NOT NULL,\n          updated_at INTEGER NOT NULL\n        );\n        CREATE TABLE IF NOT EXISTS cronwatch_runs (\n          id TEXT PRIMARY KEY,\n          job TEXT NOT NULL,\n          status TEXT NOT NULL,\n          started_at INTEGER NOT NULL,\n          finished_at INTEGER,\n          duration_ms INTEGER,\n          error TEXT,\n          output TEXT,\n          metrics TEXT NOT NULL DEFAULT '{}',\n          trigger TEXT NOT NULL DEFAULT 'run'\n        );\n        CREATE INDEX IF NOT EXISTS cronwatch_runs_job_started ON cronwatch_runs (job, started_at DESC);\n        CREATE INDEX IF NOT EXISTS cronwatch_runs_running ON cronwatch_runs (status) WHERE status = 'running';\n        CREATE TABLE IF NOT EXISTS cronwatch_state (\n          job TEXT PRIMARY KEY,\n          state TEXT NOT NULL\n        );\n      `);\n    },\n    async upsertJob(definition: StoredJobDefinition, now: number) {\n      open().prepare(`\n        INSERT INTO cronwatch_jobs (name, definition, created_at, updated_at) VALUES (?, ?, ?, ?)\n        ON CONFLICT(name) DO UPDATE SET definition = excluded.definition, updated_at = excluded.updated_at\n      `).run(definition.name, JSON.stringify(definition), now, now);\n    },\n    async getJob(name) {\n      const r = open().prepare(\"SELECT * FROM cronwatch_jobs WHERE name = ?\").get(name) as JobRow | undefined;\n      return r ? { name: r.name, definition: JSON.parse(r.definition), createdAt: r.created_at, updatedAt: r.updated_at } : null;\n    },\n    async listJobs(): Promise<StoredJob[]> {\n      const rows = open().prepare(\"SELECT * FROM cronwatch_jobs ORDER BY name\").all() as JobRow[];\n      return rows.map((r) => ({ name: r.name, definition: JSON.parse(r.definition), createdAt: r.created_at, updatedAt: r.updated_at }));\n    },\n    async deleteJob(name) {\n      const d = open();\n      d.transaction(() => {\n        d.prepare(\"DELETE FROM cronwatch_runs WHERE job = ?\").run(name);\n        d.prepare(\"DELETE FROM cronwatch_state WHERE job = ?\").run(name);\n        d.prepare(\"DELETE FROM cronwatch_jobs WHERE name = ?\").run(name);\n      })();\n    },\n    async insertRun(run) {\n      open().prepare(`\n        INSERT INTO cronwatch_runs (id, job, status, started_at, finished_at, duration_ms, error, output, metrics, trigger)\n        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)\n      `).run(run.id, run.job, run.status, run.startedAt, run.finishedAt, run.durationMs, run.error, run.output, JSON.stringify(run.metrics), run.trigger);\n    },\n    async updateRun(run) {\n      open().prepare(`\n        UPDATE cronwatch_runs SET status = ?, finished_at = ?, duration_ms = ?, error = ?, output = ?, metrics = ? WHERE id = ?\n      `).run(run.status, run.finishedAt, run.durationMs, run.error, run.output, JSON.stringify(run.metrics), run.id);\n    },\n    async getRun(id) {\n      const r = open().prepare(\"SELECT * FROM cronwatch_runs WHERE id = ?\").get(id) as RunRow | undefined;\n      return r ? rowToRun(r) : null;\n    },\n    async listRuns(job, limit) {\n      const rows = open().prepare(\"SELECT * FROM cronwatch_runs WHERE job = ? ORDER BY started_at DESC, rowid DESC LIMIT ?\").all(job, limit) as RunRow[];\n      return rows.map(rowToRun);\n    },\n    async lastRun(job) {\n      const r = open().prepare(\"SELECT * FROM cronwatch_runs WHERE job = ? ORDER BY started_at DESC, rowid DESC LIMIT 1\").get(job) as RunRow | undefined;\n      return r ? rowToRun(r) : null;\n    },\n    async runningRuns() {\n      const rows = open().prepare(\"SELECT * FROM cronwatch_runs WHERE status = 'running' ORDER BY started_at\").all() as RunRow[];\n      return rows.map(rowToRun);\n    },\n    async getState(job) {\n      const r = open().prepare(\"SELECT state FROM cronwatch_state WHERE job = ?\").get(job) as { state: string } | undefined;\n      return r ? (JSON.parse(r.state) as JobState) : null;\n    },\n    async setState(state) {\n      open().prepare(`\n        INSERT INTO cronwatch_state (job, state) VALUES (?, ?)\n        ON CONFLICT(job) DO UPDATE SET state = excluded.state\n      `).run(state.job, JSON.stringify(state));\n    },\n    async prune(before) {\n      const info = open().prepare(\"DELETE FROM cronwatch_runs WHERE status != 'running' AND started_at < ?\").run(before);\n      return info.changes;\n    },\n    async close() {\n      if (db && !options.database) {\n        db.close();\n        db = null;\n      }\n    },\n  };\n}\n"]}

package/dist/types-BQ1P8z55.d.cts

@@ -0,0 +1,159 @@
+/**
+ * Everything public about a job, a run and an alert. Kept in one file so the
+ * store and alert adapters, which are built as separate entry points, share
+ * one definition.
+ */
+/** "15m", "1h30m", "90s", "2d", or a number of milliseconds. */
+type Duration = string | number;
+type ExpectRule = string | RegExp | ((output: string) => boolean);
+interface JobOptions {
+    /**
+     * When the job is supposed to run. A five or six field cron expression
+     * ("0 2 * * *"), a cron nickname ("@hourly"), or an interval ("every 5m").
+     * Leave it out for a job that has no fixed cadence: failures, duration and
+     * budgets are still watched, but nothing is ever reported as missed.
+     */
+    schedule?: string;
+    /** IANA timezone the cron expression is read in. Defaults to the process timezone. */
+    timezone?: string;
+    /** How late a run may start before it counts as missed. Default "10m". */
+    grace?: Duration;
+    /** A run still going after this long is treated as stuck and marked timeout. Default "1h". */
+    timeout?: Duration;
+    /**
+     * Alert when a successful run takes longer than this. Without it, a run is
+     * slow when it takes more than twice the p95 of recent runs (and over 10s),
+     * once there are at least five runs to compare against.
+     */
+    maxDuration?: Duration;
+    /**
+     * Ceilings for metrics reported with job.metric(). { cost: 2 } alerts when a
+     * run reports cost above 2. Metrics without a ceiling alert when a run
+     * reports more than three times the recent median, once there are at least
+     * five runs to compare against.
+     */
+    budget?: Record<string, number>;
+    /**
+     * A successful run must produce output that satisfies this, or it counts as
+     * failed. A string must appear in the output, a RegExp must match it, and a
+     * function must return true for it. Catches the job that exits cleanly and
+     * did nothing.
+     */
+    expect?: ExpectRule;
+    /** Alert on the Nth consecutive failure rather than the first. Default 1. */
+    failuresBeforeAlert?: number;
+    description?: string;
+    tags?: string[];
+}
+interface JobDefinition extends JobOptions {
+    name: string;
+}
+/**
+ * The definition as it is written to a store. `expect` cannot be serialised
+ * when it is a RegExp or a function, so it is described instead.
+ */
+interface StoredJobDefinition extends Omit<JobDefinition, "expect"> {
+    expect?: string;
+}
+interface StoredJob {
+    name: string;
+    definition: StoredJobDefinition;
+    createdAt: number;
+    updatedAt: number;
+}
+type RunStatus = "running" | "ok" | "failed" | "timeout";
+interface Run {
+    id: string;
+    job: string;
+    status: RunStatus;
+    /** Epoch milliseconds. */
+    startedAt: number;
+    finishedAt: number | null;
+    durationMs: number | null;
+    error: string | null;
+    /** Lines written with job.log(), or the string the job returned. Capped at 16 KB. */
+    output: string | null;
+    metrics: Record<string, number>;
+    /** What started the run: "handler", "run" or a value you pass. */
+    trigger: string;
+}
+type Condition = "missed" | "failed" | "stuck" | "slow" | "over_budget";
+interface JobState {
+    job: string;
+    /** Conditions currently open, with the time each one opened. */
+    open: Partial<Record<Condition, number>>;
+    consecutiveFailures: number;
+    silencedUntil: number | null;
+    lastAlertAt: number | null;
+}
+type AlertType = Condition | "recovered";
+interface Alert {
+    type: AlertType;
+    job: string;
+    definition: StoredJobDefinition;
+    run: Run | null;
+    /** One line, suitable as a notification title. */
+    title: string;
+    /** A few lines of plain text with the specifics. */
+    message: string;
+    details: Record<string, unknown>;
+    /** A short diagnosis from the triage function, when one is configured. */
+    triage?: string;
+    at: number;
+}
+interface AlertChannel {
+    name: string;
+    send(alert: Alert): Promise<void>;
+}
+interface Store {
+    /** Called once before first use. Create tables here. */
+    init?(): Promise<void>;
+    upsertJob(definition: StoredJobDefinition, now: number): Promise<void>;
+    getJob(name: string): Promise<StoredJob | null>;
+    listJobs(): Promise<StoredJob[]>;
+    deleteJob(name: string): Promise<void>;
+    insertRun(run: Run): Promise<void>;
+    updateRun(run: Run): Promise<void>;
+    getRun(id: string): Promise<Run | null>;
+    /** Newest first. */
+    listRuns(job: string, limit: number): Promise<Run[]>;
+    lastRun(job: string): Promise<Run | null>;
+    runningRuns(): Promise<Run[]>;
+    getState(job: string): Promise<JobState | null>;
+    setState(state: JobState): Promise<void>;
+    /** Delete finished runs that started before this time. Returns how many. */
+    prune(before: number): Promise<number>;
+    close?(): Promise<void>;
+}
+type JobHealth = "healthy" | "late" | "failing" | "stuck" | "silenced" | "never_ran";
+interface JobSummary {
+    name: string;
+    definition: StoredJobDefinition;
+    health: JobHealth;
+    open: Condition[];
+    lastRun: Run | null;
+    /** When the schedule says the next run is due. Null without a schedule. */
+    nextExpectedAt: number | null;
+    consecutiveFailures: number;
+    silencedUntil: number | null;
+    /** From the last twenty successful runs. */
+    stats: {
+        runs: number;
+        okRate: number;
+        p50Ms: number | null;
+        p95Ms: number | null;
+    };
+}
+interface CheckResult {
+    checkedAt: number;
+    jobs: JobSummary[];
+    alerts: Alert[];
+    pruned: number;
+}
+interface TriageContext {
+    alert: Alert;
+    recentRuns: Run[];
+}
+type TriageFn = (context: TriageContext) => Promise<string | null>;
+
+export type { Alert as A, CheckResult as C, Duration as D, ExpectRule as E, JobOptions as J, Run as R, Store as S, TriageFn as T, AlertChannel as a, JobDefinition as b, JobSummary as c, JobState as d, Condition as e, StoredJobDefinition as f, AlertType as g, JobHealth as h, RunStatus as i, StoredJob as j, TriageContext as k };

package/dist/types-BQ1P8z55.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Everything public about a job, a run and an alert. Kept in one file so the
+ * store and alert adapters, which are built as separate entry points, share
+ * one definition.
+ */
+/** "15m", "1h30m", "90s", "2d", or a number of milliseconds. */
+type Duration = string | number;
+type ExpectRule = string | RegExp | ((output: string) => boolean);
+interface JobOptions {
+    /**
+     * When the job is supposed to run. A five or six field cron expression
+     * ("0 2 * * *"), a cron nickname ("@hourly"), or an interval ("every 5m").
+     * Leave it out for a job that has no fixed cadence: failures, duration and
+     * budgets are still watched, but nothing is ever reported as missed.
+     */
+    schedule?: string;
+    /** IANA timezone the cron expression is read in. Defaults to the process timezone. */
+    timezone?: string;
+    /** How late a run may start before it counts as missed. Default "10m". */
+    grace?: Duration;
+    /** A run still going after this long is treated as stuck and marked timeout. Default "1h". */
+    timeout?: Duration;
+    /**
+     * Alert when a successful run takes longer than this. Without it, a run is
+     * slow when it takes more than twice the p95 of recent runs (and over 10s),
+     * once there are at least five runs to compare against.
+     */
+    maxDuration?: Duration;
+    /**
+     * Ceilings for metrics reported with job.metric(). { cost: 2 } alerts when a
+     * run reports cost above 2. Metrics without a ceiling alert when a run
+     * reports more than three times the recent median, once there are at least
+     * five runs to compare against.
+     */
+    budget?: Record<string, number>;
+    /**
+     * A successful run must produce output that satisfies this, or it counts as
+     * failed. A string must appear in the output, a RegExp must match it, and a
+     * function must return true for it. Catches the job that exits cleanly and
+     * did nothing.
+     */
+    expect?: ExpectRule;
+    /** Alert on the Nth consecutive failure rather than the first. Default 1. */
+    failuresBeforeAlert?: number;
+    description?: string;
+    tags?: string[];
+}
+interface JobDefinition extends JobOptions {
+    name: string;
+}
+/**
+ * The definition as it is written to a store. `expect` cannot be serialised
+ * when it is a RegExp or a function, so it is described instead.
+ */
+interface StoredJobDefinition extends Omit<JobDefinition, "expect"> {
+    expect?: string;
+}
+interface StoredJob {
+    name: string;
+    definition: StoredJobDefinition;
+    createdAt: number;
+    updatedAt: number;
+}
+type RunStatus = "running" | "ok" | "failed" | "timeout";
+interface Run {
+    id: string;
+    job: string;
+    status: RunStatus;
+    /** Epoch milliseconds. */
+    startedAt: number;
+    finishedAt: number | null;
+    durationMs: number | null;
+    error: string | null;
+    /** Lines written with job.log(), or the string the job returned. Capped at 16 KB. */
+    output: string | null;
+    metrics: Record<string, number>;
+    /** What started the run: "handler", "run" or a value you pass. */
+    trigger: string;
+}
+type Condition = "missed" | "failed" | "stuck" | "slow" | "over_budget";
+interface JobState {
+    job: string;
+    /** Conditions currently open, with the time each one opened. */
+    open: Partial<Record<Condition, number>>;
+    consecutiveFailures: number;
+    silencedUntil: number | null;
+    lastAlertAt: number | null;
+}
+type AlertType = Condition | "recovered";
+interface Alert {
+    type: AlertType;
+    job: string;
+    definition: StoredJobDefinition;
+    run: Run | null;
+    /** One line, suitable as a notification title. */
+    title: string;
+    /** A few lines of plain text with the specifics. */
+    message: string;
+    details: Record<string, unknown>;
+    /** A short diagnosis from the triage function, when one is configured. */
+    triage?: string;
+    at: number;
+}
+interface AlertChannel {
+    name: string;
+    send(alert: Alert): Promise<void>;
+}
+interface Store {
+    /** Called once before first use. Create tables here. */
+    init?(): Promise<void>;
+    upsertJob(definition: StoredJobDefinition, now: number): Promise<void>;
+    getJob(name: string): Promise<StoredJob | null>;
+    listJobs(): Promise<StoredJob[]>;
+    deleteJob(name: string): Promise<void>;
+    insertRun(run: Run): Promise<void>;
+    updateRun(run: Run): Promise<void>;
+    getRun(id: string): Promise<Run | null>;
+    /** Newest first. */
+    listRuns(job: string, limit: number): Promise<Run[]>;
+    lastRun(job: string): Promise<Run | null>;
+    runningRuns(): Promise<Run[]>;
+    getState(job: string): Promise<JobState | null>;
+    setState(state: JobState): Promise<void>;
+    /** Delete finished runs that started before this time. Returns how many. */
+    prune(before: number): Promise<number>;
+    close?(): Promise<void>;
+}
+type JobHealth = "healthy" | "late" | "failing" | "stuck" | "silenced" | "never_ran";
+interface JobSummary {
+    name: string;
+    definition: StoredJobDefinition;
+    health: JobHealth;
+    open: Condition[];
+    lastRun: Run | null;
+    /** When the schedule says the next run is due. Null without a schedule. */
+    nextExpectedAt: number | null;
+    consecutiveFailures: number;
+    silencedUntil: number | null;
+    /** From the last twenty successful runs. */
+    stats: {
+        runs: number;
+        okRate: number;
+        p50Ms: number | null;
+        p95Ms: number | null;
+    };
+}
+interface CheckResult {
+    checkedAt: number;
+    jobs: JobSummary[];
+    alerts: Alert[];
+    pruned: number;
+}
+interface TriageContext {
+    alert: Alert;
+    recentRuns: Run[];
+}
+type TriageFn = (context: TriageContext) => Promise<string | null>;
+
+export type { Alert as A, CheckResult as C, Duration as D, ExpectRule as E, JobOptions as J, Run as R, Store as S, TriageFn as T, AlertChannel as a, JobDefinition as b, JobSummary as c, JobState as d, Condition as e, StoredJobDefinition as f, AlertType as g, JobHealth as h, RunStatus as i, StoredJob as j, TriageContext as k };

package/dist/webhook.cjs

@@ -0,0 +1,24 @@
+'use strict';
+
+var crypto = require('crypto');
+
+// src/alerts/webhook.ts
+function webhook(options) {
+  if (!options.url) throw new Error("webhook() needs a url");
+  return {
+    name: "webhook",
+    async send(alert) {
+      const body = JSON.stringify(alert);
+      const headers = { "content-type": "application/json", "user-agent": "cronwatch", ...options.headers };
+      if (options.secret) {
+        headers["x-cronwatch-signature"] = `sha256=${crypto.createHmac("sha256", options.secret).update(body).digest("hex")}`;
+      }
+      const response = await fetch(options.url, { method: "POST", headers, body });
+      if (!response.ok) throw new Error(`Webhook ${options.url} answered ${response.status}`);
+    }
+  };
+}
+
+exports.webhook = webhook;
+//# sourceMappingURL=webhook.cjs.map
+//# sourceMappingURL=webhook.cjs.map

package/dist/webhook.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/alerts/webhook.ts"],"names":["createHmac"],"mappings":";;;;;AAmBO,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,EAAa,GAAG,QAAQ,OAAA,EAAQ;AAC5H,MAAA,IAAI,QAAQ,MAAA,EAAQ;AAClB,QAAA,OAAA,CAAQ,uBAAuB,CAAA,GAAI,CAAA,OAAA,EAAUA,iBAAA,CAAW,QAAA,EAAU,OAAA,CAAQ,MAAM,CAAA,CAAE,MAAA,CAAO,IAAI,CAAA,CAAE,MAAA,CAAO,KAAK,CAAC,CAAA,CAAA;AAAA,MAC9G;AACA,MAAA,MAAM,QAAA,GAAW,MAAM,KAAA,CAAM,OAAA,CAAQ,GAAA,EAAK,EAAE,MAAA,EAAQ,MAAA,EAAQ,OAAA,EAAS,IAAA,EAAM,CAAA;AAC3E,MAAA,IAAI,CAAC,QAAA,CAAS,EAAA,EAAI,MAAM,IAAI,KAAA,CAAM,CAAA,QAAA,EAAW,OAAA,CAAQ,GAAG,CAAA,UAAA,EAAa,QAAA,CAAS,MAAM,CAAA,CAAE,CAAA;AAAA,IACxF;AAAA,GACF;AACF","file":"webhook.cjs","sourcesContent":["import { createHmac } from \"node:crypto\";\nimport type { AlertChannel } from \"../types.js\";\n\nexport interface WebhookOptions {\n  url: string;\n  /** Extra request headers, for an Authorization header say. */\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\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 */\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\", ...options.headers };\n      if (options.secret) {\n        headers[\"x-cronwatch-signature\"] = `sha256=${createHmac(\"sha256\", options.secret).update(body).digest(\"hex\")}`;\n      }\n      const response = await fetch(options.url, { method: \"POST\", headers, body });\n      if (!response.ok) throw new Error(`Webhook ${options.url} answered ${response.status}`);\n    },\n  };\n}\n"]}

package/dist/webhook.d.cts

@@ -0,0 +1,20 @@
+import { a as AlertChannel } from './types-BQ1P8z55.cjs';
+
+interface WebhookOptions {
+    url: string;
+    /** Extra request headers, for an Authorization header say. */
+    headers?: Record<string, string>;
+    /**
+     * When set, each request carries `X-CronWatch-Signature: sha256=<hex>`,
+     * the HMAC-SHA256 of the raw body with this secret, so the receiver can
+     * verify it.
+     */
+    secret?: string;
+}
+/**
+ * POSTs the alert as JSON to any URL. The body is the Alert object:
+ * { type, job, title, message, run, details, triage, at, definition }.
+ */
+declare function webhook(options: WebhookOptions): AlertChannel;
+
+export { type WebhookOptions, webhook };

package/dist/webhook.d.ts

@@ -0,0 +1,20 @@
+import { a as AlertChannel } from './types-BQ1P8z55.js';
+
+interface WebhookOptions {
+    url: string;
+    /** Extra request headers, for an Authorization header say. */
+    headers?: Record<string, string>;
+    /**
+     * When set, each request carries `X-CronWatch-Signature: sha256=<hex>`,
+     * the HMAC-SHA256 of the raw body with this secret, so the receiver can
+     * verify it.
+     */
+    secret?: string;
+}
+/**
+ * POSTs the alert as JSON to any URL. The body is the Alert object:
+ * { type, job, title, message, run, details, triage, at, definition }.
+ */
+declare function webhook(options: WebhookOptions): AlertChannel;
+
+export { type WebhookOptions, webhook };

package/dist/webhook.js

@@ -0,0 +1,22 @@
+import { createHmac } from 'crypto';
+
+// src/alerts/webhook.ts
+function webhook(options) {
+  if (!options.url) throw new Error("webhook() needs a url");
+  return {
+    name: "webhook",
+    async send(alert) {
+      const body = JSON.stringify(alert);
+      const headers = { "content-type": "application/json", "user-agent": "cronwatch", ...options.headers };
+      if (options.secret) {
+        headers["x-cronwatch-signature"] = `sha256=${createHmac("sha256", options.secret).update(body).digest("hex")}`;
+      }
+      const response = await fetch(options.url, { method: "POST", headers, body });
+      if (!response.ok) throw new Error(`Webhook ${options.url} answered ${response.status}`);
+    }
+  };
+}
+
+export { webhook };
+//# sourceMappingURL=webhook.js.map
+//# sourceMappingURL=webhook.js.map

package/dist/webhook.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/alerts/webhook.ts"],"names":[],"mappings":";;;AAmBO,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,EAAa,GAAG,QAAQ,OAAA,EAAQ;AAC5H,MAAA,IAAI,QAAQ,MAAA,EAAQ;AAClB,QAAA,OAAA,CAAQ,uBAAuB,CAAA,GAAI,CAAA,OAAA,EAAU,UAAA,CAAW,QAAA,EAAU,OAAA,CAAQ,MAAM,CAAA,CAAE,MAAA,CAAO,IAAI,CAAA,CAAE,MAAA,CAAO,KAAK,CAAC,CAAA,CAAA;AAAA,MAC9G;AACA,MAAA,MAAM,QAAA,GAAW,MAAM,KAAA,CAAM,OAAA,CAAQ,GAAA,EAAK,EAAE,MAAA,EAAQ,MAAA,EAAQ,OAAA,EAAS,IAAA,EAAM,CAAA;AAC3E,MAAA,IAAI,CAAC,QAAA,CAAS,EAAA,EAAI,MAAM,IAAI,KAAA,CAAM,CAAA,QAAA,EAAW,OAAA,CAAQ,GAAG,CAAA,UAAA,EAAa,QAAA,CAAS,MAAM,CAAA,CAAE,CAAA;AAAA,IACxF;AAAA,GACF;AACF","file":"webhook.js","sourcesContent":["import { createHmac } from \"node:crypto\";\nimport type { AlertChannel } from \"../types.js\";\n\nexport interface WebhookOptions {\n  url: string;\n  /** Extra request headers, for an Authorization header say. */\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\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 */\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\", ...options.headers };\n      if (options.secret) {\n        headers[\"x-cronwatch-signature\"] = `sha256=${createHmac(\"sha256\", options.secret).update(body).digest(\"hex\")}`;\n      }\n      const response = await fetch(options.url, { method: \"POST\", headers, body });\n      if (!response.ok) throw new Error(`Webhook ${options.url} answered ${response.status}`);\n    },\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "@cronwatch/sdk",
+  "version": "0.1.0",
+  "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": {
+    "type": "git",
+    "url": "git+https://github.com/phillips-jon/cronwatch.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://cronwatch.dev",
+  "keywords": [
+    "cron",
+    "monitoring",
+    "scheduled jobs",
+    "heartbeat",
+    "vercel cron",
+    "nextjs",
+    "agents",
+    "mcp"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    },
+    "./sqlite": {
+      "types": "./dist/sqlite.d.ts",
+      "import": "./dist/sqlite.js",
+      "require": "./dist/sqlite.cjs",
+      "default": "./dist/sqlite.js"
+    },
+    "./postgres": {
+      "types": "./dist/postgres.d.ts",
+      "import": "./dist/postgres.js",
+      "require": "./dist/postgres.cjs",
+      "default": "./dist/postgres.js"
+    },
+    "./slack": {
+      "types": "./dist/slack.d.ts",
+      "import": "./dist/slack.js",
+      "require": "./dist/slack.cjs",
+      "default": "./dist/slack.js"
+    },
+    "./discord": {
+      "types": "./dist/discord.d.ts",
+      "import": "./dist/discord.js",
+      "require": "./dist/discord.cjs",
+      "default": "./dist/discord.js"
+    },
+    "./webhook": {
+      "types": "./dist/webhook.d.ts",
+      "import": "./dist/webhook.js",
+      "require": "./dist/webhook.cjs",
+      "default": "./dist/webhook.js"
+    },
+    "./anthropic": {
+      "types": "./dist/anthropic.d.ts",
+      "import": "./dist/anthropic.js",
+      "require": "./dist/anthropic.cjs",
+      "default": "./dist/anthropic.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "TZ=UTC node --import tsx --test test/*.test.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "croner": "^10.0.1"
+  },
+  "peerDependencies": {
+    "better-sqlite3": ">=9",
+    "pg": ">=8"
+  },
+  "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.127.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^20.19.0",
+    "@types/pg": "^8.15.0",
+    "better-sqlite3": "^13.0.3",
+    "pg": "^8.23.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}