@juspay/neurolink 9.39.0 → 9.41.0

package/dist/tasks/backends/nodeTimeoutBackend.d.ts

@@ -0,0 +1,27 @@
+/**
+ * NodeTimeout Backend — Development/zero-dependency task scheduling.
+ *
+ * - Cron tasks → parsed with `croner`, scheduled via setTimeout chains
+ * - Interval tasks → setInterval
+ * - One-shot tasks → setTimeout
+ * - All timers are in-process — lost on restart
+ */
+import { type Task, type TaskBackend, type TaskExecutorFn, type TaskManagerConfig } from "../../types/taskTypes.js";
+export declare class NodeTimeoutBackend implements TaskBackend {
+    readonly name = "node-timeout";
+    private scheduled;
+    private paused;
+    private disposed;
+    private activeRuns;
+    private maxConcurrentRuns;
+    constructor(config: TaskManagerConfig);
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    schedule(task: Task, executor: TaskExecutorFn): Promise<void>;
+    cancel(taskId: string): Promise<void>;
+    pause(taskId: string): Promise<void>;
+    resume(taskId: string): Promise<void>;
+    isHealthy(): Promise<boolean>;
+    private executeTask;
+    private clearEntry;
+}

package/dist/tasks/backends/nodeTimeoutBackend.js

@@ -0,0 +1,140 @@
+/**
+ * NodeTimeout Backend — Development/zero-dependency task scheduling.
+ *
+ * - Cron tasks → parsed with `croner`, scheduled via setTimeout chains
+ * - Interval tasks → setInterval
+ * - One-shot tasks → setTimeout
+ * - All timers are in-process — lost on restart
+ */
+import { Cron } from "croner";
+import { logger } from "../../utils/logger.js";
+import { TASK_DEFAULTS, } from "../../types/taskTypes.js";
+export class NodeTimeoutBackend {
+    name = "node-timeout";
+    scheduled = new Map();
+    paused = new Map();
+    disposed = false;
+    activeRuns = 0;
+    maxConcurrentRuns;
+    constructor(config) {
+        this.maxConcurrentRuns =
+            config.maxConcurrentRuns ?? TASK_DEFAULTS.maxConcurrentRuns;
+    }
+    async initialize() {
+        logger.info("[NodeTimeout] Backend initialized");
+    }
+    async shutdown() {
+        this.disposed = true;
+        for (const entry of this.scheduled.values()) {
+            this.clearEntry(entry);
+        }
+        this.scheduled.clear();
+        this.paused.clear();
+        logger.info("[NodeTimeout] Backend shut down");
+    }
+    async schedule(task, executor) {
+        // Cancel existing schedule for this task if any
+        await this.cancel(task.id);
+        const entry = { taskId: task.id, executor, task };
+        const schedule = task.schedule;
+        if (schedule.type === "cron") {
+            entry.cronJob = new Cron(schedule.expression, {
+                timezone: schedule.timezone,
+                catch: (err) => {
+                    logger.error("[NodeTimeout] Cron execution error", {
+                        taskId: task.id,
+                        error: String(err),
+                    });
+                },
+            }, () => {
+                this.executeTask(entry);
+            });
+        }
+        else if (schedule.type === "interval") {
+            // Wait for the first interval tick before executing
+            entry.intervalId = setInterval(() => {
+                this.executeTask(entry);
+            }, schedule.every);
+        }
+        else if (schedule.type === "once") {
+            const at = typeof schedule.at === "string" ? new Date(schedule.at) : schedule.at;
+            const delay = Math.max(0, at.getTime() - Date.now());
+            entry.timeoutId = setTimeout(() => {
+                this.executeTask(entry);
+                this.scheduled.delete(task.id);
+            }, delay);
+        }
+        this.scheduled.set(task.id, entry);
+        logger.info("[NodeTimeout] Task scheduled", {
+            taskId: task.id,
+            type: schedule.type,
+        });
+    }
+    async cancel(taskId) {
+        const entry = this.scheduled.get(taskId);
+        if (entry) {
+            this.clearEntry(entry);
+            this.scheduled.delete(taskId);
+        }
+        this.paused.delete(taskId);
+        logger.debug("[NodeTimeout] Task cancelled", { taskId });
+    }
+    async pause(taskId) {
+        const entry = this.scheduled.get(taskId);
+        if (!entry) {
+            return;
+        }
+        this.clearEntry(entry);
+        this.scheduled.delete(taskId);
+        // Save the entry so we can re-schedule on resume
+        this.paused.set(taskId, entry);
+        logger.info("[NodeTimeout] Task paused", { taskId });
+    }
+    async resume(taskId) {
+        const entry = this.paused.get(taskId);
+        if (!entry) {
+            return;
+        }
+        this.paused.delete(taskId);
+        // Re-schedule with the saved task and executor
+        await this.schedule(entry.task, entry.executor);
+        logger.info("[NodeTimeout] Task resumed", { taskId });
+    }
+    async isHealthy() {
+        return !this.disposed;
+    }
+    // ── Internal ──────────────────────────────────────────
+    executeTask(entry) {
+        if (this.activeRuns >= this.maxConcurrentRuns) {
+            logger.warn("[NodeTimeout] Max concurrent runs reached, skipping tick", {
+                taskId: entry.taskId,
+                activeRuns: this.activeRuns,
+                maxConcurrentRuns: this.maxConcurrentRuns,
+            });
+            return;
+        }
+        this.activeRuns++;
+        entry
+            .executor(entry.task)
+            .catch((err) => {
+            logger.error("[NodeTimeout] Task execution failed", {
+                taskId: entry.taskId,
+                error: String(err),
+            });
+        })
+            .finally(() => {
+            this.activeRuns--;
+        });
+    }
+    clearEntry(entry) {
+        if (entry.cronJob) {
+            entry.cronJob.stop();
+        }
+        if (entry.intervalId !== undefined) {
+            clearInterval(entry.intervalId);
+        }
+        if (entry.timeoutId !== undefined) {
+            clearTimeout(entry.timeoutId);
+        }
+    }
+}

package/dist/tasks/backends/taskBackendRegistry.d.ts

@@ -0,0 +1,31 @@
+/**
+ * TaskBackendRegistry — registration point for all task backend implementations.
+ * Follows the same pattern as ProviderRegistry: dynamic imports, lazy registration.
+ */
+import type { TaskBackendName, TaskBackendFactoryFn, TaskManagerConfig, TaskBackend } from "../../types/taskTypes.js";
+export declare class TaskBackendRegistry {
+    private static factories;
+    private static registered;
+    /**
+     * Register a backend factory function.
+     * Can be called externally to add custom backends (e.g., "pg-boss").
+     */
+    static register(name: string, factory: TaskBackendFactoryFn): void;
+    /**
+     * Register the built-in backends (BullMQ, NodeTimeout).
+     * Idempotent — safe to call multiple times.
+     */
+    static registerDefaults(): void;
+    /**
+     * Create a backend instance by name.
+     */
+    static create(name: TaskBackendName | string, config: TaskManagerConfig): Promise<TaskBackend>;
+    /**
+     * Check if a backend is registered.
+     */
+    static has(name: string): boolean;
+    /**
+     * List all registered backend names.
+     */
+    static getAvailable(): string[];
+}

package/dist/tasks/backends/taskBackendRegistry.js

@@ -0,0 +1,65 @@
+/**
+ * TaskBackendRegistry — registration point for all task backend implementations.
+ * Follows the same pattern as ProviderRegistry: dynamic imports, lazy registration.
+ */
+import { logger } from "../../utils/logger.js";
+import { TaskError } from "../errors.js";
+export class TaskBackendRegistry {
+    static factories = new Map();
+    static registered = false;
+    /**
+     * Register a backend factory function.
+     * Can be called externally to add custom backends (e.g., "pg-boss").
+     */
+    static register(name, factory) {
+        TaskBackendRegistry.factories.set(name, factory);
+        logger.debug(`[TaskBackendRegistry] Registered backend: ${name}`);
+    }
+    /**
+     * Register the built-in backends (BullMQ, NodeTimeout).
+     * Idempotent — safe to call multiple times.
+     */
+    static registerDefaults() {
+        if (TaskBackendRegistry.registered) {
+            return;
+        }
+        TaskBackendRegistry.registered = true;
+        // BullMQ backend (production, Redis-backed)
+        TaskBackendRegistry.register("bullmq", async (config) => {
+            const { BullMQBackend } = await import("./bullmqBackend.js");
+            return new BullMQBackend(config);
+        });
+        // NodeTimeout backend (development, in-process timers)
+        TaskBackendRegistry.register("node-timeout", async (config) => {
+            const { NodeTimeoutBackend } = await import("./nodeTimeoutBackend.js");
+            return new NodeTimeoutBackend(config);
+        });
+        logger.debug("[TaskBackendRegistry] Registered default backends");
+    }
+    /**
+     * Create a backend instance by name.
+     */
+    static async create(name, config) {
+        TaskBackendRegistry.registerDefaults();
+        const factory = TaskBackendRegistry.factories.get(name);
+        if (!factory) {
+            const available = Array.from(TaskBackendRegistry.factories.keys());
+            throw TaskError.create("BACKEND_UNKNOWN", `Unknown task backend: "${name}". Available: ${available.join(", ")}`);
+        }
+        return factory(config);
+    }
+    /**
+     * Check if a backend is registered.
+     */
+    static has(name) {
+        TaskBackendRegistry.registerDefaults();
+        return TaskBackendRegistry.factories.has(name);
+    }
+    /**
+     * List all registered backend names.
+     */
+    static getAvailable() {
+        TaskBackendRegistry.registerDefaults();
+        return Array.from(TaskBackendRegistry.factories.keys());
+    }
+}

package/dist/tasks/errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * TaskError — Typed error factory for the TaskManager system.
+ *
+ * Uses the standard NeuroLink createErrorFactory pattern so every task-related
+ * error carries a structured code, feature tag, and optional retryable flag.
+ */
+export declare const TaskErrorCodes: {
+    readonly TASK_NOT_FOUND: "TASK-001";
+    readonly BACKEND_NOT_INITIALIZED: "TASK-002";
+    readonly BACKEND_UNKNOWN: "TASK-003";
+    readonly INVALID_TASK_STATUS: "TASK-004";
+    readonly TASK_LIMIT_REACHED: "TASK-005";
+    readonly TASK_DISABLED: "TASK-006";
+    readonly SCHEDULE_FAILED: "TASK-007";
+};
+export declare const TaskError: {
+    codes: {
+        readonly TASK_NOT_FOUND: "TASK-001";
+        readonly BACKEND_NOT_INITIALIZED: "TASK-002";
+        readonly BACKEND_UNKNOWN: "TASK-003";
+        readonly INVALID_TASK_STATUS: "TASK-004";
+        readonly TASK_LIMIT_REACHED: "TASK-005";
+        readonly TASK_DISABLED: "TASK-006";
+        readonly SCHEDULE_FAILED: "TASK-007";
+    };
+    create: (code: "TASK_NOT_FOUND" | "BACKEND_NOT_INITIALIZED" | "BACKEND_UNKNOWN" | "INVALID_TASK_STATUS" | "TASK_LIMIT_REACHED" | "TASK_DISABLED" | "SCHEDULE_FAILED", message: string, options?: {
+        retryable?: boolean;
+        details?: Record<string, unknown>;
+        cause?: Error;
+    } | undefined) => import("../index.js").NeuroLinkFeatureError;
+};

package/dist/tasks/errors.js

@@ -0,0 +1,17 @@
+/**
+ * TaskError — Typed error factory for the TaskManager system.
+ *
+ * Uses the standard NeuroLink createErrorFactory pattern so every task-related
+ * error carries a structured code, feature tag, and optional retryable flag.
+ */
+import { createErrorFactory } from "../core/infrastructure/baseError.js";
+export const TaskErrorCodes = {
+    TASK_NOT_FOUND: "TASK-001",
+    BACKEND_NOT_INITIALIZED: "TASK-002",
+    BACKEND_UNKNOWN: "TASK-003",
+    INVALID_TASK_STATUS: "TASK-004",
+    TASK_LIMIT_REACHED: "TASK-005",
+    TASK_DISABLED: "TASK-006",
+    SCHEDULE_FAILED: "TASK-007",
+};
+export const TaskError = createErrorFactory("Task", TaskErrorCodes);

package/dist/tasks/store/fileTaskStore.d.ts

@@ -0,0 +1,43 @@
+/**
+ * FileTaskStore — File-based persistence for TaskManager.
+ * Used automatically when backend is "node-timeout".
+ *
+ * Storage layout:
+ *   {storePath}                     — tasks.json (all task definitions)
+ *   {logsPath}/{taskId}.jsonl       — run log per task (append-only)
+ *   Continuation history is in-memory only (lost on restart).
+ */
+import { type Task, type TaskStatus, type TaskRunResult, type TaskStore, type TaskManagerConfig, type ConversationEntry } from "../../types/taskTypes.js";
+export declare class FileTaskStore implements TaskStore {
+    readonly type: "file";
+    private storePath;
+    private logsPath;
+    private maxRunLogs;
+    private maxHistoryEntries;
+    private tasks;
+    /** In-memory only — lost on restart */
+    private history;
+    private flushQueue;
+    constructor(config: TaskManagerConfig);
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    save(task: Task): Promise<void>;
+    get(taskId: string): Promise<Task | null>;
+    list(filter?: {
+        status?: TaskStatus;
+    }): Promise<Task[]>;
+    update(taskId: string, updates: Partial<Task>): Promise<Task>;
+    delete(taskId: string): Promise<void>;
+    appendRun(taskId: string, run: TaskRunResult): Promise<void>;
+    getRuns(taskId: string, options?: {
+        limit?: number;
+        status?: string;
+    }): Promise<TaskRunResult[]>;
+    appendHistory(taskId: string, messages: ConversationEntry[]): Promise<void>;
+    getHistory(taskId: string): Promise<ConversationEntry[]>;
+    clearHistory(taskId: string): Promise<void>;
+    /** Write all tasks to disk atomically, serialized via promise queue */
+    private flush;
+    /** Prune run log if it exceeds maxRunLogs entries */
+    private pruneRunLog;
+}

package/dist/tasks/store/fileTaskStore.js

@@ -0,0 +1,178 @@
+/**
+ * FileTaskStore — File-based persistence for TaskManager.
+ * Used automatically when backend is "node-timeout".
+ *
+ * Storage layout:
+ *   {storePath}                     — tasks.json (all task definitions)
+ *   {logsPath}/{taskId}.jsonl       — run log per task (append-only)
+ *   Continuation history is in-memory only (lost on restart).
+ */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { appendFile, readFile, rename, unlink, writeFile, } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { logger } from "../../utils/logger.js";
+import { TaskError } from "../errors.js";
+import { TASK_DEFAULTS, } from "../../types/taskTypes.js";
+export class FileTaskStore {
+    type = "file";
+    storePath;
+    logsPath;
+    maxRunLogs;
+    maxHistoryEntries;
+    tasks = new Map();
+    /** In-memory only — lost on restart */
+    history = new Map();
+    flushQueue = Promise.resolve();
+    constructor(config) {
+        this.storePath = config.storePath ?? TASK_DEFAULTS.storePath;
+        this.logsPath = config.logsPath ?? TASK_DEFAULTS.logsPath;
+        this.maxRunLogs = config.maxRunLogs ?? TASK_DEFAULTS.maxRunLogs;
+        this.maxHistoryEntries =
+            config.maxHistoryEntries ?? TASK_DEFAULTS.maxHistoryEntries;
+    }
+    async initialize() {
+        // Ensure directories exist
+        mkdirSync(dirname(this.storePath), { recursive: true });
+        mkdirSync(this.logsPath, { recursive: true });
+        // Load existing tasks
+        if (existsSync(this.storePath)) {
+            try {
+                const raw = readFileSync(this.storePath, "utf-8");
+                const data = JSON.parse(raw);
+                for (const [id, task] of Object.entries(data.tasks)) {
+                    this.tasks.set(id, task);
+                }
+                logger.info("[TaskStore:File] Loaded tasks", {
+                    count: this.tasks.size,
+                });
+            }
+            catch (err) {
+                logger.error("[TaskStore:File] Failed to load tasks file", {
+                    error: String(err),
+                });
+            }
+        }
+    }
+    async shutdown() {
+        await this.flush();
+        this.tasks.clear();
+        this.history.clear();
+    }
+    // ── Task CRUD ───────────────────────────────────────────
+    async save(task) {
+        this.tasks.set(task.id, task);
+        await this.flush();
+    }
+    async get(taskId) {
+        return this.tasks.get(taskId) ?? null;
+    }
+    async list(filter) {
+        let tasks = Array.from(this.tasks.values());
+        if (filter?.status) {
+            tasks = tasks.filter((t) => t.status === filter.status);
+        }
+        return tasks.sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
+    }
+    async update(taskId, updates) {
+        const existing = this.tasks.get(taskId);
+        if (!existing) {
+            throw TaskError.create("TASK_NOT_FOUND", `Task not found: ${taskId}`);
+        }
+        const updated = {
+            ...existing,
+            ...updates,
+            id: existing.id, // ID is immutable
+            updatedAt: new Date().toISOString(),
+        };
+        this.tasks.set(taskId, updated);
+        await this.flush();
+        return updated;
+    }
+    async delete(taskId) {
+        this.tasks.delete(taskId);
+        this.history.delete(taskId);
+        // Delete run log file
+        const logPath = join(this.logsPath, `${taskId}.jsonl`);
+        try {
+            await unlink(logPath);
+        }
+        catch {
+            // File may not exist if task never ran
+        }
+        await this.flush();
+    }
+    // ── Run Logs ──────────────────────────────────────────
+    async appendRun(taskId, run) {
+        const logPath = join(this.logsPath, `${taskId}.jsonl`);
+        mkdirSync(dirname(logPath), { recursive: true });
+        await appendFile(logPath, JSON.stringify(run) + "\n", "utf-8");
+        await this.pruneRunLog(logPath);
+    }
+    async getRuns(taskId, options) {
+        const logPath = join(this.logsPath, `${taskId}.jsonl`);
+        if (!existsSync(logPath)) {
+            return [];
+        }
+        const content = await readFile(logPath, "utf-8");
+        const lines = content.trim().split("\n").filter(Boolean);
+        let runs = lines.map((line) => JSON.parse(line));
+        if (options?.status) {
+            runs = runs.filter((r) => r.status === options.status);
+        }
+        // Return newest first, limited
+        runs.reverse();
+        const limit = options?.limit ?? 20;
+        return runs.slice(0, limit);
+    }
+    // ── Continuation History (in-memory only) ─────────────
+    async appendHistory(taskId, messages) {
+        const existing = this.history.get(taskId) ?? [];
+        existing.push(...messages);
+        // Trim to keep only the most recent entries, preventing unbounded growth
+        if (existing.length > this.maxHistoryEntries) {
+            const trimmed = existing.slice(-this.maxHistoryEntries);
+            this.history.set(taskId, trimmed);
+        }
+        else {
+            this.history.set(taskId, existing);
+        }
+    }
+    async getHistory(taskId) {
+        return this.history.get(taskId) ?? [];
+    }
+    async clearHistory(taskId) {
+        this.history.delete(taskId);
+    }
+    // ── Internal ──────────────────────────────────────────
+    /** Write all tasks to disk atomically, serialized via promise queue */
+    async flush() {
+        this.flushQueue = this.flushQueue.then(async () => {
+            const data = {
+                version: 1,
+                tasks: Object.fromEntries(this.tasks),
+            };
+            const dir = dirname(this.storePath);
+            mkdirSync(dir, { recursive: true });
+            // Write to temp file first, then atomic rename
+            const tmpPath = this.storePath + ".tmp";
+            await writeFile(tmpPath, JSON.stringify(data, null, 2), "utf-8");
+            await rename(tmpPath, this.storePath);
+        });
+        await this.flushQueue;
+    }
+    /** Prune run log if it exceeds maxRunLogs entries */
+    async pruneRunLog(logPath) {
+        try {
+            const content = await readFile(logPath, "utf-8");
+            const lines = content.trim().split("\n").filter(Boolean);
+            if (lines.length > this.maxRunLogs) {
+                // Keep the most recent entries
+                const trimmed = lines.slice(-this.maxRunLogs);
+                await writeFile(logPath, trimmed.join("\n") + "\n", "utf-8");
+            }
+        }
+        catch {
+            // Pruning is best-effort
+        }
+    }
+}

package/dist/tasks/store/redisTaskStore.d.ts

@@ -0,0 +1,42 @@
+/**
+ * RedisTaskStore — Redis-backed persistence for TaskManager.
+ * Used automatically when backend is "bullmq".
+ *
+ * Key patterns:
+ *   neurolink:tasks              (Hash)  — all task definitions
+ *   neurolink:task:{id}:runs     (List)  — run log entries (newest first)
+ *   neurolink:task:{id}:history  (List)  — continuation mode conversation history
+ */
+import { type Task, type TaskStatus, type TaskRunResult, type TaskStore, type TaskManagerConfig, type ConversationEntry } from "../../types/taskTypes.js";
+export declare class RedisTaskStore implements TaskStore {
+    private config;
+    readonly type: "redis";
+    private client;
+    private maxRunLogs;
+    private maxHistoryEntries;
+    private retentionConfig;
+    constructor(config: TaskManagerConfig);
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    save(task: Task): Promise<void>;
+    get(taskId: string): Promise<Task | null>;
+    list(filter?: {
+        status?: TaskStatus;
+    }): Promise<Task[]>;
+    update(taskId: string, updates: Partial<Task>): Promise<Task>;
+    delete(taskId: string): Promise<void>;
+    appendRun(taskId: string, run: TaskRunResult): Promise<void>;
+    getRuns(taskId: string, options?: {
+        limit?: number;
+        status?: string;
+    }): Promise<TaskRunResult[]>;
+    appendHistory(taskId: string, messages: ConversationEntry[]): Promise<void>;
+    getHistory(taskId: string): Promise<ConversationEntry[]>;
+    clearHistory(taskId: string): Promise<void>;
+    private ensureConnected;
+    /**
+     * Set Redis TTL on terminal-state tasks so they auto-expire.
+     * Active and paused tasks never expire.
+     */
+    private applyRetentionTTL;
+}