@cronwatch/sdk 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +8 -7
- package/dist/anthropic.d.cts +1 -1
- package/dist/anthropic.d.ts +1 -1
- package/dist/bugsnag.cjs +108 -0
- package/dist/bugsnag.cjs.map +1 -0
- package/dist/bugsnag.d.cts +26 -0
- package/dist/bugsnag.d.ts +26 -0
- package/dist/bugsnag.js +106 -0
- package/dist/bugsnag.js.map +1 -0
- package/dist/client-B7bqnkI5.d.cts +450 -0
- package/dist/client-pmqH3apS.d.ts +450 -0
- package/dist/d1.cjs +214 -0
- package/dist/d1.cjs.map +1 -0
- package/dist/d1.d.cts +42 -0
- package/dist/d1.d.ts +42 -0
- package/dist/d1.js +212 -0
- package/dist/d1.js.map +1 -0
- package/dist/datadog.cjs +95 -0
- package/dist/datadog.cjs.map +1 -0
- package/dist/datadog.d.cts +24 -0
- package/dist/datadog.d.ts +24 -0
- package/dist/datadog.js +93 -0
- package/dist/datadog.js.map +1 -0
- package/dist/discord.cjs +2 -0
- package/dist/discord.cjs.map +1 -1
- package/dist/discord.d.cts +1 -1
- package/dist/discord.d.ts +1 -1
- package/dist/discord.js +2 -0
- package/dist/discord.js.map +1 -1
- package/dist/email-BJ-z_epD.d.cts +21 -0
- package/dist/email-_H0faCh3.d.ts +21 -0
- package/dist/honeybadger.cjs +101 -0
- package/dist/honeybadger.cjs.map +1 -0
- package/dist/honeybadger.d.cts +23 -0
- package/dist/honeybadger.d.ts +23 -0
- package/dist/honeybadger.js +99 -0
- package/dist/honeybadger.js.map +1 -0
- package/dist/index.cjs +692 -124
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +5 -228
- package/dist/index.d.ts +5 -228
- package/dist/index.js +692 -124
- package/dist/index.js.map +1 -1
- package/dist/mailgun.cjs +115 -0
- package/dist/mailgun.cjs.map +1 -0
- package/dist/mailgun.d.cts +21 -0
- package/dist/mailgun.d.ts +21 -0
- package/dist/mailgun.js +113 -0
- package/dist/mailgun.js.map +1 -0
- package/dist/newrelic.cjs +88 -0
- package/dist/newrelic.cjs.map +1 -0
- package/dist/newrelic.d.cts +25 -0
- package/dist/newrelic.d.ts +25 -0
- package/dist/newrelic.js +86 -0
- package/dist/newrelic.js.map +1 -0
- package/dist/node.cjs +191 -0
- package/dist/node.cjs.map +1 -0
- package/dist/node.d.cts +97 -0
- package/dist/node.d.ts +97 -0
- package/dist/node.js +186 -0
- package/dist/node.js.map +1 -0
- package/dist/pg-cron.cjs +286 -0
- package/dist/pg-cron.cjs.map +1 -0
- package/dist/pg-cron.d.cts +93 -0
- package/dist/pg-cron.d.ts +93 -0
- package/dist/pg-cron.js +280 -0
- package/dist/pg-cron.js.map +1 -0
- package/dist/postgres.cjs +33 -1
- package/dist/postgres.cjs.map +1 -1
- package/dist/postgres.d.cts +1 -1
- package/dist/postgres.d.ts +1 -1
- package/dist/postgres.js +33 -1
- package/dist/postgres.js.map +1 -1
- package/dist/postmark.cjs +106 -0
- package/dist/postmark.cjs.map +1 -0
- package/dist/postmark.d.cts +18 -0
- package/dist/postmark.d.ts +18 -0
- package/dist/postmark.js +104 -0
- package/dist/postmark.js.map +1 -0
- package/dist/resend.cjs +114 -0
- package/dist/resend.cjs.map +1 -0
- package/dist/resend.d.cts +16 -0
- package/dist/resend.d.ts +16 -0
- package/dist/resend.js +112 -0
- package/dist/resend.js.map +1 -0
- package/dist/rollbar.cjs +108 -0
- package/dist/rollbar.cjs.map +1 -0
- package/dist/rollbar.d.cts +20 -0
- package/dist/rollbar.d.ts +20 -0
- package/dist/rollbar.js +106 -0
- package/dist/rollbar.js.map +1 -0
- package/dist/sendgrid.cjs +114 -0
- package/dist/sendgrid.cjs.map +1 -0
- package/dist/sendgrid.d.cts +19 -0
- package/dist/sendgrid.d.ts +19 -0
- package/dist/sendgrid.js +112 -0
- package/dist/sendgrid.js.map +1 -0
- package/dist/sentry.cjs +130 -0
- package/dist/sentry.cjs.map +1 -0
- package/dist/sentry.d.cts +28 -0
- package/dist/sentry.d.ts +28 -0
- package/dist/sentry.js +127 -0
- package/dist/sentry.js.map +1 -0
- package/dist/ses.cjs +170 -0
- package/dist/ses.cjs.map +1 -0
- package/dist/ses.d.cts +25 -0
- package/dist/ses.d.ts +25 -0
- package/dist/ses.js +168 -0
- package/dist/ses.js.map +1 -0
- package/dist/slack.cjs +2 -0
- package/dist/slack.cjs.map +1 -1
- package/dist/slack.d.cts +1 -1
- package/dist/slack.d.ts +1 -1
- package/dist/slack.js +2 -0
- package/dist/slack.js.map +1 -1
- package/dist/sqlite.cjs +62 -5
- package/dist/sqlite.cjs.map +1 -1
- package/dist/sqlite.d.cts +1 -1
- package/dist/sqlite.d.ts +1 -1
- package/dist/sqlite.js +62 -5
- package/dist/sqlite.js.map +1 -1
- package/dist/twilio.cjs +168 -0
- package/dist/twilio.cjs.map +1 -0
- package/dist/twilio.d.cts +52 -0
- package/dist/twilio.d.ts +52 -0
- package/dist/twilio.js +162 -0
- package/dist/twilio.js.map +1 -0
- package/dist/{types-C1PyRjI5.d.cts → types-Ddq1MUPL.d.cts} +50 -4
- package/dist/{types-C1PyRjI5.d.ts → types-Ddq1MUPL.d.ts} +50 -4
- package/dist/webhook.cjs +11 -5
- package/dist/webhook.cjs.map +1 -1
- package/dist/webhook.d.cts +6 -3
- package/dist/webhook.d.ts +6 -3
- package/dist/webhook.js +11 -6
- package/dist/webhook.js.map +1 -1
- package/package.json +211 -5
package/dist/index.d.cts
CHANGED
|
@@ -1,230 +1,7 @@
|
|
|
1
|
-
import {
|
|
2
|
-
export {
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
interface JobContext {
|
|
6
|
-
readonly name: string;
|
|
7
|
-
readonly runId: string;
|
|
8
|
-
readonly startedAt: number;
|
|
9
|
-
/** Aborts when the job's timeout elapses. Honour it if the work can stop. */
|
|
10
|
-
readonly signal: AbortSignal;
|
|
11
|
-
/** Append a line of output. Kept with the run, capped at 16 KB, shown in alerts and the dashboard. */
|
|
12
|
-
log(...parts: unknown[]): void;
|
|
13
|
-
/** Report a number for this run: tokens, cost, rows, anything. Watched against budgets and baselines. */
|
|
14
|
-
metric(name: string, value: number): void;
|
|
15
|
-
metrics(values: Record<string, number>): void;
|
|
16
|
-
}
|
|
17
|
-
|
|
18
|
-
interface RoutesOptions {
|
|
19
|
-
/**
|
|
20
|
-
* Required to reach anything. Send it as `Authorization: Bearer <token>`,
|
|
21
|
-
* or open the dashboard once with `?token=<token>` and a cookie is set.
|
|
22
|
-
* Defaults to process.env.CRONWATCH_TOKEN; an empty string counts as unset.
|
|
23
|
-
* With no token, the routes answer only requests to localhost while NODE_ENV
|
|
24
|
-
* is "development" or "test", and 503 otherwise. Pass `null` to opt out and serve them
|
|
25
|
-
* open everywhere, for example behind your own auth.
|
|
26
|
-
*
|
|
27
|
-
* The check endpoint (/api/check) also accepts the client's cronSecret, so
|
|
28
|
-
* a platform cron that sends `Authorization: Bearer <CRON_SECRET>` can
|
|
29
|
-
* trigger checks without knowing the dashboard token.
|
|
30
|
-
*/
|
|
31
|
-
token?: string | null;
|
|
32
|
-
/** Where the routes are mounted, so links resolve. Default "/cronwatch". */
|
|
33
|
-
basePath?: string;
|
|
34
|
-
}
|
|
35
|
-
type FetchHandler = (request: Request) => Promise<Response>;
|
|
36
|
-
interface Routes {
|
|
37
|
-
handler: FetchHandler;
|
|
38
|
-
GET: FetchHandler;
|
|
39
|
-
POST: FetchHandler;
|
|
40
|
-
DELETE: FetchHandler;
|
|
41
|
-
}
|
|
42
|
-
/**
|
|
43
|
-
* A fetch-style handler serving the dashboard and a small JSON API. Mount it
|
|
44
|
-
* in a Next.js app at app/cronwatch/[[...path]]/route.ts:
|
|
45
|
-
*
|
|
46
|
-
* export const { GET, POST, DELETE } = cw.routes();
|
|
47
|
-
*/
|
|
48
|
-
declare function createRoutes(cw: CronWatch, options?: RoutesOptions): Routes;
|
|
49
|
-
|
|
50
|
-
type JobFn<T> = (job: JobContext) => Promise<T> | T;
|
|
51
|
-
type HandlerFn<T> = (job: JobContext, request: Request) => Promise<T> | T;
|
|
52
|
-
interface HandlerOptions {
|
|
53
|
-
/**
|
|
54
|
-
* Callers must send `Authorization: Bearer <secret>`. Defaults to the
|
|
55
|
-
* client's cronSecret, which defaults to process.env.CRON_SECRET (what
|
|
56
|
-
* Vercel sends its cron requests with). An empty string counts as unset.
|
|
57
|
-
* With no secret at all the handler answers 503 unless NODE_ENV is
|
|
58
|
-
* "development" or "test". Pass null to allow anyone.
|
|
59
|
-
*/
|
|
60
|
-
secret?: string | null;
|
|
61
|
-
}
|
|
62
|
-
interface JobHandle {
|
|
63
|
-
readonly name: string;
|
|
64
|
-
readonly definition: JobDefinition;
|
|
65
|
-
/** Run the function now, recording the run. Rethrows whatever the function throws. */
|
|
66
|
-
run<T>(fn: JobFn<T>, options?: {
|
|
67
|
-
trigger?: string;
|
|
68
|
-
}): Promise<T>;
|
|
69
|
-
/** A fetch-style request handler (Next.js route, Hono, Bun, Deno) that runs the function and records the run. */
|
|
70
|
-
handler<T>(fn: HandlerFn<T>, options?: HandlerOptions): (request: Request) => Promise<Response>;
|
|
71
|
-
}
|
|
72
|
-
interface CronWatchOptions {
|
|
73
|
-
/** Where jobs, runs and state live. Defaults to an in-memory store that forgets on restart. */
|
|
74
|
-
store?: Store;
|
|
75
|
-
/** Where alerts go. Defaults to the console. */
|
|
76
|
-
alerts?: AlertChannel[];
|
|
77
|
-
/** Adds a short diagnosis to every alert except recoveries. See @cronwatch/sdk/anthropic. */
|
|
78
|
-
triage?: TriageFn;
|
|
79
|
-
/**
|
|
80
|
-
* Shared secret that handler() requests must carry. Defaults to
|
|
81
|
-
* process.env.CRON_SECRET; an empty string counts as unset. Pass null to
|
|
82
|
-
* let handlers run without one.
|
|
83
|
-
*/
|
|
84
|
-
cronSecret?: string | null;
|
|
85
|
-
/** How long finished runs are kept. Default "30d". */
|
|
86
|
-
retention?: Duration;
|
|
87
|
-
/** Applied to every job unless the job sets its own. */
|
|
88
|
-
defaults?: Pick<JobOptions, "grace" | "timeout" | "timezone" | "failuresBeforeAlert">;
|
|
89
|
-
/**
|
|
90
|
-
* Applied to every run's output and error before it is stored, shown or
|
|
91
|
-
* sent to an alert channel or triage. The default blanks values that look
|
|
92
|
-
* like secrets (password=..., URL credentials, bearer tokens, AWS, GitHub,
|
|
93
|
-
* Slack, Stripe and API key formats). Pass your own function, or false to
|
|
94
|
-
* keep output exactly as logged.
|
|
95
|
-
*/
|
|
96
|
-
redact?: ((text: string) => string) | false;
|
|
97
|
-
/**
|
|
98
|
-
* "now" (the default) sends alerts from this process. "check" sends nothing
|
|
99
|
-
* from here: each alert is queued in the store and the next check, in a
|
|
100
|
-
* process that delivers now, sends it (with triage). For a process that
|
|
101
|
-
* records runs but cannot reach the network, such as a sandboxed backup job.
|
|
102
|
-
* Its `alerts` and `triage` are not used.
|
|
103
|
-
*/
|
|
104
|
-
deliver?: "now" | "check";
|
|
105
|
-
/** Called with anything that goes wrong outside a job: the store failing, an alert channel failing, a triage timeout. */
|
|
106
|
-
onError?: (error: unknown, where: string) => void;
|
|
107
|
-
/** The clock. Tests use this. */
|
|
108
|
-
now?: () => number;
|
|
109
|
-
}
|
|
110
|
-
declare class CronWatch {
|
|
111
|
-
readonly store: Store;
|
|
112
|
-
readonly alerts: AlertChannel[];
|
|
113
|
-
readonly triage: TriageFn | undefined;
|
|
114
|
-
/** The secret handler() requests must carry, or null when none is set. */
|
|
115
|
-
readonly cronSecret: string | null;
|
|
116
|
-
readonly retentionMs: number;
|
|
117
|
-
readonly now: () => number;
|
|
118
|
-
readonly onError: (error: unknown, where: string) => void;
|
|
119
|
-
/** cronSecret was passed as null: handlers may run without a secret. */
|
|
120
|
-
private readonly secretOptOut;
|
|
121
|
-
private readonly redact;
|
|
122
|
-
/** "check": queue alerts for another process's check instead of sending them. See CronWatchOptions.deliver. */
|
|
123
|
-
private readonly deferDelivery;
|
|
124
|
-
private readonly defaults;
|
|
125
|
-
private readonly definitions;
|
|
126
|
-
private readonly synced;
|
|
127
|
-
/** The tail of each job's queue of state updates. See serial(). */
|
|
128
|
-
private readonly queues;
|
|
129
|
-
private ready;
|
|
130
|
-
private checking;
|
|
131
|
-
private lastPruneAt;
|
|
132
|
-
private timer;
|
|
133
|
-
private firstTick;
|
|
134
|
-
private usingDefaultStore;
|
|
135
|
-
private warnedNoSecret;
|
|
136
|
-
constructor(options?: CronWatchOptions);
|
|
137
|
-
/** Declare a job. Call it once, at module level, and keep the handle. */
|
|
138
|
-
job(name: string, options?: JobOptions): JobHandle;
|
|
139
|
-
/** Run a job by name without keeping a handle. Defines it on first use. */
|
|
140
|
-
run<T>(name: string, fn: JobFn<T>): Promise<T>;
|
|
141
|
-
run<T>(name: string, options: JobOptions, fn: JobFn<T>): Promise<T>;
|
|
142
|
-
/** The definitions declared in this process. */
|
|
143
|
-
definedJobs(): JobDefinition[];
|
|
144
|
-
private handle;
|
|
145
|
-
private warnNoSecret;
|
|
146
|
-
private ensureReady;
|
|
147
|
-
private sync;
|
|
148
|
-
/**
|
|
149
|
-
* Runs `fn` after every earlier state update for the same job has settled,
|
|
150
|
-
* so two runs (or a run and a check) in this process never read and write
|
|
151
|
-
* the job's state over each other. Other processes are not coordinated.
|
|
152
|
-
*/
|
|
153
|
-
private serial;
|
|
154
|
-
private readState;
|
|
155
|
-
/**
|
|
156
|
-
* Runs a function as a recorded run. The function always runs, whatever
|
|
157
|
-
* the store is doing: store errors go to onError, and the result is the
|
|
158
|
-
* function's own outcome. Never throws for the job's own error; see `threw`.
|
|
159
|
-
*/
|
|
160
|
-
private execute;
|
|
161
|
-
/** Whether a check already marked this run as timed out, for a failure that finished late. */
|
|
162
|
-
private markedTimedOut;
|
|
163
|
-
/**
|
|
164
|
-
* Record a finished run (ok, failed, or timed out by a check), evaluate it
|
|
165
|
-
* against the job's state and send what that produces. Never throws.
|
|
166
|
-
*/
|
|
167
|
-
private finishRun;
|
|
168
|
-
/**
|
|
169
|
-
* The runs before `run`, newest first, with up to BASELINE_WINDOW
|
|
170
|
-
* successful ones when the store has them. One small read normally; a
|
|
171
|
-
* larger one only when failures crowd the successes out of it.
|
|
172
|
-
*/
|
|
173
|
-
private history;
|
|
174
|
-
/**
|
|
175
|
-
* Look for missed and stuck runs across every job, send alerts, retry
|
|
176
|
-
* alerts no channel accepted, and prune old runs. Call it from an interval
|
|
177
|
-
* (start()), a cron hitting the mounted routes, or by hand. Concurrent
|
|
178
|
-
* calls share one check.
|
|
179
|
-
*/
|
|
180
|
-
check(): Promise<CheckResult>;
|
|
181
|
-
private runCheck;
|
|
182
|
-
/** A job's summary and its newest runs, without alerting. */
|
|
183
|
-
private snapshot;
|
|
184
|
-
/** Every job the store knows about, with its health. Does not send alerts. */
|
|
185
|
-
jobs(): Promise<JobSummary[]>;
|
|
186
|
-
/** Every job's summary with its newest `limit` runs, read together. What the dashboard shows. */
|
|
187
|
-
jobsWithRuns(limit?: number): Promise<{
|
|
188
|
-
job: JobSummary;
|
|
189
|
-
runs: Run[];
|
|
190
|
-
}[]>;
|
|
191
|
-
jobSummary(name: string): Promise<JobSummary | null>;
|
|
192
|
-
/** A job's runs, newest first. `limit` is a whole number from 1 to 500. */
|
|
193
|
-
runs(name: string, limit?: number): Promise<Run[]>;
|
|
194
|
-
getRun(id: string): Promise<Run | null>;
|
|
195
|
-
/** Stop alerts for a job for a while. State keeps updating underneath. */
|
|
196
|
-
silence(name: string, duration: Duration): Promise<JobState>;
|
|
197
|
-
unsilence(name: string): Promise<JobState>;
|
|
198
|
-
/** Read, change and write one job's state, in turn with every other update to it. */
|
|
199
|
-
private patchState;
|
|
200
|
-
/** Remove a job and its runs from the store. A job still declared in code comes back on its next run. */
|
|
201
|
-
forget(name: string): Promise<void>;
|
|
202
|
-
/** The dashboard and JSON API as fetch-style handlers. See createRoutes(). */
|
|
203
|
-
routes(options?: RoutesOptions): Routes;
|
|
204
|
-
/** Check on an interval, for long-running servers. Default every minute. */
|
|
205
|
-
start(every?: Duration): void;
|
|
206
|
-
stop(): void;
|
|
207
|
-
close(): Promise<void>;
|
|
208
|
-
/** Save an evaluation's state, honouring silence, and return what should be sent. Call inside serial(). */
|
|
209
|
-
private settle;
|
|
210
|
-
/**
|
|
211
|
-
* Compose, triage and send each draft. The state was saved before this
|
|
212
|
-
* (settle), so a slow channel holds up nothing else; afterwards only the
|
|
213
|
-
* delivery fields are written back, onto a fresh read of the state.
|
|
214
|
-
*/
|
|
215
|
-
private dispatch;
|
|
216
|
-
/** Send the alerts that no channel accepted last time, once each. */
|
|
217
|
-
private retryUndelivered;
|
|
218
|
-
/** Mark delivered alerts done and keep failed ones for the next check. lastAlertAt moves only on a delivery. */
|
|
219
|
-
private recordDelivery;
|
|
220
|
-
/** Send to every channel at once. True when at least one accepted it, or there are none. */
|
|
221
|
-
private deliver;
|
|
222
|
-
private addTriage;
|
|
223
|
-
}
|
|
224
|
-
/** Writes alerts to the console. The default channel. */
|
|
225
|
-
declare function consoleChannel(): AlertChannel;
|
|
226
|
-
/** Wrap any function as an alert channel. */
|
|
227
|
-
declare function custom(name: string, send: (alert: Alert) => Promise<void> | void): AlertChannel;
|
|
1
|
+
import { C as CronWatchOptions, a as CronWatch } from './client-B7bqnkI5.cjs';
|
|
2
|
+
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-B7bqnkI5.cjs';
|
|
3
|
+
import { S as Store, D as Duration, b as AlertDraft, c as StoredJobDefinition, A as Alert } from './types-Ddq1MUPL.cjs';
|
|
4
|
+
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 StoredJob, T as TriageContext, n as TriageFn } from './types-Ddq1MUPL.cjs';
|
|
228
5
|
|
|
229
6
|
/**
|
|
230
7
|
* Keeps everything in process memory. The default when no store is given,
|
|
@@ -272,4 +49,4 @@ declare function composeAlert(draft: AlertDraft, def: StoredJobDefinition, now:
|
|
|
272
49
|
*/
|
|
273
50
|
declare function cronwatch(options?: CronWatchOptions): CronWatch;
|
|
274
51
|
|
|
275
|
-
export { Alert,
|
|
52
|
+
export { Alert, AlertDraft, CronWatch, CronWatchOptions, Duration, type ParsedSchedule, Store, StoredJobDefinition, composeAlert, cronwatch, formatDuration, memory, nextFire, parseDuration, parseSchedule };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,230 +1,7 @@
|
|
|
1
|
-
import {
|
|
2
|
-
export {
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
interface JobContext {
|
|
6
|
-
readonly name: string;
|
|
7
|
-
readonly runId: string;
|
|
8
|
-
readonly startedAt: number;
|
|
9
|
-
/** Aborts when the job's timeout elapses. Honour it if the work can stop. */
|
|
10
|
-
readonly signal: AbortSignal;
|
|
11
|
-
/** Append a line of output. Kept with the run, capped at 16 KB, shown in alerts and the dashboard. */
|
|
12
|
-
log(...parts: unknown[]): void;
|
|
13
|
-
/** Report a number for this run: tokens, cost, rows, anything. Watched against budgets and baselines. */
|
|
14
|
-
metric(name: string, value: number): void;
|
|
15
|
-
metrics(values: Record<string, number>): void;
|
|
16
|
-
}
|
|
17
|
-
|
|
18
|
-
interface RoutesOptions {
|
|
19
|
-
/**
|
|
20
|
-
* Required to reach anything. Send it as `Authorization: Bearer <token>`,
|
|
21
|
-
* or open the dashboard once with `?token=<token>` and a cookie is set.
|
|
22
|
-
* Defaults to process.env.CRONWATCH_TOKEN; an empty string counts as unset.
|
|
23
|
-
* With no token, the routes answer only requests to localhost while NODE_ENV
|
|
24
|
-
* is "development" or "test", and 503 otherwise. Pass `null` to opt out and serve them
|
|
25
|
-
* open everywhere, for example behind your own auth.
|
|
26
|
-
*
|
|
27
|
-
* The check endpoint (/api/check) also accepts the client's cronSecret, so
|
|
28
|
-
* a platform cron that sends `Authorization: Bearer <CRON_SECRET>` can
|
|
29
|
-
* trigger checks without knowing the dashboard token.
|
|
30
|
-
*/
|
|
31
|
-
token?: string | null;
|
|
32
|
-
/** Where the routes are mounted, so links resolve. Default "/cronwatch". */
|
|
33
|
-
basePath?: string;
|
|
34
|
-
}
|
|
35
|
-
type FetchHandler = (request: Request) => Promise<Response>;
|
|
36
|
-
interface Routes {
|
|
37
|
-
handler: FetchHandler;
|
|
38
|
-
GET: FetchHandler;
|
|
39
|
-
POST: FetchHandler;
|
|
40
|
-
DELETE: FetchHandler;
|
|
41
|
-
}
|
|
42
|
-
/**
|
|
43
|
-
* A fetch-style handler serving the dashboard and a small JSON API. Mount it
|
|
44
|
-
* in a Next.js app at app/cronwatch/[[...path]]/route.ts:
|
|
45
|
-
*
|
|
46
|
-
* export const { GET, POST, DELETE } = cw.routes();
|
|
47
|
-
*/
|
|
48
|
-
declare function createRoutes(cw: CronWatch, options?: RoutesOptions): Routes;
|
|
49
|
-
|
|
50
|
-
type JobFn<T> = (job: JobContext) => Promise<T> | T;
|
|
51
|
-
type HandlerFn<T> = (job: JobContext, request: Request) => Promise<T> | T;
|
|
52
|
-
interface HandlerOptions {
|
|
53
|
-
/**
|
|
54
|
-
* Callers must send `Authorization: Bearer <secret>`. Defaults to the
|
|
55
|
-
* client's cronSecret, which defaults to process.env.CRON_SECRET (what
|
|
56
|
-
* Vercel sends its cron requests with). An empty string counts as unset.
|
|
57
|
-
* With no secret at all the handler answers 503 unless NODE_ENV is
|
|
58
|
-
* "development" or "test". Pass null to allow anyone.
|
|
59
|
-
*/
|
|
60
|
-
secret?: string | null;
|
|
61
|
-
}
|
|
62
|
-
interface JobHandle {
|
|
63
|
-
readonly name: string;
|
|
64
|
-
readonly definition: JobDefinition;
|
|
65
|
-
/** Run the function now, recording the run. Rethrows whatever the function throws. */
|
|
66
|
-
run<T>(fn: JobFn<T>, options?: {
|
|
67
|
-
trigger?: string;
|
|
68
|
-
}): Promise<T>;
|
|
69
|
-
/** A fetch-style request handler (Next.js route, Hono, Bun, Deno) that runs the function and records the run. */
|
|
70
|
-
handler<T>(fn: HandlerFn<T>, options?: HandlerOptions): (request: Request) => Promise<Response>;
|
|
71
|
-
}
|
|
72
|
-
interface CronWatchOptions {
|
|
73
|
-
/** Where jobs, runs and state live. Defaults to an in-memory store that forgets on restart. */
|
|
74
|
-
store?: Store;
|
|
75
|
-
/** Where alerts go. Defaults to the console. */
|
|
76
|
-
alerts?: AlertChannel[];
|
|
77
|
-
/** Adds a short diagnosis to every alert except recoveries. See @cronwatch/sdk/anthropic. */
|
|
78
|
-
triage?: TriageFn;
|
|
79
|
-
/**
|
|
80
|
-
* Shared secret that handler() requests must carry. Defaults to
|
|
81
|
-
* process.env.CRON_SECRET; an empty string counts as unset. Pass null to
|
|
82
|
-
* let handlers run without one.
|
|
83
|
-
*/
|
|
84
|
-
cronSecret?: string | null;
|
|
85
|
-
/** How long finished runs are kept. Default "30d". */
|
|
86
|
-
retention?: Duration;
|
|
87
|
-
/** Applied to every job unless the job sets its own. */
|
|
88
|
-
defaults?: Pick<JobOptions, "grace" | "timeout" | "timezone" | "failuresBeforeAlert">;
|
|
89
|
-
/**
|
|
90
|
-
* Applied to every run's output and error before it is stored, shown or
|
|
91
|
-
* sent to an alert channel or triage. The default blanks values that look
|
|
92
|
-
* like secrets (password=..., URL credentials, bearer tokens, AWS, GitHub,
|
|
93
|
-
* Slack, Stripe and API key formats). Pass your own function, or false to
|
|
94
|
-
* keep output exactly as logged.
|
|
95
|
-
*/
|
|
96
|
-
redact?: ((text: string) => string) | false;
|
|
97
|
-
/**
|
|
98
|
-
* "now" (the default) sends alerts from this process. "check" sends nothing
|
|
99
|
-
* from here: each alert is queued in the store and the next check, in a
|
|
100
|
-
* process that delivers now, sends it (with triage). For a process that
|
|
101
|
-
* records runs but cannot reach the network, such as a sandboxed backup job.
|
|
102
|
-
* Its `alerts` and `triage` are not used.
|
|
103
|
-
*/
|
|
104
|
-
deliver?: "now" | "check";
|
|
105
|
-
/** Called with anything that goes wrong outside a job: the store failing, an alert channel failing, a triage timeout. */
|
|
106
|
-
onError?: (error: unknown, where: string) => void;
|
|
107
|
-
/** The clock. Tests use this. */
|
|
108
|
-
now?: () => number;
|
|
109
|
-
}
|
|
110
|
-
declare class CronWatch {
|
|
111
|
-
readonly store: Store;
|
|
112
|
-
readonly alerts: AlertChannel[];
|
|
113
|
-
readonly triage: TriageFn | undefined;
|
|
114
|
-
/** The secret handler() requests must carry, or null when none is set. */
|
|
115
|
-
readonly cronSecret: string | null;
|
|
116
|
-
readonly retentionMs: number;
|
|
117
|
-
readonly now: () => number;
|
|
118
|
-
readonly onError: (error: unknown, where: string) => void;
|
|
119
|
-
/** cronSecret was passed as null: handlers may run without a secret. */
|
|
120
|
-
private readonly secretOptOut;
|
|
121
|
-
private readonly redact;
|
|
122
|
-
/** "check": queue alerts for another process's check instead of sending them. See CronWatchOptions.deliver. */
|
|
123
|
-
private readonly deferDelivery;
|
|
124
|
-
private readonly defaults;
|
|
125
|
-
private readonly definitions;
|
|
126
|
-
private readonly synced;
|
|
127
|
-
/** The tail of each job's queue of state updates. See serial(). */
|
|
128
|
-
private readonly queues;
|
|
129
|
-
private ready;
|
|
130
|
-
private checking;
|
|
131
|
-
private lastPruneAt;
|
|
132
|
-
private timer;
|
|
133
|
-
private firstTick;
|
|
134
|
-
private usingDefaultStore;
|
|
135
|
-
private warnedNoSecret;
|
|
136
|
-
constructor(options?: CronWatchOptions);
|
|
137
|
-
/** Declare a job. Call it once, at module level, and keep the handle. */
|
|
138
|
-
job(name: string, options?: JobOptions): JobHandle;
|
|
139
|
-
/** Run a job by name without keeping a handle. Defines it on first use. */
|
|
140
|
-
run<T>(name: string, fn: JobFn<T>): Promise<T>;
|
|
141
|
-
run<T>(name: string, options: JobOptions, fn: JobFn<T>): Promise<T>;
|
|
142
|
-
/** The definitions declared in this process. */
|
|
143
|
-
definedJobs(): JobDefinition[];
|
|
144
|
-
private handle;
|
|
145
|
-
private warnNoSecret;
|
|
146
|
-
private ensureReady;
|
|
147
|
-
private sync;
|
|
148
|
-
/**
|
|
149
|
-
* Runs `fn` after every earlier state update for the same job has settled,
|
|
150
|
-
* so two runs (or a run and a check) in this process never read and write
|
|
151
|
-
* the job's state over each other. Other processes are not coordinated.
|
|
152
|
-
*/
|
|
153
|
-
private serial;
|
|
154
|
-
private readState;
|
|
155
|
-
/**
|
|
156
|
-
* Runs a function as a recorded run. The function always runs, whatever
|
|
157
|
-
* the store is doing: store errors go to onError, and the result is the
|
|
158
|
-
* function's own outcome. Never throws for the job's own error; see `threw`.
|
|
159
|
-
*/
|
|
160
|
-
private execute;
|
|
161
|
-
/** Whether a check already marked this run as timed out, for a failure that finished late. */
|
|
162
|
-
private markedTimedOut;
|
|
163
|
-
/**
|
|
164
|
-
* Record a finished run (ok, failed, or timed out by a check), evaluate it
|
|
165
|
-
* against the job's state and send what that produces. Never throws.
|
|
166
|
-
*/
|
|
167
|
-
private finishRun;
|
|
168
|
-
/**
|
|
169
|
-
* The runs before `run`, newest first, with up to BASELINE_WINDOW
|
|
170
|
-
* successful ones when the store has them. One small read normally; a
|
|
171
|
-
* larger one only when failures crowd the successes out of it.
|
|
172
|
-
*/
|
|
173
|
-
private history;
|
|
174
|
-
/**
|
|
175
|
-
* Look for missed and stuck runs across every job, send alerts, retry
|
|
176
|
-
* alerts no channel accepted, and prune old runs. Call it from an interval
|
|
177
|
-
* (start()), a cron hitting the mounted routes, or by hand. Concurrent
|
|
178
|
-
* calls share one check.
|
|
179
|
-
*/
|
|
180
|
-
check(): Promise<CheckResult>;
|
|
181
|
-
private runCheck;
|
|
182
|
-
/** A job's summary and its newest runs, without alerting. */
|
|
183
|
-
private snapshot;
|
|
184
|
-
/** Every job the store knows about, with its health. Does not send alerts. */
|
|
185
|
-
jobs(): Promise<JobSummary[]>;
|
|
186
|
-
/** Every job's summary with its newest `limit` runs, read together. What the dashboard shows. */
|
|
187
|
-
jobsWithRuns(limit?: number): Promise<{
|
|
188
|
-
job: JobSummary;
|
|
189
|
-
runs: Run[];
|
|
190
|
-
}[]>;
|
|
191
|
-
jobSummary(name: string): Promise<JobSummary | null>;
|
|
192
|
-
/** A job's runs, newest first. `limit` is a whole number from 1 to 500. */
|
|
193
|
-
runs(name: string, limit?: number): Promise<Run[]>;
|
|
194
|
-
getRun(id: string): Promise<Run | null>;
|
|
195
|
-
/** Stop alerts for a job for a while. State keeps updating underneath. */
|
|
196
|
-
silence(name: string, duration: Duration): Promise<JobState>;
|
|
197
|
-
unsilence(name: string): Promise<JobState>;
|
|
198
|
-
/** Read, change and write one job's state, in turn with every other update to it. */
|
|
199
|
-
private patchState;
|
|
200
|
-
/** Remove a job and its runs from the store. A job still declared in code comes back on its next run. */
|
|
201
|
-
forget(name: string): Promise<void>;
|
|
202
|
-
/** The dashboard and JSON API as fetch-style handlers. See createRoutes(). */
|
|
203
|
-
routes(options?: RoutesOptions): Routes;
|
|
204
|
-
/** Check on an interval, for long-running servers. Default every minute. */
|
|
205
|
-
start(every?: Duration): void;
|
|
206
|
-
stop(): void;
|
|
207
|
-
close(): Promise<void>;
|
|
208
|
-
/** Save an evaluation's state, honouring silence, and return what should be sent. Call inside serial(). */
|
|
209
|
-
private settle;
|
|
210
|
-
/**
|
|
211
|
-
* Compose, triage and send each draft. The state was saved before this
|
|
212
|
-
* (settle), so a slow channel holds up nothing else; afterwards only the
|
|
213
|
-
* delivery fields are written back, onto a fresh read of the state.
|
|
214
|
-
*/
|
|
215
|
-
private dispatch;
|
|
216
|
-
/** Send the alerts that no channel accepted last time, once each. */
|
|
217
|
-
private retryUndelivered;
|
|
218
|
-
/** Mark delivered alerts done and keep failed ones for the next check. lastAlertAt moves only on a delivery. */
|
|
219
|
-
private recordDelivery;
|
|
220
|
-
/** Send to every channel at once. True when at least one accepted it, or there are none. */
|
|
221
|
-
private deliver;
|
|
222
|
-
private addTriage;
|
|
223
|
-
}
|
|
224
|
-
/** Writes alerts to the console. The default channel. */
|
|
225
|
-
declare function consoleChannel(): AlertChannel;
|
|
226
|
-
/** Wrap any function as an alert channel. */
|
|
227
|
-
declare function custom(name: string, send: (alert: Alert) => Promise<void> | void): AlertChannel;
|
|
1
|
+
import { C as CronWatchOptions, a as CronWatch } from './client-pmqH3apS.js';
|
|
2
|
+
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-pmqH3apS.js';
|
|
3
|
+
import { S as Store, D as Duration, b as AlertDraft, c as StoredJobDefinition, A as Alert } from './types-Ddq1MUPL.js';
|
|
4
|
+
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 StoredJob, T as TriageContext, n as TriageFn } from './types-Ddq1MUPL.js';
|
|
228
5
|
|
|
229
6
|
/**
|
|
230
7
|
* Keeps everything in process memory. The default when no store is given,
|
|
@@ -272,4 +49,4 @@ declare function composeAlert(draft: AlertDraft, def: StoredJobDefinition, now:
|
|
|
272
49
|
*/
|
|
273
50
|
declare function cronwatch(options?: CronWatchOptions): CronWatch;
|
|
274
51
|
|
|
275
|
-
export { Alert,
|
|
52
|
+
export { Alert, AlertDraft, CronWatch, CronWatchOptions, Duration, type ParsedSchedule, Store, StoredJobDefinition, composeAlert, cronwatch, formatDuration, memory, nextFire, parseDuration, parseSchedule };
|