@cronvello/sdk 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,62 @@
 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.3.0
+
+**Credentials are no longer part of defining jobs.** 0.2.0 made the SDK run locally with no account,
+but `defineCronvello()` still demanded an `apiKey`, an `appUrl` and a `dispatchSecret` before it
+would construct anything. So the documented way to try the local engine was to invent a fake API
+key for a scheduler that never makes a network call. That was real config standing in for no real
+constraint, and it landed on exactly the people the local mode is meant to attract.
+
+### Changed
+
+- **`apiKey`, `appUrl` and `dispatchSecret` are now optional.** `defineCronvello({ appName, jobs })`
+  is a complete, valid app. `cronvello dev`, `dev()` and `trigger()` work on it unchanged.
+- **The hosted side validates where it is used, not at define time.** `sync()`, `run()`, `client`,
+  `dispatchUrl`, `expressHandler()` and `nextHandler()` each check what they actually need and throw
+  a `CronvelloConfigError` naming every missing field. `client` is now built on first access rather
+  than eagerly.
+- A *present* but malformed value is still rejected at define time (`appUrl` must be absolute
+  http(s), `dispatchSecret` at least 16 chars). This removes a requirement, not a check.
+
+### Added
+
+- **`app.isCloudConfigured`** — true when `apiKey`, `appUrl` and `dispatchSecret` are all present.
+- **A rebuilt local dashboard.** The old page answered "what are my jobs" but not "is this healthy",
+  so you had to read a log to find out. It now opens on a summary (jobs, runs, succeeded, failed,
+  next fire) and a **timeline**: one lane per job, past runs plotted against upcoming fires around a
+  moving now-line. A schedule that is wrong shows up there immediately.
+  - Run detail now includes the **error message** or the **returned value**, which is the thing you
+    opened the panel for.
+  - The feed can be paused, and says how many events it is holding back.
+  - Rows are keyboard-reachable, Escape closes the drawer and returns focus.
+  - The page is driven by one `/api/state` snapshot instead of a fetch per event, and the timeline
+    advances by translating a fixed track rather than repositioning every mark each second.
+- **`GET /api/state`** on the dashboard server: jobs (with last run and upcoming fires), run history
+  and engine state in one response.
+- **`engine.startedAt`** and **`engine.running`** on `LocalEngine`.
+
+### Fixed
+
+- The dashboard's job table stayed on "Loading" forever when the registry was empty, because
+  "no jobs" and "not loaded yet" looked identical to it.
+- A `scheduled` event carries the *next fire time* as its timestamp, which the feed printed in its
+  clock column and so appeared to jump forward in time. It now reads "scheduled for HH:MM:SS" and
+  the clock column is strictly arrival time.
+
+### Security
+
+- An app without a `dispatchSecret` never runs a job from an HTTP request. `expressHandler()` and
+  `nextHandler()` throw at mount time rather than exposing a route, and `handle()` answers `500`
+  ("Dispatch is not configured") before touching the body. There is no path in which a missing
+  secret degrades into accepting unauthenticated dispatches.
+
+### Compatibility
+
+Backwards compatible: every config valid in 0.2.x is still valid and behaves identically. Minor
+rather than patch because the public config type widened and `client` / `dispatchUrl` became lazy.
+
 ## 0.2.1
 
 - Move the canonical SDK source to the public

package/README.md

@@ -4,14 +4,45 @@
 [![CI](https://github.com/niccasWilliams/cronvello-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/niccasWilliams/cronvello-sdk/actions/workflows/ci.yml)
 [![license](https://img.shields.io/npm/l/@cronvello/sdk)](./LICENSE)
 
-**Code-first cron jobs for [Cronvello](https://cronvello.com).** Define your scheduled jobs in
-your codebase, and the SDK keeps them in sync with Cronvello and runs them — **no dashboard
-required**. Your jobs always follow your code.
+**Code-first cron jobs.** Declare your scheduled jobs in your codebase and run them: with a real
+scheduler on your own machine, and optionally with [Cronvello](https://cronvello.com) hosting them.
+**No dashboard required.** Your jobs always follow your code.
+
+## Try it without an account
+
+Three steps, no signup, nothing leaves your machine:
 
 ```bash
 npm i @cronvello/sdk
 ```
 
+```ts
+// cronvello.config.ts
+import { defineCronvello, every } from "@cronvello/sdk";
+
+export default defineCronvello({
+  appName: "my-app",
+  jobs: {
+    heartbeat: { schedule: every("10s"), handler: async () => console.log("beat") },
+  },
+});
+```
+
+```bash
+npx cronvello dev
+```
+
+That starts an actual scheduler loop: each next fire time computed from the cron expression,
+timezone- and DST-aware, with overlap protection, per-run timeouts and retry with backoff. It makes
+no network calls. This part is MIT licensed and works standalone. See
+[Local development](#local-development-no-account--cronvello-dev) for the full output.
+
+The hosted side adds what a local loop can't: run history, retries you can inspect, alerts when a
+run *doesn't* happen, and replay. It's opt-in, and only the calls that use it (`sync()`, `run()`,
+the dispatch handler) need credentials.
+
+---
+
 - ✅ **Runs locally with no account** — `npx cronvello dev` starts a real scheduler loop on your
   machine (timezone/DST, overlap protection, timeouts, retry/backoff). No cloud, no network.
 - ✅ **Zero runtime dependencies** (Node 20+ `fetch` + WebCrypto).
@@ -27,7 +58,7 @@ npm i @cronvello/sdk
 
 ---
 
-## The idea
+## The idea (hosted)
 
 You declare jobs once, in code. On every deploy you call `sync()`, and the SDK reconciles your
 registry into Cronvello: **one Cronvello "job" container for your app, one task per registry
@@ -37,7 +68,10 @@ Change a schedule → it's updated. Idempotent, every time.
 
 ---
 
-## Quick start (Express)
+## Hosted quick start (Express)
+
+> Needs a Cronvello account. To stay local, skip to
+> [Local development](#local-development-no-account--cronvello-dev).
 
 ```ts
 // cronvello.ts
@@ -89,7 +123,7 @@ That's it. No dashboard clicks. The jobs in your code are the jobs that run.
 
 ---
 
-## Quick start (Next.js App Router)
+## Hosted quick start (Next.js App Router)
 
 ```ts
 // app/cronvello/dispatch/route.ts
@@ -221,15 +255,15 @@ your machine that actually fires the handlers when they're due — computing eac
 its cron expression (timezone- and DST-aware) and enforcing the same production policies the cloud
 does: **overlap protection, per-run timeout, and retry with backoff**. No cloud, no network.
 
+Jobs are the only required config. `apiKey`, `appUrl` and `dispatchSecret` belong to the hosted
+side, and nothing local asks for them:
+
 ```ts
 // cronvello.config.ts
 import { defineCronvello, every, daily } from "@cronvello/sdk";
 
 export const cronvello = defineCronvello({
   appName: "my-app",
-  appUrl: "https://my-app.example.com",
-  apiKey: "crn_local_dev",            // any non-empty value — the local engine never calls the API
-  dispatchSecret: "local-dev-secret-0123456789abcdef",
   timeZone: "Europe/Berlin",
   jobs: {
     heartbeat:      { schedule: every("10s"), handler: async () => { console.log("beat"); } },
@@ -295,15 +329,22 @@ npx cronvello dev --dashboard            # → http://127.0.0.1:4747  (override
 
 Open the printed URL and you get, live:
 
+- a **summary** across the session: jobs, runs, how many succeeded, how many failed, and what fires
+  next,
+- a **timeline** with one lane per job, plotting the runs that already happened next to the fires
+  still to come, around a now-line that moves as you watch. A schedule that is wrong is usually
+  obvious here before it is obvious anywhere else,
 - every **job** with its cron expression, timezone, and a **countdown to the next fire**,
-- a **run feed** that streams each fire, success, error, timeout, retry, and skip as it happens,
-- a **job drawer** with recent runs and the next fire times, plus a **Run now** button that triggers
-  the handler through the engine and shows the result instantly,
-- light + dark, and an honest **disconnected** state if the engine stops.
+- a **run feed** that streams each fire, success, error, timeout, retry, and skip as it happens, with
+  a pause that tells you how much you're missing,
+- a **job drawer** with the next fire times and recent runs, each one carrying its **error message**
+  or its **returned value**, plus a **Run now** button that triggers the handler through the engine,
+- light + dark, keyboard-reachable rows, and an honest **reconnecting** state if the engine stops.
 
 It binds to `127.0.0.1` by default (it's a dev tool, not a public server) and exposes a tiny
-read-only JSON API plus an SSE stream — including `GET /api/runs.ndjson` to pipe the run history out
-as NDJSON. You can also start it programmatically:
+read-only JSON API plus an SSE stream — `GET /api/state` for everything the page draws, and
+`GET /api/runs.ndjson` to pipe the run history out as NDJSON. You can also start it
+programmatically:
 
 ```ts
 const engine = cronvello.dev({ dashboard: true });   // or { dashboard: { port: 5000 } }
@@ -423,6 +464,10 @@ node -e "console.log(require('@cronvello/sdk').generateDispatchSecret())"
 Store it as `CRONVELLO_DISPATCH_SECRET` in both your app env and nowhere else — `sync()` registers
 it with Cronvello as the task's bearer token (encrypted at rest; never returned on read).
 
+An app defined without a `dispatchSecret` has no HTTP entry point to protect, so `expressHandler()`
+and `nextHandler()` refuse to be mounted at all, and a dispatch that somehow reaches `handle()` is
+rejected. There is no configuration in which an unauthenticated request runs a job.
+
 ---
 
 ## Long-running jobs — `async_callback`
@@ -549,6 +594,48 @@ Transient failures (429 / 5xx / network) are retried automatically with backoff.
 
 ---
 
+## Operator client
+
+You do not need this to *use* Cronvello. It is the backend-to-backend surface for the service
+that **provisions apps into** Cronvello — registering them, checking their registration, minting
+new per-app tokens, removing them.
+
+It is a separate class on purpose. It runs against the same host as `/v1`, but it takes
+Cronvello's **service key**, which is authorized across every registered app — far broader than
+an account `apiKey`. Two classes with two differently named options means you cannot send the
+wrong credential by accident.
+
+```ts
+import { CronvelloAdminClient } from "@cronvello/sdk";
+
+const admin = new CronvelloAdminClient({ serviceKey: process.env.CRONVELLO_SERVICE_KEY! });
+
+// Idempotent upsert, keyed on the string appId. Re-run it on every provisioning pass.
+const app = await admin.externalApps.register({
+  appId: "node-shop",
+  name: "Shop",
+  base_url: "https://shop.example.com",
+  generateApiKey: true,
+});
+app.generatedApiKey;  // plaintext, exactly ONCE, and only for a newly created app
+
+const status = await admin.externalApps.status("node-shop");
+// { registered, isActive, isLive, lastSyncedAt, jobCount }
+
+// Drift recovery when the current token is lost. Invalidates the old one.
+const { newApiKey } = await admin.externalApps.rotateKey("node-shop");
+
+// Takes the NUMERIC app id, not the string appId — an asymmetry in the server contract.
+await admin.externalApps.delete(app.id);
+```
+
+Cross-field rules (`base_url` or `targetUrl`; a key or `generateApiKey`; both OAuth credentials)
+are checked before the request leaves, so a bad call raises `CronvelloConfigError` synchronously
+rather than returning an opaque 400. Everything else — errors, retries, envelope handling —
+behaves exactly as the low-level client above.
+
+---
+
 ## License
 
 MIT