feat: Implement a generic user timers system with a scheduler to manage cooldowns, effects, and access.

src/modules/system/scheduler.ts

@@ -0,0 +1,59 @@
+import { userTimers } from "@/db/schema";
+import { eq, and, lt } from "drizzle-orm";
+import { DrizzleClient } from "@/lib/DrizzleClient";
+
+/**
+ * The Janitor responsible for cleaning up expired ACCESS timers
+ * and revoking privileges.
+ */
+export const schedulerService = {
+    start: () => {
+        console.log("🕒 Scheduler started: Janitor loop running every 60s");
+        // Run immediately on start
+        schedulerService.runJanitor();
+
+        // Loop every 60 seconds
+        setInterval(() => {
+            schedulerService.runJanitor();
+        }, 60 * 1000);
+    },
+
+    runJanitor: async () => {
+        try {
+            // Find all expired ACCESS timers
+            // We do this in a transaction to ensure we read and delete atomically if possible,
+            // though for this specific case, fetching then deleting is fine as long as we handle race conditions gracefully.
+
+            const now = new Date();
+
+            const expiredAccess = await DrizzleClient.query.userTimers.findMany({
+                where: and(
+                    eq(userTimers.type, 'ACCESS'),
+                    lt(userTimers.expiresAt, now)
+                )
+            });
+
+            if (expiredAccess.length === 0) return;
+
+            console.log(`🧹 Janitor: Found ${expiredAccess.length} expired access timers.`);
+
+            for (const timer of expiredAccess) {
+                // TODO: Here we would call Discord API to remove roles/overwrites.
+                // e.g. discordClient.channels.cache.get(timer.metadata.channelId).permissionOverwrites.delete(timer.userId)
+
+                const meta = timer.metadata as any;
+                console.log(`🚫 Revoking access for User ${timer.userId}: Key=${timer.key} (Channel: ${meta?.channelId || 'N/A'})`);
+
+                // Delete the timer row
+                await DrizzleClient.delete(userTimers)
+                    .where(and(
+                        eq(userTimers.userId, timer.userId),
+                        eq(userTimers.type, timer.type),
+                        eq(userTimers.key, timer.key)
+                    ));
+            }
+        } catch (error) {
+            console.error("Janitor Error:", error);
+        }
+    }
+};