@cronvello/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,214 @@
+import { T as Transport, P as PublicJob, J as JobCreateBody, a as JobUpdateBody, b as PublicTask, c as TaskCreateBody, A as AccountTasksQuery, d as TasksPage, e as TaskUpdateBody, R as RunNowResult, f as RunsQuery, g as RunsPage, h as AccountRunsQuery, i as PublicRun, M as MeResponse, U as UsageResponse, F as FetchLike, j as RegistryReconcileRequest, k as RegistryReconcileResponse, l as ResolvedJob, S as SyncOptions, m as ReconcileResult, D as DispatchRequest, n as DispatchResponse, C as CronvelloAppConfig } from './dispatch-handler-Bnda1Ekq.js';
+export { o as CallbackStatus, p as CronvelloJobConfig, q as CronvelloJobConfigWithKey, r as CronvelloJobContext, s as CronvelloJobHandler, t as CronvelloJobsInput, u as CronvelloLogger, E as ExecutionMode, H as HttpMethod, v as JobStatus, w as Pagination, x as ReconcileTaskChange, y as RegistryReconcileChange, z as RegistryTaskInput, B as RunStatus, G as RunType, I as SuccessCriteria, K as Urgency } from './dispatch-handler-Bnda1Ekq.js';
+import { ExpressDispatchHandler } from './express.js';
+import { NextRouteHandler } from './next.js';
+
+/**
+ * Low-level, fully-typed client for the Cronvello public `/v1` API.
+ *
+ * This is the thin REST layer: one method per endpoint, request/response types straight
+ * from the server contract. The high-level registry (`defineCronvello`) is built on top of
+ * it. Use this directly when you need ad-hoc control beyond the registry model.
+ */
+
+/** The production Cronvello API. Override `baseUrl` only for self-hosting or testing. */
+declare const CRONVELLO_DEFAULT_BASE_URL = "https://api.cronvello.com";
+interface CronvelloClientOptions {
+    /** Account API key (`crn_live_…`). Required. */
+    apiKey: string;
+    /** API base URL. Defaults to https://api.cronvello.com. */
+    baseUrl?: string;
+    /** Per-request timeout in ms (default 30_000). */
+    timeoutMs?: number;
+    /** Retry attempts for 429/5xx/network errors (default 2). */
+    maxRetries?: number;
+    /** Custom fetch implementation (default: global fetch). */
+    fetch?: FetchLike;
+    /** Telemetry hook for every request attempt. */
+    onRequest?: (info: {
+        method: string;
+        path: string;
+        status: number;
+        attempt: number;
+        durationMs: number;
+    }) => void;
+}
+declare class CronvelloClient {
+    private readonly transport;
+    /** The resolved base URL in use. */
+    readonly baseUrl: string;
+    /** Job container operations. */
+    readonly jobs: JobsResource;
+    /** Scheduled task operations. */
+    readonly tasks: TasksResource;
+    /** Execution-history (run) operations. */
+    readonly runs: RunsResource;
+    /** Account identity + usage. */
+    readonly account: AccountResource;
+    constructor(options: CronvelloClientOptions);
+    /**
+     * Atomically reconcile a whole code registry server-side (`PUT /v1/registry`): one job
+     * container + its tasks, created/updated/pruned/started in a single call. This is what
+     * `defineCronvello().sync()` prefers; the high-level API builds the body for you.
+     */
+    reconcileRegistry(body: RegistryReconcileRequest, opts?: {
+        idempotencyKey?: string;
+    }): Promise<RegistryReconcileResponse>;
+    /**
+     * Escape hatch for endpoints not yet wrapped by a typed method (heartbeat monitors,
+     * maintenance windows, DLQ, notification channels, audit log, API-key self-service …).
+     * `T` is the response shape you expect.
+     */
+    request<T>(method: string, path: string, opts?: {
+        query?: Record<string, string | number | boolean | undefined>;
+        body?: unknown;
+        idempotencyKey?: string;
+    }): Promise<T>;
+}
+declare class JobsResource {
+    private readonly t;
+    constructor(t: Transport);
+    list(): Promise<PublicJob[]>;
+    get(jobId: string): Promise<PublicJob>;
+    create(body: JobCreateBody, opts?: {
+        idempotencyKey?: string;
+    }): Promise<PublicJob>;
+    update(jobId: string, body: JobUpdateBody): Promise<PublicJob>;
+    delete(jobId: string): Promise<null>;
+    start(jobId: string): Promise<PublicJob>;
+    stop(jobId: string): Promise<PublicJob>;
+    listTasks(jobId: string): Promise<PublicTask[]>;
+    createTask(jobId: string, body: TaskCreateBody, opts?: {
+        idempotencyKey?: string;
+    }): Promise<PublicTask>;
+}
+declare class TasksResource {
+    private readonly t;
+    constructor(t: Transport);
+    /** Account-wide paginated task table. */
+    list(query?: AccountTasksQuery): Promise<TasksPage>;
+    get(taskId: string): Promise<PublicTask>;
+    update(taskId: string, body: TaskUpdateBody): Promise<PublicTask>;
+    delete(taskId: string): Promise<null>;
+    start(taskId: string): Promise<PublicTask>;
+    stop(taskId: string): Promise<PublicTask>;
+    /** Trigger a one-off manual execution (does not change the schedule). */
+    runNow(taskId: string): Promise<RunNowResult>;
+    listRuns(taskId: string, query?: RunsQuery): Promise<RunsPage>;
+}
+declare class RunsResource {
+    private readonly t;
+    constructor(t: Transport);
+    /** Account-wide paginated activity feed. */
+    list(query?: AccountRunsQuery): Promise<RunsPage>;
+    get(runId: string): Promise<PublicRun>;
+}
+declare class AccountResource {
+    private readonly t;
+    constructor(t: Transport);
+    me(): Promise<MeResponse>;
+    usage(): Promise<UsageResponse>;
+}
+
+/**
+ * `defineCronvello` — the high-level, code-first entry point.
+ *
+ *   export const cronvello = defineCronvello({
+ *     appName: "my-app",
+ *     appUrl: process.env.APP_URL!,
+ *     apiKey: process.env.CRONVELLO_API_KEY!,
+ *     dispatchSecret: process.env.CRONVELLO_DISPATCH_SECRET!,
+ *     jobs: {
+ *       "send-daily-digest": { schedule: "0 8 * * *", handler: async () => { … } },
+ *       "cleanup-temp":      { schedule: "*\/15 * * * *", handler: async () => { … } },
+ *     },
+ *   });
+ *
+ *   await cronvello.sync();                 // reconcile the registry to Cronvello (idempotent)
+ *   app.post(cronvello.dispatchPath, express.json(), cronvello.expressHandler());
+ */
+
+interface CronvelloApp {
+    /** The underlying low-level client for ad-hoc `/v1` calls. */
+    readonly client: CronvelloClient;
+    /** Resolved jobs, keyed by their stable registry key. */
+    readonly jobs: ReadonlyMap<string, ResolvedJob>;
+    /** The app identity / Job-container name. */
+    readonly appName: string;
+    /** Path the dispatch handler should be mounted at (e.g. "/cronvello/dispatch"). */
+    readonly dispatchPath: string;
+    /** Absolute URL Cronvello calls back (appUrl + dispatchPath). */
+    readonly dispatchUrl: string;
+    /** Reconcile the registry into Cronvello. Idempotent — safe to call on every boot/deploy. */
+    sync(options?: SyncOptions): Promise<ReconcileResult>;
+    /** Trigger one job immediately via Cronvello (manual run). Requires a prior `sync()`. */
+    run(key: string): Promise<RunNowResult>;
+    /** Framework-neutral dispatch entry — used by the adapters. */
+    handle(req: DispatchRequest): Promise<DispatchResponse>;
+    /** Express/Connect request handler for the dispatch endpoint. */
+    expressHandler(): ExpressDispatchHandler;
+    /** Next.js App Router (Route Handler) for the dispatch endpoint. */
+    nextHandler(): NextRouteHandler;
+    /** The registry keys, for diagnostics. */
+    keys(): string[];
+}
+declare function defineCronvello(config: CronvelloAppConfig): CronvelloApp;
+
+/**
+ * Error taxonomy for the SDK. Everything thrown by the public surface is a
+ * `CronvelloError` (or subclass), so callers can `catch (e) { if (e instanceof CronvelloError) … }`.
+ */
+declare class CronvelloError extends Error {
+    constructor(message: string);
+}
+/** A non-2xx response from the Cronvello API. */
+declare class CronvelloApiError extends CronvelloError {
+    /** HTTP status code. */
+    readonly status: number;
+    /** Machine-readable error code from the API body, when present. */
+    readonly code: string | undefined;
+    /** The method + path that failed, e.g. `POST /v1/jobs`. */
+    readonly endpoint: string;
+    /** Parsed response body (best effort). */
+    readonly body: unknown;
+    /** Seconds to wait before retrying, parsed from `Retry-After` / rate-limit payload (429 only). */
+    readonly retryAfterSeconds: number | undefined;
+    constructor(args: {
+        status: number;
+        endpoint: string;
+        message: string;
+        code?: string;
+        body?: unknown;
+        retryAfterSeconds?: number;
+    });
+    get isRateLimited(): boolean;
+    get isAuthError(): boolean;
+    get isNotFound(): boolean;
+}
+/** A network/transport failure (DNS, connection reset, timeout) before any HTTP status. */
+declare class CronvelloNetworkError extends CronvelloError {
+    readonly endpoint: string;
+    readonly cause: unknown;
+    constructor(endpoint: string, cause: unknown);
+}
+/** A misconfiguration caught before any network call (missing apiKey, bad URL, …). */
+declare class CronvelloConfigError extends CronvelloError {
+    constructor(message: string);
+}
+
+/**
+ * @cronvello/sdk — code-first cron jobs for Cronvello.
+ *
+ * Two layers, one package:
+ *   • High-level registry: `defineCronvello({ jobs })` → `.sync()` + `.expressHandler()` / `.nextHandler()`.
+ *     Define jobs in code; the SDK reconciles them to https://api.cronvello.com and runs them.
+ *   • Low-level client: `new CronvelloClient({ apiKey })` → typed access to the whole `/v1` API.
+ */
+
+/**
+ * Generate a strong random dispatch secret (hex). Convenience for setup scripts:
+ *   node -e "console.log(require('@cronvello/sdk').generateDispatchSecret())"
+ */
+declare function generateDispatchSecret(bytes?: number): string;
+
+export { AccountRunsQuery, AccountTasksQuery, CRONVELLO_DEFAULT_BASE_URL, CronvelloApiError, type CronvelloApp, CronvelloAppConfig, CronvelloClient, type CronvelloClientOptions, CronvelloConfigError, CronvelloError, CronvelloNetworkError, DispatchRequest, DispatchResponse, JobCreateBody, JobUpdateBody, MeResponse, PublicJob, PublicRun, PublicTask, ReconcileResult, RegistryReconcileRequest, RegistryReconcileResponse, RunNowResult, RunsPage, RunsQuery, SyncOptions, TaskCreateBody, TaskUpdateBody, TasksPage, UsageResponse, defineCronvello, generateDispatchSecret };