oqronkit 0.0.1-alpha.1

package/dist/index.d.mts

@@ -0,0 +1,797 @@
+import { z } from 'zod';
+import { Logger } from 'voltlog-io';
+export { Logger } from 'voltlog-io';
+import { EventEmitter } from 'eventemitter3';
+import Database from 'better-sqlite3';
+
+/**
+ * OqronKit Logger — powered by voltlog-io.
+ *
+ * Re-exports a configured voltlog-io logger instance.
+ * Users can customize via oqron.config.ts `logger` section.
+ */
+
+interface ChronoLoggerConfig {
+    /** Enable/disable logging entirely. Default: true */
+    enabled?: boolean;
+    /** Minimum log level. Default: 'INFO' */
+    level?: string;
+    /** Pretty-print with colors/icons for dev. Default: false */
+    prettify?: boolean;
+    /** Show metadata object in logs. Default: true */
+    showMetadata?: boolean;
+    /** Custom voltlog-io transport handler */
+    handler?: (entry: any) => void | Promise<void>;
+    /** Keys to redact from metadata/payload. */
+    redact?: string[];
+    /** Bring-your-own logger instance (Pino, winston, etc) */
+    logger?: any;
+}
+/**
+ * Create a OqronKit logger from config.
+ * This is the single factory used internally.
+ */
+declare function createLogger(config?: ChronoLoggerConfig, context?: Record<string, unknown>): Logger;
+
+interface ICronContext {
+    readonly id: string;
+    readonly log: Logger;
+    readonly signal: AbortSignal;
+    readonly firedAt: Date;
+    readonly scheduleName: string;
+    readonly duration: number;
+    readonly environment?: string;
+    readonly project?: string;
+    progress(value: number, label?: string): void;
+    getProgress(): number;
+}
+
+type MissedFirePolicy = "skip" | "run-once" | "run-all";
+type OverlapPolicy = "skip" | "run" | boolean;
+interface EveryConfig {
+    seconds?: number;
+    minutes?: number;
+    hours?: number;
+}
+interface RetryConfig {
+    max: number;
+    strategy: "exponential" | "fixed";
+    baseDelay: number;
+}
+interface CronHooks {
+    beforeRun?: (ctx: ICronContext) => Promise<void> | void;
+    afterRun?: (ctx: ICronContext, result: unknown) => Promise<void> | void;
+    onError?: (ctx: ICronContext, error: Error) => Promise<void> | void;
+    onMissedFire?: (ctx: ICronContext, missedAt: Date) => Promise<void> | void;
+}
+interface CronDefinition {
+    name: string;
+    expression?: string;
+    intervalMs?: number;
+    timezone?: string;
+    missedFire: MissedFirePolicy;
+    overlap: OverlapPolicy;
+    guaranteedWorker?: boolean;
+    heartbeatMs?: number;
+    lockTtlMs?: number;
+    timeout?: number;
+    tags: string[];
+    /** Override global history rolling. `true` = infinite, `false` = none, `number` = max retained jobs. */
+    keepHistory?: boolean | number;
+    /** Keep specific bounded history length for failed jobs overriding general logic */
+    keepFailedHistory?: boolean | number;
+    handler: (ctx: ICronContext) => Promise<unknown>;
+    hooks?: CronHooks;
+    retries?: RetryConfig;
+}
+interface JobRecord {
+    id: string;
+    scheduleId?: string;
+    status: "running" | "completed" | "failed" | "missed" | "dead";
+    startedAt: Date;
+    completedAt?: Date;
+    error?: string;
+    result?: string;
+    progressPercent?: number;
+    progressLabel?: string;
+    attempts?: number;
+    durationMs?: number;
+}
+
+interface ScheduleRecurring {
+    frequency: "daily" | "weekly" | "monthly" | "yearly";
+    dayOfMonth?: number;
+    at?: {
+        hour: number;
+        minute: number;
+    };
+    months?: number[];
+}
+interface ScheduleRunAfter {
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+}
+interface ScheduleHooks<TPayload = unknown> {
+    beforeRun?: (ctx: IScheduleContext<TPayload>) => Promise<void> | void;
+    afterRun?: (ctx: IScheduleContext<TPayload>, result: unknown) => Promise<void> | void;
+    onError?: (ctx: IScheduleContext<TPayload>, error: Error) => Promise<void> | void;
+    onMissedFire?: (ctx: IScheduleContext<TPayload>, missedAt: Date) => Promise<void> | void;
+}
+interface IScheduleContext<TPayload = unknown> {
+    name: string;
+    firedAt: Date;
+    payload: TPayload;
+    duration: number;
+    environment?: string;
+    project?: string;
+    log(level: string, message: string, meta?: Record<string, unknown>): void;
+    progress(percent: number, label?: string): void;
+}
+interface ScheduleDefinition<TPayload = unknown> {
+    name: string;
+    runAt?: Date;
+    runAfter?: ScheduleRunAfter;
+    recurring?: ScheduleRecurring;
+    rrule?: string;
+    every?: {
+        minutes?: number;
+        hours?: number;
+        seconds?: number;
+    };
+    timezone?: string;
+    missedFire: MissedFirePolicy;
+    overlap: OverlapPolicy;
+    guaranteedWorker?: boolean;
+    heartbeatMs?: number;
+    lockTtlMs?: number;
+    timeout?: number;
+    tags: string[];
+    /** Override global history rolling. `true` = infinite, `false` = none, `number` = max retained jobs. */
+    keepHistory?: boolean | number;
+    /** Keep specific bounded history length for failed jobs overriding general logic */
+    keepFailedHistory?: boolean | number;
+    condition?: (ctx: IScheduleContext<TPayload>) => Promise<boolean> | boolean;
+    handler: (ctx: IScheduleContext<TPayload>) => Promise<unknown>;
+    hooks?: ScheduleHooks<TPayload>;
+    retries?: RetryConfig;
+    payload?: TPayload;
+}
+
+interface IOqronAdapter {
+    /** Insert or update a schedule definition */
+    upsertSchedule(def: CronDefinition | ScheduleDefinition): Promise<void>;
+    /** Get schedules that are due to fire (nextRunAt <= now, or never run) */
+    getDueSchedules(now: Date, limit: number, prefix?: string): Promise<Pick<CronDefinition | ScheduleDefinition, "name">[]>;
+    /** Get all registered schedules and their run metadata */
+    getSchedules(prefix?: string): Promise<Array<{
+        name: string;
+        lastRunAt: Date | null;
+        nextRunAt: Date | null;
+    }>>;
+    /** Update nextRunAt for a schedule */
+    updateNextRun(scheduleId: string, nextRunAt: Date | null): Promise<void>;
+    /** Record a job execution (insert or update) */
+    recordExecution(job: JobRecord): Promise<void>;
+    /** Update progress of an active job */
+    updateJobProgress(id: string, progressPercent: number, progressLabel?: string): Promise<void>;
+    /** Get execution history for a schedule */
+    getExecutions(scheduleId: string, opts: {
+        limit: number;
+        offset: number;
+    }): Promise<JobRecord[]>;
+    /** Get all jobs currently marked as running */
+    getActiveJobs(): Promise<JobRecord[]>;
+    /** Clean old execution records */
+    cleanOldExecutions(before: Date): Promise<number>;
+    /** Roll history based on config settings */
+    pruneHistoryForSchedule(scheduleId: string, keepJobHistory: number | boolean, keepFailedJobHistory: number | boolean): Promise<void>;
+}
+
+interface ILockAdapter {
+    acquire(key: string, ownerId: string, ttlMs: number): Promise<boolean>;
+    renew(key: string, ownerId: string, ttlMs: number): Promise<boolean>;
+    release(key: string, ownerId: string): Promise<void>;
+    isOwner(key: string, ownerId: string): Promise<boolean>;
+}
+
+declare const OqronConfigSchema: z.ZodObject<{
+    project: z.ZodOptional<z.ZodString>;
+    environment: z.ZodDefault<z.ZodString>;
+    db: z.ZodOptional<z.ZodUnion<[z.ZodType<IOqronAdapter, z.ZodTypeDef, IOqronAdapter>, z.ZodObject<{
+        adapter: z.ZodEnum<["sqlite", "memory", "postgres", "mysql", "mongodb", "redis"]>;
+        url: z.ZodOptional<z.ZodString>;
+        poolMin: z.ZodDefault<z.ZodNumber>;
+        poolMax: z.ZodDefault<z.ZodNumber>;
+        tablePrefix: z.ZodDefault<z.ZodString>;
+        migrations: z.ZodDefault<z.ZodUnion<[z.ZodEnum<["auto", "manual"]>, z.ZodLiteral<false>]>>;
+        ssl: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        adapter: "sqlite" | "memory" | "postgres" | "mysql" | "mongodb" | "redis";
+        poolMin: number;
+        poolMax: number;
+        tablePrefix: string;
+        migrations: false | "auto" | "manual";
+        ssl: boolean;
+        url?: string | undefined;
+    }, {
+        adapter: "sqlite" | "memory" | "postgres" | "mysql" | "mongodb" | "redis";
+        url?: string | undefined;
+        poolMin?: number | undefined;
+        poolMax?: number | undefined;
+        tablePrefix?: string | undefined;
+        migrations?: false | "auto" | "manual" | undefined;
+        ssl?: boolean | undefined;
+    }>]>>;
+    lock: z.ZodOptional<z.ZodUnion<[z.ZodType<ILockAdapter, z.ZodTypeDef, ILockAdapter>, z.ZodObject<{
+        adapter: z.ZodEnum<["db", "memory", "redis"]>;
+        url: z.ZodOptional<z.ZodString>;
+        ttl: z.ZodDefault<z.ZodNumber>;
+        retryDelay: z.ZodDefault<z.ZodNumber>;
+        retryCount: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        adapter: "memory" | "redis" | "db";
+        ttl: number;
+        retryDelay: number;
+        retryCount: number;
+        url?: string | undefined;
+    }, {
+        adapter: "memory" | "redis" | "db";
+        url?: string | undefined;
+        ttl?: number | undefined;
+        retryDelay?: number | undefined;
+        retryCount?: number | undefined;
+    }>]>>;
+    broker: z.ZodOptional<z.ZodAny>;
+    modules: z.ZodDefault<z.ZodArray<z.ZodEnum<["cron", "scheduler", "queue", "workflow", "batch", "webhook", "pipeline"]>, "many">>;
+    cron: z.ZodDefault<z.ZodObject<{
+        enable: z.ZodDefault<z.ZodBoolean>;
+        timezone: z.ZodOptional<z.ZodString>;
+        tickInterval: z.ZodDefault<z.ZodNumber>;
+        missedFirePolicy: z.ZodDefault<z.ZodEnum<["skip", "run-once", "run-all"]>>;
+        maxConcurrentJobs: z.ZodDefault<z.ZodNumber>;
+        leaderElection: z.ZodDefault<z.ZodBoolean>;
+        keepJobHistory: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodNumber]>>;
+        keepFailedJobHistory: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodNumber]>>;
+    }, "strip", z.ZodTypeAny, {
+        enable: boolean;
+        tickInterval: number;
+        missedFirePolicy: "skip" | "run-once" | "run-all";
+        maxConcurrentJobs: number;
+        leaderElection: boolean;
+        keepJobHistory: number | boolean;
+        keepFailedJobHistory: number | boolean;
+        timezone?: string | undefined;
+    }, {
+        enable?: boolean | undefined;
+        timezone?: string | undefined;
+        tickInterval?: number | undefined;
+        missedFirePolicy?: "skip" | "run-once" | "run-all" | undefined;
+        maxConcurrentJobs?: number | undefined;
+        leaderElection?: boolean | undefined;
+        keepJobHistory?: number | boolean | undefined;
+        keepFailedJobHistory?: number | boolean | undefined;
+    }>>;
+    scheduler: z.ZodDefault<z.ZodObject<{
+        enable: z.ZodDefault<z.ZodBoolean>;
+        tickInterval: z.ZodDefault<z.ZodNumber>;
+        keepJobHistory: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodNumber]>>;
+        keepFailedJobHistory: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodNumber]>>;
+    }, "strip", z.ZodTypeAny, {
+        enable: boolean;
+        tickInterval: number;
+        keepJobHistory: number | boolean;
+        keepFailedJobHistory: number | boolean;
+    }, {
+        enable?: boolean | undefined;
+        tickInterval?: number | undefined;
+        keepJobHistory?: number | boolean | undefined;
+        keepFailedJobHistory?: number | boolean | undefined;
+    }>>;
+    jobsDir: z.ZodDefault<z.ZodString>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    worker: z.ZodDefault<z.ZodObject<{
+        concurrency: z.ZodDefault<z.ZodNumber>;
+        gracefulShutdownMs: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        concurrency: number;
+        gracefulShutdownMs: number;
+    }, {
+        concurrency?: number | undefined;
+        gracefulShutdownMs?: number | undefined;
+    }>>;
+    logger: z.ZodDefault<z.ZodUnion<[z.ZodLiteral<false>, z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        level: z.ZodDefault<z.ZodString>;
+        prettify: z.ZodDefault<z.ZodBoolean>;
+        showMetadata: z.ZodDefault<z.ZodBoolean>;
+        redact: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        level: string;
+        prettify: boolean;
+        showMetadata: boolean;
+        redact: string[];
+    }, {
+        enabled?: boolean | undefined;
+        level?: string | undefined;
+        prettify?: boolean | undefined;
+        showMetadata?: boolean | undefined;
+        redact?: string[] | undefined;
+    }>]>>;
+    telemetry: z.ZodDefault<z.ZodObject<{
+        prometheus: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            path: z.ZodDefault<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            path: string;
+            enabled: boolean;
+        }, {
+            path?: string | undefined;
+            enabled?: boolean | undefined;
+        }>>;
+        opentelemetry: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            enabled: boolean;
+        }, {
+            enabled?: boolean | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        prometheus: {
+            path: string;
+            enabled: boolean;
+        };
+        opentelemetry: {
+            enabled: boolean;
+        };
+    }, {
+        prometheus?: {
+            path?: string | undefined;
+            enabled?: boolean | undefined;
+        } | undefined;
+        opentelemetry?: {
+            enabled?: boolean | undefined;
+        } | undefined;
+    }>>;
+    shutdown: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        timeout: z.ZodDefault<z.ZodNumber>;
+        signals: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        timeout: number;
+        signals: string[];
+    }, {
+        enabled?: boolean | undefined;
+        timeout?: number | undefined;
+        signals?: string[] | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    environment: string;
+    cron: {
+        enable: boolean;
+        tickInterval: number;
+        missedFirePolicy: "skip" | "run-once" | "run-all";
+        maxConcurrentJobs: number;
+        leaderElection: boolean;
+        keepJobHistory: number | boolean;
+        keepFailedJobHistory: number | boolean;
+        timezone?: string | undefined;
+    };
+    scheduler: {
+        enable: boolean;
+        tickInterval: number;
+        keepJobHistory: number | boolean;
+        keepFailedJobHistory: number | boolean;
+    };
+    modules: ("cron" | "scheduler" | "queue" | "workflow" | "batch" | "webhook" | "pipeline")[];
+    jobsDir: string;
+    tags: string[];
+    worker: {
+        concurrency: number;
+        gracefulShutdownMs: number;
+    };
+    logger: false | {
+        enabled: boolean;
+        level: string;
+        prettify: boolean;
+        showMetadata: boolean;
+        redact: string[];
+    };
+    telemetry: {
+        prometheus: {
+            path: string;
+            enabled: boolean;
+        };
+        opentelemetry: {
+            enabled: boolean;
+        };
+    };
+    shutdown: {
+        enabled: boolean;
+        timeout: number;
+        signals: string[];
+    };
+    project?: string | undefined;
+    db?: IOqronAdapter | {
+        adapter: "sqlite" | "memory" | "postgres" | "mysql" | "mongodb" | "redis";
+        poolMin: number;
+        poolMax: number;
+        tablePrefix: string;
+        migrations: false | "auto" | "manual";
+        ssl: boolean;
+        url?: string | undefined;
+    } | undefined;
+    lock?: ILockAdapter | {
+        adapter: "memory" | "redis" | "db";
+        ttl: number;
+        retryDelay: number;
+        retryCount: number;
+        url?: string | undefined;
+    } | undefined;
+    broker?: any;
+}, {
+    project?: string | undefined;
+    environment?: string | undefined;
+    db?: IOqronAdapter | {
+        adapter: "sqlite" | "memory" | "postgres" | "mysql" | "mongodb" | "redis";
+        url?: string | undefined;
+        poolMin?: number | undefined;
+        poolMax?: number | undefined;
+        tablePrefix?: string | undefined;
+        migrations?: false | "auto" | "manual" | undefined;
+        ssl?: boolean | undefined;
+    } | undefined;
+    lock?: ILockAdapter | {
+        adapter: "memory" | "redis" | "db";
+        url?: string | undefined;
+        ttl?: number | undefined;
+        retryDelay?: number | undefined;
+        retryCount?: number | undefined;
+    } | undefined;
+    broker?: any;
+    cron?: {
+        enable?: boolean | undefined;
+        timezone?: string | undefined;
+        tickInterval?: number | undefined;
+        missedFirePolicy?: "skip" | "run-once" | "run-all" | undefined;
+        maxConcurrentJobs?: number | undefined;
+        leaderElection?: boolean | undefined;
+        keepJobHistory?: number | boolean | undefined;
+        keepFailedJobHistory?: number | boolean | undefined;
+    } | undefined;
+    scheduler?: {
+        enable?: boolean | undefined;
+        tickInterval?: number | undefined;
+        keepJobHistory?: number | boolean | undefined;
+        keepFailedJobHistory?: number | boolean | undefined;
+    } | undefined;
+    modules?: ("cron" | "scheduler" | "queue" | "workflow" | "batch" | "webhook" | "pipeline")[] | undefined;
+    jobsDir?: string | undefined;
+    tags?: string[] | undefined;
+    worker?: {
+        concurrency?: number | undefined;
+        gracefulShutdownMs?: number | undefined;
+    } | undefined;
+    logger?: false | {
+        enabled?: boolean | undefined;
+        level?: string | undefined;
+        prettify?: boolean | undefined;
+        showMetadata?: boolean | undefined;
+        redact?: string[] | undefined;
+    } | undefined;
+    telemetry?: {
+        prometheus?: {
+            path?: string | undefined;
+            enabled?: boolean | undefined;
+        } | undefined;
+        opentelemetry?: {
+            enabled?: boolean | undefined;
+        } | undefined;
+    } | undefined;
+    shutdown?: {
+        enabled?: boolean | undefined;
+        timeout?: number | undefined;
+        signals?: string[] | undefined;
+    } | undefined;
+}>;
+type ValidatedConfig = z.infer<typeof OqronConfigSchema>;
+
+type DbAdapterType = "sqlite" | "memory" | "postgres" | "mysql" | "mongodb" | "redis";
+type LockAdapterType = "db" | "memory" | "redis";
+interface OqronConfig {
+    /**
+     * The name of this project/service (e.g. 'acme-billing-svc')
+     */
+    project?: string;
+    /**
+     * Environment isolation.
+     * Workers in 'development' will never execute jobs enqueued in 'production'.
+     * @default "development"
+     */
+    environment?: string;
+    /**
+     * The primary database adapter (State Store).
+     * Union of explicit DI or declarative config.
+     */
+    db?: IOqronAdapter | {
+        adapter: DbAdapterType;
+        url?: string;
+        poolMin?: number;
+        poolMax?: number;
+        tablePrefix?: string;
+        migrations?: "auto" | "manual" | false;
+        ssl?: boolean;
+    };
+    /**
+     * The distributed lock adapter for safe concurrency.
+     * Union of explicit DI or declarative config.
+     */
+    lock?: ILockAdapter | {
+        adapter: LockAdapterType;
+        url?: string;
+        ttl?: number;
+        retryDelay?: number;
+        retryCount?: number;
+    };
+    /**
+     * The high-throughput message broker (optional, for PubSub/Queueing at scale)
+     */
+    broker?: any;
+    /**
+     * List of core modules to enable.
+     * e.g. ['cron', 'queue', 'workflow', 'batch', 'webhook', 'pipeline']
+     * @default []
+     */
+    modules?: ("cron" | "scheduler" | "queue" | "workflow" | "batch" | "webhook" | "pipeline")[];
+    /**
+     * Module-specific configs
+     */
+    cron?: {
+        enable?: boolean;
+        timezone?: string;
+        tickInterval?: number;
+        missedFirePolicy?: "skip" | "run-once" | "run-all";
+        maxConcurrentJobs?: number;
+        leaderElection?: boolean;
+        /** Rolling execution history. `true` = infinite, `false` = 0, `number` = keep N */
+        keepJobHistory?: boolean | number;
+        /** Override for failed tasks. Handled explicitly under errors */
+        keepFailedJobHistory?: boolean | number;
+    };
+    scheduler?: {
+        enable?: boolean;
+        tickInterval?: number;
+        keepJobHistory?: boolean | number;
+        keepFailedJobHistory?: boolean | number;
+    };
+    /**
+     * Directory to auto-discover job definition files from.
+     * OqronKit.init() scans this directory recursively for .ts/.js files
+     * that export definitions and registers them automatically.
+     * @default "./src/jobs"
+     */
+    jobsDir?: string;
+    /**
+     * Global tags applied to every job processed by this node.
+     * @default []
+     */
+    tags?: string[];
+    /**
+     * Worker-level configurations
+     */
+    worker?: {
+        /** Number of concurrent jobs this node processes simultaneously */
+        concurrency?: number;
+        /** Time in ms to wait for active jobs before SIGTERM exits */
+        gracefulShutdownMs?: number;
+    };
+    /**
+     * Logger configuration (powered by voltlog-io).
+     * Set to `false` to disable logging entirely.
+     */
+    logger?: ChronoLoggerConfig | false;
+    /**
+     * Telemetry configuration
+     */
+    telemetry?: {
+        prometheus?: {
+            enabled?: boolean;
+            path?: string;
+        };
+        opentelemetry?: {
+            enabled?: boolean;
+        };
+    };
+    /**
+     * Graceful shutdown configuration
+     */
+    shutdown?: {
+        enabled?: boolean;
+        timeout?: number;
+        signals?: string[];
+    };
+}
+
+declare function defineConfig(config: OqronConfig): OqronConfig;
+
+type ChronoEventMap = {
+    "job:start": [jobId: string, module: string];
+    "job:progress": [jobId: string, value: number];
+    "job:success": [jobId: string];
+    "job:fail": [jobId: string, error: Error];
+    "system:ready": [];
+    "system:stop": [];
+};
+declare class OqronEventBusClass extends EventEmitter<ChronoEventMap> {
+    private static _instance;
+    static getInstance(): OqronEventBusClass;
+}
+declare const OqronEventBus: OqronEventBusClass;
+
+declare class SqliteAdapter implements IOqronAdapter {
+    private readonly db;
+    /**
+     * @param dbOrPath - Either a `better-sqlite3` Database instance (for testing with `:memory:`)
+     *                   or a file path string. Defaults to `"oqron.sqlite"`.
+     */
+    constructor(dbOrPath?: Database.Database | string);
+    /** Create tables if they don't exist */
+    migrate(): void;
+    upsertSchedule(def: CronDefinition | ScheduleDefinition): Promise<void>;
+    getDueSchedules(now: Date, limit: number, prefix?: string): Promise<Pick<CronDefinition, "name">[]>;
+    getSchedules(prefix?: string): Promise<Array<{
+        name: string;
+        lastRunAt: Date | null;
+        nextRunAt: Date | null;
+    }>>;
+    updateNextRun(scheduleId: string, nextRunAt: Date | null): Promise<void>;
+    updateJobProgress(id: string, progressPercent: number, progressLabel?: string): Promise<void>;
+    recordExecution(job: JobRecord): Promise<void>;
+    getExecutions(scheduleId: string, opts: {
+        limit: number;
+        offset: number;
+    }): Promise<JobRecord[]>;
+    getActiveJobs(): Promise<JobRecord[]>;
+    cleanOldExecutions(before: Date): Promise<number>;
+    pruneHistoryForSchedule(scheduleId: string, keepJobHistory: number | boolean, keepFailedJobHistory: number | boolean): Promise<void>;
+}
+
+declare class DbLockAdapter implements ILockAdapter {
+    private readonly db;
+    private readonly defaultTtl;
+    /**
+     * @param dbOrPath - Either a `better-sqlite3` Database instance or a file path.
+     *                   When sharing the same SQLite file as SqliteAdapter, pass the same path.
+     * @param defaultTtlMs - Default TTL for locks if not provided in acquire (optional)
+     */
+    constructor(dbOrPath?: Database.Database | string, defaultTtlMs?: number);
+    acquire(key: string, ownerId: string, ttlMs?: number): Promise<boolean>;
+    renew(key: string, ownerId: string, ttlMs?: number): Promise<boolean>;
+    release(key: string, ownerId: string): Promise<void>;
+    isOwner(key: string, ownerId: string): Promise<boolean>;
+}
+
+/**
+ * In-memory lock adapter for single-node dev/testing.
+ * Uses a Map + setTimeout-based expiry — NOT suitable for production multi-node.
+ */
+declare class MemoryLockAdapter implements ILockAdapter {
+    private readonly locks;
+    acquire(key: string, ownerId: string, ttlMs: number): Promise<boolean>;
+    renew(key: string, ownerId: string, ttlMs: number): Promise<boolean>;
+    release(key: string, ownerId: string): Promise<void>;
+    isOwner(key: string, ownerId: string): Promise<boolean>;
+}
+
+type CronScheduleConfig = {
+    expression: string;
+    every?: never;
+} | {
+    every: EveryConfig;
+    expression?: never;
+};
+type DefineCronOptions = CronScheduleConfig & {
+    name: string;
+    timezone?: string;
+    missedFire?: MissedFirePolicy;
+    overlap?: OverlapPolicy;
+    guaranteedWorker?: boolean;
+    heartbeatMs?: number;
+    lockTtlMs?: number;
+    timeout?: number;
+    tags?: string[];
+    handler: (ctx: ICronContext) => Promise<unknown>;
+    hooks?: CronHooks;
+    retries?: RetryConfig;
+};
+/**
+ * Define a cron job. Automatically registers it with OqronKit
+ * so that `OqronKit.init()` discovers it without manual wiring.
+ *
+ * @example
+ * // Expression-based
+ * cron({ name: 'billing', expression: '0 0 1 * *', handler: ... })
+ *
+ * // Interval-based
+ * cron({ name: 'sync', every: { minutes: 15 }, handler: ... })
+ */
+declare const cron: (options: DefineCronOptions) => CronDefinition;
+
+type EnqueueOptions<TPayload> = {
+    runAt?: Date;
+    runAfter?: ScheduleRunAfter;
+    recurring?: ScheduleRecurring;
+    rrule?: string;
+    every?: {
+        minutes?: number;
+        hours?: number;
+        seconds?: number;
+    };
+    payload?: TPayload;
+    nameSuffix?: string;
+};
+type ScheduleInstance<TPayload> = ScheduleDefinition<TPayload> & {
+    trigger: (opts?: EnqueueOptions<TPayload>) => Promise<void>;
+    schedule: (opts?: EnqueueOptions<TPayload>) => Promise<void>;
+    cancel: () => Promise<void>;
+};
+type DefineScheduleOptions<TPayload> = {
+    name: string;
+    runAt?: Date;
+    runAfter?: ScheduleRunAfter;
+    recurring?: ScheduleRecurring;
+    rrule?: string;
+    every?: {
+        minutes?: number;
+        hours?: number;
+        seconds?: number;
+    };
+    timezone?: string;
+    missedFire?: MissedFirePolicy;
+    overlap?: OverlapPolicy;
+    guaranteedWorker?: boolean;
+    heartbeatMs?: number;
+    lockTtlMs?: number;
+    timeout?: number;
+    tags?: string[];
+    condition?: (ctx: IScheduleContext<TPayload>) => Promise<boolean> | boolean;
+    handler: (ctx: IScheduleContext<TPayload>) => Promise<unknown>;
+    hooks?: ScheduleHooks<TPayload>;
+    payload?: TPayload;
+    retries?: RetryConfig;
+};
+/**
+ * Define a schedule or a task.
+ * Automatically registers it with OqronKit for boot-time loading.
+ */
+declare const schedule: <TPayload = unknown>(options: DefineScheduleOptions<TPayload>) => ScheduleInstance<TPayload>;
+
+declare const OqronKit: {
+    /**
+     * Initialize OqronKit: loads config, auto-discovers jobs, and boots modules.
+     *
+     * @param opts.cwd - Working directory for config file lookup and jobsDir resolution
+     * @param opts.config - Explicit config object (skips loadConfig)
+     */
+    init(opts?: {
+        cwd?: string;
+        config?: OqronConfig;
+    }): Promise<void>;
+    /** Gracefully stop all modules */
+    stop(): Promise<void>;
+    /** Get the current validated config */
+    getConfig(): ValidatedConfig;
+    /** Get the database adapter (available after init()) */
+    getDb(): IOqronAdapter;
+    /** Get the lock adapter (available after init()) */
+    getLock(): ILockAdapter;
+    /** Get the Express router for monitoring */
+    expressRouter(): any;
+    /** Get the Fastify plugin for monitoring */
+    fastifyPlugin(fastify: any, opts: any, done: () => void): void;
+};
+
+export { type ChronoLoggerConfig, type CronDefinition, type CronHooks, DbLockAdapter, type DefineCronOptions, type DefineScheduleOptions, type EveryConfig, type ICronContext, type ILockAdapter, type IOqronAdapter, type IScheduleContext, type JobRecord, MemoryLockAdapter, type MissedFirePolicy, OqronEventBus, OqronKit, type OverlapPolicy, type RetryConfig, type ScheduleDefinition, type ScheduleHooks, type ScheduleInstance, type ScheduleRecurring, type ScheduleRunAfter, SqliteAdapter, createLogger, cron, OqronKit as default, defineConfig, schedule };