alepha 0.20.1 → 0.20.3

package/src/api/notifications/controllers/AdminNotificationController.ts

@@ -1,7 +1,8 @@
 import { $inject, t } from "alepha";
-import { JobService } from "alepha/api/jobs";
+import { jobExecutionEntity } from "alepha/api/jobs";
+import { $repository } from "alepha/orm";
 import { $secure } from "alepha/security";
-import { $action } from "alepha/server";
+import { $action, NotFoundError } from "alepha/server";
 import { NotificationJobs } from "../jobs/NotificationJobs.ts";
 import { notificationDetailResourceSchema } from "../schemas/notificationDetailResourceSchema.ts";
 import { notificationQuerySchema } from "../schemas/notificationQuerySchema.ts";
@@ -10,8 +11,8 @@ import { notificationResourceSchema } from "../schemas/notificationResourceSchem
 export class AdminNotificationController {
   protected readonly url: string = "/notifications";
   protected readonly group: string = "admin:notifications";
-  protected readonly jobService = $inject(JobService);
   protected readonly notificationJobs = $inject(NotificationJobs);
+  protected readonly executions = $repository(jobExecutionEntity);
 
   protected get jobName(): string {
     return this.notificationJobs.sendNotification.name;
@@ -26,13 +27,17 @@ export class AdminNotificationController {
       response: t.page(notificationResourceSchema),
     },
     handler: async ({ query }) => {
-      const result = await this.jobService.findExecutions({
-        ...query,
-        job: this.jobName,
-      });
+      query.sort ??= "-createdAt";
+      const where = this.executions.createQueryWhere();
+      where.jobName = { eq: this.jobName };
+      const page = await this.executions.paginate(
+        query,
+        { where },
+        { count: true },
+      );
       return {
-        ...result,
-        content: result.content.map((exec) => this.toResource(exec)),
+        ...page,
+        content: page.content.map((exec) => this.toResource(exec)),
       } as any;
     },
   });
@@ -48,8 +53,11 @@ export class AdminNotificationController {
       response: notificationDetailResourceSchema,
     },
     handler: async ({ params }) => {
-      const detail = await this.jobService.getExecution(params.id);
-      return this.toDetailResource(detail) as any;
+      const exec = await this.executions.findById(params.id);
+      if (!exec || exec.jobName !== this.jobName) {
+        throw new NotFoundError(`Notification not found: ${params.id}`);
+      }
+      return this.toDetailResource(exec) as any;
     },
   });
 
@@ -76,7 +84,6 @@ export class AdminNotificationController {
     return {
       ...this.toResource(exec),
       variables: payload.variables,
-      rendered: exec.result,
       logs: exec.logs,
     };
   }

package/src/api/notifications/index.ts

@@ -1,4 +1,6 @@
 import { $module } from "alepha";
+import { AlephaApiJobsQueue } from "alepha/api/jobs";
+import { AlephaApiParameters } from "alepha/api/parameters";
 import { AdminNotificationController } from "./controllers/AdminNotificationController.ts";
 import { NotificationJobs } from "./jobs/NotificationJobs.ts";
 import { $notification } from "./primitives/$notification.ts";
@@ -23,15 +25,16 @@ export * from "./services/NotificationSenderService.ts";
  * User notification management.
  *
  * **Features:**
- * - Notification definitions
- * - Email/SMS notification sending
- * - Job-based delivery with retry and tracking
- * - User preferences
+ * - Notification definitions (email/SMS templates)
+ * - Queue-based delivery with retry and audit trail (`record: "all"` + no ring buffer trim)
+ * - Runtime-editable retention window via `$parameter` — purge cron respects it live
+ * - Admin API for inspecting sent notifications
  *
  * @module alepha.api.notifications
  */
 export const AlephaApiNotifications = $module({
   name: "alepha.api.notifications",
+  imports: [AlephaApiJobsQueue, AlephaApiParameters],
   primitives: [$notification],
   services: [
     NotificationSenderService,

package/src/api/notifications/jobs/NotificationJobs.ts

@@ -1,16 +1,57 @@
-import { $inject } from "alepha";
+import { $inject, t } from "alepha";
 import { $job, jobExecutionEntity } from "alepha/api/jobs";
+import { $parameter } from "alepha/api/parameters";
+import { DateTimeProvider } from "alepha/datetime";
+import { $logger } from "alepha/logger";
 import { $repository } from "alepha/orm";
 import { notificationPayloadSchema } from "../schemas/notificationPayloadSchema.ts";
 import { NotificationSenderService } from "../services/NotificationSenderService.ts";
 
+/**
+ * Notification jobs + runtime-editable retention.
+ *
+ * - `settings` — a `$parameter` exposing `retentionDays` that admins can
+ *   update at runtime. Changes propagate across instances via the parameter
+ *   pub/sub; the next purge run picks up the new value with no restart.
+ * - `sendNotification` — queue-mode, audit-oriented. Every execution is kept
+ *   (`record: "all"`, `keep: { ok: 0, error: 0 }` disables the ring-buffer
+ *   trim) so the audit trail survives even under heavy volume.
+ * - `purgeOldNotifications` — cron sweep that deletes notification execution
+ *   rows whose `completedAt` is older than the current `retentionDays`.
+ *
+ * Cron expression note: the purge cron is declared statically (`0 3 * * *`)
+ * because some runtimes (Cloudflare Workers) freeze cron triggers at deploy
+ * time. The *retention window* is fully runtime-editable — that's the knob
+ * that actually matters for operators.
+ */
 export class NotificationJobs {
+  protected readonly log = $logger();
+  protected readonly dt = $inject(DateTimeProvider);
   protected readonly notificationSenderService = $inject(
     NotificationSenderService,
   );
   protected readonly executions = $repository(jobExecutionEntity);
 
+  /** Runtime-editable config. Admins can change retentionDays without deploy. */
+  public readonly settings = $parameter({
+    name: "alepha.api.notifications",
+    description: "Notification delivery & retention settings.",
+    schema: t.object({
+      retentionDays: t.integer({
+        description:
+          "Days to keep notification execution rows before the purge sweep removes them.",
+        minimum: 1,
+      }),
+    }),
+    default: {
+      retentionDays: 7,
+    },
+  });
+
   public readonly sendNotification = $job({
+    name: "api:notifications:sendNotification",
+    description:
+      "Sends a notification (email/SMS) and keeps every execution for audit.",
     schema: notificationPayloadSchema,
     retry: {
       retries: 3,
@@ -22,18 +63,48 @@ export class NotificationJobs {
       },
     },
     timeout: [30, "seconds"],
-    concurrency: 5,
-    handler: async ({ items }) => {
-      for (const item of items) {
-        const rendered = await this.notificationSenderService.send(
-          item.payload,
-        );
-        if (rendered) {
-          await this.executions.updateById(item.id, {
-            result: rendered as Record<string, unknown>,
-          });
-        }
+    record: "all",
+    keep: { ok: 0, error: 0 },
+    handler: async ({ payload }) => {
+      await this.notificationSenderService.send(payload);
+    },
+  });
+
+  public readonly purgeOldNotifications = $job({
+    name: "api:notifications:purgeOldNotifications",
+    description:
+      "Hourly sweep that deletes notification execution rows older than the configured retention window.",
+    cron: "0 * * * *",
+    handler: async ({ now }) => {
+      const { retentionDays } = this.settings.cachedCurrentContent;
+      const cutoff = now.subtract(retentionDays, "day").toISOString();
+      const jobName = this.sendNotification.name;
+
+      const expired = await this.executions.findMany({
+        where: {
+          jobName: { eq: jobName },
+          status: { inArray: ["ok", "error", "cancelled"] },
+          completedAt: { lt: cutoff },
+        },
+        columns: ["id"] as any,
+        limit: 5_000,
+      });
+
+      if (expired.length === 0) {
+        this.log.debug("Notification purge: nothing to delete", {
+          cutoff,
+          retentionDays,
+        });
+        return;
       }
+
+      await this.executions.deleteMany({
+        id: { inArray: expired.map((r) => r.id) },
+      });
+      this.log.info(
+        `Notification purge: deleted ${expired.length} row(s) older than ${retentionDays} days`,
+        { cutoff },
+      );
     },
   });
 }

package/src/api/payments/services/PaymentService.ts

@@ -21,10 +21,12 @@ export class PaymentService {
 
   /**
    * Expires stale payment intents that have been in "processing" status
-   * for more than 30 minutes. Runs every 15 minutes.
+   * for more than 30 minutes. Runs every 5 minutes — shares the CF wrangler
+   * trigger with the jobs sweep so no extra binding is consumed.
    */
   protected readonly expireStaleIntents = $job({
-    cron: "*/15 * * * *",
+    name: "api:payments:expireStaleIntents",
+    cron: "*/5 * * * *",
     handler: async () => {
       const cutoff = this.dateTime.now().subtract(30, "minutes").toISOString();
 

package/src/api/users/__tests__/UserJobs.spec.ts

@@ -1,15 +1,15 @@
 import { Alepha } from "alepha";
-import { AlephaApiJobs, jobExecutionEntity } from "alepha/api/jobs";
+import { AlephaApiJobs } from "alepha/api/jobs";
 import { $repository } from "alepha/orm";
 import { AlephaOrmPostgres } from "alepha/orm/postgres";
-import { describe, test, vi } from "vitest";
+import { describe, test } from "vitest";
 import { sessions } from "../entities/sessions.ts";
 import { users } from "../entities/users.ts";
 import { UserJobs } from "../jobs/UserJobs.ts";
 
 describe("UserJobs", () => {
   describe("purgeExpiredSessions", () => {
-    test("should delete expired sessions", async ({ expect }) => {
+    test("deletes expired sessions", async ({ expect }) => {
       const alepha = Alepha.create()
         .with(AlephaOrmPostgres)
         .with(AlephaApiJobs);
@@ -17,20 +17,17 @@ describe("UserJobs", () => {
       class TestRepositories {
         userRepository = $repository(users);
         sessionRepository = $repository(sessions);
-        executions = $repository(jobExecutionEntity);
       }
 
       const userJobs = alepha.inject(UserJobs);
       const repos = alepha.inject(TestRepositories);
       await alepha.start();
 
-      // Create a test user
       const user = await repos.userRepository.create({
         email: "test@example.com",
       });
 
-      // Create expired sessions (expiresAt in the past)
-      const pastDate = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(); // 1 day ago
+      const pastDate = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
       await repos.sessionRepository.create({
         userId: user.id,
         refreshToken: crypto.randomUUID(),
@@ -42,35 +39,20 @@ describe("UserJobs", () => {
         expiresAt: pastDate,
       });
 
-      // Create a valid session (expiresAt in the future)
       const futureDate = new Date(
         Date.now() + 24 * 60 * 60 * 1000,
-      ).toISOString(); // 1 day from now
+      ).toISOString();
       await repos.sessionRepository.create({
         userId: user.id,
         refreshToken: crypto.randomUUID(),
         expiresAt: futureDate,
       });
 
-      // Verify we have 3 sessions
-      const sessionsBefore = await repos.sessionRepository.findMany();
-      expect(sessionsBefore).toHaveLength(3);
+      expect(await repos.sessionRepository.findMany()).toHaveLength(3);
 
-      // Trigger the job
+      // Cron jobs run inline — trigger awaits the handler synchronously.
       await userJobs.purgeExpiredSessions.trigger();
 
-      // Wait for async job processing to complete
-      await vi.waitFor(async () => {
-        const executions = await repos.executions.findMany({
-          where: {
-            jobName: "UserJobs.purgeExpiredSessions",
-            status: "completed",
-          },
-        });
-        expect(executions).toHaveLength(1);
-      });
-
-      // Verify only the valid session remains
       const sessionsAfter = await repos.sessionRepository.findMany();
       expect(sessionsAfter).toHaveLength(1);
       expect(new Date(sessionsAfter[0].expiresAt).getTime()).toBeGreaterThan(
@@ -78,9 +60,7 @@ describe("UserJobs", () => {
       );
     });
 
-    test("should handle case when no expired sessions exist", async ({
-      expect,
-    }) => {
+    test("no-op when no expired sessions exist", async ({ expect }) => {
       const alepha = Alepha.create()
         .with(AlephaOrmPostgres)
         .with(AlephaApiJobs);
@@ -88,19 +68,16 @@ describe("UserJobs", () => {
       class TestRepositories {
         userRepository = $repository(users);
         sessionRepository = $repository(sessions);
-        executions = $repository(jobExecutionEntity);
       }
 
       const userJobs = alepha.inject(UserJobs);
       const repos = alepha.inject(TestRepositories);
       await alepha.start();
 
-      // Create a test user
       const user = await repos.userRepository.create({
         email: "test2@example.com",
       });
 
-      // Create only valid sessions
       const futureDate = new Date(
         Date.now() + 24 * 60 * 60 * 1000,
       ).toISOString();
@@ -110,27 +87,11 @@ describe("UserJobs", () => {
         expiresAt: futureDate,
       });
 
-      // Verify we have 1 session
-      const sessionsBefore = await repos.sessionRepository.findMany();
-      expect(sessionsBefore).toHaveLength(1);
+      expect(await repos.sessionRepository.findMany()).toHaveLength(1);
 
-      // Trigger the job - should not throw
       await userJobs.purgeExpiredSessions.trigger();
 
-      // Wait for async job processing to complete
-      await vi.waitFor(async () => {
-        const executions = await repos.executions.findMany({
-          where: {
-            jobName: "UserJobs.purgeExpiredSessions",
-            status: "completed",
-          },
-        });
-        expect(executions).toHaveLength(1);
-      });
-
-      // Session should still exist
-      const sessionsAfter = await repos.sessionRepository.findMany();
-      expect(sessionsAfter).toHaveLength(1);
+      expect(await repos.sessionRepository.findMany()).toHaveLength(1);
     });
   });
 });

package/src/api/users/audits/UserAudits.ts

@@ -7,7 +7,9 @@ type AuditContext = Omit<CreateAudit, "type" | "action">;
  * User-specific audit wrapper service.
  *
  * This service wraps the core AuditService to provide user-related audit logging.
- * It is lazy-loaded when the `audits` feature is enabled in the realm.
+ *
+ * Declared as a module variant — not auto-injected. It is instantiated
+ * lazily the first time something calls `alepha.inject(UserAudits)`.
  */
 export class UserAudits {
   protected readonly auditService = $inject(AuditService);

package/src/api/users/buckets/UserBuckets.ts

@@ -6,7 +6,8 @@ import { $bucket } from "alepha/bucket";
  * This service provides file storage for user-related files such as:
  * - User avatars/profile pictures
  *
- * It is lazy-loaded when the `avatars` feature is enabled in the realm.
+ * Declared as a module variant — not auto-injected. It is instantiated
+ * lazily the first time something calls `alepha.inject(UserBuckets)`.
  */
 export class UserBuckets {
   /**

package/src/api/users/index.ts

@@ -88,9 +88,6 @@ export const AlephaApiUsers = $module({
     AdminSessionController,
     AdminIdentityController,
     RealmController,
-    UserJobs,
-    UserNotifications,
-    UserAudits,
-    UserBuckets,
   ],
+  variants: [UserJobs, UserNotifications, UserAudits, UserBuckets],
 });

package/src/api/users/jobs/UserJobs.ts

@@ -13,7 +13,8 @@ import { sessions } from "../entities/sessions.ts";
  * - Verification code cleanup
  * - Inactive user notifications
  *
- * It is lazy-loaded when the `sessionPurge` feature is enabled in the realm.
+ * Declared as a module variant — not auto-injected. It is instantiated
+ * lazily the first time something calls `alepha.inject(UserJobs)`.
  */
 export class UserJobs {
   protected readonly log = $logger();
@@ -23,11 +24,11 @@ export class UserJobs {
   /**
    * Purge expired sessions from the database.
    *
-   * This job runs daily at 3:00 AM and removes all sessions
-   * where the `expiresAt` timestamp has passed.
+   * Runs hourly (at :00) and deletes sessions whose `expiresAt` has passed.
    */
   public readonly purgeExpiredSessions = $job({
-    cron: "0 0 * * *", // Daily at 3:00 AM
+    name: "api:users:purgeExpiredSessions",
+    cron: "0 * * * *", // Hourly at minute 0
     handler: async () => {
       const now = this.dateTimeProvider.nowISOString();
 

package/src/api/users/schemas/userQuerySchema.ts

@@ -7,7 +7,6 @@ export const userQuerySchema = t.extend(pageQuerySchema, {
   enabled: t.optional(t.boolean()),
   emailVerified: t.optional(t.boolean()),
   roles: t.optional(t.array(t.string())),
-  query: t.optional(t.text()),
 });
 
 export type UserQuery = Static<typeof userQuerySchema>;

package/src/api/users/services/UserService.ts

@@ -1,7 +1,7 @@
 import { $inject, Alepha } from "alepha";
 import type { VerificationController } from "alepha/api/verifications";
 import { $logger } from "alepha/logger";
-import { type Page, parseQueryString } from "alepha/orm";
+import type { Page } from "alepha/orm";
 import { BadRequestError } from "alepha/server";
 import { $client } from "alepha/server/links";
 import { UserAudits } from "../audits/UserAudits.ts";
@@ -229,10 +229,6 @@ export class UserService {
       where.roles = { arrayContains: q.roles };
     }
 
-    if (q.query) {
-      Object.assign(where, parseQueryString(q.query));
-    }
-
     const result = await this.users(userRealmName).paginate(
       q,
       { where },

package/src/api/verifications/__tests__/CodeVerification.spec.ts

@@ -198,6 +198,20 @@ describe("Code Verification", () => {
     const { parameters, controller, dateTimeProvider, target } =
       await createTest();
 
+    // Anchor test time at noon to keep all `limitPerDay` inserts inside the
+    // same calendar day — running near midnight (real wall-clock) used to
+    // make the cooldown travel cross day boundaries and reset the window.
+    const now = dateTimeProvider.now();
+    const noon = now.startOf("day").add(12, "hours");
+    if (noon.diff(now) > 0) {
+      await dateTimeProvider.travel(noon.diff(now), "milliseconds");
+    } else {
+      await dateTimeProvider.travel(
+        noon.add(1, "day").diff(now),
+        "milliseconds",
+      );
+    }
+
     for (let i = 0; i < parameters.limitPerDay; i++) {
       await controller.requestVerificationCode({
         params: {

package/src/api/verifications/__tests__/LinkVerification.spec.ts

@@ -198,6 +198,20 @@ describe("Link Verification", () => {
     const { parameters, controller, dateTimeProvider, target } =
       await createTest();
 
+    // Anchor test time at noon to keep all `limitPerDay` inserts inside the
+    // same calendar day — running near midnight (real wall-clock) used to
+    // make the cooldown travel cross day boundaries and reset the window.
+    const now = dateTimeProvider.now();
+    const noon = now.startOf("day").add(12, "hours");
+    if (noon.diff(now) > 0) {
+      await dateTimeProvider.travel(noon.diff(now), "milliseconds");
+    } else {
+      await dateTimeProvider.travel(
+        noon.add(1, "day").diff(now),
+        "milliseconds",
+      );
+    }
+
     for (let i = 0; i < parameters.limitPerDay; i++) {
       await controller.requestVerificationCode({
         params: {

package/src/api/verifications/jobs/VerificationJobs.ts

@@ -11,7 +11,8 @@ export class VerificationJobs {
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
 
   public readonly cleanExpired = $scheduler({
-    cron: "0 0 * * *", // Every day at midnight
+    name: "api:verifications:cleanExpired",
+    cron: "0 * * * *", // Hourly at minute 0
     description: "Clean expired verifications",
     handler: async () => {
       const purgeDays = this.verificationParameters.get("purgeDays");

package/src/api/verifications/services/VerificationService.ts

@@ -134,6 +134,7 @@ export class VerificationService {
       type: entry.type,
       target: entry.target,
       code: this.hashCode(token),
+      createdAt: this.dateTimeProvider.nowISOString(),
     });
 
     this.log.info("Verification created", {