# Cron Jobs

Cron Jobs run a site's TypeScript on a UTC schedule. They use the same isolated
runtime, site data, and site secrets as [Functions](/functions), but do not have
a browser request or user session.

## The contract

Create one self-contained TypeScript file under `/cron/`. Export a static
five-field schedule and a named handler:

```ts
export const schedule = '*/5 * * * *'

export async function handler(event: CronEvent, ctx: InterfoldCronContext) {
  await ctx.data.writeJson('/data/cron-smoke.json', {
    runId: event.runId,
    scheduledAt: event.scheduledAt,
    triggeredAt: event.triggeredAt,
  })
}
```

- **Source path:** `/cron/<name>.ts`, exactly one segment under `/cron/`.
- **Schedule:** a string-literal, five-field cron expression.
- **Time zone:** UTC.
- **Minimum cadence:** five minutes.
- **Signature:** `handler(event: CronEvent, ctx: InterfoldCronContext)`.
- **Imports:** no imports, npm packages, or Node built-ins in v0.

The schedule is extracted statically during deployment. Interfold does not
execute your code to discover when it should run.

## Deploying

Cron Jobs use the existing file upload command; no separate CLI command is
needed:

```sh
interfold files put ./smoke.ts /cron/smoke.ts \
  --site <site-id> \
  --content-type text/typescript
```

The response includes the cron definition and deployment status. Cron source is
a private workspace resource and has no public runtime URL.

To verify a job that writes site data, wait for the next tick and inspect the
result:

```sh
interfold files cat /data/cron-smoke.json --site <site-id>
```

## Event and delivery semantics

The event includes:

| Property            | Description                                      |
| ------------------- | ------------------------------------------------ |
| `event.runId`       | Stable idempotency key for this scheduled run.   |
| `event.scheduledAt` | Time the run was scheduled for.                  |
| `event.triggeredAt` | Time Interfold dispatched the run.               |
| `event.trigger`     | `SCHEDULED` in the current customer-facing flow. |

Delivery is at least once. Use `runId` as an idempotency key when calling an
external system. V0 does not overlap two runs of the same cron, retry failed
tenant handlers automatically, or create a catch-up burst after downtime.

Deleting the `/cron/*.ts` source disables future runs while preserving
platform-owned run history.

---

Next: [Databases](/databases) for structured data · [Data files](/data-storage)
for file-shaped data · [Secrets](/secrets) for runtime configuration.