@cronvello/sdk 0.1.1 → 0.1.2

package/dist/index.cjs

@@ -372,6 +372,109 @@ function enc(segment) {
   return encodeURIComponent(segment);
 }
 
+// src/internal/cron.ts
+var MACROS = /* @__PURE__ */ new Set([
+  "@yearly",
+  "@annually",
+  "@monthly",
+  "@weekly",
+  "@daily",
+  "@midnight",
+  "@hourly",
+  "@reboot"
+]);
+var MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+var DOWS = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+var FIVE = [
+  { min: 0, max: 59, label: "minute" },
+  { min: 0, max: 23, label: "hour" },
+  { min: 1, max: 31, label: "day-of-month" },
+  { min: 1, max: 12, names: MONTHS, label: "month" },
+  { min: 0, max: 7, names: DOWS, label: "day-of-week" }
+  // 0 and 7 are both Sunday
+];
+var SECONDS = { min: 0, max: 59, label: "second" };
+function validateCron(expr) {
+  if (typeof expr !== "string" || !expr.trim()) {
+    return { valid: false, error: "schedule is empty" };
+  }
+  const trimmed = expr.trim();
+  if (trimmed.startsWith("@")) {
+    return MACROS.has(trimmed.toLowerCase()) ? { valid: true } : { valid: false, error: `unknown cron macro "${trimmed}" (try @daily, @hourly, \u2026)` };
+  }
+  const parts = trimmed.split(/\s+/);
+  if (parts.length !== 5 && parts.length !== 6) {
+    return {
+      valid: false,
+      error: `expected 5 fields (min hour dom month dow) or 6 with seconds, got ${parts.length}: "${trimmed}"`
+    };
+  }
+  const specs = parts.length === 6 ? [SECONDS, ...FIVE] : FIVE;
+  for (let i = 0; i < parts.length; i++) {
+    const err = validateField(parts[i], specs[i]);
+    if (err) return { valid: false, error: `invalid ${specs[i].label} "${parts[i]}": ${err}` };
+  }
+  return { valid: true };
+}
+function validateField(field2, spec) {
+  for (const term of field2.split(",")) {
+    const err = validateTerm(term, spec);
+    if (err) return err;
+  }
+  return null;
+}
+function validateTerm(term, spec) {
+  if (term === "") return "empty list item";
+  let step;
+  let base = term;
+  const slash = term.indexOf("/");
+  if (slash >= 0) {
+    base = term.slice(0, slash);
+    step = term.slice(slash + 1);
+    if (!/^\d+$/.test(step) || Number(step) === 0) return `step must be a positive integer`;
+  }
+  if (base === "*") return null;
+  const dash = base.indexOf("-");
+  if (dash > 0) {
+    const lo = resolveValue(base.slice(0, dash), spec);
+    const hi = resolveValue(base.slice(dash + 1), spec);
+    if (lo === null) return `"${base.slice(0, dash)}" is out of range ${spec.min}-${spec.max}`;
+    if (hi === null) return `"${base.slice(dash + 1)}" is out of range ${spec.min}-${spec.max}`;
+    if (lo > hi) return `range start ${lo} is greater than end ${hi}`;
+    return null;
+  }
+  if (step !== void 0 && base !== "*") {
+    return resolveValue(base, spec) === null ? `"${base}" is out of range ${spec.min}-${spec.max}` : null;
+  }
+  return resolveValue(base, spec) === null ? `"${base}" is out of range ${spec.min}-${spec.max}` : null;
+}
+function resolveValue(token, spec) {
+  if (/^\d+$/.test(token)) {
+    const n = Number(token);
+    return n >= spec.min && n <= spec.max ? n : null;
+  }
+  if (spec.names) {
+    const idx = spec.names.indexOf(token.toLowerCase());
+    if (idx >= 0) return idx + (spec.label === "month" ? 1 : 0);
+  }
+  return null;
+}
+function assertValidCron(expr, context = "") {
+  const res = validateCron(expr);
+  if (!res.valid) {
+    throw new Error(`${context ? `${context}: ` : ""}invalid cron schedule \u2014 ${res.error}`);
+  }
+}
+function isValidTimeZone(tz) {
+  if (!tz || typeof tz !== "string") return false;
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: tz });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // src/registry/verify.ts
 var encoder = new TextEncoder();
 function parseBearer(headerValue2) {
@@ -403,17 +506,54 @@ async function signHmacSha256(payload, secret) {
 }
 
 // src/registry/dispatch.ts
+var NOOP_LOGGER = {};
 function createDispatcher(state) {
-  const log = state.logger;
+  const log = state.logger ?? NOOP_LOGGER;
+  const hooks = state.hooks;
+  const maxBodyBytes = state.maxBodyBytes ?? 1048576;
+  async function invokeHandler(job, ctx) {
+    await safeHook(() => hooks?.onJobStart?.({ key: job.key, source: ctx.source, isAsync: ctx.isAsync }), log);
+    const startedAt = Date.now();
+    try {
+      const result = await job.config.handler(ctx);
+      const durationMs = Date.now() - startedAt;
+      log.debug?.(`[cronvello] job '${job.key}' completed in ${durationMs}ms`);
+      await safeHook(() => hooks?.onJobSuccess?.({ key: job.key, source: ctx.source, durationMs, result }), log);
+      return { durationMs, result };
+    } catch (err) {
+      const durationMs = Date.now() - startedAt;
+      const error = err instanceof Error ? err : new Error(String(err));
+      log.error?.(`[cronvello] job '${job.key}' failed: ${error.message}`, { error: error.message });
+      await safeHook(() => hooks?.onJobError?.({ key: job.key, source: ctx.source, durationMs, error }), log);
+      throw error;
+    }
+  }
+  function buildContext(key, job, req, body, isAsync, source) {
+    return {
+      key,
+      schedule: typeof body["schedule"] === "string" ? body["schedule"] : job.config.schedule ?? "",
+      payload: job.config.payload ?? {},
+      body,
+      headers: req?.headers ?? {},
+      isAsync,
+      source,
+      logger: log,
+      signal: req?.signal
+    };
+  }
   async function handle(req) {
     if (req.method.toUpperCase() !== "POST") {
       return resp(405, { ok: false, error: "Method not allowed" });
     }
     const token = parseBearer(req.authorization);
     if (!token || !timingSafeEqual(token, state.dispatchSecret)) {
-      log?.warn?.("[cronvello] dispatch rejected: bad or missing bearer token");
+      log.warn?.("[cronvello] dispatch rejected: bad or missing bearer token");
       return resp(401, { ok: false, error: "Unauthorized" });
     }
+    if (byteLength(req.rawBody) > maxBodyBytes) {
+      log.warn?.(`[cronvello] dispatch rejected: body exceeds ${maxBodyBytes} bytes`);
+      return resp(413, { ok: false, error: "Payload too large" });
+    }
     let body;
     try {
       const parsed = req.rawBody ? JSON.parse(req.rawBody) : {};
@@ -430,54 +570,44 @@ function createDispatcher(state) {
     }
     const job = state.jobs.get(key);
     if (!job) {
-      log?.warn?.(`[cronvello] dispatch for unknown job '${key}'`);
+      log.warn?.(`[cronvello] dispatch for unknown job '${key}'`);
       return resp(404, { ok: false, error: `Unknown job: ${key}` });
     }
     const callback = readCallback(body["_callback"]);
     const isAsync = callback !== null;
-    const ctx = {
-      key,
-      schedule: typeof body["schedule"] === "string" ? body["schedule"] : "",
-      payload: job.config.payload ?? {},
-      body,
-      headers: req.headers,
-      isAsync,
-      signal: req.signal
-    };
+    const ctx = buildContext(key, job, req, body, isAsync, "dispatch");
     if (callback) {
-      const work = runAndReportCallback(job, ctx, callback, state.dispatchSecret, log);
+      const work = runAndReportCallback(job, ctx, callback, state.dispatchSecret, log, invokeHandler);
       if (req.waitUntil) req.waitUntil(work);
       return resp(202, { ok: true, job: key, accepted: true });
     }
-    const startedAt = Date.now();
     try {
-      const result = await job.config.handler(ctx);
-      log?.debug?.(`[cronvello] job '${key}' completed in ${Date.now() - startedAt}ms`);
+      const { result } = await invokeHandler(job, ctx);
       return resp(200, { ok: true, job: key, result: result ?? null });
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      log?.error?.(`[cronvello] job '${key}' failed: ${message}`, { error: message });
-      return resp(500, { ok: false, job: key, error: message });
+      return resp(500, { ok: false, job: key, error: err instanceof Error ? err.message : String(err) });
     }
   }
-  return { handle };
+  async function runLocal(key, payload) {
+    const job = state.jobs.get(key);
+    if (!job) throw new Error(`Unknown job '${key}'. Known: ${[...state.jobs.keys()].join(", ") || "(none)"}`);
+    const body = { job: key, schedule: job.config.schedule, ...payload ?? {} };
+    const ctx = buildContext(key, job, null, body, false, "local");
+    const { result } = await invokeHandler(job, ctx);
+    return result;
+  }
+  return { handle, runLocal };
 }
-async function runAndReportCallback(job, ctx, callback, secret, log) {
-  const startedAt = Date.now();
+async function runAndReportCallback(job, ctx, callback, secret, log, invokeHandler) {
   let payload;
   try {
-    const result = await job.config.handler(ctx);
-    payload = {
-      runId: callback.runId,
-      success: true,
-      durationMs: Date.now() - startedAt,
-      result: result ?? null
-    };
+    const { durationMs, result } = await invokeHandler(job, ctx);
+    payload = { runId: callback.runId, success: true, durationMs, result: result ?? null };
   } catch (err) {
     payload = {
       runId: callback.runId,
       success: false,
-      durationMs: Date.now() - startedAt,
+      durationMs: 0,
       error: err instanceof Error ? err.message : String(err)
     };
   }
@@ -491,14 +621,26 @@ async function runAndReportCallback(job, ctx, callback, secret, log) {
       body: bodyStr
     });
     if (!res.ok) {
-      log?.warn?.(`[cronvello] callback POST for job '${job.key}' returned ${res.status}`);
+      log.warn?.(`[cronvello] callback POST for job '${job.key}' returned ${res.status}`);
     }
   } catch (err) {
-    log?.error?.(`[cronvello] failed to deliver callback for job '${job.key}'`, {
+    log.error?.(`[cronvello] failed to deliver callback for job '${job.key}'`, {
       error: err instanceof Error ? err.message : String(err)
     });
   }
 }
+async function safeHook(fn, log) {
+  try {
+    await fn();
+  } catch (err) {
+    log.warn?.(`[cronvello] a lifecycle hook threw: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+function byteLength(s) {
+  if (!s) return 0;
+  if (typeof TextEncoder !== "undefined") return new TextEncoder().encode(s).length;
+  return s.length;
+}
 function readCallback(value) {
   if (!value || typeof value !== "object") return null;
   const v = value;
@@ -608,9 +750,9 @@ function buildDesiredTask(args) {
 function diffTask(existing, desired, opts) {
   const patch = {};
   const changed = [];
-  const set = (field, value) => {
-    patch[field] = value;
-    changed.push(field);
+  const set = (field2, value) => {
+    patch[field2] = value;
+    changed.push(field2);
   };
   if (existing.schedule !== desired.schedule) set("schedule", desired.schedule);
   if (desired.timeZone !== void 0 && existing.timeZone !== desired.timeZone) set("timeZone", desired.timeZone);
@@ -742,10 +884,14 @@ var DEFAULT_DISPATCH_PATH = "/cronvello/dispatch";
 var DEFAULT_TIME_ZONE = "Europe/Berlin";
 function defineCronvello(config) {
   validateConfig(config);
-  const jobs = normalizeJobs(config.jobs);
+  const validate = config.validateSchedules ?? true;
+  const defaultTimeZone = config.timeZone ?? DEFAULT_TIME_ZONE;
+  if (validate && !isValidTimeZone(defaultTimeZone)) {
+    throw new CronvelloConfigError(`Invalid \`timeZone\` "${defaultTimeZone}" \u2014 expected an IANA name like "Europe/Berlin" or "UTC".`);
+  }
+  const jobs = normalizeJobs(config.jobs, validate);
   const dispatchPath = normalizePath(config.dispatchPath ?? DEFAULT_DISPATCH_PATH);
   const dispatchUrl = joinUrl(config.appUrl, dispatchPath);
-  const defaultTimeZone = config.timeZone ?? DEFAULT_TIME_ZONE;
   const client = new CronvelloClient({
     apiKey: config.apiKey,
     baseUrl: config.baseUrl ?? CRONVELLO_DEFAULT_BASE_URL,
@@ -756,7 +902,9 @@ function defineCronvello(config) {
   const dispatcher = createDispatcher({
     jobs,
     dispatchSecret: config.dispatchSecret,
-    logger: config.logger
+    logger: config.logger,
+    ...config.hooks ? { hooks: config.hooks } : {},
+    ...config.maxBodyBytes !== void 0 ? { maxBodyBytes: config.maxBodyBytes } : {}
   });
   const app = {
     client,
@@ -820,6 +968,7 @@ function defineCronvello(config) {
       }
       return client.tasks.runNow(task.id);
     },
+    trigger: (key, payload) => dispatcher.runLocal(key, payload),
     handle: dispatcher.handle,
     expressHandler: () => expressHandler(app),
     nextHandler: () => nextHandler(app),
@@ -827,6 +976,30 @@ function defineCronvello(config) {
   };
   return app;
 }
+((defineCronvello2) => {
+  function fromEnv(config, env = typeof process !== "undefined" ? process.env : {}) {
+    const apiKey = config.apiKey ?? env["CRONVELLO_API_KEY"];
+    const dispatchSecret = config.dispatchSecret ?? env["CRONVELLO_DISPATCH_SECRET"];
+    const appUrl = config.appUrl ?? env["CRONVELLO_APP_URL"] ?? env["PUBLIC_URL"];
+    const baseUrl = config.baseUrl ?? env["CRONVELLO_API_URL"];
+    const missing = [
+      !apiKey && "CRONVELLO_API_KEY",
+      !dispatchSecret && "CRONVELLO_DISPATCH_SECRET",
+      !appUrl && "CRONVELLO_APP_URL (or PUBLIC_URL)"
+    ].filter(Boolean);
+    if (missing.length) {
+      throw new CronvelloConfigError(`defineCronvello.fromEnv() is missing required env: ${missing.join(", ")}.`);
+    }
+    return defineCronvello2({
+      ...config,
+      apiKey,
+      dispatchSecret,
+      appUrl,
+      ...baseUrl ? { baseUrl } : {}
+    });
+  }
+  defineCronvello2.fromEnv = fromEnv;
+})(defineCronvello || (defineCronvello = {}));
 function validateConfig(config) {
   if (!config) throw new CronvelloConfigError("defineCronvello requires a config object.");
   if (!config.appName || !config.appName.trim()) throw new CronvelloConfigError("`appName` is required.");
@@ -839,7 +1012,7 @@ function validateConfig(config) {
   }
   if (!config.jobs) throw new CronvelloConfigError("`jobs` is required.");
 }
-function normalizeJobs(input) {
+function normalizeJobs(input, validate) {
   const map = /* @__PURE__ */ new Map();
   const entries = Array.isArray(input) ? input.map(({ key, ...rest }) => ({ key, config: rest })) : Object.entries(input).map(([key, config]) => ({ key, config }));
   for (const { key, config } of entries) {
@@ -853,6 +1026,15 @@ function normalizeJobs(input) {
     if (!config.schedule || !config.schedule.trim()) {
       throw new CronvelloConfigError(`Job '${trimmed}' is missing a schedule.`);
     }
+    if (validate) {
+      const cronCheck = validateCron(config.schedule);
+      if (!cronCheck.valid) {
+        throw new CronvelloConfigError(`Job '${trimmed}' has an invalid schedule "${config.schedule}" \u2014 ${cronCheck.error}.`);
+      }
+      if (config.timeZone !== void 0 && !isValidTimeZone(config.timeZone)) {
+        throw new CronvelloConfigError(`Job '${trimmed}' has an invalid timeZone "${config.timeZone}" \u2014 expected an IANA name.`);
+      }
+    }
     map.set(trimmed, { key: trimmed, config });
   }
   if (map.size === 0) throw new CronvelloConfigError("At least one job is required.");
@@ -895,6 +1077,149 @@ function buildRegistryRequest(config, dispatchUrl, defaultTimeZone, jobs, opts)
   };
 }
 
+// src/registry/format.ts
+var ESC = String.fromCharCode(27);
+var ANSI = {
+  reset: `${ESC}[0m`,
+  dim: `${ESC}[2m`,
+  bold: `${ESC}[1m`,
+  green: `${ESC}[32m`,
+  yellow: `${ESC}[33m`,
+  red: `${ESC}[31m`,
+  cyan: `${ESC}[36m`,
+  gray: `${ESC}[90m`
+};
+var GLYPH = {
+  created: { sign: "+", color: "green" },
+  updated: { sign: "~", color: "yellow" },
+  unchanged: { sign: "=", color: "gray" },
+  deleted: { sign: "-", color: "red" },
+  skipped: { sign: "\xB7", color: "cyan" }
+};
+function formatSyncResult(result, options = {}) {
+  const paint = (s, c) => options.color ? `${ANSI[c]}${s}${ANSI.reset}` : s;
+  const verb = options.dryRun ? "would sync" : "synced";
+  const lines = [];
+  lines.push(
+    `${paint("Cronvello", "cyan")} ${verb} ${paint(`"${result.jobName}"`, "bold")} ${paint(`(${result.jobId})`, "gray")}`
+  );
+  const order = ["created", "updated", "deleted", "skipped", "unchanged"];
+  const sorted = [...result.changes].sort((a, b) => order.indexOf(a.action) - order.indexOf(b.action));
+  for (const c of sorted) {
+    const g = GLYPH[c.action];
+    const detail = c.changedFields && c.changedFields.length ? paint(` (${c.changedFields.join(", ")})`, "gray") : c.reason ? paint(` (${c.reason})`, "gray") : "";
+    lines.push(`  ${paint(g.sign, g.color)} ${paint(c.action.padEnd(9), g.color)} ${c.key}${detail}`);
+  }
+  const tally = [
+    result.created && `${result.created} created`,
+    result.updated && `${result.updated} updated`,
+    result.unchanged && `${result.unchanged} unchanged`,
+    result.deleted && `${result.deleted} deleted`,
+    result.skipped && `${result.skipped} skipped`
+  ].filter(Boolean);
+  const summary = tally.length ? tally.join(", ") : "no changes";
+  const containerNote = result.jobCreated ? paint("  \xB7  container created", "gray") : "";
+  lines.push(`  ${paint(summary, "bold")}${containerNote}`);
+  return lines.join("\n");
+}
+
+// src/schedule/index.ts
+var DOW = { sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6 };
+function cron(expression) {
+  assertValidCron(expression, "cron()");
+  return expression;
+}
+function every(interval) {
+  const m = /^(\d+)\s*(s|sec|secs|m|min|mins|h|hr|hrs|hour|hours|d|day|days)$/i.exec(interval.trim());
+  if (!m) throw new Error(`every(): cannot parse interval "${interval}" \u2014 use forms like "30s", "15m", "2h", "1d"`);
+  const n = Number(m[1]);
+  const unit = m[2].toLowerCase()[0];
+  if (n < 1) throw new Error(`every(): interval must be at least 1, got ${n}`);
+  let expr;
+  if (unit === "s") {
+    if (n > 59) throw new Error(`every(): seconds must be 1\u201359, got ${n}`);
+    expr = `*/${n} * * * * *`;
+  } else if (unit === "m") {
+    if (n > 59) throw new Error(`every(): minutes must be 1\u201359 (use "1h" for 60), got ${n}`);
+    expr = `*/${n} * * * *`;
+  } else if (unit === "h") {
+    if (n > 23) throw new Error(`every(): hours must be 1\u201323 (use "1d" for 24), got ${n}`);
+    expr = `0 */${n} * * *`;
+  } else {
+    if (n > 31) throw new Error(`every(): days must be 1\u201331, got ${n}`);
+    expr = n === 1 ? `0 0 * * *` : `0 0 */${n} * *`;
+  }
+  assertValidCron(expr, `every("${interval}")`);
+  return expr;
+}
+function everyMinutes(n) {
+  return every(`${n}m`);
+}
+function everyHours(n) {
+  return every(`${n}h`);
+}
+function hourly(minute = 0) {
+  const mm = field(minute, 0, 59, "minute");
+  return cron(`${mm} * * * *`);
+}
+function daily(time = "00:00") {
+  const { hh, mm } = parseTime(time);
+  return cron(`${mm} ${hh} * * *`);
+}
+function weekly(day, time = "00:00") {
+  const { hh, mm } = parseTime(time);
+  return cron(`${mm} ${hh} * * ${weekday(day)}`);
+}
+function monthly(dayOfMonth, time = "00:00") {
+  const { hh, mm } = parseTime(time);
+  const dom = field(dayOfMonth, 1, 31, "day-of-month");
+  return cron(`${mm} ${hh} ${dom} * *`);
+}
+function weekdays(time = "00:00") {
+  const { hh, mm } = parseTime(time);
+  return cron(`${mm} ${hh} * * 1-5`);
+}
+function weekends(time = "00:00") {
+  const { hh, mm } = parseTime(time);
+  return cron(`${mm} ${hh} * * 0,6`);
+}
+var schedule = {
+  cron,
+  every,
+  everyMinutes,
+  everyHours,
+  hourly,
+  daily,
+  weekly,
+  monthly,
+  weekdays,
+  weekends
+};
+function parseTime(time) {
+  const m = /^(\d{1,2}):(\d{2})$/.exec(time.trim());
+  if (!m) throw new Error(`Expected a time like "08:00" or "23:30", got "${time}"`);
+  const hh = Number(m[1]);
+  const mm = Number(m[2]);
+  if (hh > 23) throw new Error(`Hour must be 0\u201323, got ${hh}`);
+  if (mm > 59) throw new Error(`Minute must be 0\u201359, got ${mm}`);
+  return { hh, mm };
+}
+function weekday(day) {
+  if (typeof day === "number") {
+    if (day < 0 || day > 6) throw new Error(`Weekday number must be 0 (Sun) \u2013 6 (Sat), got ${day}`);
+    return day;
+  }
+  const n = DOW[day.toLowerCase()];
+  if (n === void 0) throw new Error(`Unknown weekday "${day}" \u2014 use sun\u2026sat or 0\u20266`);
+  return n;
+}
+function field(value, min, max, label) {
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw new Error(`${label} must be an integer ${min}\u2013${max}, got ${value}`);
+  }
+  return value;
+}
+
 // src/index.ts
 function generateDispatchSecret(bytes = 32) {
   const buf = new Uint8Array(bytes);
@@ -908,7 +1233,21 @@ exports.CronvelloClient = CronvelloClient;
 exports.CronvelloConfigError = CronvelloConfigError;
 exports.CronvelloError = CronvelloError;
 exports.CronvelloNetworkError = CronvelloNetworkError;
+exports.cron = cron;
+exports.daily = daily;
 exports.defineCronvello = defineCronvello;
+exports.every = every;
+exports.everyHours = everyHours;
+exports.everyMinutes = everyMinutes;
+exports.formatSyncResult = formatSyncResult;
 exports.generateDispatchSecret = generateDispatchSecret;
+exports.hourly = hourly;
+exports.isValidTimeZone = isValidTimeZone;
+exports.monthly = monthly;
+exports.schedule = schedule;
+exports.validateCron = validateCron;
+exports.weekdays = weekdays;
+exports.weekends = weekends;
+exports.weekly = weekly;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map