Cron Jobs

Run code on a schedule. The platform calls a path of your app on a cron schedule;
your app handles it in its normal handler. Typical uses: send reminder emails,
clean up stale rows, refresh a cache, send a daily digest.

There is no separate "cron handler" — a cron run is just an HTTP request to your app
that carries an auth token and a marker header. Verify it with isCronRequest(req).

Two ways to define jobs

1. Declarative — onvibe.json (recommended, version-controlled)

Add an onvibe.json file at the project root. It is reconciled on every deploy:
jobs are created/updated, and jobs removed from the file are deleted.

{
  "crons": [
    {
      "name": "reminders",
      "schedule": "0 9 * * *",
      "path": "/cron/reminders",
      "timezone": "Europe/Madrid"
    }
  ]
}

- name: unique per project, lowercase letters/digits/hyphens.
- schedule: standard 5-field cron (min hour day-of-month month day-of-week).
- path: a path of your app to call, must start with /.
- method: POST (default) or GET.
- timezone: IANA name (e.g. Europe/Madrid); defaults to UTC.

2. Imperative — create_cron tool

For dynamic management. Jobs created this way are independent from onvibe.json
(they are not removed by a deploy).

create_cron({ project_id, name, schedule, path, method?, timezone? })
list_crons({ project_id })
delete_cron({ project_id, name })
run_cron({ project_id, name })   // trigger once now, for testing

Handling the trigger in your app

Gate the cron logic with isCronRequest(req) so public traffic can't trigger it.

import { isCronRequest } from "./.onvibe/helpers.ts";

export default async function handler(req: Request): Promise<Response> {
  const url = new URL(req.url);
  if (url.pathname === "/cron/reminders" && isCronRequest(req)) {
    await sendReminders();           // scan DB, send emails, etc.
    return new Response("ok");
  }
  // ...rest of the app
}

isCronRequest(req) returns true only when the request carries the X-Onvibe-Cron
header AND the correct APP_TOKEN bearer (set by the platform). cronName(req)
returns the job name if you serve several jobs from one path.

Limits & semantics

- Granularity: 1 minute (standard cron). No sub-minute schedules.
- Per-run timeout: ~60s. Keep jobs short; for heavy work, do it in batches.
- Overlap: if a run is still going when the next is due, the new one is skipped.
- Missed runs: after downtime, a job fires once (missed slots are not replayed),
  then resumes its normal schedule.
- At-least-once: design handlers to be idempotent (a run may rarely repeat).

Example: daily expiry reminders

{ "crons": [{ "name": "reminders", "schedule": "0 9 * * *", "path": "/cron/reminders", "timezone": "Europe/Madrid" }] }

import { isCronRequest } from "./.onvibe/helpers.ts";

async function handler(req: Request): Promise<Response> {
  const url = new URL(req.url);
  if (url.pathname === "/cron/reminders" && isCronRequest(req)) {
    const { rows } = await pool.query(
      "SELECT email, name FROM items WHERE expires_on = CURRENT_DATE + 3",
    );
    for (const r of rows) {
      // send an email to r.email (see onvibe://docs/email when available)
    }
    return new Response(sent ${rows.length});
  }
  return new Response("not found", { status: 404 });
}
export default handler;

Notes

- Test a job without waiting for its schedule with run_cron (or just hit the path
  yourself — but it will return early unless isCronRequest passes).
- A job declared in onvibe.json will reappear on the next deploy even if you delete
  it via delete_cron; remove it from onvibe.json to delete it permanently.
- See the job's recent runs and next run with list_crons.