@cronvello/sdk 0.1.0

package/dist/dispatch-handler-Bnda1Ekq.d.cts

@@ -0,0 +1,515 @@
+/**
+ * Minimal HTTP transport over the global `fetch` (Node 18+). No axios, no node-fetch —
+ * zero runtime dependencies. Adds bearer auth, JSON (de)serialization, typed error mapping,
+ * bounded retries with backoff for transient failures, and optional idempotency keys.
+ */
+type FetchLike = (input: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}>;
+interface TransportOptions {
+    baseUrl: string;
+    apiKey: string;
+    /** Per-request timeout in ms. Default 30_000. */
+    timeoutMs?: number;
+    /** Max retry attempts for 429/5xx/network errors. Default 2 (=> up to 3 tries). */
+    maxRetries?: number;
+    /** Override the fetch implementation (testing / custom agents). */
+    fetch?: FetchLike;
+    /** Extra headers sent on every request (e.g. a custom User-Agent). */
+    defaultHeaders?: Record<string, string>;
+    /** Telemetry hook — called once per completed attempt. */
+    onRequest?: (info: {
+        method: string;
+        path: string;
+        status: number;
+        attempt: number;
+        durationMs: number;
+    }) => void;
+}
+interface RequestOptions {
+    method: string;
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    /** Idempotency-Key header value — replays of the same key are de-duplicated server-side. */
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+declare class Transport {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    private readonly defaultHeaders;
+    private readonly onRequest;
+    constructor(opts: TransportOptions);
+    request<T>(opts: RequestOptions): Promise<T>;
+    private buildUrl;
+    private withTimeout;
+    private backoff;
+}
+
+/**
+ * Wire types for the Cronvello public `/v1` API.
+ *
+ * These mirror the server-side Zod DTOs (`src/routes/v1/v1.dto.ts` in node-cron) but are
+ * hand-authored as plain TypeScript so the SDK ships with ZERO runtime dependencies. When
+ * the server contract changes, update these to match — they are the single source of truth
+ * for the SDK's request/response shapes. See `scripts/check-contract.md` for the drift check.
+ */
+type Urgency = "low" | "medium" | "high" | "critical";
+type ExecutionMode = "sync" | "async_callback";
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD";
+type JobStatus = "DISABLED" | "ACTIVE" | "ERROR" | "ERROR_MAX_RETRIES";
+type RunStatus = "queued" | "running" | "completed" | "failed";
+type RunType = "scheduled" | "manual";
+type CallbackStatus = "pending" | "acknowledged" | "completed" | "failed" | "timed_out";
+/** Optional success assertions beyond the default 2xx check. */
+interface SuccessCriteria {
+    statusCodeMin?: number;
+    statusCodeMax?: number;
+    bodyContains?: string;
+    bodyJsonPath?: string;
+    bodyJsonEquals?: string | number | boolean;
+    bodyRegex?: string;
+}
+interface PublicJob {
+    id: string;
+    name: string;
+    description: string | null;
+    status: JobStatus;
+    urgency: Urgency | null;
+    createdAt: string;
+    updatedAt: string | null;
+    taskCount: number;
+    activeTaskCount: number;
+    errorTaskCount: number;
+}
+interface JobCreateBody {
+    name: string;
+    description?: string;
+}
+interface JobUpdateBody {
+    name?: string;
+    description?: string | null;
+}
+interface TaskCreateBody {
+    name: string;
+    description?: string;
+    /** Cron expression (validated server-side). */
+    schedule: string;
+    /** IANA timezone; defaults to "Europe/Berlin" server-side. */
+    timeZone?: string;
+    /** HTTPS endpoint Cronvello calls when the task is due. */
+    targetUrl: string;
+    /** Bearer token Cronvello attaches as `Authorization: Bearer <token>`. Encrypted at rest. */
+    targetToken?: string;
+    /** HTTP method for the outbound call (default POST). */
+    method?: HttpMethod;
+    /** Custom request headers (values encrypted at rest, never returned on read). */
+    headers?: Record<string, string>;
+    /** JSON string forwarded to the target as the request body. */
+    requestBody?: string;
+    requestTimeoutMs?: number;
+    successCriteria?: SuccessCriteria;
+    urgency?: Urgency;
+    maxRetries?: number;
+    executionMode?: ExecutionMode;
+    callbackTimeoutMs?: number;
+    allowConcurrentRuns?: boolean;
+}
+interface TaskUpdateBody {
+    name?: string;
+    description?: string | null;
+    schedule?: string;
+    timeZone?: string;
+    targetUrl?: string;
+    targetToken?: string | null;
+    method?: HttpMethod;
+    headers?: Record<string, string> | null;
+    requestBody?: string | null;
+    requestTimeoutMs?: number | null;
+    successCriteria?: SuccessCriteria | null;
+    urgency?: Urgency;
+    maxRetries?: number;
+    executionMode?: ExecutionMode;
+    callbackTimeoutMs?: number | null;
+    allowConcurrentRuns?: boolean;
+}
+interface PublicTask {
+    id: string;
+    jobId: string;
+    jobName: string;
+    name: string;
+    description: string | null;
+    schedule: string;
+    timeZone: string;
+    type: string;
+    status: JobStatus;
+    targetUrl: string | null;
+    hasTargetToken: boolean;
+    method: HttpMethod;
+    customHeaderNames: string[];
+    requestBody: string | null;
+    requestTimeoutMs: number | null;
+    successCriteria: SuccessCriteria | null;
+    urgency: Urgency | null;
+    maxRetries: number | null;
+    executionMode: string | null;
+    callbackTimeoutMs: number | null;
+    allowConcurrentRuns: boolean | null;
+    nextRun: string | null;
+    lastRunAt: string | null;
+    lastRunStatus: RunStatus | null;
+    createdAt: string;
+    hasOpenDlq: boolean;
+    statusReason: string;
+}
+interface PublicRun {
+    id: string;
+    jobTaskId: string;
+    taskName: string;
+    jobId: string;
+    jobName: string;
+    status: RunStatus;
+    runType: RunType;
+    httpStatusCode: number | null;
+    responseBody: string | null;
+    startedAt: string | null;
+    endedAt: string | null;
+    durationMs: number | null;
+    error: string | null;
+    executionMode: string | null;
+    callbackStatus: CallbackStatus | null;
+}
+interface Pagination {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+}
+interface RunsPage {
+    runs: PublicRun[];
+    pagination: Pagination;
+}
+interface TasksPage {
+    tasks: PublicTask[];
+    pagination: Pagination;
+}
+interface RunNowResult {
+    success: boolean;
+    runId?: string;
+    async?: boolean;
+    error?: string;
+}
+interface RegistryTaskInput {
+    key: string;
+    schedule: string;
+    targetUrl: string;
+    targetToken?: string;
+    method?: HttpMethod;
+    headers?: Record<string, string>;
+    requestBody?: string;
+    requestTimeoutMs?: number;
+    timeZone?: string;
+    description?: string;
+    urgency?: Urgency;
+    maxRetries?: number;
+    executionMode?: ExecutionMode;
+    callbackTimeoutMs?: number;
+    allowConcurrentRuns?: boolean;
+    successCriteria?: SuccessCriteria;
+    enabled?: boolean;
+}
+interface RegistryReconcileRequest {
+    appName: string;
+    description?: string;
+    tasks: RegistryTaskInput[];
+    prune?: boolean;
+    rotateSecret?: boolean;
+}
+interface RegistryReconcileChange {
+    key: string;
+    action: "created" | "updated" | "unchanged" | "deleted" | "skipped";
+    taskId: string | null;
+    changedFields?: string[];
+}
+interface RegistryReconcileResponse {
+    job: PublicJob;
+    jobCreated: boolean;
+    created: number;
+    updated: number;
+    unchanged: number;
+    deleted: number;
+    skipped: number;
+    changes: RegistryReconcileChange[];
+    tasks: PublicTask[];
+}
+interface MeResponse {
+    accountId: number;
+    accountName: string;
+    email: string;
+    isActive: boolean;
+    createdAt: string;
+    serverTime: string;
+    plan: {
+        planName: string;
+        displayName: string;
+    } | null;
+    limits: {
+        maxJobs: number | null;
+        maxTasksPerJob: number | null;
+        minIntervalSeconds: number | null;
+        rateLimitPerMinute: number | null;
+        rateLimitPerHour: number | null;
+    };
+    usage: {
+        jobsUsed: number;
+        period: {
+            start: string;
+            end: string;
+        };
+        executionCount: number;
+        executionQuota: number | null;
+    };
+    summary: {
+        openDlqCount: number;
+        heartbeatNeedsAttention: number;
+        activeMaintenanceWindows: number;
+    };
+}
+interface UsageResponse {
+    accountId: number;
+    serverTime: string;
+    plan: {
+        planName: string;
+        displayName: string;
+    } | null;
+    period: {
+        start: string;
+        end: string;
+    };
+    usage: {
+        executionCount: number;
+        quota: number | null;
+        quotaExceeded: boolean;
+        quotaUsedPercent: number | null;
+    };
+}
+interface RunsQuery {
+    page?: number;
+    limit?: number;
+    status?: RunStatus;
+    runType?: RunType;
+}
+interface AccountTasksQuery {
+    page?: number;
+    limit?: number;
+    jobId?: string;
+    status?: JobStatus;
+}
+interface AccountRunsQuery {
+    page?: number;
+    limit?: number;
+    taskId?: string;
+    jobId?: string;
+    status?: RunStatus;
+    runType?: RunType;
+}
+
+/**
+ * Public types for the code-first registry layer (`defineCronvello`).
+ */
+
+/** Context passed to a job handler when Cronvello fires it. */
+interface CronvelloJobContext<Payload = Record<string, unknown>> {
+    /** The stable registry key of the job being run. */
+    key: string;
+    /** The cron schedule Cronvello fired for (echoed back in the request body). */
+    schedule: string;
+    /** Static payload configured on the job, if any. */
+    payload: Payload;
+    /** The full parsed request body Cronvello sent. */
+    body: Record<string, unknown>;
+    /** Raw request headers (lower-cased keys). */
+    headers: Record<string, string>;
+    /** True when this is an async_callback run (handler may take longer than the HTTP timeout). */
+    isAsync: boolean;
+    /** Aborts if the runtime cancels the request. */
+    signal: AbortSignal | undefined;
+}
+type CronvelloJobHandler<Payload = Record<string, unknown>> = (ctx: CronvelloJobContext<Payload>) => unknown | Promise<unknown>;
+/** Shape of a single job in the keyed-object form. */
+interface CronvelloJobConfig<Payload = Record<string, unknown>> {
+    /** Cron expression, e.g. "0 8 * * *". Validated by Cronvello on sync. */
+    schedule: string;
+    /** The function that runs when the job fires. */
+    handler: CronvelloJobHandler<Payload>;
+    /** Human description (stored on the Cronvello task). */
+    description?: string;
+    /** IANA timezone for this job's schedule. Defaults to the app-level `timeZone`. */
+    timeZone?: string;
+    urgency?: Urgency;
+    /** Max automatic retries on failure (0–20). */
+    maxRetries?: number;
+    /**
+     * "sync" (default): handler runs inline, result returned in the HTTP response.
+     * "async_callback": respond immediately, run in the background, post the result back.
+     * Use async only for work that exceeds the request timeout AND a long-running (non-serverless) host.
+     */
+    executionMode?: ExecutionMode;
+    /** Async-mode budget before Cronvello marks the run timed out (ms). */
+    callbackTimeoutMs?: number;
+    /** Allow a new run to start while a previous one is still in flight (default false). */
+    allowConcurrentRuns?: boolean;
+    /** Optional success assertions beyond the default 2xx. */
+    successCriteria?: SuccessCriteria;
+    /** Static payload merged into the request body Cronvello stores and sends. */
+    payload?: Payload;
+    /** Set false to keep the code but stop syncing/scheduling this job. */
+    enabled?: boolean;
+}
+/** Array form — each entry carries its own stable `key`. */
+interface CronvelloJobConfigWithKey extends CronvelloJobConfig {
+    /** Stable identity. Renaming the display elsewhere never breaks the link. */
+    key: string;
+}
+/** Jobs may be declared as a keyed object (key = identity) or an array of keyed entries. */
+type CronvelloJobsInput = Record<string, CronvelloJobConfig> | CronvelloJobConfigWithKey[];
+interface CronvelloLogger {
+    debug?(msg: string, meta?: Record<string, unknown>): void;
+    info?(msg: string, meta?: Record<string, unknown>): void;
+    warn?(msg: string, meta?: Record<string, unknown>): void;
+    error?(msg: string, meta?: Record<string, unknown>): void;
+}
+interface CronvelloAppConfig {
+    /** Your jobs — keyed object or array form. */
+    jobs: CronvelloJobsInput;
+    /**
+     * App identity. Becomes the name of the single Cronvello Job container that holds all
+     * your tasks. Must be stable and unique within your account.
+     */
+    appName: string;
+    /**
+     * Public base URL of THIS app, where Cronvello delivers callbacks.
+     * e.g. "https://app.example.com". The dispatch handler is mounted under it.
+     */
+    appUrl: string;
+    /** Cronvello account API key (`crn_live_…`). */
+    apiKey: string;
+    /**
+     * Shared secret. Cronvello sends it back as `Authorization: Bearer <secret>` on every
+     * dispatch; the mounted handler verifies it in constant time. Generate a strong random
+     * value and store it in your env (e.g. `openssl rand -hex 32`).
+     */
+    dispatchSecret: string;
+    /** Path the dispatch handler is mounted at. Default "/cronvello/dispatch". */
+    dispatchPath?: string;
+    /** Cronvello API base URL. Default "https://api.cronvello.com". */
+    baseUrl?: string;
+    /** Default timezone for jobs that don't set their own. Default "Europe/Berlin". */
+    timeZone?: string;
+    /** Per-request API timeout in ms (default 30_000). */
+    timeoutMs?: number;
+    /** Retry attempts for transient API failures (default 2). */
+    maxRetries?: number;
+    /** Custom fetch implementation (default: global fetch). */
+    fetch?: FetchLike;
+    /** Optional structured logger. */
+    logger?: CronvelloLogger;
+}
+/** Per-job result of a reconcile. */
+interface ReconcileTaskChange {
+    key: string;
+    action: "created" | "updated" | "unchanged" | "deleted" | "skipped";
+    taskId: string | null;
+    /** Field names that changed (for "updated"). */
+    changedFields?: string[];
+    reason?: string;
+}
+interface ReconcileResult {
+    jobId: string;
+    jobName: string;
+    /** True if the Job container was created during this sync. */
+    jobCreated: boolean;
+    created: number;
+    updated: number;
+    unchanged: number;
+    deleted: number;
+    skipped: number;
+    changes: ReconcileTaskChange[];
+    /** Resulting tasks — populated when the reconcile ran server-side (PUT /v1/registry). */
+    tasks?: PublicTask[];
+}
+interface SyncOptions {
+    /**
+     * Delete tasks in the app's Job container that are no longer in the registry.
+     * Default true — the container is fully SDK-managed. Set false to leave orphans.
+     */
+    prune?: boolean;
+    /** Re-write the dispatch secret on every task even if unchanged (use after rotating). */
+    rotateSecret?: boolean;
+    /** Compute the diff and return it WITHOUT making any changes. */
+    dryRun?: boolean;
+}
+
+/**
+ * Framework-neutral dispatch core.
+ *
+ * Cronvello fires a due task by POSTing to the app's dispatch URL with
+ *   Authorization: Bearer <dispatchSecret>
+ *   body: { job: "<registry-key>", schedule: "<cron>", ...payload, _callback?: {...} }
+ *
+ * This module verifies the bearer, selects the job by key, runs its handler, and returns a
+ * response. The Express/Next adapters are thin shells that translate their request/response
+ * objects to/from the neutral shapes below.
+ */
+
+interface ResolvedJob {
+    key: string;
+    config: CronvelloJobConfig;
+}
+interface DispatchRequest {
+    method: string;
+    /** Value of the Authorization header, if any. */
+    authorization: string | undefined;
+    /** Raw request body as text. */
+    rawBody: string;
+    /** Lower-cased request headers. */
+    headers: Record<string, string>;
+    /** Abort signal for the inbound request, if the host provides one. */
+    signal?: AbortSignal;
+    /**
+     * Optional serverless lifecycle hook (e.g. Vercel/Cloudflare `ctx.waitUntil`). When present,
+     * async_callback background work is registered with it so the function stays alive until done.
+     */
+    waitUntil?: (promise: Promise<unknown>) => void;
+}
+interface DispatchResponse {
+    status: number;
+    body: Record<string, unknown>;
+}
+
+/**
+ * The minimal interface the adapters depend on: anything that can turn a neutral
+ * `DispatchRequest` into a `DispatchResponse`. `CronvelloApp` implements it.
+ */
+
+interface DispatchHandler {
+    handle(req: DispatchRequest): Promise<DispatchResponse>;
+}
+
+export { type AccountTasksQuery as A, type RunStatus as B, type CronvelloAppConfig as C, type DispatchRequest as D, type ExecutionMode as E, type FetchLike as F, type RunType as G, type HttpMethod as H, type SuccessCriteria as I, type JobCreateBody as J, type Urgency as K, type DispatchHandler as L, type MeResponse as M, type PublicJob as P, type RunNowResult as R, type SyncOptions as S, Transport as T, type UsageResponse as U, type JobUpdateBody as a, type PublicTask as b, type TaskCreateBody as c, type TasksPage as d, type TaskUpdateBody as e, type RunsQuery as f, type RunsPage as g, type AccountRunsQuery as h, type PublicRun as i, type RegistryReconcileRequest as j, type RegistryReconcileResponse as k, type ResolvedJob as l, type ReconcileResult as m, type DispatchResponse as n, type CallbackStatus as o, type CronvelloJobConfig as p, type CronvelloJobConfigWithKey as q, type CronvelloJobContext as r, type CronvelloJobHandler as s, type CronvelloJobsInput as t, type CronvelloLogger as u, type JobStatus as v, type Pagination as w, type ReconcileTaskChange as x, type RegistryReconcileChange as y, type RegistryTaskInput as z };