@cronvello/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cronvello
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# @cronvello/sdk
+
+**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.
+
+```bash
+npm i @cronvello/sdk
+```
+
+- ✅ **Zero runtime dependencies** (Node 18+ `fetch`).
+- ✅ **Dual ESM + CJS**, full TypeScript types.
+- ✅ **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.
+
+---
+
+## The idea
+
+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
+entry.** When a task is due, Cronvello calls your app back over HTTPS; the SDK's mounted handler
+verifies the call and runs the right job. Add a job → it appears. Remove a job → it's pruned.
+Change a schedule → it's updated. Idempotent, every time.
+
+---
+
+## Quick start (Express)
+
+```ts
+// cronvello.ts
+import { defineCronvello } 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
+
+  jobs: {
+    "send-daily-digest": {
+      schedule: "0 8 * * *",
+      handler: async () => {
+        await sendDigests();
+      },
+    },
+    "cleanup-temp": {
+      schedule: "*/15 * * * *",
+      description: "Purge temp files older than an hour",
+      handler: async ({ schedule }) => {
+        const removed = await purgeTemp();
+        return { removed, schedule };           // returned value is recorded on the run
+      },
+    },
+  },
+});
+```
+
+```ts
+// server.ts
+import express from "express";
+import { cronvello } from "./cronvello";
+
+const app = express();
+
+// Mount the dispatch endpoint Cronvello calls when a job is due.
+app.post(cronvello.dispatchPath, express.json(), cronvello.expressHandler());
+
+app.listen(3000, async () => {
+  // Reconcile the registry → Cronvello. Safe to run on every boot/deploy.
+  const result = await cronvello.sync();
+  console.log(`Cronvello synced: +${result.created} ~${result.updated} -${result.deleted}`);
+});
+```
+
+That's it. No dashboard clicks. The jobs in your code are the jobs that run.
+
+---
+
+## Quick start (Next.js App Router)
+
+```ts
+// app/cronvello/dispatch/route.ts
+import { cronvello } from "@/lib/cronvello";
+export const POST = cronvello.nextHandler();
+```
+
+```ts
+// scripts/sync-cron.ts  (run in CI / on deploy)
+import { cronvello } from "@/lib/cronvello";
+await cronvello.sync();
+```
+
+> On serverless hosts use the default **sync** execution mode so jobs finish within the request.
+> `async_callback` (below) needs a host that keeps running after the HTTP response.
+
+---
+
+## Defining jobs — two styles, your choice
+
+**Keyed object** (the key is the stable identity):
+
+```ts
+jobs: {
+  "rotate-keys": { schedule: "0 3 * * 0", handler: rotateKeys },
+}
+```
+
+**Array** (each entry carries its own `key`) — handy when jobs live across modules:
+
+```ts
+import { billingJobs } from "./billing/jobs";
+import { reportJobs } from "./reports/jobs";
+
+jobs: [...billingJobs, ...reportJobs]   // each: { key, schedule, handler, … }
+```
+
+### Job options
+
+| Field | Default | Notes |
+|---|---|---|
+| `schedule` | — | Cron expression, validated 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. |
+| `urgency` | — | `low` \| `medium` \| `high` \| `critical`. |
+| `maxRetries` | server default | 0–20. |
+| `executionMode` | `sync` | `async_callback` for long jobs (see below). |
+| `allowConcurrentRuns` | `false` | Allow overlap with an in-flight run. |
+| `payload` | — | Static object merged into the request body and exposed as `ctx.payload`. |
+| `enabled` | `true` | `false` keeps the code but stops scheduling. |
+
+### The handler context
+
+```ts
+handler: async (ctx) => {
+  ctx.key;       // "cleanup-temp"
+  ctx.schedule;  // "*/15 * * * *"
+  ctx.payload;   // your static payload, if any
+  ctx.body;      // full request body Cronvello sent
+  ctx.isAsync;   // true under async_callback mode
+};
+```
+
+---
+
+## `sync()` — idempotent reconcile
+
+```ts
+const result = await cronvello.sync();
+// { jobId, jobName, jobCreated, created, updated, unchanged, deleted, skipped, changes[] }
+```
+
+- Ensures one Cronvello **job container** named `appName`.
+- For each registry job: **creates** it (and starts it — Cronvello creates tasks disabled),
+  **patches** it when the schedule/options changed, or leaves it **unchanged**.
+- **Prunes** tasks in the container that are no longer in your registry (`prune: false` to keep them).
+- `dryRun: true` returns the diff without touching anything.
+
+Under the hood `sync()` does this in a **single server-side call** (`PUT /v1/registry`) when the
+API supports it, and transparently falls back to a client-side diff against older servers — you
+don't need to care which path ran.
+
+```ts
+await cronvello.sync({ dryRun: true });   // preview
+await cronvello.sync({ prune: false });   // never delete
+await cronvello.sync({ rotateSecret: true }); // re-write the dispatch secret on every task
+```
+
+Only tasks inside **your** app's container are ever touched — anything else in your account is
+left alone.
+
+### Trigger a job now
+
+```ts
+await cronvello.run("send-daily-digest");   // manual one-off run via Cronvello
+```
+
+---
+
+## Security model
+
+Cronvello calls your dispatch endpoint with `Authorization: Bearer <dispatchSecret>`. The mounted
+handler verifies it in **constant time** before running anything. Generate a strong secret once:
+
+```bash
+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).
+
+---
+
+## Long-running jobs — `async_callback`
+
+For work that exceeds the request timeout, set `executionMode: "async_callback"`. The handler
+returns immediately with `202`, runs in the background, and the SDK posts the result back to
+Cronvello (HMAC-signed). Use only on a host that keeps executing after the response (a
+long-running Node server — **not** typical serverless).
+
+```ts
+"rebuild-search-index": {
+  schedule: "0 4 * * *",
+  executionMode: "async_callback",
+  callbackTimeoutMs: 600_000,
+  handler: async () => { await rebuildIndex(); },
+}
+```
+
+---
+
+## Low-level client
+
+The full typed `/v1` surface, for anything beyond the registry model:
+
+```ts
+import { CronvelloClient } from "@cronvello/sdk";
+
+const cv = new CronvelloClient({ apiKey: process.env.CRONVELLO_API_KEY! });
+
+const jobs = await cv.jobs.list();
+const job = await cv.jobs.create({ name: "adhoc" });
+const task = await cv.jobs.createTask(job.id, {
+  name: "ping",
+  schedule: "* * * * *",
+  targetUrl: "https://example.com/ping",
+});
+await cv.tasks.start(task.id);
+
+const runs = await cv.runs.list({ limit: 20 });
+const me = await cv.account.me();
+```
+
+Endpoints not yet wrapped (heartbeat monitors, maintenance windows, DLQ, notification channels,
+audit log, API-key self-service, analytics) are reachable via the escape hatch:
+
+```ts
+const monitors = await cv.request("GET", "/v1/heartbeat-monitors");
+```
+
+### Errors
+
+```ts
+import { CronvelloApiError } from "@cronvello/sdk";
+
+try {
+  await cv.jobs.get("missing");
+} catch (e) {
+  if (e instanceof CronvelloApiError) {
+    e.status;             // 404
+    e.isNotFound;         // true
+    e.isRateLimited;      // false
+    e.retryAfterSeconds;  // set on 429
+  }
+}
+```
+
+Transient failures (429 / 5xx / network) are retried automatically with backoff.
+
+---
+
+## License
+
+MIT