@cronvello/sdk 0.1.0 → 0.1.2

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-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.cjs';
-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.cjs';
+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-BNy-H5Nr.cjs';
+export { o as CallbackStatus, p as CronvelloHooks, q as CronvelloJobConfig, r as CronvelloJobConfigWithKey, s as CronvelloJobContext, t as CronvelloJobHandler, u as CronvelloJobsInput, v as CronvelloLogger, w as CronvelloRunSource, E as ExecutionMode, H as HttpMethod, x as JobStatus, y as Pagination, z as ReconcileTaskChange, B as RegistryReconcileChange, G as RegistryTaskInput, I as RunStatus, K as RunType, L as SuccessCriteria, N as Urgency } from './dispatch-handler-BNy-H5Nr.cjs';
 import { ExpressDispatchHandler } from './express.cjs';
 import { NextRouteHandler } from './next.cjs';
 
@@ -143,6 +143,11 @@ interface CronvelloApp {
     sync(options?: SyncOptions): Promise<ReconcileResult>;
     /** Trigger one job immediately via Cronvello (manual run). Requires a prior `sync()`. */
     run(key: string): Promise<RunNowResult>;
+    /**
+     * Run a job's handler locally, in-process — no HTTP round-trip, no Cronvello, no deploy.
+     * Perfect for unit tests and `npx cronvello dev`. Lifecycle hooks fire (`source: "local"`).
+     */
+    trigger(key: string, payload?: Record<string, unknown>): Promise<unknown>;
     /** Framework-neutral dispatch entry — used by the adapters. */
     handle(req: DispatchRequest): Promise<DispatchResponse>;
     /** Express/Connect request handler for the dispatch endpoint. */
@@ -152,7 +157,107 @@ interface CronvelloApp {
     /** The registry keys, for diagnostics. */
     keys(): string[];
 }
+/** Config for `defineCronvello.fromEnv` — the three secret fields become optional (read from env). */
+type CronvelloEnvConfig = Omit<CronvelloAppConfig, "apiKey" | "dispatchSecret" | "appUrl"> & Partial<Pick<CronvelloAppConfig, "apiKey" | "dispatchSecret" | "appUrl">>;
 declare function defineCronvello(config: CronvelloAppConfig): CronvelloApp;
+declare namespace defineCronvello {
+    /**
+     * Build an app from environment variables, so you don't repeat the same reads in every service.
+     * Reads `CRONVELLO_API_KEY`, `CRONVELLO_DISPATCH_SECRET`, `CRONVELLO_APP_URL` (or `PUBLIC_URL`),
+     * and optionally `CRONVELLO_API_URL` (base URL). Anything passed explicitly overrides the env.
+     *
+     *   export const cronvello = defineCronvello.fromEnv({ appName: "my-app", jobs: { … } });
+     */
+    function fromEnv(config: CronvelloEnvConfig, env?: Record<string, string | undefined>): CronvelloApp;
+}
+
+/**
+ * Render a `ReconcileResult` as a clean, human-readable summary — for boot logs, CI output, and
+ * `npx cronvello sync`. Zero-dependency ANSI colouring, opt-in via `color: true`.
+ */
+
+interface FormatOptions {
+    /** Emit ANSI colour codes (default false — safe for log files). */
+    color?: boolean;
+    /** Label the summary as a preview ("would …") rather than an applied change. */
+    dryRun?: boolean;
+}
+/** Build the multi-line summary string. */
+declare function formatSyncResult(result: ReconcileResult, options?: FormatOptions): string;
+
+/**
+ * Human-friendly schedule builders. Each returns a plain cron string (so it drops straight into a
+ * job's `schedule`), validated on the way out — a bad argument throws immediately with a clear
+ * message instead of silently producing a wrong schedule.
+ *
+ *   import { every, daily, weekly, hourly, cron } from "@cronvello/sdk";
+ *
+ *   jobs: {
+ *     "digest":  { schedule: daily("08:00"),        handler },
+ *     "poll":    { schedule: every("15m"),          handler },
+ *     "report":  { schedule: weekly("mon", "09:00"),handler },
+ *     "beat":    { schedule: hourly(),              handler },
+ *     "custom":  { schedule: cron("0 0 1 * *"),     handler },
+ *   }
+ */
+type Weekday = "sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/** Validate a raw cron expression and return it unchanged. The explicit escape hatch. */
+declare function cron(expression: string): string;
+/**
+ * A recurring interval expressed as `<n><unit>` where unit is `s`, `m`, `h`, or `d`.
+ *   every("30s") → every 30 seconds   every("15m") → every 15 minutes
+ *   every("2h")  → every 2 hours      every("1d")  → daily at midnight
+ * Note: sub-hour intervals that don't divide evenly (e.g. 7m) restart each hour, matching cron.
+ */
+declare function every(interval: string): string;
+/** Every N minutes (1–59). */
+declare function everyMinutes(n: number): string;
+/** Every N hours (1–23). */
+declare function everyHours(n: number): string;
+/** Once an hour, at the given minute past (default :00). */
+declare function hourly(minute?: number): string;
+/** Once a day at "HH:MM" (24h, default midnight). */
+declare function daily(time?: string): string;
+/** Once a week on `day` at "HH:MM". */
+declare function weekly(day: Weekday, time?: string): string;
+/** Once a month on `dayOfMonth` (1–31) at "HH:MM". */
+declare function monthly(dayOfMonth: number, time?: string): string;
+/** Monday–Friday at "HH:MM". */
+declare function weekdays(time?: string): string;
+/** Saturday & Sunday at "HH:MM". */
+declare function weekends(time?: string): string;
+/** Namespace form for discoverability: `import { schedule } from "@cronvello/sdk"`. */
+declare const schedule: {
+    cron: typeof cron;
+    every: typeof every;
+    everyMinutes: typeof everyMinutes;
+    everyHours: typeof everyHours;
+    hourly: typeof hourly;
+    daily: typeof daily;
+    weekly: typeof weekly;
+    monthly: typeof monthly;
+    weekdays: typeof weekdays;
+    weekends: typeof weekends;
+};
+
+/**
+ * Client-side cron + IANA-timezone validation.
+ *
+ * The goal is to catch *typos* at define/sync time with a clear message — not to re-implement the
+ * server's scheduler. So the validator is deliberately permissive: it accepts the standard 5-field
+ * crontab syntax (and an optional leading seconds field), the common `@macros`, names for months
+ * and weekdays, and step/range/list combinations. Anything it cannot confidently reject is allowed
+ * through, so a valid-but-unusual expression never blocks a deploy.
+ */
+interface CronValidation {
+    valid: boolean;
+    /** Human-readable reason when invalid. */
+    error?: string;
+}
+/** Validate a cron expression. Returns `{ valid, error? }` rather than throwing. */
+declare function validateCron(expr: string): CronValidation;
+/** True if `tz` is a valid IANA timezone (uses the runtime's Intl database). "UTC" always passes. */
+declare function isValidTimeZone(tz: string): boolean;
 
 /**
  * Error taxonomy for the SDK. Everything thrown by the public surface is a
@@ -211,4 +316,4 @@ declare class CronvelloConfigError extends CronvelloError {
  */
 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 };
+export { AccountRunsQuery, AccountTasksQuery, CRONVELLO_DEFAULT_BASE_URL, type CronValidation, CronvelloApiError, type CronvelloApp, CronvelloAppConfig, CronvelloClient, type CronvelloClientOptions, CronvelloConfigError, type CronvelloEnvConfig, CronvelloError, CronvelloNetworkError, DispatchRequest, DispatchResponse, type FormatOptions, JobCreateBody, JobUpdateBody, MeResponse, PublicJob, PublicRun, PublicTask, ReconcileResult, RegistryReconcileRequest, RegistryReconcileResponse, RunNowResult, RunsPage, RunsQuery, SyncOptions, TaskCreateBody, TaskUpdateBody, TasksPage, UsageResponse, type Weekday, cron, daily, defineCronvello, every, everyHours, everyMinutes, formatSyncResult, generateDispatchSecret, hourly, isValidTimeZone, monthly, schedule, validateCron, weekdays, weekends, weekly };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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 { 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-BNy-H5Nr.js';
+export { o as CallbackStatus, p as CronvelloHooks, q as CronvelloJobConfig, r as CronvelloJobConfigWithKey, s as CronvelloJobContext, t as CronvelloJobHandler, u as CronvelloJobsInput, v as CronvelloLogger, w as CronvelloRunSource, E as ExecutionMode, H as HttpMethod, x as JobStatus, y as Pagination, z as ReconcileTaskChange, B as RegistryReconcileChange, G as RegistryTaskInput, I as RunStatus, K as RunType, L as SuccessCriteria, N as Urgency } from './dispatch-handler-BNy-H5Nr.js';
 import { ExpressDispatchHandler } from './express.js';
 import { NextRouteHandler } from './next.js';
 
@@ -143,6 +143,11 @@ interface CronvelloApp {
     sync(options?: SyncOptions): Promise<ReconcileResult>;
     /** Trigger one job immediately via Cronvello (manual run). Requires a prior `sync()`. */
     run(key: string): Promise<RunNowResult>;
+    /**
+     * Run a job's handler locally, in-process — no HTTP round-trip, no Cronvello, no deploy.
+     * Perfect for unit tests and `npx cronvello dev`. Lifecycle hooks fire (`source: "local"`).
+     */
+    trigger(key: string, payload?: Record<string, unknown>): Promise<unknown>;
     /** Framework-neutral dispatch entry — used by the adapters. */
     handle(req: DispatchRequest): Promise<DispatchResponse>;
     /** Express/Connect request handler for the dispatch endpoint. */
@@ -152,7 +157,107 @@ interface CronvelloApp {
     /** The registry keys, for diagnostics. */
     keys(): string[];
 }
+/** Config for `defineCronvello.fromEnv` — the three secret fields become optional (read from env). */
+type CronvelloEnvConfig = Omit<CronvelloAppConfig, "apiKey" | "dispatchSecret" | "appUrl"> & Partial<Pick<CronvelloAppConfig, "apiKey" | "dispatchSecret" | "appUrl">>;
 declare function defineCronvello(config: CronvelloAppConfig): CronvelloApp;
+declare namespace defineCronvello {
+    /**
+     * Build an app from environment variables, so you don't repeat the same reads in every service.
+     * Reads `CRONVELLO_API_KEY`, `CRONVELLO_DISPATCH_SECRET`, `CRONVELLO_APP_URL` (or `PUBLIC_URL`),
+     * and optionally `CRONVELLO_API_URL` (base URL). Anything passed explicitly overrides the env.
+     *
+     *   export const cronvello = defineCronvello.fromEnv({ appName: "my-app", jobs: { … } });
+     */
+    function fromEnv(config: CronvelloEnvConfig, env?: Record<string, string | undefined>): CronvelloApp;
+}
+
+/**
+ * Render a `ReconcileResult` as a clean, human-readable summary — for boot logs, CI output, and
+ * `npx cronvello sync`. Zero-dependency ANSI colouring, opt-in via `color: true`.
+ */
+
+interface FormatOptions {
+    /** Emit ANSI colour codes (default false — safe for log files). */
+    color?: boolean;
+    /** Label the summary as a preview ("would …") rather than an applied change. */
+    dryRun?: boolean;
+}
+/** Build the multi-line summary string. */
+declare function formatSyncResult(result: ReconcileResult, options?: FormatOptions): string;
+
+/**
+ * Human-friendly schedule builders. Each returns a plain cron string (so it drops straight into a
+ * job's `schedule`), validated on the way out — a bad argument throws immediately with a clear
+ * message instead of silently producing a wrong schedule.
+ *
+ *   import { every, daily, weekly, hourly, cron } from "@cronvello/sdk";
+ *
+ *   jobs: {
+ *     "digest":  { schedule: daily("08:00"),        handler },
+ *     "poll":    { schedule: every("15m"),          handler },
+ *     "report":  { schedule: weekly("mon", "09:00"),handler },
+ *     "beat":    { schedule: hourly(),              handler },
+ *     "custom":  { schedule: cron("0 0 1 * *"),     handler },
+ *   }
+ */
+type Weekday = "sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/** Validate a raw cron expression and return it unchanged. The explicit escape hatch. */
+declare function cron(expression: string): string;
+/**
+ * A recurring interval expressed as `<n><unit>` where unit is `s`, `m`, `h`, or `d`.
+ *   every("30s") → every 30 seconds   every("15m") → every 15 minutes
+ *   every("2h")  → every 2 hours      every("1d")  → daily at midnight
+ * Note: sub-hour intervals that don't divide evenly (e.g. 7m) restart each hour, matching cron.
+ */
+declare function every(interval: string): string;
+/** Every N minutes (1–59). */
+declare function everyMinutes(n: number): string;
+/** Every N hours (1–23). */
+declare function everyHours(n: number): string;
+/** Once an hour, at the given minute past (default :00). */
+declare function hourly(minute?: number): string;
+/** Once a day at "HH:MM" (24h, default midnight). */
+declare function daily(time?: string): string;
+/** Once a week on `day` at "HH:MM". */
+declare function weekly(day: Weekday, time?: string): string;
+/** Once a month on `dayOfMonth` (1–31) at "HH:MM". */
+declare function monthly(dayOfMonth: number, time?: string): string;
+/** Monday–Friday at "HH:MM". */
+declare function weekdays(time?: string): string;
+/** Saturday & Sunday at "HH:MM". */
+declare function weekends(time?: string): string;
+/** Namespace form for discoverability: `import { schedule } from "@cronvello/sdk"`. */
+declare const schedule: {
+    cron: typeof cron;
+    every: typeof every;
+    everyMinutes: typeof everyMinutes;
+    everyHours: typeof everyHours;
+    hourly: typeof hourly;
+    daily: typeof daily;
+    weekly: typeof weekly;
+    monthly: typeof monthly;
+    weekdays: typeof weekdays;
+    weekends: typeof weekends;
+};
+
+/**
+ * Client-side cron + IANA-timezone validation.
+ *
+ * The goal is to catch *typos* at define/sync time with a clear message — not to re-implement the
+ * server's scheduler. So the validator is deliberately permissive: it accepts the standard 5-field
+ * crontab syntax (and an optional leading seconds field), the common `@macros`, names for months
+ * and weekdays, and step/range/list combinations. Anything it cannot confidently reject is allowed
+ * through, so a valid-but-unusual expression never blocks a deploy.
+ */
+interface CronValidation {
+    valid: boolean;
+    /** Human-readable reason when invalid. */
+    error?: string;
+}
+/** Validate a cron expression. Returns `{ valid, error? }` rather than throwing. */
+declare function validateCron(expr: string): CronValidation;
+/** True if `tz` is a valid IANA timezone (uses the runtime's Intl database). "UTC" always passes. */
+declare function isValidTimeZone(tz: string): boolean;
 
 /**
  * Error taxonomy for the SDK. Everything thrown by the public surface is a
@@ -211,4 +316,4 @@ declare class CronvelloConfigError extends CronvelloError {
  */
 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 };
+export { AccountRunsQuery, AccountTasksQuery, CRONVELLO_DEFAULT_BASE_URL, type CronValidation, CronvelloApiError, type CronvelloApp, CronvelloAppConfig, CronvelloClient, type CronvelloClientOptions, CronvelloConfigError, type CronvelloEnvConfig, CronvelloError, CronvelloNetworkError, DispatchRequest, DispatchResponse, type FormatOptions, JobCreateBody, JobUpdateBody, MeResponse, PublicJob, PublicRun, PublicTask, ReconcileResult, RegistryReconcileRequest, RegistryReconcileResponse, RunNowResult, RunsPage, RunsQuery, SyncOptions, TaskCreateBody, TaskUpdateBody, TasksPage, UsageResponse, type Weekday, cron, daily, defineCronvello, every, everyHours, everyMinutes, formatSyncResult, generateDispatchSecret, hourly, isValidTimeZone, monthly, schedule, validateCron, weekdays, weekends, weekly };