@connextar/house 0.10.0 → 0.11.0

package/dist/jobs/scheduler.js

@@ -0,0 +1,282 @@
+import { errorMessage } from "../ux/errors.js";
+import { countLines, countsSummary, declaredCounts } from "./counts.js";
+import { buildJobView, effectiveTimeout, formatWhen } from "./health.js";
+import { DEFAULT_COOLDOWN_MS, DEFAULT_TIMEOUT_MS, MAX_WINDOW_KEY, } from "./registry.js";
+import { MANUAL_KEY_PREFIX } from "./windows.js";
+const MAX_ERROR = 1000;
+function messageOf(error) {
+    const message = errorMessage(error, "It failed without saying why.");
+    return message.length > MAX_ERROR ? `${message.slice(0, MAX_ERROR - 1)}…` : message;
+}
+const minutes = (ms) => {
+    const n = Math.max(1, Math.round(ms / 60_000));
+    return `${n} minute${n === 1 ? "" : "s"}`;
+};
+/**
+ * The dispatcher, and everything else that touches the ledger.
+ *
+ * Declared once in the app beside its jobs and its store adapter; the tick
+ * route, the own-schedule routes, the Run now and switch routes and the health
+ * page all call this one object.
+ */
+export function createScheduler(options) {
+    const { jobs, store } = options;
+    const clock = options.clock ?? (() => new Date());
+    const fallbackTimeout = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const format = { locale: options.locale };
+    const find = (id) => jobs.find((job) => job.id === id);
+    /** Run a claimed job and record the outcome. Never throws. */
+    async function execute(job, runId, context) {
+        let counts = null;
+        let error = null;
+        try {
+            counts = declaredCounts(job.counts, await job.run(context));
+        }
+        catch (thrown) {
+            error = messageOf(thrown);
+        }
+        let unrecorded = null;
+        try {
+            await store.finishRun(runId, { finishedAt: clock(), ok: error === null, counts, error });
+        }
+        catch (thrown) {
+            // The work is done (or failed) either way; the ledger just doesn't know.
+            // It will read as "never finished" once the timeout passes, which is true.
+            unrecorded = messageOf(thrown);
+        }
+        return { counts, error, unrecorded };
+    }
+    /** The switch, the window, the claim and the run — for one job, with nothing allowed to escape. */
+    async function dispatch(job, now, switches, windowKeyFor) {
+        const base = { job: job.id };
+        try {
+            if (job.switchable ?? true) {
+                if (switches instanceof Error) {
+                    return {
+                        ...base,
+                        status: "failed",
+                        error: switches.message,
+                        message: `${job.label} didn't start: whether it is switched on couldn't be read (${switches.message}).`,
+                    };
+                }
+                const state = switches.get(job.id);
+                if (state?.paused) {
+                    // Its window is not claimed, so switched back on inside the same window it still runs.
+                    const who = state.by ? ` by ${state.by}` : "";
+                    const when = state.at ? ` on ${formatWhen(state.at.toISOString())}` : "";
+                    return { ...base, status: "paused", message: `${job.label} is switched off${who}${when}; not started.` };
+                }
+            }
+            const windowKey = windowKeyFor(now);
+            if (windowKey === null)
+                return { ...base, status: "not-due", message: `${job.label} is not due.` };
+            if (windowKey.length > MAX_WINDOW_KEY) {
+                throw new Error(`Its window key is longer than ${MAX_WINDOW_KEY} characters.`);
+            }
+            const runId = await store.claimRun({ job: job.id, windowKey, tenantId: null, by: null, startedAt: now });
+            if (runId === null) {
+                return { ...base, windowKey, status: "already-ran", message: `${job.label} has already run in ${windowKey}.` };
+            }
+            const context = { now, trigger: "schedule", tenantId: null, force: false, windowKey, by: null };
+            const { counts, error, unrecorded } = await execute(job, runId, context);
+            if (error !== null) {
+                return { ...base, windowKey, status: "failed", error, message: `${job.label} failed: ${error}` };
+            }
+            const summary = countsSummary(countLines(job.counts, counts, format));
+            return {
+                ...base,
+                windowKey,
+                status: "ran",
+                counts: counts ?? {},
+                ...(unrecorded ? { error: unrecorded } : {}),
+                message: unrecorded
+                    ? `${job.label} ran, but its result couldn't be recorded: ${unrecorded}`
+                    : `${job.label} ran${summary ? `: ${summary}` : ""}.`,
+            };
+        }
+        catch (thrown) {
+            // A store that failed to claim, a window function that threw: this job's
+            // problem, reported as this job's result. The next job still runs.
+            const error = messageOf(thrown);
+            return { ...base, status: "failed", error, message: `${job.label} didn't run: ${error}` };
+        }
+    }
+    async function readSwitches() {
+        try {
+            return await store.readSwitches();
+        }
+        catch (thrown) {
+            return new Error(messageOf(thrown));
+        }
+    }
+    return {
+        jobs,
+        async tick(now = clock()) {
+            const switches = await readSwitches();
+            const results = [];
+            // One at a time, in declaration order: predictable load, and the order the card lists them in.
+            for (const job of jobs) {
+                if ((job.schedule ?? "tick") !== "tick")
+                    continue;
+                results.push(await dispatch(job, now, switches, (at) => job.window(at)));
+            }
+            return results;
+        },
+        async runOwn(jobId, now = clock()) {
+            const job = find(jobId);
+            if (!job || job.schedule !== "own") {
+                throw new Error(`"${jobId}" is not a job with its own schedule.`);
+            }
+            return dispatch(job, now, await readSwitches(), (at) => job.window ? job.window(at) : `run:${at.toISOString()}`);
+        },
+        async runNow(jobId, caller, now = clock()) {
+            const job = find(jobId);
+            if (!job)
+                return { status: "refused", job: jobId, reason: "unknown", message: "There is no scheduled job by that name." };
+            const refuse = (reason, message) => ({
+                status: "refused",
+                job: job.id,
+                reason,
+                message,
+            });
+            const rule = job.runNow;
+            if (!rule)
+                return refuse("not-runnable", `${job.label} runs on its schedule only.`);
+            if (rule.scope === "tenant" && !caller.tenantId) {
+                return refuse("out-of-scope", `${job.label} can only be run for your own organisation, and you aren't in one.`);
+            }
+            if (rule.scope === "platform" && !caller.platform) {
+                return refuse("out-of-scope", `${job.label} runs across every account, so only a platform administrator can run it.`);
+            }
+            const tenantId = rule.scope === "tenant" ? caller.tenantId : null;
+            if ((job.switchable ?? true) && (await store.readSwitches()).get(job.id)?.paused) {
+                return refuse("paused", `${job.label} is switched off. Turn it back on to run it.`);
+            }
+            // Nothing in flight that this run could overlap: the schedule's sweep covers this tenant too.
+            const tenants = tenantId === null ? [null] : [null, tenantId];
+            const latest = await store.latestRun({ job: job.id, tenants });
+            const timeout = effectiveTimeout(job, fallbackTimeout);
+            if (latest && !latest.finishedAt && now.getTime() - latest.startedAt.getTime() <= timeout) {
+                return refuse("running", `${job.label} is running now — it started ${formatWhen(latest.startedAt.toISOString())}.`);
+            }
+            const cooldown = rule.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+            if (cooldown > 0) {
+                const last = await store.latestRun({ job: job.id, tenants: [tenantId], manualOnly: true });
+                const since = last ? now.getTime() - last.startedAt.getTime() : Infinity;
+                if (since < cooldown) {
+                    return refuse("too-soon", `${job.label} was run ${minutes(since)} ago. It can be run again in ${minutes(cooldown - since)}.`);
+                }
+            }
+            // Two presses in the same breath share a key, so the index lets one through.
+            const at = cooldown > 0 ? new Date(Math.floor(now.getTime() / cooldown) * cooldown) : now;
+            const windowKey = `${MANUAL_KEY_PREFIX}${tenantId === null ? "platform" : `tenant:${tenantId}`}:${at.toISOString()}`;
+            if (windowKey.length > MAX_WINDOW_KEY)
+                throw new Error(`The Run now key for ${job.id} is too long to store.`);
+            const runId = await store.claimRun({ job: job.id, windowKey, tenantId, by: caller.actor.name, startedAt: now });
+            if (runId === null)
+                return refuse("too-soon", `${job.label} has just been run.`);
+            const context = { now, trigger: "manual", tenantId, force: true, windowKey, by: caller.actor };
+            const { counts, error } = await execute(job, runId, context);
+            if (error !== null) {
+                return { status: "failed", job: job.id, windowKey, error, message: `${job.label} failed: ${error}` };
+            }
+            const lines = countLines(job.counts, counts, format);
+            const summary = countsSummary(lines);
+            return {
+                status: "ran",
+                job: job.id,
+                windowKey,
+                counts: lines,
+                message: `Ran ${job.label}${summary ? ` — ${summary}` : ""}.`,
+            };
+        },
+        async setPaused(jobId, paused, caller, now = clock()) {
+            const job = find(jobId);
+            if (!job)
+                return { status: "refused", job: jobId, reason: "unknown", message: "There is no scheduled job by that name." };
+            if (!(job.switchable ?? true)) {
+                return {
+                    status: "refused",
+                    job: job.id,
+                    reason: "not-switchable",
+                    message: `${job.label} can't be switched off.`,
+                };
+            }
+            if (!caller.platform) {
+                return {
+                    status: "refused",
+                    job: job.id,
+                    reason: "out-of-scope",
+                    message: `Switching ${job.label} off stops it for every account, so only a platform administrator can.`,
+                };
+            }
+            const current = (await store.readSwitches()).get(job.id)?.paused ?? false;
+            if (current === paused) {
+                return {
+                    status: "unchanged",
+                    job: job.id,
+                    paused,
+                    message: paused ? `${job.label} is already paused.` : `${job.label} is already on.`,
+                };
+            }
+            await store.writeSwitch({ job: job.id, label: job.label, paused, at: now, by: caller.actor });
+            return {
+                status: "switched",
+                job: job.id,
+                paused,
+                message: paused
+                    ? `${job.label} is paused. A run already under way finishes; no more start until you turn it back on.`
+                    : `${job.label} is back on. It runs at its next scheduled time.`,
+            };
+        },
+        async views(audience, now = clock()) {
+            const switches = await store.readSwitches();
+            const tenants = audience.tenantId ? [null, audience.tenantId] : [null];
+            return Promise.all(jobs.map(async (job) => {
+                const [latest, lastWholeSuccess, lastVisibleSuccess] = await Promise.all([
+                    store.latestRun({ job: job.id, tenants }),
+                    store.latestRun({ job: job.id, tenants: [null], ok: true }),
+                    tenants.length > 1 ? store.latestRun({ job: job.id, tenants, ok: true }) : null,
+                ]);
+                return buildJobView(job, {
+                    switch: switches.get(job.id) ?? null,
+                    latest,
+                    lastWholeSuccess,
+                    lastVisibleSuccess: tenants.length > 1 ? lastVisibleSuccess : lastWholeSuccess,
+                }, audience, { now, timeoutMs: fallbackTimeout, locale: options.locale });
+            }));
+        },
+    };
+}
+/** The tick in one line: "2 ran, 1 failed, 1 paused, 5 not due". */
+export function summariseTick(results) {
+    const order = [
+        ["ran", "ran"],
+        ["failed", "failed"],
+        ["paused", "paused"],
+        ["already-ran", "already ran"],
+        ["not-due", "not due"],
+    ];
+    const parts = order.flatMap(([status, words]) => {
+        const n = results.filter((result) => result.status === status).length;
+        return n ? [`${n} ${words}`] : [];
+    });
+    return parts.length ? parts.join(", ") : "No scheduled jobs";
+}
+/** The HTTP status a refusal maps to, so every app answers the same refusal the same way. */
+export function refusalStatus(reason) {
+    switch (reason) {
+        case "unknown":
+            return 404;
+        case "not-runnable":
+        case "not-switchable":
+        case "out-of-scope":
+            return 403;
+        case "paused":
+        case "running":
+            return 409;
+        case "too-soon":
+            return 429;
+    }
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/jobs/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../../src/jobs/scheduler.ts"],"names":[],"mappings":"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"}

package/dist/jobs/store.d.ts

@@ -0,0 +1,94 @@
+import type { JobActor } from "./registry.js";
+/**
+ * Where runs and switches are kept — the app's, behind this interface.
+ *
+ * The package owns no schema. Both apps already have a `cron_run` table with
+ * the same eight columns, and AltEd keeps its switches in a settings table it
+ * shares with the harvest's own screen; a package migration would fight both.
+ * The README carries a reference Prisma model and adapter that both existing
+ * tables map onto, adding two nullable columns and losing nothing.
+ */
+/** A ledger row as the app stores it. `counts` is whatever JSON is there; it is read through the job's declarations. */
+export interface JobRunRecord {
+    id: string;
+    job: string;
+    windowKey: string;
+    /** `null`: a run over every tenant. Otherwise the one tenant a Run now swept. */
+    tenantId: string | null;
+    /** Who pressed Run now, by name; `null` for the schedule. */
+    by: string | null;
+    startedAt: Date;
+    finishedAt: Date | null;
+    ok: boolean;
+    counts: unknown;
+    error: string | null;
+}
+export interface JobRunClaim {
+    job: string;
+    windowKey: string;
+    tenantId: string | null;
+    by: string | null;
+    startedAt: Date;
+}
+export interface JobRunOutcome {
+    finishedAt: Date;
+    ok: boolean;
+    counts: Record<string, number> | null;
+    error: string | null;
+}
+/** "The most recent run of this job, among these tenants" — `null` in the list meaning runs over every tenant. */
+export interface JobRunQuery {
+    job: string;
+    tenants: readonly (string | null)[];
+    /** Successful runs only. */
+    ok?: true;
+    /** Run now runs only (their key starts `manual:`). */
+    manualOnly?: true;
+}
+/** Whether a job is switched off, and the latest change. No entry means on. */
+export interface JobSwitchState {
+    paused: boolean;
+    at: Date | null;
+    by: string | null;
+}
+export interface JobSwitchChange {
+    job: string;
+    label: string;
+    paused: boolean;
+    at: Date;
+    by: JobActor;
+}
+export interface JobStore {
+    /**
+     * Insert the run row, claiming `(job, windowKey)`. Resolve with its id, or
+     * with `null` when the pair already exists — the unique index refusing it is
+     * the idempotency, so that refusal is an answer, not an error. Anything else
+     * throws.
+     */
+    claimRun(claim: JobRunClaim): Promise<string | null>;
+    finishRun(id: string, outcome: JobRunOutcome): Promise<void>;
+    latestRun(query: JobRunQuery): Promise<JobRunRecord | null>;
+    readSwitches(): Promise<ReadonlyMap<string, JobSwitchState>>;
+    /**
+     * Record a switch. **Write the audit entry here too, in the same
+     * transaction:** the switch keeps only the latest change, and a job paused and
+     * forgotten — billing reminders, say — is found by asking who, and when.
+     */
+    writeSwitch(change: JobSwitchChange): Promise<void>;
+}
+/**
+ * A stored switch value, read the way AltEd learnt to: a row that exists but
+ * does not read as `{ paused: boolean }` is **paused**. Somebody stored it, and a
+ * switch nobody can read should not send a job out spending.
+ */
+export declare function pausedFromStored(value: unknown): boolean;
+/**
+ * The whole contract in memory — for tests, the app's included. It keeps the
+ * unique `(job, windowKey)` rule exactly as the database would.
+ */
+export declare function createMemoryJobStore(): JobStore & {
+    runs: JobRunRecord[];
+    switches: Map<string, JobSwitchState>;
+    switchLog: JobSwitchChange[];
+};
+//# sourceMappingURL=store.d.ts.map

package/dist/jobs/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/jobs/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG9C;;;;;;;;GAQG;AAEH,wHAAwH;AACxH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,6DAA6D;IAC7D,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,SAAS,EAAE,IAAI,CAAC;IAChB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,IAAI,CAAC;IACjB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IACtC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,kHAAkH;AAClH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;IACpC,4BAA4B;IAC5B,EAAE,CAAC,EAAE,IAAI,CAAC;IACV,sDAAsD;IACtD,UAAU,CAAC,EAAE,IAAI,CAAC;CACnB;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,OAAO,CAAC;IAChB,EAAE,EAAE,IAAI,GAAG,IAAI,CAAC;IAChB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,EAAE,EAAE,IAAI,CAAC;IACT,EAAE,EAAE,QAAQ,CAAC;CACd;AAED,MAAM,WAAW,QAAQ;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACrD,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC5D,YAAY,IAAI,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;IAC7D;;;;OAIG;IACH,WAAW,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKxD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,QAAQ,GAAG;IACjD,IAAI,EAAE,YAAY,EAAE,CAAC;IACrB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACtC,SAAS,EAAE,eAAe,EAAE,CAAC;CAC9B,CA2CA"}

package/dist/jobs/store.js

@@ -0,0 +1,56 @@
+import { isManualKey } from "./windows.js";
+/**
+ * A stored switch value, read the way AltEd learnt to: a row that exists but
+ * does not read as `{ paused: boolean }` is **paused**. Somebody stored it, and a
+ * switch nobody can read should not send a job out spending.
+ */
+export function pausedFromStored(value) {
+    if (value && typeof value === "object" && typeof value.paused === "boolean") {
+        return value.paused;
+    }
+    return true;
+}
+/**
+ * The whole contract in memory — for tests, the app's included. It keeps the
+ * unique `(job, windowKey)` rule exactly as the database would.
+ */
+export function createMemoryJobStore() {
+    const runs = [];
+    const switches = new Map();
+    const switchLog = [];
+    let next = 0;
+    return {
+        runs,
+        switches,
+        switchLog,
+        async claimRun(claim) {
+            if (runs.some((run) => run.job === claim.job && run.windowKey === claim.windowKey))
+                return null;
+            const id = `run-${++next}`;
+            runs.push({ id, ...claim, finishedAt: null, ok: false, counts: null, error: null });
+            return id;
+        },
+        async finishRun(id, outcome) {
+            const run = runs.find((row) => row.id === id);
+            if (!run)
+                throw new Error(`No run ${id}`);
+            Object.assign(run, outcome);
+        },
+        async latestRun(query) {
+            const matches = runs.filter((run) => run.job === query.job &&
+                query.tenants.includes(run.tenantId) &&
+                (!query.ok || run.ok) &&
+                (!query.manualOnly || isManualKey(run.windowKey)));
+            // Latest by start; on a tie, the one inserted last.
+            return matches.reduce((latest, run) => (!latest || run.startedAt.getTime() >= latest.startedAt.getTime() ? run : latest), null);
+        },
+        async readSwitches() {
+            return new Map(switches);
+        },
+        async writeSwitch(change) {
+            switches.set(change.job, { paused: change.paused, at: change.at, by: change.by.name });
+            switchLog.push(change);
+        },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/jobs/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/jobs/store.ts"],"names":[],"mappings":"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"}

package/dist/jobs/windows.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Run windows: which window a moment falls in, or none.
+ *
+ * A window is a function from "now" to a key, or `null` when the job is not due
+ * at all. The key is what the ledger's unique index is on, together with the
+ * job, so **one run per job per key** is the whole of idempotency: a second tick
+ * in the same window finds the key taken and does nothing.
+ *
+ * Both apps wrote this as two functions — `attempt(now)` and `windowKey(now)` —
+ * which could disagree. One function cannot.
+ *
+ * The helpers carry one lesson each:
+ *
+ * - **A day is a day somewhere.** AltEd keyed its tracker job on the UTC date
+ *   while the job took "yesterday" from the UK calendar; in summer a tick after
+ *   23:00 UTC and the next at 00:00 UTC fell in different windows but the same
+ *   UK day, so that day's misses were sent twice and the next day's never. Every
+ *   calendar helper takes the `timeZone` the job's own idea of a day comes from.
+ * - **Not before a civil hour.** `from` keeps a morning email out of midnight —
+ *   AltEd's weekly digest waits for 07:00 "so nobody's phone lights up".
+ * - **A missed start is caught up, not lost.** Quickie's monthly report ran only
+ *   on the 1st, so a day of failed ticks on the 1st lost the month. `weekly` and
+ *   `monthly` stay open from their start to the end of their period (after
+ *   `from` each day), and the key keeps it to one run.
+ *
+ * Keys match what both apps already store (`2026-09-30`, `2026-09-30T14`,
+ * `2026-09-30Q2`, `month:2026-09`), so moving a job onto a helper does not run
+ * it a second time in the window it moves in.
+ */
+export type JobWindow = (now: Date) => string | null;
+export interface CalendarWindowOptions {
+    /** The first hour of the day the window is open, in `timeZone`. Default 0. */
+    from?: number;
+    /** Whose calendar. Default `UTC`. A job that reasons about "today" in the UK says `Europe/London`. */
+    timeZone?: string;
+}
+/** Once an hour. Key `2026-09-30T14` (UTC) — Quickie's hourly key. */
+export declare function hourly(): JobWindow;
+/**
+ * Once every `hours` hours, in blocks from UTC midnight. Key `2026-09-30Q2` —
+ * with 6, exactly Quickie's four-a-day bank feed key.
+ */
+export declare function everyHours(hours: number): JobWindow;
+/** Once a day, from `from` o'clock to midnight in `timeZone`. Key `2026-09-30`, the date there. */
+export declare function daily(options?: CalendarWindowOptions): JobWindow;
+/**
+ * Once a week, opening on `weekday` (1 = Monday) at `from` and staying open —
+ * from `from` each day — until the next one opens. Key `week:2026-09-28`, the
+ * date it opened.
+ */
+export declare function weekly(options?: CalendarWindowOptions & {
+    weekday?: number;
+}): JobWindow;
+/**
+ * Once a month, opening on `day` at `from` and staying open — from `from` each
+ * day — to the month's end. Key `month:2026-09` — Quickie's monthly key.
+ * `day` is 1–28, so the window opens in February too.
+ */
+export declare function monthly(options?: CalendarWindowOptions & {
+    day?: number;
+}): JobWindow;
+/** The prefix every Run now key starts with, in both apps' existing rows and in this module's. */
+export declare const MANUAL_KEY_PREFIX = "manual:";
+/** Whether a stored window key was a Run now rather than the schedule. */
+export declare function isManualKey(windowKey: string): boolean;
+//# sourceMappingURL=windows.d.ts.map

package/dist/jobs/windows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows.d.ts","sourceRoot":"","sources":["../../src/jobs/windows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,IAAI,KAAK,MAAM,GAAG,IAAI,CAAC;AAoDrD,MAAM,WAAW,qBAAqB;IACpC,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sGAAsG;IACtG,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,sEAAsE;AACtE,wBAAgB,MAAM,IAAI,SAAS,CAElC;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAKnD;AAED,mGAAmG;AACnG,wBAAgB,KAAK,CAAC,OAAO,GAAE,qBAA0B,GAAG,SAAS,CAOpE;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,OAAO,GAAE,qBAAqB,GAAG;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,SAAS,CAY5F;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,OAAO,GAAE,qBAAqB,GAAG;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,SAAS,CASzF;AAED,kGAAkG;AAClG,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAE3C,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEtD"}