@cronvello/sdk 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to `@cronvello/sdk` are documented here. This project adheres to
+[Semantic Versioning](https://semver.org/) (pre-1.0: minor-feature additions ship as patch releases).
+
+## 0.1.2
+
+A big developer-experience release — everything is additive and backward-compatible.
+
+### Added
+
+- **Readable schedule builders**: `every`, `everyMinutes`, `everyHours`, `hourly`, `daily`,
+  `weekly`, `monthly`, `weekdays`, `weekends`, and `cron` — each returns a validated cron string.
+- **Client-side validation** of cron expressions and IANA timezones at define time
+  (`validateCron`, `isValidTimeZone`); a typo now throws a clear, job-scoped error instead of
+  failing silently server-side. Opt out per app with `validateSchedules: false`.
+- **`cronvello.trigger(key, payload?)`** — run a job's handler in-process (no HTTP, no deploy).
+  Ideal for unit tests and local development. `ctx.source` is `"local"` for these runs.
+- **`defineCronvello.fromEnv(config)`** — read `CRONVELLO_API_KEY`, `CRONVELLO_DISPATCH_SECRET`,
+  and `CRONVELLO_APP_URL` (or `PUBLIC_URL`) from the environment so you don't repeat them.
+- **Lifecycle hooks** (`onJobStart`, `onJobSuccess`, `onJobError`) for logging, metrics, and error
+  reporting. A throwing hook is logged and never breaks the run.
+- **`ctx.logger`** (your configured logger, or a no-op) and **`ctx.source`** on the handler context.
+- **`formatSyncResult(result, { color?, dryRun? })`** — a clean, human-readable reconcile summary.
+- **CLI** — `npx cronvello` with `whoami`, `list`, `tasks`, `runs`, `run`, `status`, `sync`,
+  `dev`, and `secret`. Polished, colour-aware output; `--json` for scripting.
+- **Dispatch body-size guard** (`maxBodyBytes`, default 1 MiB) — oversized inbound bodies are
+  rejected with `413` before parsing.
+
+### Internal
+
+- Comprehensive test suite (unit + contract + opt-in live e2e) and a CI gate
+  (typecheck + tests + build across Node 18/20/22) wired ahead of publish.
+
+## 0.1.1
+
+- **Fix**: unwrap the server's `{ success, message, data }` response envelope centrally in the
+  transport, so `sync()` and the typed client methods see the inner payload (the 0.1.0 release
+  returned the wrapper).
+
+## 0.1.0
+
+- Initial release: code-first registry (`defineCronvello` → `sync()` + Express/Next adapters) and
+  a typed low-level `/v1` client. Zero runtime dependencies, dual ESM + CJS.

package/README.md

@@ -13,6 +13,11 @@ npm i @cronvello/sdk
 - ✅ **Base URL baked in** (`https://api.cronvello.com`) — override only for self-hosting.
 - ✅ **Two layers**: a turnkey code-first **registry**, and a typed **low-level client** for the
   full `/v1` API.
+- ✅ **Readable schedules** — `daily("08:00")`, `every("15m")`, `weekly("mon", "09:00")` instead of
+  raw cron — with **typo-proof validation** at define time.
+- ✅ **Test jobs locally** with `cronvello.trigger("job")` — no deploy, no HTTP.
+- ✅ **Lifecycle hooks** for logging / metrics / error reporting.
+- ✅ **A real CLI** — `npx cronvello whoami | list | runs | status | sync | dev`.
 
 ---
 
@@ -30,26 +35,26 @@ Change a schedule → it's updated. Idempotent, every time.
 
 ```ts
 // cronvello.ts
-import { defineCronvello } from "@cronvello/sdk";
+import { defineCronvello, daily, every } from "@cronvello/sdk";
 
-export const cronvello = defineCronvello({
-  appName: "my-app",                              // your app's identity (stable, unique)
-  appUrl: process.env.APP_URL!,                   // public URL of THIS app, e.g. https://my-app.com
-  apiKey: process.env.CRONVELLO_API_KEY!,         // crn_live_…
-  dispatchSecret: process.env.CRONVELLO_DISPATCH_SECRET!, // random 32-byte secret
+// `fromEnv` reads CRONVELLO_API_KEY, CRONVELLO_DISPATCH_SECRET, and CRONVELLO_APP_URL
+// (or PUBLIC_URL) for you — pass them explicitly instead if you prefer.
+export const cronvello = defineCronvello.fromEnv({
+  appName: "my-app", // your app's identity (stable, unique)
 
   jobs: {
     "send-daily-digest": {
-      schedule: "0 8 * * *",
+      schedule: daily("08:00"),                 // ← readable; or a raw "0 8 * * *"
       handler: async () => {
         await sendDigests();
       },
     },
     "cleanup-temp": {
-      schedule: "*/15 * * * *",
+      schedule: every("15m"),
       description: "Purge temp files older than an hour",
-      handler: async ({ schedule }) => {
+      handler: async ({ schedule, logger }) => {
         const removed = await purgeTemp();
+        logger.info?.(`purged ${removed} files`);
         return { removed, schedule };           // returned value is recorded on the run
       },
     },
@@ -120,14 +125,16 @@ jobs: [...billingJobs, ...reportJobs]   // each: { key, schedule, handler, … }
 
 | Field | Default | Notes |
 |---|---|---|
-| `schedule` | — | Cron expression, validated by Cronvello on sync. |
+| `schedule` | — | Cron string or a [schedule builder](#readable-schedules). Validated client-side at define time, and again by Cronvello on sync. |
 | `handler` | — | `async (ctx) => result`. The return value is recorded on the run. |
 | `description` | — | Stored on the task. |
-| `timeZone` | app default (`Europe/Berlin`) | IANA zone. |
+| `timeZone` | app default (`Europe/Berlin`) | IANA zone. Validated client-side. |
 | `urgency` | — | `low` \| `medium` \| `high` \| `critical`. |
 | `maxRetries` | server default | 0–20. |
 | `executionMode` | `sync` | `async_callback` for long jobs (see below). |
+| `callbackTimeoutMs` | — | Async-mode budget before Cronvello marks the run timed out. |
 | `allowConcurrentRuns` | `false` | Allow overlap with an in-flight run. |
+| `successCriteria` | — | Assert success beyond 2xx (status range, body contains / JSON path / regex). |
 | `payload` | — | Static object merged into the request body and exposed as `ctx.payload`. |
 | `enabled` | `true` | `false` keeps the code but stops scheduling. |
 
@@ -140,11 +147,102 @@ handler: async (ctx) => {
   ctx.payload;   // your static payload, if any
   ctx.body;      // full request body Cronvello sent
   ctx.isAsync;   // true under async_callback mode
+  ctx.source;    // "dispatch" (Cronvello fired it) | "local" (you called trigger())
+  ctx.logger;    // your configured logger (no-op if none) — ctx.logger.info?.("…")
+  ctx.signal;    // AbortSignal, if the host provides one
 };
 ```
 
 ---
 
+## Readable schedules
+
+Stop hand-writing cron. These builders return a validated cron string, so a bad argument throws
+**at define time** with a clear message — not silently at the server:
+
+```ts
+import { every, everyMinutes, everyHours, hourly, daily, weekly, monthly, weekdays, weekends, cron } from "@cronvello/sdk";
+
+every("30s")              // "*/30 * * * * *"
+every("15m")              // "*/15 * * * *"
+every("2h")               // "0 */2 * * *"
+hourly()                  // "0 * * * *"        — top of every hour
+hourly(30)                // "30 * * * *"
+daily("08:00")            // "0 8 * * *"
+weekly("mon", "09:00")    // "0 9 * * 1"
+monthly(1, "00:00")       // "0 0 1 * *"        — 1st of the month
+weekdays("07:00")         // "0 7 * * 1-5"      — Mon–Fri
+weekends("10:00")         // "0 10 * * 0,6"
+cron("0 6,7 * * *")       // raw cron, still validated
+```
+
+Validation runs on every job's `schedule` and `timeZone` when you call `defineCronvello`. Opt out
+with `validateSchedules: false`. You can also validate directly:
+
+```ts
+import { validateCron, isValidTimeZone } from "@cronvello/sdk";
+validateCron("0 25 * * *");     // { valid: false, error: 'invalid hour "25": …' }
+isValidTimeZone("Europe/Berlin"); // true
+```
+
+---
+
+## Test & run jobs locally — `trigger()`
+
+Run a job's handler **in-process** — no HTTP, no Cronvello, no deploy. Perfect for unit tests and
+local development:
+
+```ts
+const result = await cronvello.trigger("send-daily-digest");
+// runs the handler with ctx.source === "local"; lifecycle hooks fire; returns the handler's value
+```
+
+```ts
+// In a test:
+it("sends digests", async () => {
+  const out = await cronvello.trigger("send-daily-digest", { dryRun: true });
+  expect(out).toEqual({ sent: 3 });
+});
+```
+
+---
+
+## Lifecycle hooks & logging
+
+Observe every run — for structured logs, metrics, or error reporting (Sentry, etc.). Hooks never
+break a run: if a hook throws, it's logged and the job still completes.
+
+```ts
+defineCronvello.fromEnv({
+  appName: "my-app",
+  logger: console, // surfaced to handlers as ctx.logger
+  hooks: {
+    onJobStart:   ({ key, source })            => metrics.increment(`cron.start`, { key }),
+    onJobSuccess: ({ key, durationMs })        => metrics.timing(`cron.ms`, durationMs, { key }),
+    onJobError:   ({ key, error })             => Sentry.captureException(error, { tags: { key } }),
+  },
+  jobs: { /* … */ },
+});
+```
+
+---
+
+## Pretty sync output
+
+```ts
+import { formatSyncResult } from "@cronvello/sdk";
+
+const result = await cronvello.sync();
+console.log(formatSyncResult(result, { color: true }));
+// Cronvello synced "my-app" (job_…)
+//   + created   send-daily-digest
+//   ~ updated   cleanup-temp (schedule)
+//   = unchanged rotate-keys
+//   1 created, 1 updated, 1 unchanged
+```
+
+---
+
 ## `sync()` — idempotent reconcile
 
 ```ts
@@ -211,6 +309,59 @@ long-running Node server — **not** typical serverless).
 
 ---
 
+## CLI — `npx cronvello`
+
+Installing the SDK gives you a `cronvello` command. Point it at your account with
+`CRONVELLO_API_KEY` (a `crn_live_…` key) and inspect or drive everything from the terminal:
+
+```bash
+export CRONVELLO_API_KEY=crn_live_…
+
+npx cronvello whoami                  # account, plan, limits & usage
+npx cronvello list                    # job containers (tasks / active / errors)
+npx cronvello list "my-app"           # the tasks inside one container
+npx cronvello tasks --job "my-app"    # account-wide task table
+npx cronvello runs --limit 20         # recent execution feed
+npx cronvello runs --status failed    # …filtered
+npx cronvello run <taskId>            # trigger a task now
+npx cronvello run "my-app" "digest"   # …resolved by job + task name
+npx cronvello status                  # health overview + recent failures
+npx cronvello secret                  # generate a strong dispatch secret
+```
+
+```
+$ cronvello whoami
+╭─ System (internal siblings) ───────────────────╮
+│ account   #1  ✔ system@node-cron.internal      │
+│ plan      Enterprise                           │
+│ limits    1000 jobs · 100 tasks/job · 6000/min │
+│ usage     236253 / ∞ executions  (6 jobs)      │
+│ attention 4 DLQ · 0 heartbeats · 0 maintenance │
+╰────────────────────────────────────────────────╯
+```
+
+**Drive your code registry**, too — these load your config module (a file that exports a
+`defineCronvello(...)` app as the default export or a named `cronvello`):
+
+```bash
+npx cronvello sync ./cronvello.config.js          # reconcile to Cronvello
+npx cronvello sync ./cronvello.config.js --dry     # preview the diff
+npx cronvello dev  ./cronvello.config.js my-job    # run a job's handler locally
+```
+
+> Running a **TypeScript** config? Launch the CLI under a TS loader:
+> `node --import tsx node_modules/@cronvello/sdk/dist/cli.js sync ./cronvello.config.ts`
+
+Global flags: `--json` (machine-readable output for scripting), `--no-color`, `-h/--help`,
+`-v/--version`. Colour auto-disables when piped or when `NO_COLOR` is set.
+
+---
+
+Runnable examples live in [`examples/`](./examples): a full Express app (`examples/express`) and a
+Next.js App Router setup (`examples/next`).
+
+---
+
 ## Low-level client
 
 The full typed `/v1` surface, for anything beyond the registry model: