alepha 0.18.2 → 0.18.3

package/package.json

@@ -2,7 +2,7 @@
   "name": "alepha",
   "description": "Easy-to-use modern TypeScript framework for building many kind of applications.",
   "author": "Nicolas Foures",
-  "version": "0.18.2",
+  "version": "0.18.3",
   "type": "module",
   "engines": {
     "node": ">=22.0.0"
@@ -25,18 +25,18 @@
     "drizzle-orm": "^0.45.1",
     "postgres": "^3.4.8",
     "tsx": "^4.21.0",
-    "typebox": "^1.1.1",
+    "typebox": "^1.1.5",
     "typescript": "^5.9.3",
     "vite-bundle-analyzer": "^1.3.6",
     "ws": "^8.19.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.4",
+    "@biomejs/biome": "^2.4.5",
     "@electric-sql/pglite": "^0.3.15",
     "@faker-js/faker": "^10.3.0",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
-    "@types/node": "^25.3.0",
+    "@types/node": "^25.3.3",
     "@types/nodemailer": "^7.0.11",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
@@ -51,7 +51,7 @@
     "prom-client": "^15.1.3",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
-    "swagger-ui-dist": "^5.31.2",
+    "swagger-ui-dist": "^5.32.0",
     "tsdown": "^0.20.3",
     "vite": "^7.3.1",
     "vitest": "^4.0.18"
@@ -174,6 +174,11 @@
       "import": "./dist/cache/redis/index.js",
       "default": "./dist/cache/redis/index.js"
     },
+    "./cli/config": {
+      "types": "./dist/cli/config/index.d.ts",
+      "import": "./dist/cli/config/index.js",
+      "default": "./dist/cli/config/index.js"
+    },
     "./cli": {
       "types": "./dist/cli/core/index.d.ts",
       "import": "./dist/cli/core/index.js",

package/src/api/jobs/providers/JobProvider.ts

@@ -796,9 +796,12 @@ export class JobProvider {
         entries.push(entry);
       });
 
-      // Run initial sweeps to recover from previous crashes
-      await this.delayedDispatchSweep();
-      await this.recoverySweep();
+      // Run initial sweeps to recover from previous crashes.
+      // Skipped on serverless — cron triggers handle periodic sweeps instead.
+      if (!this.alepha.isServerless()) {
+        await this.delayedDispatchSweep();
+        await this.recoverySweep();
+      }
 
       // Periodic sweeps via cron (works in serverless environments like Cloudflare Workers)
       this.cronProvider.createCronJob(

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

@@ -0,0 +1,83 @@
+import { $inject, t } from "alepha";
+import { JobService } from "alepha/api/jobs";
+import { $secure } from "alepha/security";
+import { $action } from "alepha/server";
+import { NotificationJobs } from "../jobs/NotificationJobs.ts";
+import { notificationDetailResourceSchema } from "../schemas/notificationDetailResourceSchema.ts";
+import { notificationQuerySchema } from "../schemas/notificationQuerySchema.ts";
+import { notificationResourceSchema } from "../schemas/notificationResourceSchema.ts";
+
+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 get jobName(): string {
+    return this.notificationJobs.sendNotification.name;
+  }
+
+  public readonly findNotifications = $action({
+    path: this.url,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:notification:read"] })],
+    schema: {
+      query: notificationQuerySchema,
+      response: t.page(notificationResourceSchema),
+    },
+    handler: async ({ query }) => {
+      const result = await this.jobService.findExecutions({
+        ...query,
+        job: this.jobName,
+      });
+      return {
+        ...result,
+        content: result.content.map((exec) => this.toResource(exec)),
+      } as any;
+    },
+  });
+
+  public readonly getNotification = $action({
+    path: `${this.url}/:id`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:notification:read"] })],
+    schema: {
+      params: t.object({
+        id: t.uuid(),
+      }),
+      response: notificationDetailResourceSchema,
+    },
+    handler: async ({ params }) => {
+      const detail = await this.jobService.getExecution(params.id);
+      return this.toDetailResource(detail) as any;
+    },
+  });
+
+  protected toResource(exec: Record<string, unknown>) {
+    const payload = (exec.payload ?? {}) as Record<string, unknown>;
+    return {
+      id: exec.id,
+      createdAt: exec.createdAt,
+      status: exec.status,
+      template: payload.template,
+      type: payload.type,
+      contact: payload.contact,
+      category: payload.category,
+      critical: payload.critical,
+      sensitive: payload.sensitive,
+      startedAt: exec.startedAt,
+      completedAt: exec.completedAt,
+      error: exec.error,
+    };
+  }
+
+  protected toDetailResource(exec: Record<string, unknown>) {
+    const payload = (exec.payload ?? {}) as Record<string, unknown>;
+    return {
+      ...this.toResource(exec),
+      variables: payload.variables,
+      rendered: exec.result,
+      logs: exec.logs,
+    };
+  }
+}

package/src/api/notifications/index.browser.ts

@@ -4,7 +4,10 @@ import { $module } from "alepha";
 
 export * from "./schemas/notificationContactPreferencesSchema.ts";
 export * from "./schemas/notificationContactSchema.ts";
+export * from "./schemas/notificationDetailResourceSchema.ts";
 export * from "./schemas/notificationPayloadSchema.ts";
+export * from "./schemas/notificationQuerySchema.ts";
+export * from "./schemas/notificationResourceSchema.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 

package/src/api/notifications/index.ts

@@ -1,15 +1,20 @@
 import { $module } from "alepha";
+import { AdminNotificationController } from "./controllers/AdminNotificationController.ts";
 import { NotificationJobs } from "./jobs/NotificationJobs.ts";
 import { $notification } from "./primitives/$notification.ts";
 import { NotificationSenderService } from "./services/NotificationSenderService.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
+export * from "./controllers/AdminNotificationController.ts";
 export * from "./jobs/NotificationJobs.ts";
 export * from "./primitives/$notification.ts";
 export * from "./schemas/notificationContactPreferencesSchema.ts";
 export * from "./schemas/notificationContactSchema.ts";
+export * from "./schemas/notificationDetailResourceSchema.ts";
 export * from "./schemas/notificationPayloadSchema.ts";
+export * from "./schemas/notificationQuerySchema.ts";
+export * from "./schemas/notificationResourceSchema.ts";
 export * from "./services/NotificationSenderService.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -28,8 +33,15 @@ export * from "./services/NotificationSenderService.ts";
 export const AlephaApiNotifications = $module({
   name: "alepha.api.notifications",
   primitives: [$notification],
-  services: [NotificationSenderService, NotificationJobs],
+  services: [
+    NotificationSenderService,
+    NotificationJobs,
+    AdminNotificationController,
+  ],
   register: (alepha) => {
-    alepha.with(NotificationSenderService).with(NotificationJobs);
+    alepha
+      .with(NotificationSenderService)
+      .with(NotificationJobs)
+      .with(AdminNotificationController);
   },
 });

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

@@ -1,5 +1,6 @@
 import { $inject } from "alepha";
-import { $job } from "alepha/api/jobs";
+import { $job, jobExecutionEntity } from "alepha/api/jobs";
+import { $repository } from "alepha/orm";
 import { notificationPayloadSchema } from "../schemas/notificationPayloadSchema.ts";
 import { NotificationSenderService } from "../services/NotificationSenderService.ts";
 
@@ -7,6 +8,7 @@ export class NotificationJobs {
   protected readonly notificationSenderService = $inject(
     NotificationSenderService,
   );
+  protected readonly executions = $repository(jobExecutionEntity);
 
   public readonly sendNotification = $job({
     schema: notificationPayloadSchema,
@@ -23,7 +25,14 @@ export class NotificationJobs {
     concurrency: 5,
     handler: async ({ items }) => {
       for (const item of items) {
-        await this.notificationSenderService.send(item.payload);
+        const rendered = await this.notificationSenderService.send(
+          item.payload,
+        );
+        if (rendered) {
+          await this.executions.updateById(item.id, {
+            result: rendered as Record<string, unknown>,
+          });
+        }
       }
     },
   });

package/src/api/notifications/schemas/notificationDetailResourceSchema.ts

@@ -0,0 +1,20 @@
+import { type Static, t } from "alepha";
+import { logEntrySchema } from "alepha/logger";
+import { notificationResourceSchema } from "./notificationResourceSchema.ts";
+
+export const notificationDetailResourceSchema = t.extend(
+  notificationResourceSchema,
+  {
+    variables: t.optional(t.record(t.text(), t.any())),
+    rendered: t.optional(t.record(t.text(), t.any())),
+    logs: t.optional(t.array(logEntrySchema)),
+  },
+  {
+    title: "NotificationDetailResource",
+    description: "A notification resource with rendered content and logs.",
+  },
+);
+
+export type NotificationDetailResource = Static<
+  typeof notificationDetailResourceSchema
+>;

package/src/api/notifications/schemas/notificationQuerySchema.ts

@@ -0,0 +1,19 @@
+import { type Static, t } from "alepha";
+import { pageQuerySchema } from "alepha/orm";
+
+export const notificationQuerySchema = t.extend(pageQuerySchema, {
+  status: t.optional(
+    t.enum([
+      "pending",
+      "scheduled",
+      "retrying",
+      "running",
+      "completed",
+      "failed",
+      "dead",
+      "cancelled",
+    ]),
+  ),
+});
+
+export type NotificationQuery = Static<typeof notificationQuerySchema>;

package/src/api/notifications/schemas/notificationResourceSchema.ts

@@ -0,0 +1,18 @@
+import { type Static, t } from "alepha";
+
+export const notificationResourceSchema = t.object({
+  id: t.uuid(),
+  createdAt: t.datetime(),
+  status: t.text(),
+  template: t.optional(t.text()),
+  type: t.optional(t.text()),
+  contact: t.optional(t.text()),
+  category: t.optional(t.text()),
+  critical: t.optional(t.boolean()),
+  sensitive: t.optional(t.boolean()),
+  startedAt: t.optional(t.datetime()),
+  completedAt: t.optional(t.datetime()),
+  error: t.optional(t.text()),
+});
+
+export type NotificationResource = Static<typeof notificationResourceSchema>;

package/src/api/notifications/services/NotificationSenderService.ts

@@ -19,19 +19,32 @@ export class NotificationSenderService {
     });
 
     if (payload.type === "email") {
-      await this.emailProvider.send(this.renderEmail(payload));
+      const rendered = this.renderEmail(payload);
+      await this.emailProvider.send(rendered);
       this.log.info("Email notification sent", {
         template: payload.template,
         contact: payload.contact,
       });
+      return {
+        type: "email" as const,
+        to: rendered.to,
+        subject: rendered.subject,
+        body: rendered.body,
+      };
     }
 
     if (payload.type === "sms") {
-      await this.smsProvider.send(this.renderSms(payload));
+      const rendered = this.renderSms(payload);
+      await this.smsProvider.send(rendered);
       this.log.info("SMS notification sent", {
         template: payload.template,
         contact: payload.contact,
       });
+      return {
+        type: "sms" as const,
+        to: rendered.to,
+        message: rendered.message,
+      };
     }
   }
 

package/src/api/users/atoms/realmAuthSettingsAtom.ts

@@ -1,5 +1,19 @@
 import { $atom, type Static, t } from "alepha";
 
+/**
+ * Tri-state field requirement for realm auth settings.
+ *
+ * - `"none"`: Field is disabled and not shown.
+ * - `"optional"`: Field is shown but not required.
+ * - `"required"`: Field is shown and required.
+ */
+export type FieldRequirement = "none" | "optional" | "required";
+
+const fieldRequirement = (description: string) =>
+  t.union([t.const("none"), t.const("optional"), t.const("required")], {
+    description,
+  });
+
 export const realmAuthSettingsAtom = $atom({
   name: "alepha.api.users.realmAuthSettings",
   schema: t.object({
@@ -25,40 +39,26 @@ export const realmAuthSettingsAtom = $atom({
     registrationAllowed: t.boolean({
       description: "Enable user self-registration",
     }),
-    emailEnabled: t.boolean({
-      description: "Enable email address as a login/registration credential",
-    }),
-    emailRequired: t.boolean({
-      description: "Require email address for user accounts",
-    }),
-    usernameEnabled: t.boolean({
-      description: "Enable username as a login/registration credential",
-    }),
-    usernameRequired: t.boolean({
-      description: "Require username for user accounts",
-    }),
+    email: fieldRequirement(
+      "Email address field requirement for user accounts",
+    ),
+    username: fieldRequirement("Username field requirement for user accounts"),
     usernameRegExp: t.string({
       description:
         "Regular expression that usernames must match (if username is enabled)",
     }),
-    phoneEnabled: t.boolean({
-      description: "Enable phone number as a login/registration credential",
-    }),
-    phoneRequired: t.boolean({
-      description: "Require phone number for user accounts",
-    }),
+    phoneNumber: fieldRequirement(
+      "Phone number field requirement for user accounts",
+    ),
     verifyEmailRequired: t.boolean({
       description: "Require email verification for user accounts",
     }),
     verifyPhoneRequired: t.boolean({
       description: "Require phone verification for user accounts",
     }),
-    firstNameLastNameEnabled: t.boolean({
-      description: "Enable first and last name for user accounts",
-    }),
-    firstNameLastNameRequired: t.boolean({
-      description: "Require first and last name for user accounts",
-    }),
+    firstNameLastName: fieldRequirement(
+      "First and last name field requirement for user accounts",
+    ),
     resetPasswordAllowed: t.boolean({
       description: "Enable forgot password functionality",
     }),
@@ -93,18 +93,14 @@ export const realmAuthSettingsAtom = $atom({
   default: {
     // for a fresh hello world setup, we accept registration and email login
     registrationAllowed: true,
-    emailEnabled: true,
-    emailRequired: true,
-    usernameEnabled: false,
-    usernameRequired: false,
+    email: "required" as FieldRequirement,
+    username: "none" as FieldRequirement,
     usernameRegExp: "^[a-zA-Z0-9_]{3,30}$",
-    phoneEnabled: false,
-    phoneRequired: false,
+    phoneNumber: "none" as FieldRequirement,
     verifyEmailRequired: false,
     verifyPhoneRequired: false,
     resetPasswordAllowed: false,
-    firstNameLastNameEnabled: false,
-    firstNameLastNameRequired: false,
+    firstNameLastName: "none" as FieldRequirement,
     adminEmails: [],
     adminUsernames: [],
     // TODO: not implemented yet

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

@@ -6,7 +6,7 @@ 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 `files` feature is enabled in the realm.
+ * It is lazy-loaded when the `avatars` feature is enabled in the realm.
  */
 export class UserBuckets {
   /**

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

@@ -13,7 +13,7 @@ import { sessions } from "../entities/sessions.ts";
  * - Verification code cleanup
  * - Inactive user notifications
  *
- * It is lazy-loaded when the `jobs` feature is enabled in the realm.
+ * It is lazy-loaded when the `sessionPurge` feature is enabled in the realm.
  */
 export class UserJobs {
   protected readonly log = $logger();

package/src/api/users/primitives/$realm.ts

@@ -57,28 +57,14 @@ export const $realm = (options: RealmOptions = {}): RealmPrimitive => {
 
   options.settings ??= {};
 
-  if (options.settings.emailRequired) {
-    options.settings.emailEnabled = true;
-  }
-
-  if (options.settings.usernameRequired) {
-    options.settings.usernameEnabled = true;
-  }
-
-  if (options.settings.phoneRequired) {
-    options.settings.phoneEnabled = true;
-  }
-
   // Merge features with defaults
   const features: RealmFeatures = {
-    jobs: false,
+    sessionPurge: false,
     notifications: false,
     apiKeys: false,
-    clients: false,
     parameters: false,
-    files: false,
+    avatars: false,
     audits: false,
-    organizations: false,
     ...options.features,
   };
 
@@ -97,7 +83,7 @@ export const $realm = (options: RealmOptions = {}): RealmPrimitive => {
   // Enable features based on configuration
   // Each feature registers its wrapper service which internally uses the module primitives
 
-  if (features.files) {
+  if (features.avatars) {
     alepha.with(UserBuckets);
   }
 
@@ -105,7 +91,7 @@ export const $realm = (options: RealmOptions = {}): RealmPrimitive => {
     alepha.with(UserAudits);
   }
 
-  if (features.jobs) {
+  if (features.sessionPurge) {
     alepha.with(UserJobs);
   }
 
@@ -226,11 +212,11 @@ export const $realm = (options: RealmOptions = {}): RealmPrimitive => {
 
 export interface RealmFeatures {
   /**
-   * Enable job execution tracking and purge functionality.
+   * Enable session purge functionality for cleaning up expired sessions.
    *
    * @default false
    */
-  jobs?: boolean;
+  sessionPurge?: boolean;
 
   /**
    * Enable notification system for password reset, verification emails, etc.
@@ -256,26 +242,6 @@ export interface RealmFeatures {
    */
   apiKeys?: boolean;
 
-  /**
-   * Enable OAuth2 Authorization Server for third-party client authentication.
-   *
-   * When enabled, Alepha acts as an OAuth2 Authorization Server, allowing
-   * third-party applications to authenticate users via standard OAuth2 flows:
-   * - Authorization Code + PKCE (OAuth 2.1)
-   * - Client Credentials (machine-to-machine)
-   * - Refresh Token
-   *
-   * Also provides:
-   * - Token introspection (RFC 7662)
-   * - Token revocation (RFC 7009)
-   * - AS metadata (RFC 8414)
-   * - Protected Resource metadata (RFC 9728)
-   * - MCP-compatible OAuth2 flow
-   *
-   * @default false
-   */
-  clients?: boolean;
-
   /**
    * Enable runtime configuration management.
    *
@@ -286,11 +252,11 @@ export interface RealmFeatures {
   parameters?: boolean;
 
   /**
-   * Enable file management for avatar uploads and attachments.
+   * Enable avatar uploads for user profiles.
    *
    * @default false
    */
-  files?: boolean;
+  avatars?: boolean;
 
   /**
    * Enable audit trail for compliance and event logging.
@@ -298,13 +264,6 @@ export interface RealmFeatures {
    * @default false
    */
   audits?: boolean;
-
-  /**
-   * Enable organization management to group users.
-   *
-   * @default false
-   */
-  organizations?: boolean;
 }
 
 // ---------------------------------------------------------------------------------------------------------------------

package/src/api/users/providers/RealmProvider.ts

@@ -34,13 +34,12 @@ export class RealmProvider {
   public register(realmName: string, realmOptions: RealmOptions = {}) {
     // Merge features with defaults
     const features: RealmFeatures = {
-      jobs: false,
+      sessionPurge: false,
       notifications: false,
       apiKeys: false,
       parameters: false,
-      files: false,
+      avatars: false,
       audits: false,
-      organizations: false,
       ...realmOptions.features,
     };
 

package/src/api/users/services/RegistrationService.spec.ts

@@ -146,7 +146,7 @@ describe("alepha/api/users - RegistrationService", () => {
 
       realmProvider.register("username-required-realm", {
         settings: {
-          usernameRequired: true,
+          username: "required",
         } as never,
       });
 
@@ -180,8 +180,8 @@ describe("alepha/api/users - RegistrationService", () => {
 
       realmProvider.register("phone-required-realm", {
         settings: {
-          phoneRequired: true,
-          emailRequired: false,
+          phoneNumber: "required",
+          email: "optional",
         } as never,
       });
 
@@ -240,8 +240,8 @@ describe("alepha/api/users - RegistrationService", () => {
 
       realmProvider.register("phone-realm", {
         settings: {
-          phoneEnabled: true,
-          emailRequired: false,
+          phoneNumber: "optional",
+          email: "optional",
         } as never,
       });
 
@@ -530,7 +530,7 @@ describe("alepha/api/users - RegistrationService", () => {
       expect,
     }) => {
       const { registrationService, sessionService } = await setup({
-        usernameEnabled: true,
+        username: "optional",
       });
 
       const intent = await registrationService.createRegistrationIntent({
@@ -559,7 +559,7 @@ describe("alepha/api/users - RegistrationService", () => {
       expect,
     }) => {
       const { registrationService, sessionService } = await setup({
-        usernameEnabled: true,
+        username: "optional",
       });
 
       // Phase 1: Create intent

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

@@ -97,7 +97,7 @@ export class RegistrationService {
     }
 
     // Validate required fields based on settings
-    if (realmSettings?.usernameRequired && !body.username) {
+    if (realmSettings?.username === "required" && !body.username) {
       this.log.debug("Registration rejected: username required", {
         userRealmName,
       });
@@ -120,14 +120,14 @@ export class RegistrationService {
       }
     }
 
-    if (realmSettings?.emailRequired !== false && !body.email) {
+    if (realmSettings?.email === "required" && !body.email) {
       this.log.debug("Registration rejected: email required", {
         userRealmName,
       });
       throw new BadRequestError("Email is required");
     }
 
-    if (realmSettings?.phoneRequired && !body.phoneNumber) {
+    if (realmSettings?.phoneNumber === "required" && !body.phoneNumber) {
       this.log.debug("Registration rejected: phone required", {
         userRealmName,
       });