SDK API

The public surface of @weev/sdk: register jobs, receive execution, report outcomes. This page is a reference companion to the quickstart.

Registration

weev.job(config, handler)

Registers one job. Returns void; throws DuplicateJobError if a job with the same name is already registered. The handler is async (ctx) => result — its return value is reported as the run result and must be JSON-serializable.

Signature

weev.job(
  config: JobConfig,
  handler: (ctx: JobContext) => Promise<unknown>
): void

name

string, required. Stable job identifier — unique across the whole manifest, not just the batch.

batch

string, required. Groups related jobs into one workflow.

description

string, optional. Free-text description shown in the console.

predecessors

string[], optional. Upstream jobs (in the same batch) that must finish first.

These four fields are the complete config. Schedules are configured in Weev after deployment, not in code.

Execution

JobContext

Every handler receives one context object per dispatched run.

runId

string — the jobRunId of this dispatch.

batchRunId

string — the enclosing batch run.

jobName / batchName

string — from the registered config.

signal

AbortSignal — aborted when Weev requests cancellation. Cooperative: check it in long loops.

log(level, message, meta?)

Structured logger. Levels: "info" | "warn" | "error" | "debug". Emits single-line JSON with runId and job injected.

Transport

createWeevMiddleware(options?)

Imported from @weev/sdk/express (not the package root). Returns an Express Router that mounts exactly one route — POST /.weev/run — where Weev delivers execution offers. Express 4 and 5 are supported as an optional peer dependency.

Mount

import { createWeevMiddleware } from "@weev/sdk/express";

app.use(createWeevMiddleware({
  // all options fall back to env vars
  token: process.env.WEEV_TOKEN,
  runToken: process.env.WEEV_RUN_TOKEN
}));

apiUrl

Weev API base URL. Default: WEEV_API_URL, else https://api.weev.dev.

token

Inbound key (wvin_) used on callbacks to Weev. Default: WEEV_TOKEN.

runToken

Expected bearer on incoming offers (the wvout_ key). Default: WEEV_RUN_TOKEN. If unset, /.weev/run accepts unauthenticated offers and the SDK logs a loud warning.

heartbeatIntervalMs

Lease heartbeat interval. Default 30000.

maxConcurrentJobs

Concurrency cap before offers are answered busy. Default 50.

The first call also registers process-wide SIGTERM/SIGINT handlers so in-flight runs shut down cleanly. The offer/claim/heartbeat/complete flow behind this endpoint is documented in Webhooks & the execution endpoint.

Errors

Error classes

The SDK exports WeevError (base class with code and details) and DuplicateJobError (code: "DUPLICATE_JOB", thrown at registration time). Handler failures don't need special error types — throw anything, and the run is reported failed with the error message.